[Presentation API] 1-UA presentation support + presenter APIs.

chrome/browser/media/router/offscreen_presentation_manager.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_OFFSCREEN_PRESENTATION_MANAGER_H_
+#define CHROME_BROWSER_MEDIA_ROUTER_OFFSCREEN_PRESENTATION_MANAGER_H_
+
+#include <map>
+#include <string>
+#include <vector>
+
+#include "base/containers/scoped_ptr_map.h"
+#include "base/macros.h"
+#include "chrome/browser/media/router/render_frame_host_helper.h"
+#include "components/keyed_service/core/keyed_service.h"
+#include "content/public/browser/presentation_service_delegate.h"
+#include "content/public/browser/presentation_session.h"
+
+namespace content {
+class BrowserContext;
+class WebContents;
+}
+
+namespace media_router {
+
+class OffscreenPresentationManager;
+
+// Exposes APIs to get presentation receiver sessions and operate on receiver

[miu, 2015/09/27 00:22:08]

IMO, this class should be deleted.  It adds too little functional value to
justify the extra indirection (and extra 100+ LOC).  FWICT,
ReceiverPresentationServiceDelegateImpl should just call methods of the
OffscreenPresentationManager directly.

[imcheng, 2015/09/30 01:13:41]

Done.

+// sessions for an offscreen presentation given by |presentation_id_| hosted in
+// an offscreen tab given by |presenter_web_contents_|.
+// Obtained by calling |OffscreenPresentationManager::RegisterPresenterTab|.
+// When this class is destroyed, all presentation receiver sessions will
+// be removed from its OffscreenPresentationManager.
+// This class must not outlive OffscreenPresentationManager or
+// |presenter_web_contents_|.
+class OffscreenPresenterContext {
+ public:
+  ~OffscreenPresenterContext();
+
+  void GetPresentationReceiverSession(

[miu, 2015/09/27 00:22:08]

These two methods have almost the exact same name, and also seem to differ a lot
in behavior (an async callback versus a sync return value).  Why is that? 
Should their names be more different to reflect their major differences?  How
about some comments explaining what they do and how they are meant to be used?

[imcheng, 2015/09/30 01:13:41]

I have removed these functions from here. I will document their behaviors in
PresentationServiceDelegate.

+      const RenderFrameHostId& frame_id,
+      const content::PresentationReceiverSessionAvailableCallback&
+          success_callback,
+      const base::Callback<void(const std::string&)>& error_callback);
+  std::vector<content::PresentationSessionInfo> GetPresentationReceiverSessions(
+      const RenderFrameHostId& frame_id) const;
+
+  bool IsPresenterFrame(const RenderFrameHostId& frame_id) const;
+
+  void SendMessage(const RenderFrameHostId& frame_id,
+                   const content::PresentationSessionInfo& session,
+                   scoped_ptr<content::PresentationSessionMessage> message,
+                   const content::SendMessageCallback& callback);
+  void ListenForMessages(
+      const RenderFrameHostId& frame_id,
+      const content::PresentationSessionInfo& session,
+      const content::PresentationSessionMessageCallback& callback);
+  void ListenForStateChanges(
+      const RenderFrameHostId& frame_id,
+      content::PresentationSessionStateListener* listener);
+
+ private:
+  friend class OffscreenPresentationManager;
+
+  OffscreenPresenterContext(content::WebContents* presenter_web_contents,
+                            const std::string& presentation_id,
+                            OffscreenPresentationManager* manager);
+
+  content::WebContents* const presenter_web_contents_;
+  const std::string presentation_id_;
+
+  // Calls are delegated to manager.
+  OffscreenPresentationManager* const manager_;
+
+  DISALLOW_COPY_AND_ASSIGN(OffscreenPresenterContext);
+};
+
+// Exposes APIs to operate on a single controller session for an offscreen

[miu, 2015/09/27 00:22:08]

This class doesn't expose APIs.  It declares public methods, and it's redundant
to say that.  ;-)

[imcheng, 2015/09/30 01:13:41]

Updated comment.

