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

module presentation;

struct PresentationSessionInfo {
  string url;
  string id;
};

enum PresentationSessionState {
  CONNECTED,
  DISCONNECTED
};

enum PresentationErrorType {
  NO_AVAILABLE_SCREENS,
  SESSION_REQUEST_CANCELLED,
  NO_PRESENTATION_FOUND,
  UNKNOWN,
};

struct PresentationError {
  PresentationErrorType error_type;
  string message;
};

enum PresentationMessageType {
  TEXT,
  ARRAY_BUFFER,
  BLOB,
};

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 PresentationService {
  // Called when the frame sets or changes the default presentation URL.
  SetDefaultPresentationURL(string url);

  // Sets the PresentationServiceClient.
  SetClient(PresentationServiceClient client);

  // Starts listening for screen availability for presentation of
  // |url|. Availability results will be returned to the client via
  // PresentationServiceClient::OnScreenAvailabilityUpdated.
  ListenForScreenAvailability(string url);

  // Stops listening for screen availability for the presentation of |url|. The
  // PresentationServiceClient will stop receiving availability updates for
  // |url|.
  StopListeningForScreenAvailability(string url);

  // Called when the renderer is ready to receive the browser initiated
  // session. If the default session is started by the embedder before this
  // call, the embedder may queue it and run the callback when the call is
  // performed.
  ListenForDefaultSessionStart()
      => (PresentationSessionInfo? defaultSessionInfo);

  // Called when startSession() is called by the frame. The result callback
  // will return a non-null and valid PresentationSessionInfo if starting the
  // session succeeded, or null with a PresentationError if starting the
  // session failed.
  // The presentation id returned in |sessionInfo| on success is generated by
  // the UA.
  // If the UA identifies a matching session (same presentation url), the user
  // may choose this existing session and the page will join it rather than get
  // a new one.
  StartSession(string presentation_url)
      => (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(string presentation_url, string? presentation_id)
      => (PresentationSessionInfo? sessionInfo, PresentationError? error);

  // 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 closeSession() is called by the frame.
  CloseSession(string presentation_url, string presentation_id);

  // Starts listening for state changes for sessions created on this frame.
  // When state change occurs, PresentationServiceClient::OnSessionStateChanged
  // will be invoked with the session and its new state.
  // This is called after a presentation session is created.
  ListenForSessionStateChange();

  // 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);
};

interface PresentationServiceClient {
  // Called when the client tries to listen for screen availability changes for
  // 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(string 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(string url, bool available);

  // See PresentationService::ListenForSessionStateChange.
  OnSessionStateChanged(PresentationSessionInfo sessionInfo,
                        PresentationSessionState newState);

  // See PresentationService::ListenForSessionMessages.
  OnSessionMessagesReceived(PresentationSessionInfo sessionInfo, array<SessionMessage> messages);
};