[Media Router] Design MediaRouter interface with stub implementation.

chrome/browser/media/router/media_router.h

+// Copyright 2015 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_MEDIA_ROUTER_MEDIA_ROUTER_H_
+#define CHROME_BROWSER_MEDIA_ROUTER_MEDIA_ROUTER_H_
+
+#include <string>
+#include <vector>
+
+#include "base/callback.h"
+#include "chrome/browser/media/router/media_route.h"
+#include "chrome/browser/media/router/media_route_id.h"
+#include "chrome/browser/media/router/media_sink.h"
+
+namespace media_router {
+
+class MediaRouteResponse;
+class MediaRoutesObserver;
+class MediaSource;
+class MediaSinksObserver;
+
+using MediaRouteResponseCallback =
+    base::Callback<void(scoped_ptr<MediaRoute>, const std::string&)>;

[xhwang, 2015/04/09 17:33:34]

Since this is part of the interface. Please add a comment.

[imcheng, 2015/04/09 17:49:10]

Done.

+
+// An interface for handling resources related to media routing.
+// Responsible for registering observers for receiving sink availability
+// updates, handling route requests/responses, and operating on routes (e.g.
+// posting messages or closing).
+class MediaRouter {
+ public:
+  virtual ~MediaRouter() {}
+
+  // Requests a media route from |source| to |sink_id|.
+  // |callback| is invoked with a response indicating success or failure.
+  virtual void RequestRoute(const MediaSource& source,
+                            const MediaSinkId& sink_id,

[xhwang, 2015/04/09 17:33:34]

OOC, is there any reason not to use a MediaSink here? Or use a source_id instead
of source?

[imcheng, 2015/04/09 17:49:10]

That's because RequestRoute only needs to know the sink ID - other fields such
as name are unnecessary. For source, if we included extra options onto the
source, those will need to be included in RequestRoute as well.

+                            const MediaRouteResponseCallback& callback) = 0;
+
+  // Closes the media route specified by |route_id|.
+  virtual void CloseRoute(const MediaRouteId& route_id) = 0;
+
+  // Posts |message| to a MediaSink connected via MediaRoute with |route_id|.
+  // TODO(imcheng): Support additional data types: Blob, ArrayBuffer,
+  // ArrayBufferView.
+  virtual void PostMessage(const MediaRouteId& route_id,
+                           const std::string& message) = 0;
+
+  // Receives updates from a MediaRouter instance.
+  class Delegate {
+    // Called when there is a message from a route.

[Kevin Marshall, 2015/04/09 18:16:59]

Missing public:

[imcheng, 2015/04/09 18:44:27]

Done.

+    // |route_id|: The route ID.
+    // |message|: The message.
+    virtual void OnMessage(const MediaRouteId& route_id,
+                           const std::string& message) = 0;
+  };
+
+ private:
+  friend class MediaSinksObserver;
+  friend class MediaRoutesObserver;
+
+  // The following APIs are called by MediaSinksObserver/MediaRoutesObserver
+  // only.
+
+  // Registers |observer| with this MediaRouter. |observer| specifies a media
+  // source and will receive updates with media sinks that are compatible with
+  // that source. The initial update may happen synchronously.
+  // NOTE: This class does not assume ownership of |observer|. Callers must
+  // manage |observer| and make sure |UnregisterObserver()| is called
+  // before the observer is destroyed.
+  // Returns true if registration succeeded.
+  // It is invalid to request the same observer more than once and will result
+  // in undefined behavior.
+  // If the MRPM Host is not available, the registration request will fail
+  // immediately.
+  virtual bool RegisterMediaSinksObserver(MediaSinksObserver* observer) = 0;
+
+  // Removes a previously added MediaSinksObserver. |observer| will stop
+  // receiving further updates.
+  virtual void UnregisterMediaSinksObserver(MediaSinksObserver* observer) = 0;

[xhwang, 2015/04/09 17:33:33]

Do you expect all customers of MeidaRouter to implement MediaSinksObserver? For
example, MediaRouterImpl is also a customer of this interface. If so, this
interface should work. Otherwise, you may want to keep the two On* methods in
the Delegate, and remove the observers from this interface. Then in
implementation, you can have observers on MediaRouterImpl (not MediaRouter
interface).

[imcheng, 2015/04/09 17:49:10]

Yes, customers will have to provide their own implementation of the Observers.
And actually I am not currently aware of cases where we need to bubble up the
query results back to the "master" MediaRouterImpl, as long as we are pushing
the responsibility of notifying the observers down to the
ExtensionMediaRouteProviderManagerHost.

+
+  // Adds a MediaRoutesObserver to listen for updates on MediaRoutes.
+  // The initial update may happen synchronously.
+  // MediaRouter does not own |observer|. |RemoveMediaRoutesObserver| should
+  // be called before |observer| is destroyed.
+  virtual bool RegisterMediaRoutesObserver(MediaRoutesObserver* observer) = 0;
+
+  // Removes a previously added MediaRoutesObserver. |observer| will stop
+  // receiving further updates.
+  virtual void UnregisterMediaRoutesObserver(MediaRoutesObserver* observer) = 0;
+};
+
+}  // namespace media_router
+
+#endif  // CHROME_BROWSER_MEDIA_ROUTER_MEDIA_ROUTER_H_