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;
+
+enum MDnsUpdateType {

[szym, 2013/06/07 16:40:02]

nit: Needs a comment on what it is used for.

[Noam Samuel, 2013/06/07 23:54:43]

Done.

+  kMDnsRecordAdded,
+  kMDnsRecordChanged,
+  kMDnsRecordRemoved
+};
+
+enum MDnsTransactionResult {

[szym, 2013/06/07 16:40:02]

nit: Needs a comment on what it is used for.

[Noam Samuel, 2013/06/07 23:54:43]

Done.

+  // Called whenever a record is found.

[szym, 2013/06/07 16:40:02]

Nit: "Passed" would be better than "called".

[Noam Samuel, 2013/06/07 23:54:43]

Done.

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

[szym, 2013/06/07 16:40:02]

nit: Would make sense to mention that this is the case of time-out?

[Noam Samuel, 2013/06/07 23:54:43]

Done.

+  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
+};
+
+enum MDnsTransactionFlags {

[szym, 2013/06/07 16:40:02]

nit: Needs a comment on what it is used for.

[Noam Samuel, 2013/06/07 23:54:43]

Done.

+  // 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 = 0x1,

[szym, 2013/06/07 16:40:02]

nit: Use 1 << 0 instead of 0x1. Same below.

[Noam Samuel, 2013/06/07 23:54:43]

Done.

+  // Query the cache or the network. May both be used. One must be present.
+  kMDnsTransactionQueryCache = 0x2,
+  kMDnsTransactionQueryNetwork = 0x4,
+  // TODO(noamsml): Add flag for flushing cache when feature is implemented
+  // Mask of all possible flags on MDnsTransaction.
+  kMDnsTransactionFlagMask = 0x7,

[szym, 2013/06/07 16:40:02]

Never used. Remove.

[Noam Samuel, 2013/06/07 23:54:43]

This is used in a DCHECK to warn users who pass nonexistent flags to
CreateTransaction.

+};
+
+// A class representing a one-time record lookup. A transaction takes one

[szym, 2013/06/07 16:40:02]

nit: "A class" is redundant. "Represents a one-time record lookup." is better,
but just "A one-time record lookup." would suffice as well.

[Noam Samuel, 2013/06/07 23:54:43]

Done.

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

[szym, 2013/06/07 16:40:02]

nit: Return what?

[Noam Samuel, 2013/06/07 23:54:43]

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.
+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.
+  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;
+};
+
+// This class listens for Multicast DNS on the local network. You can access

[szym, 2013/06/07 16:40:02]

nit: No need for "This class".

[Noam Samuel, 2013/06/07 23:54:43]

Done.

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

[szym, 2013/06/07 16:40:02]

Update comment to reflect change in interface.

[Noam Samuel, 2013/06/07 23:54:43]

Done.

+  virtual scoped_ptr<MDnsListener> CreateListener(
+      uint16 rrtype,
+      const std::string& name,
+      MDnsListener::Delegate* delegate) = 0;
+
+  // Create a transaction to Query MDNS for a query to the cache, to the

[szym, 2013/06/07 16:40:02]

Confusing grammar.

[Noam Samuel, 2013/06/07 23:54:43]

Done.

+  // network, or to both, it completes via a callback that may be called
+  // synchronously.
+  virtual scoped_ptr<MDnsTransaction> CreateTransaction(
+      uint16 rrtype,
+      const std::string& name,
+      int flags,  // See MDnsTransactionFlags
+      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_