1// Copyright 2015 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5// The <code>chrome.displaySource</code> API creates a Display
6// session using WebMediaStreamTrack as sources.
7namespace displaySource {
8  enum ErrorType {
9    // The connection with sink cannot be established or has dropped
10    // unexpectedly.
11    connection_error,
12
13    // The capabilities of this Display Source and the connected
14    // sink do not fit (e.g. the sink cannot play the media content of
15    // the formats given by the source).
16    capabilities_negotiation_error,
17
18    // There was an error in media pipeline: while encoding, packetizing or
19    // sending the media content.
20    media_pipeline_error,
21
22    // The sink became unresponsive.
23    timeout_error,
24
25    // Unspecified error.
26    unknown_error
27  };
28
29  dictionary ErrorInfo {
30    ErrorType type;
31    DOMString? description;
32  };
33
34  enum SinkState {
35    // Connected using this Display Source (i.e., there is an active session)
36    Connected,
37    // In process of connection to this Display Source
38    Connecting,
39    // Disconnected from this Display Source
40    Disconnected
41  };
42
43  dictionary SinkInfo {
44    // Id of the sink. It is guaranteed to be unique during the browser session.
45    long id;
46    // Human readable name of the sink.
47    DOMString name;
48    // State of the sink.
49    SinkState state;
50  };
51
52  enum AuthenticationMethod {
53    // Push Button Config authentication method.
54    PBC,
55    // PIN authentication method.
56    PIN
57  };
58
59  dictionary AuthenticationInfo {
60    // Authentication method.
61    AuthenticationMethod method;
62    // Authentication data (e.g. PIN value).
63    DOMString? data;
64  };
65
66  dictionary StartSessionInfo {
67    // Id of the sink to connect.
68    long sinkId;
69    // Authentication information.
70    AuthenticationInfo? authenticationInfo;
71    // The source audio track.
72    [instanceOf=MediaStreamTrack] object? audioTrack;
73    // The source audio track.
74    [instanceOf=MediaStreamTrack] object? videoTrack;
75  };
76
77  callback GetSinksCallback = void (SinkInfo[] result);
78  callback RequestAuthenticationCallback = void (AuthenticationInfo result);
79
80  // The callback is used by <code>startSession, terminateSession</code>
81  // to signal completion. The callback is called with
82  // <code>chrome.runtime.lastError</code> set to error
83  // message if the call has failed.
84  [inline_doc] callback CallCompleteCallback = void ();
85
86  interface Functions {
87    // Queries the list of the currently available Display sinks.
88    //
89    // |callback| : Called when the request is completed. The argument list
90    // is empty if no available sinks were found.
91    static void getAvailableSinks(GetSinksCallback callback);
92
93    // Queries authentication data from the sink device.
94    //
95    // |sinkId| : Id of the sink
96    // |callback| : Called when authentication info retrieved from the sink.
97    // The argument |method| field contains the authentication method required
98    // by the sink for connection; the |data| field can be null or can contain
99    // some supplementary data provided by the sink. If authentication info
100    // cannot be retrieved from the sink the "chrome.runtime.lastError" property
101    // is defined.
102    static void requestAuthentication(long sinkId,
103                                      RequestAuthenticationCallback callback);
104
105    // Creates a Display session using the provided StartSessionInfo instance.
106    // The input argument fields must be initialized as described below:
107    // The |sinkId|  must be a valid id of a sink (obtained via
108    // ‘getAvailableSinks’).
109    //
110    // The |audioTrack| or |videoTrack| must be of type MediaStreamTrack.
111    // Either |audioTrack| or |videoTrack| can be null but not both. This
112    // means creating a session with only audio or video.
113    //
114    // The |authenticationInfo| can be null if no additional authentication data
115    // are required by the sink; otherwise its |data| field must contain the
116    // required authentication data (e.g. PIN value) and its |method| field must
117    // be the same as one obtained from ‘requestAuthentication’.
118    // |callback| : Called when the session is started.
119    [nocompile] static void startSession(
120        StartSessionInfo sessionInfo, optional CallCompleteCallback callback);
121
122    // Terminates the active Display session.
123    // |sinkId| : Id of the connected sink.
124    // |callback| : Called when the session is terminated.
125    [nocompile] static void terminateSession(
126        long sinkId, optional CallCompleteCallback callback);
127  };
128
129  interface Events {
130    // Event fired when the available sinks are modified (either their amount
131    // or properties)
132    // |sinks| the list of all currently available sinks
133    static void onSinksUpdated(SinkInfo[] sinks);
134    // Event fired when the Display session is terminated.
135    // |sinkId| Id of the peer sink
136    [nocompile] static void onSessionTerminated(long sinkId);
137    // Event fired when an error occurs.
138    // |sinkId| Id of the peer sink
139    // |errorInfo| error description
140    [nocompile] static void onSessionErrorOccured(long sinkId,
141                                                  ErrorInfo errorInfo);
142  };
143};
144