path: root/dom/presentation/interfaces/nsIPresentationService.idl

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
 * You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIDOMBlob;
interface nsIDOMEventTarget;
interface nsIInputStream;
interface nsIPresentationAvailabilityListener;
interface nsIPresentationRespondingListener;
interface nsIPresentationSessionListener;
interface nsIPresentationTransportBuilderConstructor;
interface nsIPrincipal;

%{C++
#define PRESENTATION_SERVICE_CID \
  { 0x1d9bb10c, 0xc0ab, 0x4fe8, \
    { 0x9e, 0x4f, 0x40, 0x58, 0xb8, 0x51, 0x98, 0x32 } }
#define PRESENTATION_SERVICE_CONTRACTID \
  "@mozilla.org/presentation/presentationservice;1"

#include "nsTArray.h"

class nsString;
%}

[ref] native URLArrayRef(const nsTArray<nsString>);

[scriptable, uuid(12073206-0065-4b10-9488-a6eb9b23e65b)]
interface nsIPresentationServiceCallback : nsISupports
{
  /*
   * Called when the operation succeeds.
   *
   * @param url: the selected request url used to start or reconnect a session.
   */
  void notifySuccess(in DOMString url);

  /*
   * Called when the operation fails.
   *
   * @param error: error message.
   */
  void notifyError(in nsresult error);
};

[scriptable, uuid(de42b741-5619-4650-b961-c2cebb572c95)]
interface nsIPresentationService : nsISupports
{
  const unsigned short ROLE_CONTROLLER = 0x1;
  const unsigned short ROLE_RECEIVER = 0x2;

  const unsigned short CLOSED_REASON_ERROR = 0x1;
  const unsigned short CLOSED_REASON_CLOSED = 0x2;
  const unsigned short CLOSED_REASON_WENTAWAY = 0x3;

  /*
   * Start a new presentation session and display a prompt box which asks users
   * to select a device.
   *
   * @param urls: The candidate Urls of presenting page. Only one url would be used.
   * @param sessionId: An ID to identify presentation session.
   * @param origin: The url of requesting page.
   * @param deviceId: The specified device of handling this request, null string
   *                  for prompt device selection dialog.
   * @param windowId: The inner window ID associated with the presentation
   *                  session. (0 implies no window ID since no actual window
   *                  uses 0 as its ID. Generally it's the case the window is
   *                  located in different process from this service)
   * @param eventTarget: The chrome event handler, in particular XUL browser
   *                     element in parent process, that the request was
   *                     originated in.
   * @param principal: The principal that initiated the session.
   * @param callback: Invoke the callback when the operation is completed.
   *                  NotifySuccess() is called with |id| if a session is
   *                  established successfully with the selected device.
   *                  Otherwise, NotifyError() is called with a error message.
   * @param constructor: The constructor for creating a transport builder.
   */
  [noscript] void startSession(in URLArrayRef urls,
                               in DOMString sessionId,
                               in DOMString origin,
                               in DOMString deviceId,
                               in unsigned long long windowId,
                               in nsIDOMEventTarget eventTarget,
                               in nsIPrincipal principal,
                               in nsIPresentationServiceCallback callback,
                               in nsIPresentationTransportBuilderConstructor constructor);

  /*
   * Send the message to the session.
   *
   * @param sessionId: An ID to identify presentation session.
   * @param role: Identify the function called by controller or receiver.
   * @param data: the message being sent out.
   */
  void sendSessionMessage(in DOMString sessionId,
							            in uint8_t role,
                          in DOMString data);

  /*
   * Send the binary message to the session.
   *
   * @param sessionId: An ID to identify presentation session.
   * @param role: Identify the function called by controller or receiver.
   * @param data: the message being sent out.
   */
  void sendSessionBinaryMsg(in DOMString sessionId,
                            in uint8_t role,
                            in ACString data);

  /*
   * Send the blob to the session.
   *
   * @param sessionId: An ID to identify presentation session.
   * @param role: Identify the function called by controller or receiver.
   * @param blob: The input blob to be sent.
   */
  void sendSessionBlob(in DOMString sessionId,
                       in uint8_t role,
                       in nsIDOMBlob blob);

  /*
   * Close the session.
   *
   * @param sessionId: An ID to identify presentation session.
   * @param role: Identify the function called by controller or receiver.
   */
  void closeSession(in DOMString sessionId,
                    in uint8_t role,
                    in uint8_t closedReason);

