In-browser DNS-based service discovery system

chrome/browser/local_discovery/service_discovery_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 CHROME_BROWSER_LOCAL_DISCOVERY_SERVICE_DISCOVERY_CLIENT_H_
+#define CHROME_BROWSER_LOCAL_DISCOVERY_SERVICE_DISCOVERY_CLIENT_H_
+
+#include <string>
+#include <vector>
+
+#include "base/callback.h"
+#include "base/memory/scoped_ptr.h"
+#include "base/time.h"
+#include "net/base/host_port_pair.h"
+
+namespace local_discovery {
+
+// Lets users browse the network for services of interest or listen for changes
+// in the services they are interested in. See
+// |ServiceDiscoveryClient::CreateServiceTypeWatcher|.
+class ServiceTypeWatcher {
+ public:
+  class Delegate {
+   public:
+    virtual ~Delegate() {}
+
+    // A service has been added or removed for a certain service name.
+    virtual void OnServiceStatusChanged(bool available,
+                                        const std::string& service_name) = 0;
+  };
+
+  // Listening will automatically stop when the destructor is called.
+  virtual ~ServiceTypeWatcher() {}
+
+  // Start the service type watcher.
+  virtual bool Start() = 0;
+
+  // Get all known services names of this watcher's type. Return them in
+  // |services|.
+  virtual void GetAvailableServices(
+      std::vector<std::string>* services) const = 0;

[Vitaly Buka (NO REVIEWS), 2013/06/15 00:22:30]

one line?

[Noam Samuel, 2013/06/18 22:46:03]

Doesn't fit.

+
+  // Probe for services of this type.
+  virtual void DiscoverNewServices() = 0;
+
+  // Probe for services of this type and also force early invalidation
+  // of existing services, having the effect of throwing away invalidated
+  // services. This method should NOT be called periodically, but only
+  // in response to user action.
+  virtual void ForceUpdateServices() = 0;
+
+  virtual std::string GetServiceType() const = 0;
+
+  virtual bool IsActive() const = 0;
+};
+
+// Represents a service on the network and allows users to access the service's
+// address and metadata. See |ServiceDiscoveryClient::CreateServiceReader|.
+class ServiceReader {
+ public:
+  enum RequestStatus {
+    STATUS_SUCCESS = 0,
+    STATUS_TIMEOUT = 1,
+    STATUS_KNOWN_NONEXISTENT = 2
+  };
+
+  class Delegate {
+   public:
+    virtual ~Delegate() {}
+
+    virtual void OnAddressChanged(const std::string& service_name,
+                                  const net::HostPortPair& address) = 0;
+
+    virtual void OnMetadataChanged(
+        const std::string& service_name,
+        const std::vector<std::string>& metadata) = 0;
+  };
+
+  // A callback for recieving metadata. The first argument is the request status
+  // and the second argument is the metadata.
+  typedef base::Callback<void(ServiceReader::RequestStatus,
+                              const std::vector<std::string>&)>
+      MetadataCallback;

[Vitaly Buka (NO REVIEWS), 2013/06/15 00:22:30]

Maybe move all callback into delegate?

[Noam Samuel, 2013/06/15 00:42:06]

Hm. It would definitely provide some simplicity. The concept behind using
callbacks for these is to make them similar to other asynchronous data requests,
whereas the delegate signifies changes in state. Not sure if the distinction is
that useful, though.

I could add On*RequestComplete separate from the On*Changed functions in the
delegate, which would be called whenever a request is finished rather than being
called whenever the value changes, or I could try merging the two which might be
messy from the API user's side.

[Noam Samuel, 2013/06/18 22:46:03]

Made irrelevant by refactor.

On 2013/06/15 00:42:06, Noam Samuel wrote:

+
+  // A callback for recieving the address. The first argument is the request
+  // status and the second argument is the address.
+  typedef base::Callback<void(ServiceReader::RequestStatus,
+                              const net::HostPortPair&)>
+      AddressCallback;
+
+  // A callback for recieving the last time the PTR record has been seen.
+  typedef base::Callback<void(base::Time)> LastSeenCallback;
+
+  // Listening will automatically stop when the destructor is called.
+  virtual ~ServiceReader() {}
+
+  // Start the service reader.
+  virtual bool Start() = 0;
+
+  // Get the cached TXT record for a service. Returns true and fills |metadata|
+  // if the record exists. Use NULL for |metadata| to simply check if the value
+  // is present.
+  virtual bool GetMetadata(std::vector<std::string>* metadata) const = 0;
+
+  // Read the TXT record for a service. If |force_refresh| is
+  // true, force a refresh of the record even if it is cached, otherwise
+  // defer to the cache when it is available.
+  virtual void ReadMetadata(const MetadataCallback& callback,
+                            bool force_refresh) = 0;
+
+  // Get the cached SRV record for a service. Returns true and fills |address|
+  // if the record exists. Use NULL for |address| to simply check if the value
+  // is present.
+  virtual bool GetAddress(net::HostPortPair* address) const = 0;
+
+  // Read the SRV record for a service. If |force_refresh| is
+  // true, force a refresh of the record even if it is cached, otherwise
+  // defer to the cache when it is available.
+  virtual void ReadAddress(const AddressCallback& callback,
+                            bool force_refresh) = 0;

[Vitaly Buka (NO REVIEWS), 2013/06/15 00:22:30]

missaligned

[Noam Samuel, 2013/06/18 22:46:03]

Code removed.

+
+  virtual std::string GetHumanReadableName() const = 0;
+  virtual std::string GetType() const = 0;
+  virtual std::string GetName() const = 0;
+
+  // Check whether the service is available, measured by the existence of an SRV
+  // record. This does not determine whether a service is still being
+  // advertised.
+  virtual bool IsAvailable() const = 0;
+
+  // Call |callback| with the last time the SRV record has been seen. Uses the
+  // default value of base::Time to signify that it is unavailable.
+  virtual void ReadLastSeen(const LastSeenCallback& callback) = 0;
+};
+
+class ServiceDiscoveryClient {
+ public:
+  virtual ~ServiceDiscoveryClient() {}
+
+  // Create a service object listening for DNS-SD service announcements on
+  // service type |service_type|. If a service type watcher is |active|,
+  // it will query the network for new services. If |alert_existing_services| is
+  // true, the delegate will be alerted for services already in the cache.
+  virtual scoped_ptr<ServiceTypeWatcher> CreateServiceTypeWatcher(
+      const std::string& service_type,
+      bool active,
+      bool alert_existing_services,
+      ServiceTypeWatcher::Delegate* delegate) = 0;
+
+  // Create a service object listening for DNS-SD service announcements on
+  // service |service_name|. |delegate| may be null in which case the
+  // object will not recieve continuous announcements but may still query
+  // about the relevant service.
+  virtual scoped_ptr<ServiceReader> CreateServiceReader(
+      const std::string& service_name,
+      ServiceReader::Delegate* delegate) = 0;
+
+  // Lazily create and return static instance for ServiceDiscoveryClient.
+  static ServiceDiscoveryClient* GetInstance();
+
+  // Set the global instance (for testing). MUST be called before the first call
+  // to GetInstance.
+  static void SetInstance(ServiceDiscoveryClient* instance);
+};
+
+}  // namespace local_discovery
+
+#endif  // CHROME_BROWSER_LOCAL_DISCOVERY_SERVICE_DISCOVERY_CLIENT_H_