Introduce chrome.displaySource API

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 {
+    // Cannot create media pipeline from the given media stream which could be
+    // appropriate for a Display session (e.g., necessary codecs are missing
+    // on the platform).
+    create_media_pipeline_error,
+
+    // A new Display session cannot be started before the existing one is
+    // terminated.
+    exceeded_session_limit_error,
+
+    // Could not establish connection to the sink.
+    establish_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 while packetizing and sending the media content.
+    media_send_error,
+
+    // The TCP connection with sink has dropped unexpectedly.
+    connection_error,
+
+    // An unexpected message has arrived from the sink.
+    unexpected_message_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);
+  callback TerminateSessionCallback = 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’.
+    [nocompile] static void startSession(StartSessionInfo sessionInfo);
+
+    // 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 TerminateSessionCallback 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 started.
+    // |sinkId| Id of the peer sink
+    [nocompile] static void onSessionStarted(long sinkId);
+    // 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);
+  };
+};