// Copyright 2015 The Chromium Authors
// 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);
// Called when target connection notifies connection state change. This should
// not be called with CLOSED. Instead, call DidClose().
DidChangeState(PresentationConnectionState state);
// Called when target connection calls close().
DidClose(PresentationConnectionCloseReason reason);
};
// Holds result from successfully starting or reconnecting to a presentation
// with a pair of Mojo pipes to communicate with the presentation page.
// |presentation_info| holds the URL and ID of the presentation.
// |connection_remote| holds the connection from the presentation to the
// controlling frame. |connection_receiver| is fulfilled by the controlling
// frame with a new connection to return to the presentation.
struct PresentationConnectionResult {
PresentationInfo presentation_info;
pending_remote<PresentationConnection> connection_remote;
pending_receiver<PresentationConnection> connection_receiver;
};
// 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(pending_remote<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(pending_remote<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 PresentationConnectionResult if starting
// the presentation succeeded, or null with a PresentationError if starting
// the presentation failed.
StartPresentation(array<url.mojom.Url> presentation_urls)
=> (PresentationConnectionResult? result,
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)
=> (PresentationConnectionResult? result,
PresentationError? error);
// 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(PresentationConnectionResult result);
// 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.
interface PresentationReceiver {
// Notifies the PresentationReceiver that a receiver connection has become
// available.
OnReceiverConnectionAvailable(PresentationConnectionResult result);
};
Codebase Browser
chromium