extensions/common/api/display_source.idl

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

// The <code>chrome.displaySource</code> API creates a Display
// session using WebMediaStreamTrack as sources.
namespace displaySource {
  enum ErrorType {
    // The connection with sink cannot be established or has dropped
    // unexpectedly.
    connection_error,

    // The capabilities of this Display Source and the connected
    // sink do not fit (e.g. the sink cannot play the media content of
    // the formats given by the source).
    capabilities_negotiation_error,

    // There was an error in media pipeline: while encoding, packetizing or
    // sending the media content.
    media_pipeline_error,

    // The sink became unresponsive.
    timeout_error,

    // Unspecified error.
    unknown_error
  };

  dictionary ErrorInfo {
    ErrorType type;
    DOMString? description;
  };

  enum SinkState {
    // Connected using this Display Source (i.e., there is an active session)
    Connected,
    // In process of connection to this Display Source
    Connecting,
    // Disconnected from this Display Source
    Disconnected
  };

  dictionary SinkInfo {
    // Id of the sink. It is guaranteed to be unique during the browser session.
    long id;
    // Human readable name of the sink.
    DOMString name;
    // State of the sink.
    SinkState state;
  };

  enum AuthenticationMethod {
    // Push Button Config authentication method.
    PBC,
    // PIN authentication method.
    PIN
  };

  dictionary AuthenticationInfo {
    // Authentication method.
    AuthenticationMethod method;
    // Authentication data (e.g. PIN value).
    DOMString? data;
  };

  dictionary StartSessionInfo {
    // Id of the sink to connect.
    long sinkId;
    // Authentication information.
    AuthenticationInfo? authenticationInfo;
    // The source audio track.
    [instanceOf=MediaStreamTrack] object? audioTrack;
    // The source audio track.
    [instanceOf=MediaStreamTrack] object? videoTrack;
  };

  callback GetSinksCallback = void (SinkInfo[] result);
  callback RequestAuthenticationCallback = void (AuthenticationInfo result);

  // The callback is used by <code>startSession, terminateSession</code>
  // to signal completion. The callback is called with
  // <code>chrome.runtime.lastError</code> set to error
  // message if the call has failed.
  [inline_doc] callback CallCompleteCallback = void ();

  interface Functions {
    // Queries the list of the currently available Display sinks.
    //
    // |callback| : Called when the request is completed. The argument list
    // is empty if no available sinks were found.
    static void getAvailableSinks(GetSinksCallback callback);

    // Queries authentication data from the sink device.
    //
    // |sinkId| : Id of the sink
    // |callback| : Called when authentication info retrieved from the sink.
    // The argument |method| field contains the authentication method required
    // by the sink for connection; the |data| field can be null or can contain
    // some supplementary data provided by the sink. If authentication info
    // cannot be retrieved from the sink the "chrome.runtime.lastError" property
    // is defined.
    static void requestAuthentication(long sinkId,
                                      RequestAuthenticationCallback callback);

    // Creates a Display session using the provided StartSessionInfo instance.
    // The input argument fields must be initialized as described below:
    // The |sinkId|  must be a valid id of a sink (obtained via
    // ‘getAvailableSinks’).
    //
    // The |audioTrack| or |videoTrack| must be of type MediaStreamTrack.
    // Either |audioTrack| or |videoTrack| can be null but not both. This
    // means creating a session with only audio or video.
    //
    // The |authenticationInfo| can be null if no additional authentication data
    // are required by the sink; otherwise its |data| field must contain the
    // required authentication data (e.g. PIN value) and its |method| field must
    // be the same as one obtained from ‘requestAuthentication’.
    // |callback| : Called when the session is started.
    [nocompile] static void startSession(
        StartSessionInfo sessionInfo, optional CallCompleteCallback callback);

    // Terminates the active Display session.
    // |sinkId| : Id of the connected sink.
    // |callback| : Called when the session is terminated.
    [nocompile] static void terminateSession(
        long sinkId, optional CallCompleteCallback callback);
  };

  interface Events {
    // Event fired when the available sinks are modified (either their amount
    // or properties)
    // |sinks| the list of all currently available sinks
    static void onSinksUpdated(SinkInfo[] sinks);
    // Event fired when the Display session is terminated.
    // |sinkId| Id of the peer sink
    [nocompile] static void onSessionTerminated(long sinkId);
    // Event fired when an error occurs.
    // |sinkId| Id of the peer sink
    // |errorInfo| error description
    [nocompile] static void onSessionErrorOccured(long sinkId,
                                                  ErrorInfo errorInfo);
  };
};