[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"
+
+namespace media_router {
+
+// Acts as an intermediary between the party that hosts an offscreen
+// presentation (AKA the receiver) and the render frames that start/connect and
+// control the presentation (AKA the controller frames). Coordinates the
+// (un)registration of receivers and controller frames in the context of an
+// offscreen presentation to enable the exchange of messages and notification
+// of state change to/from the other side.
+//
+// Example usage:
+//
+// Receiver is created to host the offscreen presentation and registers itself
+// so that controller frames can connect to it:
+//
+//   OffscreenPresentationManager* manager =
+//       OffscreenPresentationManagerFactory::GetOrCreateForBrowserContext(
+//           context);
+//   manager->RegisterOffscreenPresentationReceiver(presentation_id,
+//       base::Bind(&OnSessionAvailable));
+//   ...
+//   void OnSessionAvailable(
+//       scoped_ptr<OffscreenPresentationSession> receiver_session) {
+//     [Calls methods in |receiver_session| to send/receive messages, etc.]

[mark a. foltz, 2015/10/12 21:56:10]

Nitpick: I wouldn't expect this to happen in this callback, rather, it would
happen in different callbacks based on send() invocations.

Maybe instead:

[Retains |receiver_session| to send/receive messages in response to send()]

[imcheng, 2015/10/17 01:00:23]

Done.

+//   }
+//
+// Controller frame establishes connection with the receiver side, resulting
+// in a connection with the two endpoints being the controller session (given
+// to controller frame) and the receiver session (given to receiver). Note

[mark a. foltz, 2015/10/12 21:56:10]

To be clear, each controller <--> receiver relationship corresponds to exactly
one pair of OffscreenPresentationSessions (one for the controller, one for the
receiver)?

[imcheng, 2015/10/17 01:00:23]

Yes that's correct.

+// calling this will trigger |OnSessionAvailable| on the receiver side.
+//
+//   scoped_ptr<OffscreenPresentationSession> controller_session =
+//       manager->CreateOffscreenPresentationConnection(
+//           presentation_id, controller_frame_id);
+//   [Calls methods in |controller_session| to send/receive messages, etc.]
+//
+// A controller or receiver session leaves the offscreen presentation (e.g.,
+// due to navigation) by destroying the OffscreenPresentationSession object
+// returned by this class.
+//
+// When the receiver is no longer associated with an offscreen presentation, it

[mark a. foltz, 2015/10/12 21:56:10]

Which object is "the receiver" in this context?  It seems like this could be the
job of the OffscreenPresentationManager (by observing the offscreen
tab/WebContents)?

[imcheng, 2015/10/17 01:00:23]

The receiver is the party that called RegisterOffscreenPresentationReceiver
which in our case is ReceiverPresentationServiceDelegateImpl. As discussed in
person, since RPSDImpl's lifetime is tied to that of the offscreen tab's, it's
fairly easy for it to destroy all OffscreenPresentationSession objects and
unregister itself with OPM when the offscreen presentation is about to end.

+// shall destroy all outstanding sessions and then unregister itself with
+// OffscreenPresentationManager. Unregistration will prevent additional
+// controllers from establishing a connection with the receiver:
+//
+//   receiver_sessions.clear();

[mark a. foltz, 2015/10/12 21:56:10]

Where does the receiver get |receiver_sessions|?  From multiple invocations of
OnReceiverSession()?

[imcheng, 2015/10/17 01:00:23]

Yes. I added an example above using |receiver_sessions|.

+//   manager->UnregisterOffscreenPresentationReceiver(presentation_id);
+//
+// This class is not thread safe. All functions must be invoked on the UI
+// thread. All callbacks passed into this class will also be invoked on UI
+// thread.
+class OffscreenPresentationManager : public KeyedService {
+ private:
+  // Forward declarations for OffscreenPresentationSession.

[whywhat, 2015/10/13 15:21:30]

nit: I think this comment is redundant.

[imcheng, 2015/10/17 01:00:23]

I added it to justify the extra 'private:' portion here which usually does not
preceed 'public:'.

+  class OffscreenPresentationConnection;
+  class OffscreenPresentation;
+
+ public:
+  // RAII representation of either the controller or receiver endpoint of an
+  // offscreen presentation connection. Roughly corresponds to a
+  // PresentationSession object created as a result of
+  // PresentationRequest.start/reconnect (for controller) or
+  // navigator.presentation.receiver APIs (for receiver).
+  // Two instances, one representing the controller and other representing the
+  // receiver, are created and returned by OffscreenPresentationManager when
+  // |CreateOffscreenPresentationConnection| is called.
+  // The controller or receiver session may disconnect itself by destroying the
+  // instance.
+  // Instances must not outlive the OffscreenPresentationManager instance that
+  // created it.
+  class OffscreenPresentationSession {
+   public:
+    ~OffscreenPresentationSession();
+
+    // Sends |message| to the other endpoint of the connection.
+    // |callback| will be invoked with whether the message was sent.
+    void SendMessage(scoped_ptr<content::PresentationSessionMessage> message,
+                     const content::SendMessageCallback& callback);
+    // Listens for messages from the other endpoint of the connection.
+    // |callback| will be invoked with messages whenever there are messages.
+    void ListenForMessages(
+        const content::PresentationSessionMessageCallback& callback);
+    void ListenForStateChanges(

[whywhat, 2015/10/13 15:21:30]

nit: missed a comment for this method?

[imcheng, 2015/10/17 01:00:23]

Done.

+        content::PresentationSessionStateListener* listener);
+
+   private:
+    friend class OffscreenPresentation;
+    friend class OffscreenPresentationConnection;
+
+    explicit OffscreenPresentationSession(
+        OffscreenPresentationConnection* connection);
+    void OnSessionStateChanged(content::PresentationSessionState state);
+    void OnMessageReceived(scoped_ptr<content::PresentationSessionMessage>);
+
+    OffscreenPresentationConnection* connection_;
+    content::PresentationSessionMessageCallback messages_callback_;
+    content::PresentationSessionStateListener* state_change_listener_;

[whywhat, 2015/10/13 15:21:30]

nit: make it const pointer?

[imcheng, 2015/10/17 01:00:23]

It cannot be const since state_change_listener_ is set when
ListenForstateChanges is called. Also non-const methods are called on
state_change_listener_.

+
+    DISALLOW_COPY_AND_ASSIGN(OffscreenPresentationSession);
+  };
+
+  ~OffscreenPresentationManager() override;
+
+  using ReceiverSessionAvailableCallback =
+      base::Callback<void(scoped_ptr<OffscreenPresentationSession>)>;
+
+  // Registers an offscreen presentation given by |presentation_id|.
+  // Enables controller frames to call |CreateOffscreenPresentationConnection|
+  // with the same presentation ID to establish a connection with the receiver
+  // side of the presentation.
+  // Whenever a connection is established, |receiver_available_callback| will be
+  // invoked with a OffscreenPresentationSession that represents the receiver
+  // side of the resulting connection.
+  void RegisterOffscreenPresentationReceiver(
+      const std::string& presentation_id,
+      const ReceiverSessionAvailableCallback& receiver_available_callback);
+
+  // Unregisters a previously registered offscreen presentation. After this
+  // call, controller frames will no longer be able to establish connections
+  // to the presentation. The ReceiverSessionAvailableCallback previously
+  // registered will be removed and will no longer be invoked.
+  // NOTE: before this call can be made, all OffscreenPresentationSession
+  // owned by the receiver must be destroyed first.
+  void UnregisterOffscreenPresentationReceiver(
+      const std::string& presentation_id);
+
+  // Creates a connection to the receiver side of an offscreen presentation
+  // given by |presentation_id| registered with this instance, with the frame
+  // |controller_frame_id| as the controller side of the connection.
+  // Returns nullptr if the offscreen presentation is not already registered.
+  // Returns a OffscreenPresentationSession object representing the controller
+  // side of the resulting connection. In addition, the entity that has
+  // registered the receiver will have its ReceiverSessionAvailableCallback run
+  // to notify it that a new connection is now available.
+  scoped_ptr<OffscreenPresentationSession> ConnectToOffscreenPresentation(
+      const std::string& presentation_id,
+      const RenderFrameHostId& controller_frame_id);
+
+ private:
+  friend class OffscreenPresentationManagerFactory;
+
+  // Represents a connection between a controller session and a receiver session
+  // of an offscreen presentation and coordinates the exchange of information
+  // between them.
+  // Note that each offscreen presentation may contain multiple connections.
+  class OffscreenPresentationConnection {
+   public:
+    ~OffscreenPresentationConnection();
+    void RemoveSession(OffscreenPresentationSession* session);
+    void SendMessageFrom(
+        OffscreenPresentationSession* session,
+        scoped_ptr<content::PresentationSessionMessage> message,
+        const content::SendMessageCallback& callback);
+
+   private:
+    friend class OffscreenPresentation;
+    OffscreenPresentationConnection(
+        const RenderFrameHostId& controller_frame_id,
+        OffscreenPresentation* presentation);
+    void Init(OffscreenPresentationSession* controller,
+              OffscreenPresentationSession* receiver);
+
+    const RenderFrameHostId controller_frame_id_;
+    OffscreenPresentation* const presentation_;
+
+    // Not owned by this class.

[whywhat, 2015/10/13 15:21:30]

nit: Should this comment relate to the pointer above as well?

[whywhat, 2015/10/13 15:21:30]

nit: Should this comment relate to the pointer above as well?

[imcheng, 2015/10/17 01:00:23]

Done.

[imcheng, 2015/10/17 01:00:23]

Done.

+    OffscreenPresentationSession* controller_;

[whywhat, 2015/10/13 15:21:31]

nit: const pointers?

[imcheng, 2015/10/17 01:00:23]

They are non-const because they are set during Init(). This is due to a circular
reference between this class and OffscreenPresentationSession. See comments in
earlier PS.

+    OffscreenPresentationSession* receiver_;
+
+    DISALLOW_COPY_AND_ASSIGN(OffscreenPresentationConnection);
+  };
+
+  // Represents an offscreen presentation registered with
+  // OffscreenPresentationManager.
+  // Maintains set of connections to the presentation.
+  // Contains callback to the receiver to inform it of new connections
+  // established from a controller.
+  class OffscreenPresentation {
+   public:
+    OffscreenPresentation(
+        const std::string& presentation_id,
+        const ReceiverSessionAvailableCallback& receiver_available_callback,
+        OffscreenPresentationManager* manager);
+    ~OffscreenPresentation();
+
+    scoped_ptr<OffscreenPresentationSession> AddConnection(
+        const RenderFrameHostId& controller_frame_id);
+
+   private:
+    friend class OffscreenPresentationConnection;
+
+    void RemoveConnection(const RenderFrameHostId& controller_frame_id);
+
+    const std::string presentation_id_;
+    ReceiverSessionAvailableCallback receiver_available_callback_;
+    base::ScopedPtrMap<RenderFrameHostId,
+                       scoped_ptr<OffscreenPresentationConnection>>
+        connections_;
+    OffscreenPresentationManager* const manager_;
+
+    DISALLOW_COPY_AND_ASSIGN(OffscreenPresentation);
+  };
+
+  // Used by OffscreenPresentationManagerFactory::GetOrCreateForBrowserContext.
+  OffscreenPresentationManager();
+
+  // Maps from presentation ID to OffscreenPresentation.
+  base::ScopedPtrMap<std::string, scoped_ptr<OffscreenPresentation>>
+      offscreen_presentations_;
+
+  DISALLOW_COPY_AND_ASSIGN(OffscreenPresentationManager);
+};
+
+}  // namespace media_router

[whywhat, 2015/10/13 15:21:31]

nit: I know this is kind of the current style of the media/router codebase but
I'd prefer better separation between all the classes (there're four in one
header and worse in .cc). Could you at least separate the implementations in the
.cc file better (with a 80 char comment line and more line breaks?)

[imcheng, 2015/10/17 01:00:23]

Done. LGTY?

+
+#endif  // CHROME_BROWSER_MEDIA_ROUTER_OFFSCREEN_PRESENTATION_MANAGER_H_