[Presentation API] (alternative) 1-UA: send message between controller and receiver page

third_party/WebKit/public/platform/modules/presentation/presentation.mojom

 // 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.
 
 // TODO(crbug.com/647290): Rename "Session" to "Connection"
 
 module blink.mojom;
 
 import "url/mojo/url.mojom";
 
 struct PresentationSessionInfo {
   url.mojom.Url url;
   string id;
+  bool is_offscreen_presentation;

[mark a. foltz, 2016/10/21 00:53:03]

Or just is_offscreen?  Since it's part of PresentationSessionInfo.

[zhaobin, 2016/10/22 02:44:14]

Done.

 };
 
 enum PresentationConnectionState {
   CONNECTING,
   CONNECTED,
   CLOSED,
   TERMINATED
 };
 
 enum PresentationConnectionCloseReason {
@@ skipping 21 matching lines @@
 };
 
 struct SessionMessage {
   PresentationMessageType type;
   // Used when message type is TEXT.
   string? message;
   // Used when message type is ARRAY_BUFFER or BLOB.
   array<uint8>? data;
 };
 
+interface PresentationConnection {

[mark a. foltz, 2016/10/21 00:53:03]

Can you add a TODO to migrate SendSessionMessage from PresenationService =>
PresentationConnection.Send()?

[zhaobin, 2016/10/22 02:44:14]

Done.

+   // Called to set the PresentationConnection that is the destination for
+   // messages sent and the source of messages received by this connection.
+   SetTargetConnection(PresentationConnection connection);
+
+   // Called when a message is sent by the target connection.
+   OnConnectionMessageReceived(SessionMessage message);

[mark a. foltz, 2016/10/21 00:53:03]

Or just OnMessage() (similar to the Presentation API) since it seems clear as a
member of PresentationConnection that it's a connection message.

[zhaobin, 2016/10/22 02:44:14]

Done.

+};
+
 interface PresentationService {
   // Sets the PresentationServiceClient.
   SetClient(PresentationServiceClient client);
 

[mark a. foltz, 2016/10/21 00:53:04]

Can you add a comment block starting here that the functions here are for the
controller part of the API?

[zhaobin, 2016/10/22 02:44:14]

Done.

   // Called when the frame sets or changes the default presentation URLs.
   // When the default presentation is started on this frame,
   // PresentationServiceClient::OnDefaultSessionStarted will be invoked.
   SetDefaultPresentationUrls(array<url.mojom.Url> presentation_urls);
 
   // Starts listening for screen availability for presentation of
   // |availability_url|. Availability results will be returned to the client via
   // PresentationServiceClient::OnScreenAvailabilityUpdated.
   ListenForScreenAvailability(url.mojom.Url availability_url);
 
@@ skipping 13 matching lines @@
   // a new one.
   StartSession(array<url.mojom.Url> presentation_urls)
       => (PresentationSessionInfo? sessionInfo, PresentationError? error);
 
   // Called when joinSession() is called by the frame. The result callback
   // works the same as for the method above. JoinSession will join a known
   // session (i.e. when the page navigates or the user opens another tab)
   // silently and without user action.
   JoinSession(array<url.mojom.Url> presentation_urls, string? presentation_id)
       => (PresentationSessionInfo? sessionInfo, PresentationError? error);
 

[mark a. foltz, 2016/10/21 00:53:03]

... And end the comment block.  The functions below here are shared between
controller and receiver I believe.

[zhaobin, 2016/10/22 02:44:14]

Done.

   // Called when send() is called by the frame. The true in the
   // result callback notifies that the service is ready for next message.
   // The false in the result callback notifies the renderer to stop sending
   // the send requests and invalidate all pending requests. This occurs
   // for eg., when frame is deleted or navigated away.
   SendSessionMessage(PresentationSessionInfo sessionInfo,
                      SessionMessage message_request) => (bool success);
 
   // Called when close() is called by the frame.
   CloseConnection(url.mojom.Url presentation_url, string presentation_id);
 
   // Called when terminate() is called by the frame.
   Terminate(url.mojom.Url presentation_url, string presentation_id);
 
   // Starts listening for messages for session with |sessionInfo|.
   // Messages will be received in
   // PresentationServiceClient::OnSessionMessagesReceived.
   // This is called after a presentation session is created.
   ListenForSessionMessages(PresentationSessionInfo sessionInfo);
+
+  SetPresentationConnection(PresentationSessionInfo sessionInfo,

[mark a. foltz, 2016/10/21 00:53:03]

Document this function.  Is it called on the controller, the receiver or both?

[zhaobin, 2016/10/22 02:44:14]

Done.

+                            PresentationConnection connection);
 };
 
 interface PresentationServiceClient {
   // Called when the client tries to listen for screen availability changes for

[mark a. foltz, 2016/10/21 00:53:03]

Can you add a block comment above here that these functions are called only on
the controlling page.

[zhaobin, 2016/10/22 02:44:14]

Done.

   // presentation of |url| but it is not supported by the device or underlying
   // platform. This can also be called if the device is currently in a mode
   // where it can't do screen discoveries (eg. low battery).
   OnScreenAvailabilityNotSupported(url.mojom.Url url);
 
   // Called when the client is listening for screen availability for
   // presentation of |url| and the state changes. When the client starts to
   // listen for screen availability, this method will always be called to give
   // the current known state. It will then be called to notify of state updates.
   OnScreenAvailabilityUpdated(url.mojom.Url url, bool available);
 

[mark a. foltz, 2016/10/21 00:53:03]

And end the comment as the functions below except for the last two are shared.

[zhaobin, 2016/10/22 02:44:14]

Done.

   // Called when the state of PresentationConnection |connection| started on
   // this frame has changed to |newState|.
   OnConnectionStateChanged(PresentationSessionInfo connection,
                            PresentationConnectionState newState);
 
   // Caled when the state of |connection| started on this frame has changed to
   // CLOSED.
   OnConnectionClosed(PresentationSessionInfo connection,
                      PresentationConnectionCloseReason reason,
                      string message);
 
   // See PresentationService::ListenForSessionMessages.
   OnSessionMessagesReceived(PresentationSessionInfo sessionInfo,
                             array<SessionMessage> messages);
 
   // See PresentationService::SetDefaultPresentationURL.
   OnDefaultSessionStarted(PresentationSessionInfo sessionInfo);

[mark a. foltz, 2016/10/21 00:53:03]

Can this be moved above with the other controller-only functions?

Maybe we can eventually combine this with OnReceiverConnectionAvailable and just
have OnConnectionAvailable.  (Not to be done in this change.)

In the controlling page, it signals that the browser has started a presentation.
In the receiving page, it signals that the controller has connected to the
receiver.

Would that make sense, or is it more confusing?  Not sure.

[zhaobin, 2016/10/22 02:44:14]

Done.

 
-  // See PresentationService::ListeningForReceiverPageRendered.
-  OnReceiverConnectionAvailable(PresentationSessionInfo sessionInfo);
+  // Called on a presentation receiver when the first presentation connection is
+  // available from the controlling page.
+  OnReceiverConnectionAvailable(PresentationSessionInfo sessionInfo,

[mark a. foltz, 2016/10/21 00:53:03]

Maybe this should be OnFirstConnectionAvailable?  Or is it called for all
connections to the receiver page?

[zhaobin, 2016/10/22 02:44:14]

It is called for all connections to the receiver page.

+                                PresentationConnection connection);
 };