net/dns/mdns_client.h

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