Introduce chrome.displaySource API

extensions/common/api/display_source.idl

Index: extensions/common/api/display_source.idl
diff --git a/extensions/common/api/display_source.idl b/extensions/common/api/display_source.idl
new file mode 100644
index 0000000000000000000000000000000000000000..523c4e7007af8157801c36e3a81482d91c3b579a
--- /dev/null
+++ b/extensions/common/api/display_source.idl
@@ -0,0 +1,131 @@
+// 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;
+  };
+
+  dictionary AuthenticationInfo {
+    // Authentication method (e.g. ‘pin’ or ‘pbc’ )
+    DOMString method;

[Reilly Grant (use Gerrit), 2015/11/10 18:51:34]

Why not an enum here?

[Mikhail, 2015/11/11 13:36:04]

The intention is to keep API generic and flexible for adding more auth
mechanisms, pls. see
https://docs.google.com/document/d/1svs0p_b6KAIiBrKjaORsA2D8Pd84u8ksnTCfubYVV...

[Reilly Grant (use Gerrit), 2015/11/11 18:36:13]

If more mechanisms are added the API can be very easily extended. It is
important for the documentation of this API to cover the expected authentication
mechanisms and how an application using them should use them. That is easier if
this is an enum. The fact is, in the Javascript bindings this becomes a string
anyways. Making it an enum simply means the list of possible values is
documented.

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