Non-Local Join for Media Router and Presentation API

chrome/browser/media/router/media_router.mojom

 // 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.
 
 module media_router.interfaces;
 
 // Represents an output sink to which media can be routed.
 struct MediaSink {
   enum IconType {
     CAST,
@@ skipping 125 matching lines @@
   // (See CreateRoute for additional documentation)
   // If the operation was successful, |route| will be defined and
   //     |error_text| will be null.
   // If the operation failed, |route| will be null and |error_text|
   //     will be set.
   JoinRoute(string media_source,
             string presentation_id,
             string origin,
             int32 tab_id) => (MediaRoute? route, string? error_text);
 
+  // Joins an established route given by |route_id| with
+  // |media_source|.
+  // |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.
+  // If the operation failed, |route| will be null and |error_text|
+  //     will be set.
+  ConnectRouteByRouteId(string media_source,
+                        string route_id,
+                        string presentation_id,

[mark a. foltz, 2015/12/16 07:17:34]

Why does the mojo interface take a presentation id while the MediaRouter does
not?
It looks like you are generating a GUID and passing it in.  Is it used by the
MRPM or can it be removed? 

[matt.boetger, 2015/12/18 23:37:15]

It's the same reason CreateRoute is creating a presentation ID.  With a
non-local join, a presentation session does not actually exist yet, and thus to
make sense within the framework, a presentation ID needs to be generated.  This
presentation ID is passed back to to the MediaRouteResponseCallbacks the same
way CreateRoute does.

+                        string origin,
+                        int32 tab_id) =>
+                            (MediaRoute? route, string? error_text);
+
   // Closes the route specified by |route_id|.
   CloseRoute(string route_id);
 
   // Sends |message| via the media route |media_route_id|.
   // If the operation was successful, |sent| is true; otherwise it is false.
   SendRouteMessage(string media_route_id, string message) => (bool sent);
 
   // Sends |data| via the media route |media_route_id|.
   // If the operation was successful, |sent| is true; otherwise it is false.
   SendRouteBinaryMessage(string media_route_id, array<uint8> data)
       => (bool sent);
 
   // Starts querying for sinks capable of displaying |media_source|.
   StartObservingMediaSinks(string media_source);
 
   // Stops querying sinks for |media_source|.
   StopObservingMediaSinks(string media_source);
 
   // Starts reporting the state of active media routes via
-  // OnRoutesUpdated(). Querying will continue until
-  // StopObservingMediaRoutes() is called.
-  StartObservingMediaRoutes();
+  // OnRoutesUpdated() in the context of the |media_source|.
+  // The |media_source| should be considered when returning joinable

[mark a. foltz, 2015/12/16 07:17:34]

What is the meaning of an empty media_source?

[imcheng, 2015/12/17 02:30:57]

+1. It would be good to document what is the purpose of |media_source| instead.

[matt.boetger, 2015/12/18 23:37:14]

Added an explanation in the comments.
Done.

[matt.boetger, 2015/12/18 23:37:14]

Done.

+  // routes in the OnRoutesUpdated() call.
+  // Querying will continue until StopObservingMediaRoutes is called with the
+  // same |media_source| (even if it's empty).
+  StartObservingMediaRoutes(string? media_source);
 
-  // Stops querying the state of all media routes.
-  StopObservingMediaRoutes();
+  // 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.
+  // Calling StopObservingMediaRoutes without a media_source will stop
+  // any media routes queries associated with emtpy strings.
+  StopObservingMediaRoutes(string? media_source);
 
   // Called when the MediaRouter is ready to get the next batch of messages
   // associated with |route_id|.
   // |messages| returned will contain the batch of messages.
   // |messages| will be empty if |StopListeningForRouteMessages| was invoked.
   // |error| indicates if a permanent error occurred. If true, then subsequent
   // calls will also return with |error| being true.
   ListenForRouteMessages(string route_id) =>
       (array<RouteMessage> messages, bool error);
 
@@ skipping 34 matching lines @@
   // process.
   RegisterMediaRouteProvider(MediaRouteProvider media_router_provider) =>
       (string instance_id);
 
   // Called when the Media Route Manager receives a new list of sinks.
   OnSinksReceived(string media_source, array<MediaSink> sinks);
 
   // 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(string media_source, array<MediaRoute> routes,
+      array<string> joinable_route_ids);
 
   // Called when the overall availability of media sinks has been updated.
   OnSinkAvailabilityUpdated(SinkAvailability availability);
 
   // Called when the state of presentation connected to route |route_id| has
   // changed to |state|.
   OnPresentationConnectionStateChanged(
       string route_id, PresentationConnectionState state);
 };