[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 tab that hosts an offscreen presentation

[mark a. foltz, 2015/10/01 18:39:12]

Nit: there's no "tab" per se just a WebContents container.

Also: There's no guarantee that the presentation has to outlive navigation. 
(The spec is vague on this.)

[imcheng, 2015/10/06 00:59:14]

Ok, I will replace "tab" with "WebContents".

Regarding navigation, that is my understanding as well. The current
implementation is that controllers will be disconnected if receiver navigates
with a chance to reconnect.

+// (AKA the receiver tab) and the frames that start/connect and control the
+// presentation (AKA the controller frames). Coordinates the (un)registration
+// of receiver tabs 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 tab is created to host the offscreen presentation and registers

[mark a. foltz, 2015/10/01 18:39:13]

It's not clear how the receiver WebContents is used in the example below.
The example is just registering a presentation_id.

[imcheng, 2015/10/06 00:59:14]

Actually, the receiver side of OPM is not necessarily tied to WebContents. It
just so happens for offscreen tabs that it is. I will just refer to them as
"receivers".

+// itself so that controller frames can connect to it:
+//
+//   OffscreenPresentationManager* manager =
+//       OffscreenPresentationManagerFactory::GetOrCreateForBrowserContext(
+//           context);
+//   manager->RegisterOffscreenPresentationReceiver(presentation_id,
+//       &base::Bind(&OnSessionAvailable));
+//   ...
+//   void OnSessionAvailable(

[mark a. foltz, 2015/10/01 18:39:12]

Can this be called more than once as additional controllers are connected?

[imcheng, 2015/10/06 00:59:14]

Yes. In fact this provides a pretty straightforward implementation of
onsessionavailable.

+//       scoped_ptr<OffscreenPresentationSession> receiver_session) {
+//     [Calls methods in |receiver_session| to send/receive messages, etc.]
+//   }
+//
+// 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 tab).
+// Note calling this will trigger |OnSessionAvailable| on the receiver side.
+//
+//   scoped_ptr<OffscreenPresentationSession> controller_session =

[mark a. foltz, 2015/10/01 18:39:12]

The comments should make it clear that the OPS is used by the receiver
WebContents; the controller WebContents already has created a
PresentationSession for the connection (represented by |session_info| I assume)

[imcheng, 2015/10/06 00:59:14]

For symmetry, Controllers also use OffscrenPresentationSession to communicate
with receiver and they are created by calling this function. I've updated
comments here so the function only takes a presentation id and frame id.

PresentationSessionInfo is just a POD. It only contains presentation url and id.

+//       manager->CreateOffscreenPresentationConnection(
+//           session_info, 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.
+//
+// Receiver tab is no longer associated with an offscreen presentation.
+// This will prevent additional controllers from establishing a connection with
+// the receiver tab:
+//
+//   manager->UnregisterOffscreenPresentationReceiver(presentation_id);

[mark a. foltz, 2015/10/01 18:39:13]

This would be called in response to PresentationSession.terminate(), or a
request by the user or the MRP to kill the associated route.

I would imagine that the manager would also observe the WebContents and
unregister the presentation on window.close() or navigation.

[imcheng, 2015/10/06 00:59:14]

Correct. Right now this is called on ~ReceiverPresentationServiceDelegate, which
is called when receiver WebContents is being destroyed.

+//

[mark a. foltz, 2015/10/01 18:39:12]

Threading constraints need to be discussed somewhere in here.

[imcheng, 2015/10/06 00:59:14]

Done.

+class OffscreenPresentationManager : public KeyedService {
+ private:
+  // Forward declarations for OffscreenPresentationSession.
+  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

[mark a. foltz, 2015/10/01 18:39:12]

Does the manager keep track of the live sessions/presentations?
Will the manager live forever once created, or can it be destroyed and
re-created on demand?

[imcheng, 2015/10/06 00:59:14]

Since it is a KeyedService, it will live for as long as the BrowserContext once
created.

+  // 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(
+        content::PresentationSessionStateListener* listener);
+
+   private:
+    friend class OffscreenPresentation;
+    friend class OffscreenPresentationConnection;
+
+    OffscreenPresentationSession(bool is_controller,
+                                 OffscreenPresentationConnection* connection);
+    void OnSessionStateChanged(content::PresentationSessionState state);
+    void OnMessageReceived(scoped_ptr<content::PresentationSessionMessage>);
+
+    const bool is_controller_;
+    OffscreenPresentationConnection* const connection_;
+    content::PresentationSessionMessageCallback messages_callback_;
+    content::PresentationSessionStateListener* 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.

[mark a. foltz, 2015/10/01 18:39:12]

What happens to pending callbacks passed into Register*Receiver()?

[imcheng, 2015/10/06 00:59:14]

The callback will be removed from this class. I will add comments stating that.

+  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,
+  // |receiver_available_callback_| will be invoked with a
+  // OffscreenPresentationSession object representing the receiver side of the
+  // connection.
+  scoped_ptr<OffscreenPresentationSession>
+  CreateOffscreenPresentationConnection(

[mark a. foltz, 2015/10/01 18:39:12]

Nit: Might name this ConnectToOffscreenPresentation to lead with the verb.

[imcheng, 2015/10/06 00:59:14]

Done.

+      const std::string& presentation_id,
+      const RenderFrameHostId& controller_frame_id);

[mark a. foltz, 2015/10/01 18:39:13]

It seems a little asymmetrical for the controller to be able to connect
synchronously, while the receiver must pass a callback.

What state is the session in when it is returned?

[imcheng, 2015/10/06 00:59:14]

Yes, this is also how presentation.receiver API works (i.e., it has to wait for
sessions to be available)? Nevertheless, I tried to address this by making sure
controllers and receiver use the same OffscreenPresentationSession API to talk
to each other.

The state will be connected.

+
+ 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(bool is_controller);

[mark a. foltz, 2015/10/01 18:39:12]

What does is_controller mean?  Does this mean the caller is a controller or it's
trying to remove a session created by a controller?


In general I prefer APIs that are explicit instead of using boolean flags, so
instead:

RemoveControllerSession()
RemoveReceiverSession()

[imcheng, 2015/10/06 00:59:14]

Done.

+    void SendMessage(bool is_controller,

[mark a. foltz, 2015/10/01 18:39:13]

SendMessageToController()
SendMessageToReceiver()

What would happen if a controller called this with is_controller = false?

[imcheng, 2015/10/06 00:59:14]

Done.
 
Then it will send a message to itself. We could add DCHECK to make sure it
doesn't happen. But IMO it's not a major issue since this is only used
internally.

+                     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.

[mark a. foltz, 2015/10/01 18:39:13]

Destruction of either would seem to require that this is also destroyed,
otherwise, one end of the connection is dangling and that doesn't seem useful.

What enforces that?

[imcheng, 2015/10/06 00:59:14]

Currently, this will be destroyed once both sessions become nullptr. To change
it so it's destroyed when either one becomes nullptr, we just have to invalidate
the other session's pointer to this class, and make the SendMessage failure
logic to that class. 

+    OffscreenPresentationSession* controller_;
+    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

[mark a. foltz, 2015/10/01 18:39:13]

Called only once, or once per connected controller?

[imcheng, 2015/10/06 00:59:14]

Once per connected controller.

+  // established from a controller.
+  class OffscreenPresentation {
+   public:
+    OffscreenPresentation(
+        const std::string& presentation_id,
+        const ReceiverSessionAvailableCallback& receiver_available_callback,
+        OffscreenPresentationManager* manager);
+    ~OffscreenPresentation();
+
+    scoped_ptr<OffscreenPresentationSession> AddConnectionAndNotifyReceiver(

[mark a. foltz, 2015/10/01 18:39:12]

Is this called when a new controller connects?
Maybe OnControllerConnected()

[imcheng, 2015/10/06 00:59:14]

I want to keep name as AddConnection() so there's a symmetry with
RemoveConnection().

+        const RenderFrameHostId& controller_frame_id);
+    void OnReceiverDetached();

[mark a. foltz, 2015/10/01 18:39:12]

What is a "detached" receiver?  Do you mean controller?

Maybe OnControllerDisconnected()?

[imcheng, 2015/10/06 00:59:14]

No, this is called when the receiver unregisters. Actually now that we destroy
the connection when either controller or receiver is gone, we don't need this
method anymore as long as the receiver destroys all of its session objects
before calling unregister, which is the case now.

+
+    bool IsReceiverGone() const {
+      return receiver_available_callback_.is_null();
+    }
+
+   private:
+    friend class OffscreenPresentationConnection;
+
+    void RemoveConnection(const RenderFrameHostId& controller_frame_id);
+    void MaybeSelfDestruct();
+
+    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();
+
+  void RemovePresentation(const std::string& presentation_id);
+
+  // Maps from presentation ID to OffscreenPresentation.
+  base::ScopedPtrMap<std::string, scoped_ptr<OffscreenPresentation>>
+      offscreen_presentations_;
+
+  DISALLOW_COPY_AND_ASSIGN(OffscreenPresentationManager);
+};
+
+}  // namespace media_router
+
+#endif  // CHROME_BROWSER_MEDIA_ROUTER_OFFSCREEN_PRESENTATION_MANAGER_H_