1 // Copyright 2013 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 // Unspecified error. 46 unknown 47 }; 48 49 // Describes the state of a channel to a Cast receiver. 50 dictionary ChannelInfo { 51 // Id for the channel. 52 long channelId; 53 54 // The URL to the receiver. The URL should be of the form: 55 // cast://<IP>:<port> (for an unauthenticated channel) or 56 // casts://<IP>:<port> (for an authenticated channel). Name resolution is 57 // not currently supported for cast:// URLs, but may be added in the future. 58 DOMString url; 59 60 // The current state of the channel. 61 ReadyState readyState; 62 63 // If set, the last error condition encountered by the channel. 64 ChannelError? errorState; 65 }; 66 67 // Describes a message sent or received over the channel. Currently only 68 // string messages are supported, although ArrayBuffer and Blob types may be 69 // supported in the future. 70 dictionary MessageInfo { 71 // The message namespace. A namespace is a URN of the form 72 // urn:cast-x:<namespace> that is used to interpret and route Cast messages. 73 DOMString namespace_; 74 75 // source and destination ids identify the origin and destination of the 76 // message. They are used to route messages between endpoints that share a 77 // device-to-device channel. 78 // 79 // For messages between applications: 80 // - The sender application id is a unique identifier generated on behalf 81 // of the sender application. 82 // - The receiver id is always the the session id for the application. 83 // 84 // For messages to or from the sender or receiver platform, the special ids 85 // 'sender-0' and 'receiver-0' can be used. 86 // 87 // For messages intended for all endpoints using a given channel, the 88 // wildcard destination_id '*' can be used. 89 DOMString sourceId; 90 DOMString destinationId; 91 92 // The content of the message. Must be either a string or an ArrayBuffer. 93 any data; 94 }; 95 96 // Callback holding the result of a channel operation. 97 callback ChannelInfoCallback = void (ChannelInfo result); 98 99 interface Functions { 100 // Opens a new channel to the Cast receiver specified by the URL. Only one 101 // channel may be connected to the same URL from the same extension at a 102 // time. If the open request is successful, the callback will be invoked 103 // with a ChannelInfo with readyState == 'connecting'. If unsuccessful, the 104 // callback will be invoked with a ChannelInfo with channel.readyState == 105 // 'closed' and channel.errorState will be set to the error condition. 106 static void open(DOMString url, 107 ChannelInfoCallback callback); 108 109 // Sends a message on the channel and invokes callback with the resulting 110 // channel status. The channel must be in readyState == 'open'. If 111 // unsuccessful, channel.readyState will be set to 'closed', 112 // channel.errorState will be set to the error condition. 113 static void send(ChannelInfo channel, 114 MessageInfo message, 115 ChannelInfoCallback callback); 116 117 // Requests that the channel be closed and invokes callback with the 118 // resulting channel status. The channel must be in readyState == 'open' or 119 // 'connecting'. If successful, onClose will be fired with readyState == 120 // 'closed'. If unsuccessful, channel.readyState will be set to 'closed', 121 // and channel.errorState will be set to the error condition. 122 static void close(ChannelInfo channel, 123 ChannelInfoCallback callback); 124 }; 125 126 // Events on the channel. 127 interface Events { 128 // Fired when a message is received on an open channel. 129 static void onMessage(ChannelInfo channel, 130 MessageInfo message); 131 132 // Fired when an error occurs as a result of a channel method or a network 133 // event. 134 static void onError(ChannelInfo channel); 135 }; 136 }; 137
