Non-Local Join for Media Router and Presentation API

chrome/browser/media/router/media_router.mojom

Index: chrome/browser/media/router/media_router.mojom
diff --git a/chrome/browser/media/router/media_router.mojom b/chrome/browser/media/router/media_router.mojom
index 060ad71b1f69f853c6ea283ef8df092b930838a8..1f9016d7258ed415b663ceac405d3b4e07826d78 100644
--- a/chrome/browser/media/router/media_router.mojom
+++ b/chrome/browser/media/router/media_router.mojom
@@ -143,6 +143,21 @@ interface MediaRouteProvider {
             string origin,
             int32 tab_id) => (MediaRoute? route, string? error_text);
 
+  // Connects an established route given by |route_id| with
+  // |media_source|.

[mark a. foltz, 2016/01/05 18:39:40]

Extra newline.

[matt.boetger, 2016/01/06 22:49:07]

Done.

+  // |origin| and |tab_id| are used for validating same-origin/tab scopes.
+  // (See CreateRoute for additional documentation)
+  // If the operation was successful, |route| will be defined and
+  //     |error_text| will be null.

[mark a. foltz, 2016/01/05 18:39:40]

Extra whitespace after //

[matt.boetger, 2016/01/06 22:49:07]

Done.

+  // If the operation failed, |route| will be null and |error_text|
+  //     will be set.

[mark a. foltz, 2016/01/05 18:39:40]

Ditto

[matt.boetger, 2016/01/06 22:49:07]

Done.

+  ConnectRouteByRouteId(string media_source,
+                        string route_id,
+                        string presentation_id,

[mark a. foltz, 2016/01/05 18:39:40]

Document use of |presentation_id|

[matt.boetger, 2016/01/06 22:49:07]

Done.

+                        string origin,
+                        int32 tab_id) =>
+                            (MediaRoute? route, string? error_text);
+
   // Closes the route specified by |route_id|.
   CloseRoute(string route_id);
 
@@ -162,12 +177,29 @@ interface MediaRouteProvider {
   StopObservingMediaSinks(string media_source);
 
   // Starts reporting the state of active media routes via
-  // OnRoutesUpdated(). Querying will continue until
-  // StopObservingMediaRoutes() is called.
-  StartObservingMediaRoutes();
-
-  // Stops querying the state of all media routes.
-  StopObservingMediaRoutes();
+  // |OnRoutesUpdated()| in the context of the |media_source|.  The
+  // |media_source| represents the application interested in the media
+  // routes (usually the web page from which the content originates).
+  // If no |media_source| is given, this should be considered a
+  // headless observer (e.g. a remote control) that has no interest in

[mark a. foltz, 2016/01/05 18:39:40]

maybe "this should be considered an observer that is not associated with a media
source, and thus cannot connect to a remote route showing a source."

[matt.boetger, 2016/01/06 22:49:07]

Done.

+  // joining a route.  The |media_source| should be considered when
+  // returning joinable routes in the |OnRoutesUpdated()| call. If an empty
+  // |media_source| is given, there is no context in which a joinable
+  // route makes sense and therefore, there should not be any joinable
+  // routes returned in |OnRoutesUpdated()|.  Querying will continue until
+  // |StopObservingMediaRoutes()| is called with the same
+  // |media_source| (even if it's an empty string).
+  StartObservingMediaRoutes(string media_source);
+
+  // Stops querying the state of all media routes in the context of
+  // the |media_source|.  |StartObservingMediaRoutes()| has
+  // to be called with the same |media_source| for this to have any effect even
+  // if it's emtpy.  Thus, |StartObservingMediaRoutes(media_source)| must be

[mark a. foltz, 2016/01/05 18:39:40]

typo in empty

[matt.boetger, 2016/01/06 22:49:07]

Done.

+  // matched with |StopObservingMediaRoutes(media_soruce)|.

[mark a. foltz, 2016/01/05 18:39:40]

typo in source

[matt.boetger, 2016/01/06 22:49:07]

Done.

+  // Calling |StopObservingMediaRoutes()| without a media_source will stop

[mark a. foltz, 2016/01/05 18:39:40]

The style I like is to use pipes around parameters but not function names, so
just |media_source| here and elsewhere.  The style guide doesn't seem to be
specific though.

[matt.boetger, 2016/01/06 22:49:07]

Done.

+  // any media routes queries associated with emtpy strings (queries
+  // that being with |StartObservingMediaRoutes()|).
+  StopObservingMediaRoutes(string media_source);
 
   // Called when the MediaRouter is ready to get the next batch of messages
   // associated with |route_id|.
@@ -222,8 +254,11 @@ interface MediaRouter {
   // Called when issues are reported for media routes.
   OnIssue(Issue issue);
 
-  // Called when list of routes has been updated.
-  OnRoutesUpdated(array<MediaRoute> routes);
+  // Called when list of routes has been updated in the context of the
+  // calling |media_source|.  The array |joinable_route_ids| should
+  // contain route IDs of joinable routes found in the |routes| array.
+  OnRoutesUpdated(array<MediaRoute> routes, string media_source,
+      array<string> joinable_route_ids);
 
   // Called when the overall availability of media sinks has been updated.
   OnSinkAvailabilityUpdated(SinkAvailability availability);