1 // Copyright 2013 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #ifndef NET_DNS_MDNS_CLIENT_H_
6 #define NET_DNS_MDNS_CLIENT_H_
11 #include "base/callback.h"
12 #include "net/base/ip_endpoint.h"
13 #include "net/dns/dns_query.h"
14 #include "net/dns/dns_response.h"
15 #include "net/dns/record_parsed.h"
21 // Represents a one-time record lookup. A transaction takes one
22 // associated callback (see |MDnsClient::CreateTransaction|) and calls it
23 // whenever a matching record has been found, either from the cache or
24 // by querying the network (it may choose to query either or both based on its
25 // creation flags, see MDnsTransactionFlags). Network-based transactions will
26 // time out after a reasonable number of seconds.
27 class NET_EXPORT MDnsTransaction
{
29 // Used to signify what type of result the transaction has recieved.
31 // Passed whenever a record is found.
33 // The transaction is done. Applies to non-single-valued transactions. Is
34 // called when the transaction has finished (this is the last call to the
37 // No results have been found. Applies to single-valued transactions. Is
38 // called when the transaction has finished without finding any results.
39 // For transactions that use the network, this happens when a timeout
40 // occurs, for transactions that are cache-only, this happens when no
41 // results are in the cache.
43 // Called when an NSec record is read for this transaction's
44 // query. This means there cannot possibly be a record of the type
45 // and name for this transaction.
49 // Used when creating an MDnsTransaction.
51 // Transaction should return only one result, and stop listening after it.
52 // Note that single result transactions will signal when their timeout is
53 // reached, whereas multi-result transactions will not.
54 SINGLE_RESULT
= 1 << 0,
55 // Query the cache or the network. May both be used. One must be present.
57 QUERY_NETWORK
= 1 << 2,
58 // TODO(noamsml): Add flag for flushing cache when feature is implemented
59 // Mask of all possible flags on MDnsTransaction.
60 FLAG_MASK
= (1 << 3) - 1,
63 typedef base::Callback
<void(Result
, const RecordParsed
*)>
66 // Destroying the transaction cancels it.
67 virtual ~MDnsTransaction() {}
69 // Start the transaction. Return true on success. Cache-based transactions
70 // will execute the callback synchronously.
71 virtual bool Start() = 0;
73 // Get the host or service name for the transaction.
74 virtual const std::string
& GetName() const = 0;
76 // Get the type for this transaction (SRV, TXT, A, AAA, etc)
77 virtual uint16
GetType() const = 0;
80 // A listener listens for updates regarding a specific record or set of records.
81 // Created by the MDnsClient (see |MDnsClient::CreateListener|) and used to keep
82 // track of listeners.
83 class NET_EXPORT MDnsListener
{
85 // Used in the MDnsListener delegate to signify what type of change has been
95 virtual ~Delegate() {}
97 // Called when a record is added, removed or updated.
98 virtual void OnRecordUpdate(UpdateType update
,
99 const RecordParsed
* record
) = 0;
101 // Called when a record is marked nonexistent by an NSEC record.
102 virtual void OnNsecRecord(const std::string
& name
, unsigned type
) = 0;
104 // Called when the cache is purged (due, for example, ot the network
106 virtual void OnCachePurged() = 0;
109 // Destroying the listener stops listening.
110 virtual ~MDnsListener() {}
112 // Start the listener. Return true on success.
113 virtual bool Start() = 0;
115 // Get the host or service name for this query.
116 // Return an empty string for no name.
117 virtual const std::string
& GetName() const = 0;
119 // Get the type for this query (SRV, TXT, A, AAA, etc)
120 virtual uint16
GetType() const = 0;
123 // Listens for Multicast DNS on the local network. You can access information
124 // regarding multicast DNS either by creating an |MDnsListener| to be notified
125 // of new records, or by creating an |MDnsTransaction| to look up the value of a
126 // specific records. When all listeners and active transactions are destroyed,
127 // the client stops listening on the network and destroys the cache.
128 class NET_EXPORT MDnsClient
{
130 virtual ~MDnsClient() {}
132 // Create listener object for RRType |rrtype| and name |name|.
133 virtual scoped_ptr
<MDnsListener
> CreateListener(
135 const std::string
& name
,
136 MDnsListener::Delegate
* delegate
) = 0;
138 // Create a transaction that can be used to query either the MDns cache, the
139 // network, or both for records of type |rrtype| and name |name|. |flags| is
140 // defined by MDnsTransactionFlags.
141 virtual scoped_ptr
<MDnsTransaction
> CreateTransaction(
143 const std::string
& name
,
145 const MDnsTransaction::ResultCallback
& callback
) = 0;
147 virtual bool StartListening() = 0;
149 // Do not call this inside callbacks from related MDnsListener and
150 // MDnsTransaction objects.
151 virtual void StopListening() = 0;
152 virtual bool IsListening() const = 0;
154 // Create the default MDnsClient
155 static scoped_ptr
<MDnsClient
> CreateDefault();
158 IPEndPoint NET_EXPORT
GetMDnsIPEndPoint(AddressFamily address_family
);
161 #endif // NET_DNS_MDNS_CLIENT_H_