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 {

[szym, 2013/06/12 21:35:41]

Perhaps put this nested in MDnsListener::UpdateType.

[Noam Samuel, 2013/06/13 01:08:40]

Done.

+  kMDnsRecordAdded,

[szym, 2013/06/12 21:35:41]

http://www.chromium.org/developers/coding-style prefers macro-style naming for
enums.

[Noam Samuel, 2013/06/13 01:08:40]

Done.

+  kMDnsRecordChanged,
+  kMDnsRecordRemoved
+};
+
+// Used in the MDnsTransaction to signify what type of result the transaction
+// has recieved.
+enum MDnsTransactionResult {

[szym, 2013/06/12 21:35:41]

You could move this into MDnsTransaction so that the enum constant names are
just RESULT_RECORD, RESULT_DONE, etc.

[Noam Samuel, 2013/06/13 01:08:40]

Done.

+  // 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
+};
+
+// 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. Return true on success.

[szym, 2013/06/12 21:35:41]

Add a comment that cache-only transactions execute the callback immediately.

[Noam Samuel, 2013/06/13 01:08:40]

Done.

+  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.

[szym, 2013/06/12 21:35:41]

Add a short comment explaining the design responsibility of this class, e.g.
"Created by MDnsClient and used to keep track of active listeners."

You should also explain either here or in MDnsClient that the internal cache is
destroyed when nobody is listening.

[Noam Samuel, 2013/06/13 01:08:40]

Done.

+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. 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;
+};
+
+// 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|.
+  virtual scoped_ptr<MDnsListener> CreateListener(
+      uint16 rrtype,
+      const std::string& name,
+      MDnsListener::Delegate* delegate) = 0;
+
+  // Create a transaction that can be used to query either the MDns cache, the
+  // network, or both for records of type |rrtype| and name |name|. |flags| is
+  // defined by MDnsTransactionFlags.
+  virtual scoped_ptr<MDnsTransaction> CreateTransaction(
+      uint16 rrtype,
+      const std::string& name,
+      int flags,
+      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);
+};
+
+}  // namespace net
+#endif  // NET_DNS_MDNS_CLIENT_H_