/* 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 nsIPresentationControlChannel;

%{C++
#define PRESENTATION_CONTROL_SERVICE_CONTACT_ID \
  "@mozilla.org/presentation/control-service;1"
%}

/*
 * The device information required for establishing control channel.
 */
[scriptable, uuid(296fd171-e4d0-4de0-99ff-ad8ed52ddef3)]
interface nsITCPDeviceInfo: nsISupports
{
  readonly attribute AUTF8String id;
  readonly attribute AUTF8String address;
  readonly attribute uint16_t port;
  // SHA-256 fingerprint of server certificate. Empty string represents
  // server doesn't support TLS or not available.
  readonly attribute AUTF8String certFingerprint;
};

[scriptable, uuid(09bddfaf-fcc2-4dc9-b33e-a509a1c2fb6d)]
interface nsIPresentationControlServerListener: nsISupports
{
  /**
   * Callback while the server is ready or restarted.
   * @param   aPort
   *          The port of the server socket.
   * @param   aCertFingerprint
   *          The SHA-256 fingerprint of TLS server certificate.
   *          Empty string represents server started without encryption.
   */
  void onServerReady(in uint16_t aPort, in AUTF8String aCertFingerprint);

  /**
   * Callback while the server is stopped or fails to start.
   * @param   aResult
   *          The error cause of server stopped or the reason of
   *          start failure.
   *          NS_OK means the server is stopped by close.
   */
  void onServerStopped(in nsresult aResult);

  /**
   * Callback while the remote host is requesting to start a presentation session.
   * @param aDeviceInfo The device information related to the remote host.
   * @param aUrl The URL requested to open by remote device.
   * @param aPresentationId The Id for representing this session.
   * @param aControlChannel The control channel for this session.
   */
  void onSessionRequest(in nsITCPDeviceInfo aDeviceInfo,
                        in DOMString aUrl,
                        in DOMString aPresentationId,
                        in nsIPresentationControlChannel aControlChannel);

  /**
   * Callback while the remote host is requesting to terminate a presentation session.
   * @param aDeviceInfo The device information related to the remote host.
   * @param aPresentationId The Id for representing this session.
   * @param aControlChannel The control channel for this session.
   * @param aIsFromReceiver true if termination is initiated by receiver.
   */
  void onTerminateRequest(in nsITCPDeviceInfo aDeviceInfo,
                          in DOMString aPresentationId,
                          in nsIPresentationControlChannel aControlChannel,
                          in boolean aIsFromReceiver);

  /**
   * Callback while the remote host is requesting to reconnect a presentation session.
   * @param aDeviceInfo The device information related to the remote host.
   * @param aUrl The URL requested to open by remote device.
   * @param aPresentationId The Id for representing this session.
   * @param aControlChannel The control channel for this session.
   */
  void onReconnectRequest(in nsITCPDeviceInfo aDeviceInfo,
                          in DOMString url,
                          in DOMString aPresentationId,
                          in nsIPresentationControlChannel aControlChannel);
};

/**
 * Presentation control service which can be used for both presentation
 * control client and server.
 */
[scriptable, uuid(55d6b605-2389-4aae-a8fe-60d4440540ea)]
interface nsIPresentationControlService: nsISupports
{
  /**
   * This method initializes server socket. Caller should set listener and
   * monitor onServerReady event to get the correct server info.
   * @param   aEncrypted
   *          True for using TLS control channel.
   * @param   aPort
   *          The port of the server socket.  Pass 0 or opt-out to indicate no
   *          preference, and a port will be selected automatically.
   * @throws  NS_ERROR_FAILURE if the server socket has been inited or the
   *          server socket can not be inited.
   */
  void startServer(in boolean aEncrypted, [optional] in uint16_t aPort);

  /**
   * Request connection to designated remote presentation control receiver.
   * @param   aDeviceInfo
   *          The remtoe device info for establish connection.
   * @returns The control channel for this session.
   * @throws  NS_ERROR_FAILURE if the Id hasn't been inited.
   */
  nsIPresentationControlChannel connect(in nsITCPDeviceInfo aDeviceInfo);

  /**
   * Check the compatibility to remote presentation control server.
   * @param  aVersion
   *         The version of remote server.
   */
  boolean isCompatibleServer(in uint32_t aVersion);

  /**
   * Close server socket and call |listener.onClose(NS_OK)|
   */
  void close();

  /**
   * Get the listen port of the TCP socket, valid after the server is ready.
   * 0 indicates the server socket is not ready or is closed.
   */
  readonly attribute uint16_t port;

  /**
   * The protocol version implemented by this server.
   */
  readonly attribute uint32_t version;

  /**
   * The id of the TCP presentation server. |requestSession| won't
   * work until the |id| is set.
   */
  attribute AUTF8String id;

  /**
   * The fingerprint of the TLS server certificate.
   * Empty string indicates the server is not ready or not encrypted.
   */
  attribute AUTF8String certFingerprint;

  /**
   * The listener for handling events of this presentation control server.
   * Listener must be provided before invoke |startServer| and |close|.
   */
  attribute nsIPresentationControlServerListener listener;
};