1// Copyright 2014 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// API for communicating with a Google Cast device over an authenticated
6// channel.
7namespace cast.channel {
8
9  // The state of the channel.
10  enum ReadyState {
11    // The channel is connecting.
12    connecting,
13    // The channel is open and available for messaging.
14    open,
15    // The channel is closing.
16    closing,
17    // The channel is closed.
18    closed
19  };
20
21  // Error conditions that the channel may encounter.  All error conditions
22  // are terminal.  When an error condition is encountered the API will:
23  // (1) Transition the channel to readyState == 'closed'.
24  // (2) Set ChannelInfo.lastError to the error condition.
25  // (3) Fire an onError event with the error condition.
26  // (4) Fire an onClose event.
27  enum ChannelError {
28    // cast.channel.send() was called when ChannelInfo.readyState != 'open'.
29    channel_not_open,
30    // Authentication was requested and the receiver could not be
31    // authenticated (invalid signature, invalid handhake, TLS error, etc.)
32    authentication_error,
33    // A new channel could not be created for reasons unrelated to
34    // authentication (e.g., there is already an open channel to the same URL).
35    connect_error,
36    // There was an error writing or reading from the underlying socket.
37    socket_error,
38    // A transport level occurred (like an unparseable message).
39    transport_error,
40    // The client attempted to send an unsupported message type through the
41    // channel.
42    invalid_message,
43    // An invalid channel id was passed.
44    invalid_channel_id,
45    // The connection could not be established before timing out.
46    connect_timeout,
47    // Unspecified error.
48    unknown
49  };
50
51  // Authentication methods that may be required to connect to a Cast receiver.
52  enum ChannelAuthType {
53    // SSL over TCP.
54    ssl,
55    // SSL over TCP with challenge and receiver signature verification.
56    ssl_verified
57  };
58
59  // Describes the information needed to connect to a Cast receiver.
60  // This replaces the prior use of cast:// and casts:// URLs.
61  dictionary ConnectInfo {
62    // The IPV4 address of the Cast receiver, e.g. '198.1.0.2'.
63    // TODO(mfoltz): Investigate whether IPV6 addresses "just work."
64    DOMString ipAddress;
65
66    // The port number to connect to, 0-65535.
67    long port;
68
69    // The amount of time to wait in milliseconds before stopping the
70    // connection process. Timeouts are disabled if the value is zero.
71    // The default timeout is 8000ms.
72    long? timeout;
73
74    // The authentication method required for the channel.
75    ChannelAuthType auth;
76  };
77
78  // Describes the state of a channel to a Cast receiver.
79  dictionary ChannelInfo {
80    // Id for the channel.
81    long channelId;
82
83    // DEPRECATED: The URL to the receiver.  This field will be removed in a
84    // future release.
85    DOMString url;
86
87    // Connection information that was used to establish the channel to the
88    // receiver.
89    ConnectInfo connectInfo;
90
91    // The current state of the channel.
92    ReadyState readyState;
93      
94    // If set, the last error condition encountered by the channel.
95    ChannelError? errorState;
96  };
97
98  // Describes a message sent or received over the channel.  Currently only
99  // string messages are supported, although ArrayBuffer and Blob types may be
100  // supported in the future.
101  dictionary MessageInfo {
102    // The message namespace.  A namespace is a URN of the form
103    // urn:cast-x:<namespace> that is used to interpret and route Cast messages.
104    DOMString namespace_;
105
106    // source and destination ids identify the origin and destination of the
107    // message.  They are used to route messages between endpoints that share a
108    // device-to-device channel.
109    //
110    // For messages between applications:
111    //   - The sender application id is a unique identifier generated on behalf
112    //     of the sender application.
113    //   - The receiver id is always the the session id for the application.
114    //
115    // For messages to or from the sender or receiver platform, the special ids
116    // 'sender-0' and 'receiver-0' can be used.
117    // 
118    // For messages intended for all endpoints using a given channel, the
119    // wildcard destination_id '*' can be used.
120    DOMString sourceId;
121    DOMString destinationId;
122
123    // The content of the message.  Must be either a string or an ArrayBuffer.
124    any data;
125  };
126
127  // Describes a terminal error encountered by the channel with details of the
128  // error that caused the channel to be closed.  One or more of the optional
129  // fields may be set with specific error codes from the underlying
130  // implementation.
131  dictionary ErrorInfo {
132    // The type of error encountered by the channel.
133    ChannelError errorState;
134
135    // The event that was occurring when the error happened.  Values are defined
136    // in the enum EventType in logging.proto.
137    long? eventType;
138
139    // An error encountered when processing the authentication handshake.
140    // Values are defined in the enum ChallengeReplyErrorType in logging.proto.
141    long? challengeReplyErrorType;
142
143    // A return value from the underlying net:: socket libraries. Values are
144    // defined in net/base/net_error_list.h.
145    long? netReturnValue;
146
147    // An error code returned by NSS. Values are defined in secerr.h.
148    long? nssErrorCode;
149  };
150
151  // Callback holding the result of a channel operation.
152  callback ChannelInfoCallback = void (ChannelInfo result);
153
154  // Callback from <code>getLogs</code> method.
155  // |log|: compressed serialized raw bytes containing the logs.
156  // The log is formatted using protocol buffer.
157  // See extensions/browser/api/cast_channel/logging.proto for definition.
158  // Compression is in gzip format.
159  callback GetLogsCallback = void (ArrayBuffer log);
160  
161  interface Functions {
162    // Opens a new channel to the Cast receiver specified by connectInfo.  Only
163    // one channel may be connected to same receiver from the same extension at
164    // a time.  If the open request is successful, the callback will be invoked
165    // with a ChannelInfo with readyState == 'connecting'.  If unsuccessful, the
166    // callback will be invoked with a ChannelInfo with channel.readyState ==
167    // 'closed', channel.errorState will be set to the error condition, and
168    // onError will be fired with error details.
169    //
170    // TODO(mfoltz): Convert 'any' to ConnectInfo once all clients are updated
171    // to not send URLs.
172    static void open(any connectInfo,
173                     ChannelInfoCallback callback);
174
175    // Sends a message on the channel and invokes callback with the resulting
176    // channel status.  The channel must be in readyState == 'open'.  If
177    // unsuccessful, channel.readyState will be set to 'closed',
178    // channel.errorState will be set to the error condition, and onError will
179    // be fired with error details.
180    static void send(ChannelInfo channel,
181                     MessageInfo message,
182                     ChannelInfoCallback callback);
183
184    // Requests that the channel be closed and invokes callback with the
185    // resulting channel status.  The channel must be in readyState == 'open' or
186    // 'connecting'.  If successful, onClose will be fired with readyState ==
187    // 'closed'.  If unsuccessful, channel.readyState will be set to 'closed',
188    // and channel.errorState will be set to the error condition.
189    static void close(ChannelInfo channel,
190                      ChannelInfoCallback callback);
191      
192    // Get logs in compressed serialized format. See GetLogsCallback for
193    // details.  
194    // |callback|: If successful, |callback| is invoked with data. Otherwise,
195    // an error will be raised.                
196    static void getLogs(GetLogsCallback callback);
197  };
198
199  // Events on the channel.
200  interface Events {
201    // Fired when a message is received on an open channel.
202    static void onMessage(ChannelInfo channel,
203                          MessageInfo message);
204
205    // Fired when an error occurs as a result of a channel operation or a
206    // network event. |error| contains details of the error.
207    static void onError(ChannelInfo channel, ErrorInfo error);
208  };
209};
210