[Media Router] Design MediaRouter interface with stub implementation.

chrome/browser/media/router/media_route_provider_manager_host.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_ROUTE_PROVIDER_MANAGER_HOST_H_
+#define CHROME_BROWSER_MEDIA_ROUTER_MEDIA_ROUTE_PROVIDER_MANAGER_HOST_H_
+
+#include <string>
+#include <vector>
+
+#include "base/callback.h"
+#include "chrome/browser/media/router/media_route.h"
+#include "chrome/browser/media/router/media_sink.h"
+#include "chrome/browser/media/router/media_source.h"
+
+namespace media_router {
+
+class MediaRoute;
+
+// Acts as the Chrome endpoint for communication between Media Router and
+// Media Route Providers (via the Media Route Provider Manager).
+class MediaRouteProviderManagerHost {
+ public:
+  virtual ~MediaRouteProviderManagerHost() {}
+
+  // Delegate called by the MediaRouteProviderManagerHost when a response is
+  // received from the MRPM.
+  class Delegate {

[xhwang, 2015/04/02 17:13:02]

Please see comment below. For response of a particular call, usually I like to
use callbacks. For calls initiated by MRPM, we can use a Delegate or permanent
callbacks. I don't know your system well enough to suggest which is better, but
that's something worth considering.

[imcheng, 2015/04/02 23:05:23]

Thanks for the suggestion. Please refer to comments below.

+   public:
+    virtual ~Delegate() {}
+
+    // Called when results from a media sinks query have been received.
+    // |source|: Media source of the query.
+    // |sinks|: List of sinks compatible with the source.
+    // |routes|: Currently active routes on |sinks|.

[xhwang, 2015/04/02 17:13:02]

I don't see |routes|.

[imcheng, 2015/04/02 23:05:23]

Removed.

+    virtual void OnSinksReceived(const MediaSource& source,
+                                 const std::vector<MediaSink>& sinks) = 0;
+
+    // Called when there is a message from a route.
+    // |route_id|: The route ID.
+    // |message|: The message.
+    virtual void OnMessage(const MediaRouteId& route_id,
+                           const std::string& message) = 0;
+
+    // Called when a response to a route request has been received and
+    // a route has been established.
+    // |request_id|: ID of original request.
+    // |route|: Description of the established route.

[xhwang, 2015/04/02 17:13:02]

Can |route| be Empty()? In that case, is "a route has been established" still
accurate?

[imcheng, 2015/04/02 23:05:23]

Since the "emtpy MediaRoute" has been reverted, it can no longer be
empty/invalid.

+    virtual void OnRouteResponseReceived(const RouteRequestId& request_id,
+                                         const MediaRoute& route) = 0;
+
+    // Called when an error occurred while establishing a route.
+    // |request_id|: ID of original request.
+    // |error_text|: Text describing the error.
+    virtual void OnRouteResponseError(const RouteRequestId& request_id,
+                                      const std::string& error_text) = 0;
+
+    // Called when the list of currently MediaRoutes and their MediaSinks
+    // has been updated.
+    // |routes|: List of MediaRoutes.
+    // |sinks|: List of MediaSinks associated with the routes.
+    virtual void OnRoutesUpdated(
+        const std::vector<MediaRoute>& routes,
+        const std::vector<MediaSink>& sinks) = 0;
+
+    // Called when the MRPMHost is being destroyed.
+    virtual void OnHostDestroyed(MediaRouteProviderManagerHost* host) = 0;
+  };
+
+  // The following API allows the media router to send commands to the MRPM.

[xhwang, 2015/04/02 17:13:02]

s/API allows/APIs allow/

[imcheng, 2015/04/02 23:05:23]

Done.

+
+  // Instructs MRPM to start a query for compatible media sinks for |source|.
+  // Results from the query and subsequent updates will be received via
+  // |Delegate::OnSinksReceived| until the query is removed from MRPM
+  // via |RemoveMediaSinksQuery|.
+  virtual void AddMediaSinksQuery(const MediaSource& source) = 0;

[xhwang, 2015/04/02 17:13:02]

Can we replace OnSinksReceived() with a callback here? Then in the callback you
don't need to pass |source| as you are doing in OnSinksReceived().

[imcheng, 2015/04/02 23:05:24]

We considered using callbacks here. But since AddMediaSinksQuery and
OnSinksReceived aren't 1:1 (OnSinksReceived will be called multiple times as
updates come in), I feel OnSinksReceived() is more explicit in expressing the
relationship.

[xhwang, 2015/04/06 20:51:29]

Acknowledged.

+
+  // Instructs MRPM to stop a query for compatible media sinks for |source|.
+  virtual void RemoveMediaSinksQuery(const MediaSource& source) = 0;
+
+  // Requests MRPM to establish a route between |source| and a media sink given
+  // by |sink_id|. |request_id| is generated by Media Router and passed
+  // to MRPM to identify the request.
+  virtual void RequestRoute(const RouteRequestId& request_id,

[xhwang, 2015/04/02 17:13:02]

Will the response be either OnRouteResponseReceived() or OnRouteResponseError()?
If so, update the comment to make it clear.

Can you have multiple pending RequestRoute() calls?

Is it viable to use a response callback instead of the Delegate() call?

[imcheng, 2015/04/02 23:05:23]

Updated comment. I think that this is a place where it might be fine to use a
callback, but since this call is async, it does require the implementation to
keep track of the callbacks. Perhaps we could revisit this we upstream the
implementation?

[xhwang, 2015/04/06 20:51:29]

Acknowledged.

+                            const MediaSource& source,
+                            const MediaSinkId& sink_id) = 0;
+
+  // Requests MRPM to close a route specified by |route_id|.
+  virtual void CloseRoute(const MediaRouteId& route_id) = 0;
+
+  // Requests MRPM to post |message| to a MediaSink connected by MediaRoute
+  // with |route_id|.
+  virtual void PostMessage(const MediaRouteId& route_id,
+                           const std::string& message) = 0;
+
+  // Requests MRPM to send updates on all MediaRoutes and their MediaSinks.
+  // The updated lists will be received via
+  // |Delegate::OnActiveSinksAndRoutesReceived|.

[xhwang, 2015/04/02 17:13:02]

This doesn't exist...

[imcheng, 2015/04/02 23:05:23]

Updated comment.

+  virtual void StartMediaRoutesQuery() = 0;
+
+  // Requests MRPM to stop sending updates on MediaRoutes.
+  virtual void StopMediaRoutesQuery() = 0;

[xhwang, 2015/04/02 17:13:02]

I am confused by Query vs Update...

[imcheng, 2015/04/02 23:05:24]

Changed the comment here to match AddMediaSinksQuery. Both types of queries are
continuous, i.e. once Start is called, results can be received multiple times if
there are updates, until Stop is called.

+};
+
+}  // namespace media_router
+
+#endif  // CHROME_BROWSER_MEDIA_ROUTER_MEDIA_ROUTE_PROVIDER_MANAGER_HOST_H_