Cast: Stop logging kVideoFrameSentToEncoder and rename a couple events.
[chromium-blink-merge.git] / chrome / common / extensions / api / cast_channel.idl
blobd034bf13790ecdd21526d68d184a7ad6ad5e58bf
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.
5 // API for communicating with a Google Cast device over an authenticated
6 // channel.
7 namespace cast.channel {
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
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
49 // Authentication methods that may be required to connect to a Cast receiver.
50 enum ChannelAuthType {
51 // SSL over TCP.
52 ssl,
53 // SSL over TCP with challenge and receiver signature verification.
54 ssl_verified
57 // Describes the information needed to connect to a Cast receiver.
58 // This replaces the prior use of cast:// and casts:// URLs.
59 dictionary ConnectInfo {
60 // The IPV4 address of the Cast receiver, e.g. '198.1.0.2'.
61 // TODO(mfoltz): Investigate whether IPV6 addresses "just work."
62 DOMString ipAddress;
64 // The port number to connect to, 0-65535.
65 long port;
67 // The authentication method required for the channel.
68 ChannelAuthType auth;
71 // Describes the state of a channel to a Cast receiver.
72 dictionary ChannelInfo {
73 // Id for the channel.
74 long channelId;
76 // DEPRECATED: The URL to the receiver. This field will be removed in a
77 // future release.
78 DOMString url;
80 // Connection information that was used to establish the channel to the
81 // receiver.
82 ConnectInfo connectInfo;
84 // The current state of the channel.
85 ReadyState readyState;
87 // If set, the last error condition encountered by the channel.
88 ChannelError? errorState;
91 // Describes a message sent or received over the channel. Currently only
92 // string messages are supported, although ArrayBuffer and Blob types may be
93 // supported in the future.
94 dictionary MessageInfo {
95 // The message namespace. A namespace is a URN of the form
96 // urn:cast-x:<namespace> that is used to interpret and route Cast messages.
97 DOMString namespace_;
99 // source and destination ids identify the origin and destination of the
100 // message. They are used to route messages between endpoints that share a
101 // device-to-device channel.
103 // For messages between applications:
104 // - The sender application id is a unique identifier generated on behalf
105 // of the sender application.
106 // - The receiver id is always the the session id for the application.
108 // For messages to or from the sender or receiver platform, the special ids
109 // 'sender-0' and 'receiver-0' can be used.
111 // For messages intended for all endpoints using a given channel, the
112 // wildcard destination_id '*' can be used.
113 DOMString sourceId;
114 DOMString destinationId;
116 // The content of the message. Must be either a string or an ArrayBuffer.
117 any data;
120 // Callback holding the result of a channel operation.
121 callback ChannelInfoCallback = void (ChannelInfo result);
123 interface Functions {
124 // Opens a new channel to the Cast receiver specified by connectInfo. Only
125 // one channel may be connected to same receiver from the same extension at
126 // a time. If the open request is successful, the callback will be invoked
127 // with a ChannelInfo with readyState == 'connecting'. If unsuccessful, the
128 // callback will be invoked with a ChannelInfo with channel.readyState ==
129 // 'closed' and channel.errorState will be set to the error condition.
131 // TODO(mfoltz): Convert 'any' to ConnectInfo once all clients are updated
132 // to not send URLs.
133 static void open(any connectInfo,
134 ChannelInfoCallback callback);
136 // Sends a message on the channel and invokes callback with the resulting
137 // channel status. The channel must be in readyState == 'open'. If
138 // unsuccessful, channel.readyState will be set to 'closed',
139 // channel.errorState will be set to the error condition.
140 static void send(ChannelInfo channel,
141 MessageInfo message,
142 ChannelInfoCallback callback);
144 // Requests that the channel be closed and invokes callback with the
145 // resulting channel status. The channel must be in readyState == 'open' or
146 // 'connecting'. If successful, onClose will be fired with readyState ==
147 // 'closed'. If unsuccessful, channel.readyState will be set to 'closed',
148 // and channel.errorState will be set to the error condition.
149 static void close(ChannelInfo channel,
150 ChannelInfoCallback callback);
153 // Events on the channel.
154 interface Events {
155 // Fired when a message is received on an open channel.
156 static void onMessage(ChannelInfo channel,
157 MessageInfo message);
159 // Fired when an error occurs as a result of a channel method or a network
160 // event.
161 static void onError(ChannelInfo channel);