+// presentation given by |session|_ in a frame given by |controller_frame_id_|.
+// Obtained by calling |OffscreenPresentationManager::RegisterController|.
+// When this class is destroyed, the controller session will be removed from
+// its OffscreenPresentationManager.
+// This class must not outlive OffscreenPresentationManager or the
+// RenderFrameHost of |controller_frame_id|.
+class OffscreenController {

[miu, 2015/09/27 00:22:08]

This class doesn't include any control logic.  It's a facade class, providing
messaging capability to/from an off-screen tab.  Consider re-naming it to
something like OffscreenTabPresentation, and adjusting comments and naming
around that.

(The PresenterFrame that uses this class would have the role of the "controller"
here.)

[imcheng, 2015/09/30 01:13:41]

As discussed offline yesterday, I have reworked this class to give it more role
of handling the callbacks by shifting the logic from
OffscreenPresentationManager to this class.

+ public:
+  ~OffscreenController();
+
+  void SendMessage(scoped_ptr<content::PresentationSessionMessage> message,
+                   const content::SendMessageCallback& callback);
+  void ListenForMessages(
+      const content::PresentationSessionMessageCallback& callback);
+  void ListenForStateChanges(
+      content::PresentationSessionStateListener* listener);
+
+ private:
+  friend class OffscreenPresentationManager;
+
+  OffscreenController(const RenderFrameHostId& controller_frame_id,
+                      const content::PresentationSessionInfo& session,
+                      OffscreenPresentationManager* manager);
+
+  const RenderFrameHostId controller_frame_id_;
+  const content::PresentationSessionInfo session_;
+
+  // Calls are delegated to manager.
+  OffscreenPresentationManager* const manager_;
+
+  DISALLOW_COPY_AND_ASSIGN(OffscreenController);
+};
+
+class OffscreenPresentationManager : public KeyedService {

[miu, 2015/09/27 00:22:08]

Naming: "Manager" is so abstract.  How about "OffscreenTabMessageExchanger" or
something to that effect?

[imcheng, 2015/09/30 01:13:42]

Not sure if it's a better name, since message exchange don't happen directly in
this class anymore. Now that this class is mostly bookkeeping and coordination
between controllers and receiver, how about OffscreenPresentationRegistry?

+ public:
+  ~OffscreenPresentationManager() override;
+
+  // Registers the presenter of a offscreen presentation given by
+  // |presentation_id|
+  // as the main frame of tab given by |presenter_web_contents|.
+  // Only 1 presenter may be registered for a given presentation.
+  // A given WebContents can be a presenter for at most one presentation.
+  void RegisterPresenterTab(const std::string& presentation_id,
+                            content::WebContents* presenter_web_contents);
+  void UnregisterPresenterTab(content::WebContents* presenter_web_contents);
+
+  // Returns an OffscreenPresenterContext that can be used to operate on
+  // presenter
+  // session objects on tab |presenter_web_contents| that have been connected
+  // to their corresponding controllers.
+  scoped_ptr<OffscreenPresenterContext> GetOffscreenPresenterContext(
+      content::WebContents* presenter_web_contents);
+
+  // Registers a controller of a offscreen presentation given by
+  // |presentation_id|
+  // as the frame given by |controller_frame_id|.
+  // Note that each presentation may have multiple controller frames, and that
+  // a frame may be a controller for multiple presentations.
+  // Returns a OffscreenController object that can be used to operate
+  // on the registered controller of the offscreen presentation.
+  scoped_ptr<OffscreenController> RegisterController(
+      const content::PresentationSessionInfo& session,
+      const RenderFrameHostId& controller_frame_id);
+
+ private:
+  friend class OffscreenPresenterContext;
+  friend class OffscreenController;
+
+ private:
+  friend class OffscreenPresentationManagerFactory;
+
+  // Represents a presentation session object. Contains information on the
+  // session object, including callbacks to be invoked for messages and state
+  // changes (which comes from the other side of the controller/presenter).
+  struct OffscreenPresentationSessionInfo {

[miu, 2015/09/27 00:22:08]

Consider merging this into OffscreenController.  This will require you to change
the ownership semantics around OffscreenController (e.g., RegisterController
might return a WeakPtr<OffscreenController> instead), but will result in fewer
moving parts and simpler code.

[imcheng, 2015/09/30 01:13:41]

I have moved the callback and listener fields what used to be known as
OffscreenController, which is now a RAII-ish class created by
OffscreenPresentationManager and owned by the PresentationServiceDelegate
implementations.

+    OffscreenPresentationSessionInfo(
+        const RenderFrameHostId& controller_frame_id,
+        const content::PresentationSessionInfo& session);
+    ~OffscreenPresentationSessionInfo();
+
+    const RenderFrameHostId controller_frame_id;
+    const content::PresentationSessionInfo session;
+    content::PresentationSessionMessageCallback message_callback;
+    content::PresentationSessionStateListener* state_change_listener;
+  };
+
+  // Represents a connection between a controller and the presentation.
+  // Contains the controller session object in the controller frame, and its
+  // corresponding presenter session object proxy in the presenter frame.
+  struct OffscreenPresentationRoute {

[miu, 2015/09/27 00:22:08]

Suggestion: Delete this class, and move |presenter| and |controller| into the
struct below.

[imcheng, 2015/09/30 01:13:42]

I have added support for multiple controllers for offscreen presentations in
this class. We will have multiple OffscreenPresentationRoutes in what used to be
known as OffscreenPresentationInfo. 

+    OffscreenPresentationRoute();
+    ~OffscreenPresentationRoute();
+
+    scoped_ptr<OffscreenPresentationSessionInfo> presenter;
+    scoped_ptr<OffscreenPresentationSessionInfo> controller;
+  };
+
+  // Represents a offscreen presentation.
+  // Contains information on the presenter frame, as well as list of controllers
+  // currently connected to presentation.
+  struct OffscreenPresentationInfo {

[miu, 2015/09/27 00:22:08]

naming: "Info" isn't accurate.

[imcheng, 2015/09/30 01:13:42]

Renamed to OffscreenPresentation.

+    OffscreenPresentationInfo();
+    ~OffscreenPresentationInfo();
+    bool IsEmpty() const;

[miu, 2015/09/27 00:22:08]

naming: How about HasRoutedPeers()?  (This suggestion inverts the boolean.)

[imcheng, 2015/09/30 01:13:41]

Removed function.

+
+    RenderFrameHostId presenter_frame_id;
+
+    // Callback for getSession(). Must be made from |presenter_frame|.
+    content::PresentationReceiverSessionAvailableCallback session_callback;
+
+    // TODO(imcheng): Support multiple controllers.
+    OffscreenPresentationRoute route;
+  };
+
+  // Used by OffscreenPresentationManagerFactory::GetOrCreateForBrowserContext.
+  OffscreenPresentationManager();
+
+  void UnregisterController(const RenderFrameHostId& controller_frame_id,
+                            const std::string& presentation_id);
+
+  // Presenting API - must be a presenter frame to call.
+  // Obtains a presenter-side PresentationSessionInfo object that represents a
+  // proxy to its corresponding controller for the presentation session with
+  // presenter frame given by |presenter_frame_id|.
+  // |callback| will be invoked with the object once a controller has
+  // registered itself with the presentation.
+  void GetReceiverSession(
+      const RenderFrameHostId& presenter_frame_id,
+      const content::PresentationReceiverSessionAvailableCallback& callback);
+
+  // TODO(imcheng): Support getSessions() once we can support multiple
+  // controllers. Currently we have no mechanism to distinguish one controller
+  // from another.
+  // Gets a list of presenter-side PresentationSessionInfo objects that
+  // represent proxies to their corresponding controllers for the presentation
+  // session with presenter frame given by |presenter_frame_id|.
+  std::vector<content::PresentationSessionInfo> GetPresentationReceiverSessions(
+      const RenderFrameHostId& presenter_frame_id) const;
+
+  // Messaging - may be called by either presenter or controller frames.
+  void SendMessage(const content::PresentationSessionInfo& session,
+                   scoped_ptr<content::PresentationSessionMessage> message,
+                   const content::SendMessageCallback& callback);
+  void ListenForMessages(
+      const content::PresentationSessionInfo& session,
+      const content::PresentationSessionMessageCallback& callback);
+
+  // State changes - may be called by either presenter or controller frames.
+  void ListenForStateChanges(
+      content::PresentationSessionStateListener* listener);
+
+  // Remove the presenter/controller side from |presentation_info| and notify
+  // the other party of state change to "disconnected".
+  void RemovePresenterAndNotifyStateChange(
+      OffscreenPresentationInfo* presentation_info);
+  void RemoveControllerAndNotifyStateChange(
+      OffscreenPresentationInfo* presentation_info,
+      const RenderFrameHostId& controller_frame_id);
+
+  OffscreenPresentationInfo* GetOrCreateOffscreenPresentationInfo(
+      const std::string& presentation_id);
+  OffscreenPresentationInfo* GetOffscreenPresentationInfo(
+      const std::string& presentation_id) const;
+
+  // Maps from presentation ID to OffscreenPresentationInfo.
+  base::ScopedPtrMap<std::string, scoped_ptr<OffscreenPresentationInfo>>
+      offscreen_presentation_infos_;
+
+  // Maps from presenter frame ID to presentation ID.
+  std::map<RenderFrameHostId, std::string> presenter_frames_;
+
+  DISALLOW_COPY_AND_ASSIGN(OffscreenPresentationManager);
+};
+
+}  // namespace media_router
+
+#endif  // CHROME_BROWSER_MEDIA_ROUTER_OFFSCREEN_PRESENTATION_MANAGER_H_