[Media Router] Implement JoinRoute + update CreateRoute API.

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>
 
@@ skipping 11 matching lines @@
 
 // Type of callback used in |CreateRoute()|. Callback is invoked when the
 // route request either succeeded or failed.
 // The first argument is the route created. If the route request failed, this
 // will be a nullptr.
 // The second argument is the error string, which will be nonempty if the route
 // request failed.
 using MediaRouteResponseCallback =
     base::Callback<void(scoped_ptr<MediaRoute>, const std::string&)>;
 
+// Used in cases where a tab ID is not applicable in CreateRoute/JoinRoute.
+const int kInvalidTabId = -1;
+
 // 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() {}
 
   // Creates a media route from |source_id| to |sink_id|.
+  // |origin| and |tab_id| are used for enforcing same-origin and/or same-tab
+  // scope, and are optional.

[mark a. foltz, 2015/06/10 23:18:51]

Since this API is for creating a new route, it's a little confusing to say
"same-origin" or "same-tab" - same with respect to what other origin or tab?

IIUC these values are actually for the provider to enforce these constraints on
JoinRoute() requests.

Can you elaborate the documentation to clarify a bit?

[imcheng (use chromium acct), 2015/06/11 22:49:12]

Ok, I added some comments on the values of |origin| and |tab_id|. Also clarified
the join case with example.

+  // The caller may pass in empty GURL for |origin| and/or |kInvalidTabId| for
+  // |tab_id| if not enforcing same-origin and/or same-tab scope.

[mark a. foltz, 2015/06/10 23:18:51]

The caller doesn't know if the provider is going to enforce this or not - so
should they be mandatory?

[imcheng (use chromium acct), 2015/06/11 22:49:12]

Good point. We can make them mandatory. I left the option to pass -1 for tab_id
for the Chrome apps use case.

   // |callback| is invoked with a response indicating success or failure.
   virtual void CreateRoute(const MediaSource::Id& source_id,
                            const MediaSink::Id& sink_id,
+                           const GURL& origin,
+                           int tab_id,
                            const MediaRouteResponseCallback& callback) = 0;
 
+  // Joins an existing route identified by |presentation_id|.
+  // |source|: The source to route to the existing route.
+  // |presentation_id|: Presentation ID of the existing route.
+  // |origin|, |tab_id|: Origin and tab of the join route request. Used for
+  // validation when enforcing same-origin and/or same-tab scope, and
+  // are optional. (See CreateRoute documentation).

[mark a. foltz, 2015/06/10 23:18:51]

Similar comment about mandatory vs optional for origin, tab_id

[imcheng (use chromium acct), 2015/06/11 22:49:12]

Done.

+  // |callback| is invoked with a response indicating success or failure.
+  virtual void JoinRoute(const MediaSource::Id& source,
+                         const std::string& presentation_id,
+                         const GURL& origin,
+                         int tab_id,
+                         const MediaRouteResponseCallback& callback) = 0;
+
   // Closes the media route specified by |route_id|.
   virtual void CloseRoute(const MediaRoute::Id& 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 MediaRoute::Id& route_id,
                            const std::string& message) = 0;
 
   // Clears the issue with the id |issue_id|.
@@ skipping 50 matching lines @@
   // in undefined behavior.
   virtual void AddIssuesObserver(IssuesObserver* observer) = 0;
 
   // Removes the IssuesObserver |observer|.
   virtual void RemoveIssuesObserver(IssuesObserver* observer) = 0;
 };
 
 }  // namespace media_router
 
 #endif  // CHROME_BROWSER_MEDIA_ROUTER_MEDIA_ROUTER_H_