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. 7 namespace 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