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,

[asargent_no_longer_on_chrome, 2015/11/14 00:53:32]

nit: for readability, please add a newline in between each value when there are
comments >= 2 lines long. For example, here it's kind of hard to see each enum
value name:

// Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
// tempor incididunt ut labore et dolore magna aliqua.
foo,
// Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
// aliquip ex ea commodo consequat.
bar,
// Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore
// eu fugiat nulla pariatur
baz



but the following is better:



// Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
// tempor incididunt ut labore et dolore magna aliqua.
foo,

// Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
// aliquip ex ea commodo consequat.
bar,

// Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore
// eu fugiat nulla pariatur
baz

[Mikhail, 2015/11/16 14:22:23]

Done.

+    // A new Display session cannot be started before the existing one is terminated.

[asargent_no_longer_on_chrome, 2015/11/14 00:53:32]

nit: please keep lines <= 80 chars long where possible

Same comment applies in a few other places down below. 

[Mikhail, 2015/11/16 14:22:23]

Done.

+    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);
+  };
+};