chrome/browser/media/router/media_router.h

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef CHROME_BROWSER_MEDIA_ROUTER_MEDIA_ROUTER_H_
   6 #define CHROME_BROWSER_MEDIA_ROUTER_MEDIA_ROUTER_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "base/callback.h"
  12 #include "chrome/browser/media/router/issue.h"
  13 #include "chrome/browser/media/router/media_route.h"
  14 #include "chrome/browser/media/router/media_sink.h"
  15 #include "chrome/browser/media/router/media_source.h"
  16 #include "content/public/browser/presentation_session_message.h"
  17
  18 namespace media_router {
  19
  20 class IssuesObserver;
  21 class MediaRoutesObserver;
  22 class MediaSinksObserver;
  23
  24 // Type of callback used in |CreateRoute()|. Callback is invoked when the
  25 // route request either succeeded or failed.
  26 // The first argument is the route created. If the route request failed, this
  27 // will be a nullptr.
  28 // The second argument is the error string, which will be nonempty if the route
  29 // request failed.
  30 using MediaRouteResponseCallback =
  31     base::Callback<void(scoped_ptr<MediaRoute>, const std::string&)>;
  32
  33 // Used in cases where a tab ID is not applicable in CreateRoute/JoinRoute.
  34 const int kInvalidTabId = -1;
  35
  36 // An interface for handling resources related to media routing.
  37 // Responsible for registering observers for receiving sink availability
  38 // updates, handling route requests/responses, and operating on routes (e.g.
  39 // posting messages or closing).
  40 class MediaRouter {
  41  public:
  42   using PresentationSessionMessageCallback = base::Callback<void(
  43       scoped_ptr<ScopedVector<content::PresentationSessionMessage>>)>;
  44   using SendRouteMessageCallback = base::Callback<void(bool sent)>;
  45
  46   virtual ~MediaRouter() {}
  47
  48   // Creates a media route from |source_id| to |sink_id|.
  49   // |origin| is the URL of requestor's page.
  50   // |tab_id| is the ID of the tab in which the request was made.
  51   // |origin| and |tab_id| are used for enforcing same-origin and/or same-tab
  52   // scope for JoinRoute() requests. (e.g., if enforced, the page
  53   // requesting JoinRoute() must have the same origin as the page that requested
  54   // CreateRoute()).
  55   // The caller may pass in|kInvalidTabId| if tab is not applicable.
  56   // |callback| is invoked with a response indicating success or failure.
  57   virtual void CreateRoute(const MediaSource::Id& source_id,
  58                            const MediaSink::Id& sink_id,
  59                            const GURL& origin,
  60                            int tab_id,
  61                            const MediaRouteResponseCallback& callback) = 0;
  62
  63   // Joins an existing route identified by |presentation_id|.
  64   // |source|: The source to route to the existing route.
  65   // |presentation_id|: Presentation ID of the existing route.
  66   // |origin|, |tab_id|: Origin and tab of the join route request. Used for
  67   // validation when enforcing same-origin and/or same-tab scope.
  68   // (See CreateRoute documentation).
  69   // |callback| is invoked with a response indicating success or failure.
  70   virtual void JoinRoute(const MediaSource::Id& source,
  71                          const std::string& presentation_id,
  72                          const GURL& origin,
  73                          int tab_id,
  74                          const MediaRouteResponseCallback& callback) = 0;
  75
  76   // Closes the media route specified by |route_id|.
  77   virtual void CloseRoute(const MediaRoute::Id& route_id) = 0;
  78
  79   // Posts |message| to a MediaSink connected via MediaRoute with |route_id|.
  80   // TODO(imcheng): Support additional data types: Blob, ArrayBuffer,
  81   // ArrayBufferView.
  82   virtual void SendRouteMessage(const MediaRoute::Id& route_id,
  83                                 const std::string& message,
  84                                 const SendRouteMessageCallback& callback) = 0;
  85
  86   // Gets the next batch of messages from one of the routes in |route_ids|.
  87   // |message_cb|: Invoked with a non-empty list of messages when there are
  88   //      messages, an empty list when messaging channel had error.
  89   //      It is not invoked until there are messages available or error.
  90   virtual void ListenForRouteMessages(
  91       const std::vector<MediaRoute::Id>& route_ids,
  92       const PresentationSessionMessageCallback& message_cb) = 0;
  93
  94   // Clears the issue with the id |issue_id|.
  95   virtual void ClearIssue(const Issue::Id& issue_id) = 0;
  96
  97  private:
  98   friend class IssuesObserver;
  99   friend class MediaSinksObserver;
 100   friend class MediaRoutesObserver;
 101
 102   // The following functions are called by IssuesObserver, MediaSinksObserver,
 103   // and MediaRoutesObserver.
 104
 105   // Registers |observer| with this MediaRouter. |observer| specifies a media
 106   // source and will receive updates with media sinks that are compatible with
 107   // that source. The initial update may happen synchronously.
 108   // NOTE: This class does not assume ownership of |observer|. Callers must
 109   // manage |observer| and make sure |UnregisterObserver()| is called
 110   // before the observer is destroyed.
 111   // It is invalid to register the same observer more than once and will result
 112   // in undefined behavior.
 113   // If the MRPM Host is not available, the registration request will fail
 114   // immediately.
 115   virtual void RegisterMediaSinksObserver(MediaSinksObserver* observer) = 0;
 116
 117   // Removes a previously added MediaSinksObserver. |observer| will stop
 118   // receiving further updates.
 119   virtual void UnregisterMediaSinksObserver(MediaSinksObserver* observer) = 0;
 120
 121   // Adds a MediaRoutesObserver to listen for updates on MediaRoutes.
 122   // The initial update may happen synchronously.
 123   // MediaRouter does not own |observer|. |RemoveMediaRoutesObserver| should
 124   // be called before |observer| is destroyed.
 125   // It is invalid to register the same observer more than once and will result
 126   // in undefined behavior.
 127   virtual void RegisterMediaRoutesObserver(MediaRoutesObserver* observer) = 0;
 128
 129   // Removes a previously added MediaRoutesObserver. |observer| will stop
 130   // receiving further updates.
 131   virtual void UnregisterMediaRoutesObserver(MediaRoutesObserver* observer) = 0;
 132
 133   // Adds the IssuesObserver |observer|.
 134   // It is invalid to register the same observer more than once and will result
 135   // in undefined behavior.
 136   virtual void RegisterIssuesObserver(IssuesObserver* observer) = 0;
 137
 138   // Removes the IssuesObserver |observer|.
 139   virtual void UnregisterIssuesObserver(IssuesObserver* observer) = 0;
 140 };
 141
 142 }  // namespace media_router
 143
 144 #endif  // CHROME_BROWSER_MEDIA_ROUTER_MEDIA_ROUTER_H_