  /*
   * Terminate the session.
   *
   * @param sessionId: An ID to identify presentation session.
   * @param role: Identify the function called by controller or receiver.
   */
  void terminateSession(in DOMString sessionId,
                        in uint8_t role);

  /*
   * Reconnect the session.
   *
   * @param url: The request Urls.
   * @param sessionId: An ID to identify presentation session.
   * @param role: Identify the function called by controller or receiver.
   * @param callback: NotifySuccess() is called when a control channel
   *                  is opened successfully.
   *                  Otherwise, NotifyError() is called with a error message.
   */
  [noscript] void reconnectSession(in URLArrayRef urls,
                                   in DOMString sessionId,
                                   in uint8_t role,
                                   in nsIPresentationServiceCallback callback);

  /*
   * Register an availability listener. Must be called from the main thread.
   *
   * @param availabilityUrls: The Urls that this listener is interested in.
   * @param listener: The listener to register.
   */
  [noscript] void registerAvailabilityListener(
                              in URLArrayRef availabilityUrls,
                              in nsIPresentationAvailabilityListener listener);

  /*
   * Unregister an availability listener. Must be called from the main thread.
   *
   * @param availabilityUrls: The Urls that are registered before.
   * @param listener: The listener to unregister.
   */
  [noscript] void unregisterAvailabilityListener(
                              in URLArrayRef availabilityUrls,
                              in nsIPresentationAvailabilityListener listener);

  /*
   * Register a session listener. Must be called from the main thread.
   *
   * @param sessionId: An ID to identify presentation session.
   * @param role: Identify the function called by controller or receiver.
   * @param listener: The listener to register.
   */
  void registerSessionListener(in DOMString sessionId,
                               in uint8_t role,
                               in nsIPresentationSessionListener listener);

  /*
   * Unregister a session listener. Must be called from the main thread.
   *
   * @param sessionId: An ID to identify presentation session.
   * @param role: Identify the function called by controller or receiver.
   */
  void unregisterSessionListener(in DOMString sessionId,
                                 in uint8_t role);

  /*
   * Register a responding listener. Must be called from the main thread.
   *
   * @param windowId: The window ID associated with the listener.
   * @param listener: The listener to register.
   */
  void registerRespondingListener(in unsigned long long windowId,
                                  in nsIPresentationRespondingListener listener);

  /*
   * Unregister a responding listener. Must be called from the main thread.
   * @param windowId: The window ID associated with the listener.
   */
  void unregisterRespondingListener(in unsigned long long windowId);

  /*
   * Notify the receiver page is ready for presentation use.
   *
   * @param sessionId An ID to identify presentation session.
   * @param windowId  The inner window ID associated with the presentation
   *                  session.
   * @param isLoading true if receiver page is loading successfully.
   * @param constructor: The constructor for creating a transport builder.
   */
  void notifyReceiverReady(in DOMString sessionId,
                           in unsigned long long windowId,
                           in boolean isLoading,
                           in nsIPresentationTransportBuilderConstructor constructor);

  /*
   * Notify the transport is closed
   *
   * @param sessionId: An ID to identify presentation session.
   * @param role: Identify the function called by controller or receiver.
   * @param reason: the error message. NS_OK indicates it is closed normally.
   */
  void NotifyTransportClosed(in DOMString sessionId,
                             in uint8_t role,
                             in nsresult reason);

  /*
   * Untrack the relevant info about the presentation session if there's any.
   *
   * @param sessionId: An ID to identify presentation session.
   * @param role: Identify the function called by controller or receiver.
   */
  void untrackSessionInfo(in DOMString sessionId, in uint8_t role);

  /*
   * The windowId for building RTCDataChannel session transport
   *
   * @param sessionId: An ID to identify presentation session.
   * @param role: Identify the function called by controller or receiver.
   */
  unsigned long long getWindowIdBySessionId(in DOMString sessionId,
                                            in uint8_t role);

  /*
   * Update the mapping of the session ID and window ID.
   *
   * @param sessionId: An ID to identify presentation session.
   * @param role: Identify the function called by controller or receiver.
   * @param windowId: The inner window ID associated with the presentation
   *                  session.
   */
  void updateWindowIdBySessionId(in DOMString sessionId,
                                 in uint8_t role,
                                 in unsigned long long windowId);

  /*
   * To build the session transport.
   * NOTE: This function should be only called at controller side.
   *
   * @param sessionId: An ID to identify presentation session.
   * @param role: Identify the function called by controller or receiver.
   */
  void buildTransport(in DOMString sessionId, in uint8_t role);
};