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. 4 5 #ifndef NET_DNS_MDNS_CLIENT_H_ 6 #define NET_DNS_MDNS_CLIENT_H_ 7 8 #include <string> 9 #include <vector> 10 11 #include "base/callback.h" 12 #include "net/dns/dns_query.h" 13 #include "net/dns/dns_response.h" 14 #include "net/dns/record_parsed.h" 15 16 namespace net { 17 18 class RecordParsed; 19 20 // Represents a one-time record lookup. A transaction takes one 21 // associated callback (see |MDnsClient::CreateTransaction|) and calls it 22 // whenever a matching record has been found, either from the cache or 23 // by querying the network (it may choose to query either or both based on its 24 // creation flags, see MDnsTransactionFlags). Network-based transactions will 25 // time out after a reasonable number of seconds. 26 class NET_EXPORT MDnsTransaction { 27 public: 28 // Used to signify what type of result the transaction has recieved. 29 enum Result { 30 // Passed whenever a record is found. 31 RESULT_RECORD, 32 // The transaction is done. Applies to non-single-valued transactions. Is 33 // called when the transaction has finished (this is the last call to the 34 // callback). 35 RESULT_DONE, 36 // No results have been found. Applies to single-valued transactions. Is 37 // called when the transaction has finished without finding any results. 38 // For transactions that use the network, this happens when a timeout 39 // occurs, for transactions that are cache-only, this happens when no 40 // results are in the cache. 41 RESULT_NO_RESULTS, 42 // Called when an NSec record is read for this transaction's 43 // query. This means there cannot possibly be a record of the type 44 // and name for this transaction. 45 RESULT_NSEC 46 }; 47 48 // Used when creating an MDnsTransaction. 49 enum Flags { 50 // Transaction should return only one result, and stop listening after it. 51 // Note that single result transactions will signal when their timeout is 52 // reached, whereas multi-result transactions will not. 53 SINGLE_RESULT = 1 << 0, 54 // Query the cache or the network. May both be used. One must be present. 55 QUERY_CACHE = 1 << 1, 56 QUERY_NETWORK = 1 << 2, 57 // TODO(noamsml): Add flag for flushing cache when feature is implemented 58 // Mask of all possible flags on MDnsTransaction. 59 FLAG_MASK = (1 << 3) - 1, 60 }; 61 62 typedef base::Callback<void(Result, const RecordParsed*)> 63 ResultCallback; 64 65 // Destroying the transaction cancels it. 66 virtual ~MDnsTransaction() {} 67 68 // Start the transaction. Return true on success. Cache-based transactions 69 // will execute the callback synchronously. 70 virtual bool Start() = 0; 71 72 // Get the host or service name for the transaction. 73 virtual const std::string& GetName() const = 0; 74 75 // Get the type for this transaction (SRV, TXT, A, AAA, etc) 76 virtual uint16 GetType() const = 0; 77 }; 78 79 // A listener listens for updates regarding a specific record or set of records. 80 // Created by the MDnsClient (see |MDnsClient::CreateListener|) and used to keep 81 // track of listeners. 82 class NET_EXPORT MDnsListener { 83 public: 84 // Used in the MDnsListener delegate to signify what type of change has been 85 // made to a record. 86 enum UpdateType { 87 RECORD_ADDED, 88 RECORD_CHANGED, 89 RECORD_REMOVED 90 }; 91 92 class Delegate { 93 public: 94 virtual ~Delegate() {} 95 96 // Called when a record is added, removed or updated. 97 virtual void OnRecordUpdate(UpdateType update, 98 const RecordParsed* record) = 0; 99 100 // Called when a record is marked nonexistent by an NSEC record. 101 virtual void OnNsecRecord(const std::string& name, unsigned type) = 0; 102 103 // Called when the cache is purged (due, for example, ot the network 104 // disconnecting). 105 virtual void OnCachePurged() = 0; 106 }; 107 108 // Destroying the listener stops listening. 109 virtual ~MDnsListener() {} 110 111 // Start the listener. Return true on success. 112 virtual bool Start() = 0; 113 114 // Get the host or service name for this query. 115 // Return an empty string for no name. 116 virtual const std::string& GetName() const = 0; 117 118 // Get the type for this query (SRV, TXT, A, AAA, etc) 119 virtual uint16 GetType() const = 0; 120 }; 121 122 // Listens for Multicast DNS on the local network. You can access information 123 // regarding multicast DNS either by creating an |MDnsListener| to be notified 124 // of new records, or by creating an |MDnsTransaction| to look up the value of a 125 // specific records. When all listeners and active transactions are destroyed, 126 // the client stops listening on the network and destroys the cache. 127 class NET_EXPORT MDnsClient { 128 public: 129 virtual ~MDnsClient() {} 130 131 // Create listener object for RRType |rrtype| and name |name|. 132 virtual scoped_ptr<MDnsListener> CreateListener( 133 uint16 rrtype, 134 const std::string& name, 135 MDnsListener::Delegate* delegate) = 0; 136 137 // Create a transaction that can be used to query either the MDns cache, the 138 // network, or both for records of type |rrtype| and name |name|. |flags| is 139 // defined by MDnsTransactionFlags. 140 virtual scoped_ptr<MDnsTransaction> CreateTransaction( 141 uint16 rrtype, 142 const std::string& name, 143 int flags, 144 const MDnsTransaction::ResultCallback& callback) = 0; 145 146 virtual bool StartListening() = 0; 147 148 // Do not call this inside callbacks from related MDnsListener and 149 // MDnsTransaction objects. 150 virtual void StopListening() = 0; 151 virtual bool IsListening() const = 0; 152 153 // Create the default MDnsClient 154 static scoped_ptr<MDnsClient> CreateDefault(); 155 }; 156 157 } // namespace net 158 #endif // NET_DNS_MDNS_CLIENT_H_ 159
