[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/macros.h"
+#include "chrome/browser/media/router/render_frame_host_id.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(&OnConnectionAvailable));
+//   ...
+//   void OnConnectionAvailable(
+//       std::unique_ptr<OffscreenPresentationConnection> receiver_connection) {
+//     [Retains |receiver_connection| to send/receive messages in response to
+//      send()]
+//     receiver_connection.push_back(std::move(receiver_connection));
+//   }
+//
+// Controller frame establishes connection with the receiver side, resulting
+// in a session with the two endpoints being the controller connection (given
+// to controller frame) and the receiver connection (given to receiver). Note
+// calling this will trigger |OnConnectionAvailable| on the receiver side.
+//
+//   std::unique_ptr<OffscreenPresentationConnection> controller_connection =
+//       manager->ConnectToOffscreenPresentation(
+//           presentation_id, controller_frame_id);
+//   [Calls methods in |controller_connection| to send/receive messages, etc.]
+//
+// A controller or receiver connection leaves the offscreen presentation (e.g.,
+// due to navigation) by destroying the OffscreenPresentationConnection object
+// returned by this class.
+//
+// When the receiver is no longer associated with an offscreen presentation, it
+// shall destroy all outstanding connections and then unregister itself with
+// OffscreenPresentationManager. Unregistration will prevent additional
+// controllers from establishing a connection with the receiver:
+//
+//   receiver_connections.clear();
+//   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 OffscreenPresentationConnection.
+  class OffscreenPresentationSession;
+  class OffscreenPresentation;
+
+ public:
+  // RAII representation of either the controller or receiver endpoint of an
+  // offscreen presentation connection. Roughly corresponds to a
+  // PresentationConnection 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
+  // |ConnectToOffscreenPresentation| is called.
+  // The controller or receiver connection may disconnect itself by destroying
+  // the instance.
+  // Instances must not outlive the OffscreenPresentationManager instance that
+  // created it.
+  class OffscreenPresentationConnection {
+   public:
+    ~OffscreenPresentationConnection();
+
+    // Sends |message| to the other endpoint of the connection.
+    // |callback| will be invoked with whether the message was sent.
+    void SendMessage(
+        std::unique_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);
+
+    // Listen for state changes to this connection. When a state change occurs,
+    // |callback| will be invoked with the new state.
+    void ListenForStateChange(
+        const content::PresentationConnectionStateChangedCallback& callback);
+
+    // If |session_| is not nullptr, removes itself from |session_|, and
+    // notifies the other endpoint of state change with |remove_reason|.
+    // |remove_reason|'s state must be CLOSED or TERMINATED.
+    // |session_| will be nullptr after this method is called.
+    // If |session_| is not nullptr when this object is destroyed, then this
+    // method will be called with {state = CLOSED, reason = WENT_AWAY}.
+    void RemoveFromPresentation(
+        const content::PresentationConnectionStateChangeInfo& remove_reason);
+
+   private:
+    friend class OffscreenPresentation;
+    friend class OffscreenPresentationSession;
+
+    explicit OffscreenPresentationConnection(
+        OffscreenPresentationSession* session);
+
+    // If this method is invoked with state = CLOSED or TERMINATED, then
+    // |session_| will be set to nullptr.
+    void OnConnectionStateChanged(
+        const content::PresentationConnectionStateChangeInfo& info);
+    void OnMessageReceived(
+        std::unique_ptr<content::PresentationSessionMessage>);
+
+    // Reference to the session which this connection is an endpoint of.
+    // Set to nullptr either this or the other endpoint has been removed from
+    // the presentation.
+    // Not owned by this class.
+    OffscreenPresentationSession* session_;
+
+    content::PresentationSessionMessageCallback messages_callback_;
+    content::PresentationConnectionStateChangedCallback state_change_callback_;
+
+    DISALLOW_COPY_AND_ASSIGN(OffscreenPresentationConnection);
+  };
+
+  ~OffscreenPresentationManager() override;
+
+  using ReceiverConnectionAvailableCallback =
+      base::Callback<void(std::unique_ptr<OffscreenPresentationConnection>)>;
+
+  // Registers an offscreen presentation given by |presentation_id|.
+  // Enables controller frames to call |ConnectToOffscreenPresentation|
+  // 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 OffscreenPresentationConnection that represents the receiver
+  // side of the resulting connection.
+  void RegisterOffscreenPresentationReceiver(
+      const std::string& presentation_id,
+      const ReceiverConnectionAvailableCallback& 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 ReceiverConnectionAvailableCallback previously
+  // registered will be removed and will no longer be invoked.
+  // NOTE: before this call can be made, all OffscreenPresentationConnection
+  // 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 OffscreenPresentationConnection object representing the
+  // controller
+  // side of the resulting connection. In addition, the entity that has
+  // registered the receiver will have its ReceiverConnectionAvailableCallback
+  // run
+  // to notify it that a new connection is now available.
+  std::unique_ptr<OffscreenPresentationConnection>
+  ConnectToOffscreenPresentation(const std::string& presentation_id,
+                                 const RenderFrameHostId& controller_frame_id);
+
+ private:
+  friend class OffscreenPresentationManagerFactory;
+  friend class OffscreenPresentationManagerTest;
+
+  // Represents a session consisting of a controller endpoint and a receiver
+  // endpoint of an offscreen presentation and coordinates the exchange of
+  // information between them.
+  // Note that each offscreen presentation may contain multiple sessions.
+  class OffscreenPresentationSession {
+   public:
+    ~OffscreenPresentationSession();
+    void RemoveConnection(
+        OffscreenPresentationConnection* connection,
+        const content::PresentationConnectionStateChangeInfo& remove_reason);
+    void SendMessageFrom(
+        OffscreenPresentationConnection* connection,
+        std::unique_ptr<content::PresentationSessionMessage> message,
+        const content::SendMessageCallback& callback);
+
+   private:
+    friend class OffscreenPresentation;
+    OffscreenPresentationSession(const RenderFrameHostId& controller_frame_id,
+                                 OffscreenPresentation* presentation);
+    void Init(OffscreenPresentationConnection* controller,
+              OffscreenPresentationConnection* receiver);
+
+    const RenderFrameHostId controller_frame_id_;
+
+    // Not owned by this class.
+    OffscreenPresentation* const presentation_;
+
+    // Not owned by this class.
+    OffscreenPresentationConnection* controller_;
+    OffscreenPresentationConnection* receiver_;
+
+    DISALLOW_COPY_AND_ASSIGN(OffscreenPresentationSession);
+  };
+
+  // Represents an offscreen presentation registered with
+  // OffscreenPresentationManager.
+  // Maintains set of sessions to the presentation.
+  // Contains callback to the receiver to inform it of new sessions
+  // established from a controller.
+  class OffscreenPresentation {
+   public:
+    OffscreenPresentation(
+        const std::string& presentation_id,
+        const ReceiverConnectionAvailableCallback& receiver_available_callback,
+        OffscreenPresentationManager* manager);
+    ~OffscreenPresentation();
+
+    std::unique_ptr<OffscreenPresentationConnection> AddSession(
+        const RenderFrameHostId& controller_frame_id);
+
+   private:
+    friend class OffscreenPresentationSession;
+
+    void RemoveSession(const RenderFrameHostId& controller_frame_id);
+
+    const std::string presentation_id_;
+    ReceiverConnectionAvailableCallback receiver_available_callback_;
+    std::map<RenderFrameHostId, std::unique_ptr<OffscreenPresentationSession>>
+        sessions_;
+
+    // Not owned by this class.
+    OffscreenPresentationManager* const manager_;
+
+    DISALLOW_COPY_AND_ASSIGN(OffscreenPresentation);
+  };
+
+  // Used by OffscreenPresentationManagerFactory::GetOrCreateForBrowserContext.
+  OffscreenPresentationManager();
+
+  // Maps from presentation ID to OffscreenPresentation.
+  std::map<std::string, std::unique_ptr<OffscreenPresentation>>
+      offscreen_presentations_;
+
+  DISALLOW_COPY_AND_ASSIGN(OffscreenPresentationManager);
+};
+
+}  // namespace media_router
+
+#endif  // CHROME_BROWSER_MEDIA_ROUTER_OFFSCREEN_PRESENTATION_MANAGER_H_