// 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 blink.mojom;

import "url/mojom/url.mojom";

// This file contains definition of objects and interfaces required to
// implement the Presentation API. For more information on the API, please see:
// http://w3c.github.io/presentation-api/

struct PresentationInfo {
  url.mojom.Url url;
  string id;
};

enum ScreenAvailability {
  UNKNOWN,
  UNAVAILABLE,
  SOURCE_NOT_SUPPORTED,
  DISABLED,
  AVAILABLE
};

enum PresentationConnectionState {
  CONNECTING,
  CONNECTED,
  CLOSED,
  TERMINATED
};

enum PresentationConnectionCloseReason {
  CONNECTION_ERROR,
  CLOSED,
  WENT_AWAY
};

enum PresentationErrorType {
  NO_AVAILABLE_SCREENS,
  PRESENTATION_REQUEST_CANCELLED,
  NO_PRESENTATION_FOUND,
  PREVIOUS_START_IN_PROGRESS,
  UNKNOWN,
};

struct PresentationError {
  PresentationErrorType error_type;
  string message;
};

union PresentationConnectionMessage {
  string message;
  array<uint8> data;
};

// Represents a connection from the controller side of a presentation to the
// receiver side of a presentation, and vice versa. This interface is used to
// communicate messages to the other side. It can also be used to notify state
// changes to the presentation.
// The controller side PresentationConnection is implemented in the renderer
// process of the frame that initiated the presentation.
// For 1-UA presentations, the receiver side PresentationConnection is
// implemented in the renderer process of the frame that hosts the presentation
// page. For 2-UA presentations, it is implemented in the browser process to act
// as a intermediary to forward/receive the messages to/from a remote user
// agent.
interface PresentationConnection {
   // Called when a message is sent by the target connection.
   // TODO(crbug.com/749327): Remove the return value since it is no longer
   // used.
   OnMessage(PresentationConnectionMessage message) => (bool success);

   // Called when target connection notifies connection state change.
   DidChangeState(PresentationConnectionState state);

   // Called when target connection calls close().
   RequestClose();
};

// Service provided by the browser process to implement parts of the
// Presentation API for initiating a presentation. This includes querying screen
// availability, starting/reconnecting a presentation, and setting the
// page-level default presentation request.
// A PresentationService is instantiated on a frame when Presentation API is
// first used on a page. The renderer process of the page will then set either
// a PresentationController or PresentationReceiver on the service to receive
// updates.
// TODO(crbug.com/749327): The Presentation API code is in the process of being
// onion-souped. Part of the work will be to split this interface into
// controller and receiver parts.
interface PresentationService {
  // Sets the PresentationController of the frame. This is called by the
  // controller page of a presentation to listen for screen availability and
  // initiate presentations.
  SetController(PresentationController controller);

  // Sets the PresentationReceiver of the page. This is called by the
  // presentation page of a 1-UA presentation in order to receive updates on new
  // connections (initiated by a controller) becoming available.
  // TODO(crbug.com/749327): Move this method out of PresentationService and
  // define a new interface that implements only Presentation Receiver APIs.
  SetReceiver(PresentationReceiver receiver);

  ///////////// Functions here are for the controller part of the API. /////////

  // Called when the frame sets or changes the default presentation URLs.
  // When the default presentation is started on this frame,
  // PresentationController::OnDefaultPresentationStarted 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
  // PresentationController::OnScreenAvailabilityUpdated.
  ListenForScreenAvailability(url.mojom.Url availability_url);

  // Stops listening for screen availability for the presentation of |url|. The
  // PresentationController will stop receiving availability updates for
  // |url|.
  StopListeningForScreenAvailability(url.mojom.Url availability_url);

  // Called when start() is called by the frame. The result callback
  // will return a non-null and valid PresentationInfo if starting the
  // presentation succeeded, or null with a PresentationError if starting the
  // presentation failed.
  StartPresentation(array<url.mojom.Url> presentation_urls)
      => (PresentationInfo? presentation_info, PresentationError? error);

  // Called when reconnect() is called by the frame. The result callback
  // works the same as for the method above. reconnect() will create a new
  // connection to a presentation with the matching URL and id.
  ReconnectPresentation(array<url.mojom.Url> presentation_urls, string presentation_id)
      => (PresentationInfo? presentation_info, PresentationError? error);

  // Notifies the service that a PresentationConnection has been started.
  // |controller_connection_ptr| is a handle to a PresentationConnection in
  // the page that started the presentation (aka the "controller"). This can be
  // used by PresentationService to send messages to the controller
  // PresentationConnection, for example.
  // |receiver_connection_request| will be bound to a PresentationConnection
  // implementation in order to receive messages and commands issued by the
  // controller PresentationConnection. The process in which the receiver
  // connection resides depends on whether the presentation is 1-UA or 2-UA:
  // see PresentationConnection interface for more info.
  SetPresentationConnection(
      PresentationInfo presentation_info,
      PresentationConnection controller_connection_ptr,
      PresentationConnection& receiver_connection_request);

  // Called when close() is called by the frame.
  // TODO(crbug.com/749327): Move this method into a separate interface that
  // deals with modifying the state of a presentation.
  CloseConnection(url.mojom.Url presentation_url, string presentation_id);

  // Called when terminate() is called by the frame.
  // TODO(crbug.com/749327): Move this method into a separate interface that
  // deals with modifying the state of a presentation.
  Terminate(url.mojom.Url presentation_url, string presentation_id);
};

// Implemented by a render frame that uses the Presentation Controller API.
// A PresentationController can receive updates on screen availability, default
// presentation, and connection state changes originating from the browser.
// This interface is shared by controller implementations for both 1-UA and
// 2-UA presentations.
interface PresentationController {
  // 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,
                              ScreenAvailability availability);

  // See PresentationService::SetDefaultPresentationURL.
  OnDefaultPresentationStarted(PresentationInfo presentation_info);

  // Called when the state of PresentationConnection |connection| started on
  // this frame has changed to |newState|.
  OnConnectionStateChanged(PresentationInfo presentation_info,
                           PresentationConnectionState newState);

  // Caled when the state of |presentation_info| started on this frame has
  // changed to CLOSED.
  OnConnectionClosed(PresentationInfo presentation_info,
                     PresentationConnectionCloseReason reason,
                     string message);
};

// Implemented by a render frame that uses Presentation Receiver API.
// Receives updates of receiver PresentationConnections becoming available as
// a result of a controller initiating a 1-UA presentation and calling
// PresentationService::SetPresentationConnection (i.e. the connection ptr /
// requests are routed to the receiver page to be bound there).
interface PresentationReceiver {
  // Notifies the PresentationReceiver that a receiver connection has become
  // available.
  // |info|: URL and ID of the PresentationConnection.
  // |controller_connection|: Ptr to the corresponding controller connection.
  // |receiver_connection_request|: Interface request to be bound to a receiver
  // connection implementation.
  OnReceiverConnectionAvailable(
      PresentationInfo info,
      PresentationConnection controller_connection,
      PresentationConnection& receiver_connection_request);
};