Multicast DNS implementation (initial)

net/dns/mdns_client.h

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef NET_DNS_MDNS_CLIENT_H_
 #define NET_DNS_MDNS_CLIENT_H_
 
 #include <string>
 #include <vector>
 
 #include "base/callback.h"
 #include "net/dns/dns_query.h"
 #include "net/dns/dns_response.h"
 #include "net/dns/record_parsed.h"
 
 namespace net {
 
 class RecordParsed;
 
+// Used in the MDnsListener delegate to signify what type of change has been
+// made to a record.
 enum MDnsUpdateType {
   kMDnsRecordAdded,
   kMDnsRecordChanged,
   kMDnsRecordRemoved
 };
 
+// Used in the MDnsTransaction to signify what type of result the transaction
+// has recieved.
 enum MDnsTransactionResult {
-  kMDnsTransactionSuccess,
-  kMDnsTransactionTimeout,
-  kMDnsTransactionNsec
+  // Passed whenever a record is found.
+  kMDnsTransactionRecord,
+  // The transaction is done. Applies to non-single-valued transactions. Is
+  // called when the transaction has finished (this is the last call to the
+  // callback).
+  kMDnsTransactionDone,
+  // No results have been found. Applies to single-valued transactions. Is
+  // called when the transaction has finished without finding any results.
+  // For transactions that use the network, this happens when a timeout occurs,
+  // for transactions that are cache-only, this happens when no results are in
+  // the cache.
+  kMDnsTransactionNoResults,
+  // Called when an NSec record is read for this transaction's query. This means
+  // there cannot possibly be a record of the type and name for this
+  // transaction.
+  kMDnsTransactionNSec
 };
 
-// A class representing a one-time unique-record lookup. A transaction takes one
-// associated callback (see |MDnsClient::CreateTransaction|) and calls it when
-// a matching record has been found, either from the cache or by querying the
-// network. Transactions will time out after a reasonable number of seconds.
+// Used when creating an MDnsTransaction.
+enum MDnsTransactionFlags {
+  // Transaction should return only one result, and stop listening after it.
+  // Note that single result transactions will signal when their timeout is
+  // reached, whereas multi-result transactions will not.
+  kMDnsTransactionSingleResult = 1 << 0,
+  // Query the cache or the network. May both be used. One must be present.
+  kMDnsTransactionQueryCache = 1 << 1,
+  kMDnsTransactionQueryNetwork = 1 << 2,
+  // TODO(noamsml): Add flag for flushing cache when feature is implemented
+  // Mask of all possible flags on MDnsTransaction.
+  kMDnsTransactionFlagMask = (1 << 3) - 1,
+};
+
+// Represents a one-time record lookup. A transaction takes one
+// associated callback (see |MDnsClient::CreateTransaction|) and calls it
+// whenever a matching record has been found, either from the cache or
+// by querying the network (it may choose to query either or both based on its
+// creation flags, see MDnsTransactionFlags). Network-based transactions will
+// time out after a reasonable number of seconds.
 class MDnsTransaction {
  public:
   typedef base::Callback<void(MDnsTransactionResult, const RecordParsed*)>
   ResultCallback;
 
   // Destroying the transaction cancels it.
   virtual ~MDnsTransaction() {}
 
-  // Start the transaction.
+  // Start the transaction. Return true on success.
   virtual bool Start() = 0;
 
   // Get the host or service name for the transaction.
   virtual const std::string& GetName() const = 0;
 
   // Get the type for this transaction (SRV, TXT, A, AAA, etc)
   virtual uint16 GetType() const = 0;
 };
 
 // A listener listens for updates regarding a specific record or set of records.
-// If a listener is active (determined at its creation) it will send queries
-// when appropriate.
 class MDnsListener {
  public:
   class Delegate {
    public:
     virtual ~Delegate() {}
 
     // Called when a record is added, removed or updated.
     virtual void OnRecordUpdate(MDnsUpdateType update,
                                 const RecordParsed* record) = 0;
 
     // Called when a record is marked nonexistent by an NSEC record.
     virtual void OnNsecRecord(const std::string& name, unsigned type) = 0;
+
+    // Called when the cache is purged (due, for example, ot the network
+    // disconnecting).
+    virtual void OnCachePurged() = 0;
   };
 
   // Destroying the listener stops listening.
   virtual ~MDnsListener() {}
 
-  // Start the listener.
+  // Start the listener. Return true on success.
   virtual bool Start() = 0;
 
   // Get the host or service name for this query.
   // Return an empty string for no name.
   virtual const std::string& GetName() const = 0;
 
   // Get the type for this query (SRV, TXT, A, AAA, etc)
   virtual uint16 GetType() const = 0;
-
-  // Whether this listener is active (true) or passive (false)
-  virtual bool IsActive() const = 0;
-
-  // Applies only to listeners with names. Will send out a query for new
-  // information. |force_refresh_cache| will force a refresh of all cached
-  // entities.
-  virtual bool SendQuery(bool force_refresh_cache) = 0;
-
-  // Applies only to listeners with names. Query mDNS cache synchronously for
-  // either single- or multi- valued records.
-  virtual bool QueryCache(std::vector<const RecordParsed*>* records) const = 0;
 };
 
-// This class listens for Multicast DNS on the local network. You can access
+// Listens for Multicast DNS on the local network. You can access
 // information regarding multicast DNS either by creating an |MDnsListener| to
 // be notified of new records, or by creating an |MDnsTransaction| to look up
 // the value of a specific records.
 class MDnsClient {
  public:
   virtual ~MDnsClient() {}
 
   // Create listener object for RRType |rrtype| and name |name|.
   // If |name| is an empty string, listen to all notification of type
-  // |rrtype|. If a listener is |active|, it will send queries when the client
-  // thinks they are needed. If |alert_existing_records| is true, a listener's
-  // delegate will be alerted for records already in the cache when it is
-  // created.
+  // |rrtype|.
   virtual scoped_ptr<MDnsListener> CreateListener(
       uint16 rrtype,
       const std::string& name,
-      bool active,
-      bool alert_existing_records,
       MDnsListener::Delegate* delegate) = 0;
 
-  // Create a transaction to Query MDNS for a single-value query
-  // (A, AAAA, TXT, and SRV) asynchronously. May defer to cache.
+  // Create a transaction that can be used to query either the MDns cache, the
+  // network, or both.
   virtual scoped_ptr<MDnsTransaction> CreateTransaction(
       uint16 rrtype,
       const std::string& name,
+      int flags,  // See MDnsTransactionFlags

[szym, 2013/06/10 21:58:28]

Move this to the comment above.

[Noam Samuel, 2013/06/11 20:35:03]

Done.

       const MDnsTransaction::ResultCallback& callback) = 0;
 
   // Lazily create and return static instance for MDnsClient.
   static MDnsClient* GetInstance();
 
   // Set the global instance (for testing). MUST be called before the first call
   // to GetInstance.
   static void SetInstance(MDnsClient* instance);
 };
 
 }  // net
 #endif  // NET_DNS_MDNS_CLIENT_H_