OLD | NEW |
---|---|
(Empty) | |
1 /* Copyright (c) 2011 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 | |
6 /** | |
7 * This file defines the <code>PPB_WebSocket_Dev</code> interface. | |
8 */ | |
9 label Chrome { | |
10 M17 = 0.1 | |
11 }; | |
12 | |
13 | |
14 /** | |
15 * This enumeration contains the types representing the WebSocket ready state | |
16 * and these states are based on the JavaScript WebSocket API specification. | |
17 * GetReadyState() returns one of these states. | |
18 */ | |
19 [assert_size(4)] | |
20 enum PP_WebSocketReadyState_Dev { | |
21 /** | |
22 * Ready state that the connection has not yet been established. | |
23 */ | |
24 PP_WEBSOCKETREADYSTATE_CONNECTING_DEV = 0, | |
25 | |
26 /** | |
27 * Ready state that the WebSocket connection is established and communication | |
28 * is possible. | |
29 */ | |
30 PP_WEBSOCKETREADYSTATE_OPEN_DEV = 1, | |
31 | |
32 /** | |
33 * Ready state that the connection is going through the closing handshake. | |
34 */ | |
35 PP_WEBSOCKETREADYSTATE_CLOSING_DEV = 2, | |
36 | |
37 /** | |
38 * Ready state that the connection has been closed or could not be opened. | |
39 */ | |
40 PP_WEBSOCKETREADYSTATE_CLOSED_DEV = 3 | |
41 }; | |
42 | |
43 /** | |
44 * This enumeration contains the types representing the WebSocket message type | |
45 * and these types are based on the JavaScript WebSocket API specification. | |
46 * ReceiveMessage() and SendMessage() use them as a parameter to represent | |
47 * handling message types. | |
48 */ | |
49 [assert_size(4)] | |
50 enum PP_WebSocketMessageType_Dev { | |
51 /** | |
52 * Message type that represents a text message type. | |
53 */ | |
54 PP_WEBSOCKET_MESSAGE_TYPE_TEXT_DEV = 0, | |
55 | |
56 /** | |
57 * Message type that represents a binary message type. | |
58 */ | |
59 PP_WEBSOCKET_MESSAGE_TYPE_BINARY_DEV = 1 | |
60 }; | |
61 | |
62 [version=0.1, macro="PPB_WEBSOCKET_DEV_INTERFACE"] | |
63 interface PPB_WebSocket_Dev { | |
64 /** | |
65 * Create() creates a WebSocket instance. | |
66 * | |
67 * @param[in] instance A <code>PP_Instance</code> identifying the instance | |
68 * with the WebSocket. | |
69 * | |
70 * @return A <code>PP_Resource</code> corresponding to a WebSocket if | |
71 * successful. | |
72 */ | |
73 PP_Resource Create([in] PP_Instance instance); | |
74 | |
75 /** | |
76 * IsWebSocket() determines if the provided <code>resource</code> is a | |
77 * WebSocket instance. | |
78 * | |
79 * @param[in] resource A <code>PP_Resource</code> corresponding to a | |
80 * WebSocket. | |
81 * | |
82 * @return Returns <code>PP_TRUE</code> if <code>resource</code> is a | |
83 * <code>PPB_WebSocket_Dev</code>, <code>PP_FALSE</code> if the | |
84 * <code>resource</code> is invalid or some type other than | |
85 * <code>PPB_WebSocket_Dev</code>. | |
86 */ | |
87 PP_Bool IsWebSocket([in] PP_Resource resource); | |
88 | |
89 /** | |
90 * Connect() connects to the specified WebSocket server. Caller can call this | |
91 * method at most once for a <code>web_socket</code>. | |
92 * | |
93 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
94 * WebSocket. | |
95 * | |
96 * @param[in] url A <code>PP_Var</code> representing a WebSocket server URL. | |
97 * The <code>PP_VarType</code> must be <code>PP_VARTYPE_STRING</code>. | |
98 * | |
99 * @param[in] protocols A pointer to an array of <code>PP_Var</code> | |
100 * specifying sub-protocols. Each <code>PP_Var</code> represents one | |
101 * sub-protocol and its <code>PP_VarType</code> must be | |
102 * <code>PP_VARTYPE_STRING</code>. This argument can be null only if | |
103 * <code>protocol_count</code> is 0. | |
104 * | |
105 * @param[in] protocol_count The number of sub-protocols in | |
106 * <code>protocols</code>. | |
107 * | |
108 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | |
109 * when the connection is established or an error occurs in establishing | |
110 * connection. | |
111 * | |
112 * @return In case of immediate failure, returns an error code as follows. | |
113 * Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript | |
114 * SyntaxError and <code>PP_ERROR_NOACCESS</code> corresponding to JavaScript | |
115 * SecurityError. Otherwise, returns <code>PP_OK_COMPLETIONPENDING</code> | |
116 * and invokes <code>callback</code> later. | |
117 */ | |
118 int32_t Connect([in] PP_Resource web_socket, | |
119 [in] PP_Var url, | |
120 [in, size_as=protocol_count] PP_Var[] protocols, | |
121 [in] uint32_t protocol_count, | |
122 [in] PP_CompletionCallback callback); | |
123 | |
124 /** | |
125 * Close() closes the specified WebSocket connection by specifying | |
126 * <code>code</code> and <code>reason</code>. | |
127 * | |
128 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
129 * WebSocket. | |
130 * | |
131 * @param[in] code The WebSocket close code. Ignored if it is 0. | |
132 * | |
133 * @param[in] reason A <code>PP_Var</code> which represents the WebSocket | |
134 * close reason. Ignored if it is <code>PP_VARTYPE_UNDEFINED</code>. | |
135 * Otherwise, its <code>PP_VarType</code> must be | |
136 * <code>PP_VARTYPE_STRING</code>. | |
137 * | |
138 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | |
139 * when the connection is closed or an error occurs in closing connection. | |
140 * | |
141 * @return In case of immediate failure, returns an error code as follows. | |
142 * Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript | |
143 * SyntaxError and <code>PP_ERROR_NOACCESS</code> corresponding to JavaScript | |
144 * InvalidAccessError. Otherwise, returns | |
145 * <code>PP_OK_COMPLETIONPENDING</code> and invokes <code>callback</code> | |
146 * later. | |
147 */ | |
148 int32_t Close([in] PP_Resource web_socket, | |
149 [in] uint16_t code, | |
150 [in] PP_Var reason, | |
151 [in] PP_CompletionCallback callback); | |
152 | |
153 /** | |
154 * ReceiveMessage() receives a message from the WebSocket server. | |
155 * This interface only returns bytes of a single message. That is, this | |
156 * interface must be called at least N times to receive N messages, no matter | |
157 * how small each message is. | |
158 * | |
159 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
160 * WebSocket. | |
161 * | |
162 * @param[out] message The received message is copied to provided | |
163 * <code>message</code>. | |
164 * | |
165 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | |
166 * when the receiving message is completed. It is ignored when the function | |
167 * return <code>PP_OK</code>. | |
168 * | |
169 * @return In case of immediate failure, returns | |
170 * <code>PP_ERROR_FAILED</code>. If a message is currently available, returns | |
171 * <code>PP_OK</code>. Otherwise, returns <PP_OK_COMPLETIONPENDING</code> | |
172 * and invokes <code>callback</code> later. At that case, if GetReadyState() | |
173 * returns <code>PP_WEBSOCKETREADYSTATE_OPEN</code>, the received | |
174 * message is also copied to procided <code>message</code>. Otherwise, | |
175 * the connection is closed and ReceiveMessage() failed to receive a message. | |
176 */ | |
177 int32_t ReceiveMessage([in] PP_Resource web_socket, | |
178 [out] PP_Var message, | |
179 [in] PP_CompletionCallback callback); | |
dmichael (off chromium)
2011/11/10 17:32:33
I mentioned before that I was a little worried abo
Takashi Toyoshima
2011/11/10 18:40:45
Receiving data could be automatically transmitted
| |
180 | |
181 /** | |
182 * SendMessage() sends a message to the WebSocket server. | |
183 * | |
184 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
185 * WebSocket. | |
186 * | |
187 * @param[in] message A message to send. The message is copied to internal | |
188 * buffer. So caller can free <code>message</code> safely after returning | |
189 * from the function. | |
190 * | |
191 * @return In case of immediate failure, returns an error code as follows. | |
192 * Returns <code>PP_ERROR_FAILED</code> corresponding to JavaScript | |
193 * InvalidStateError and <code>PP_ERROR_BADARGUMENT</code> corresponding to | |
194 * JavaScript SyntaxError. Otherwise, return <code>PP_OK</code>. | |
195 * <code>PP_OK</code> doesn't necessarily mean that the server received the | |
196 * message. | |
197 */ | |
198 int32_t SendMessage([in] PP_Resource web_socket, | |
199 [in] PP_Var message); | |
200 | |
201 /** | |
202 * GetBufferedAmount() returns the number of bytes of text and binary | |
203 * messages that have been queued for the WebSocket connection to send but | |
204 * have not been transmitted to the network yet. | |
205 * | |
206 * Note: This interface might not be able to return exact bytes in the first | |
207 * release. Current WebSocket implementation can not estimate exact protocol | |
208 * frame overheads. | |
209 * | |
210 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
211 * WebSocket. | |
212 * | |
213 * @return Returns the number of bytes. | |
214 */ | |
215 uint64_t GetBufferedAmount([in] PP_Resource web_socket); | |
216 | |
217 /** | |
218 * GetCloseCode() returns the connection close code for the WebSocket | |
219 * connection. | |
220 * | |
221 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
222 * WebSocket. | |
223 * | |
224 * @return Returns 0 if called before the close code is set. | |
225 */ | |
226 uint16_t GetCloseCode([in] PP_Resource web_socket); | |
227 | |
228 /** | |
229 * GetCloseReason() returns the connection close reason for the WebSocket | |
230 * connection. | |
231 * | |
232 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
233 * WebSocket. | |
234 * | |
235 * @return Returns a <code>PP_VARTYPE_NULL</code> var if called before the | |
236 * close reason is set, or <code>PP_VARTYPE_UNDEFINED</code> if called on an | |
237 * invalid resource. | |
238 */ | |
239 PP_Var GetCloseReason([in] PP_Resource web_socket); | |
240 | |
241 /** | |
242 * GetCloseWasClean() returns if the connection was closed cleanly for the | |
243 * specified WebSocket connection. | |
244 * | |
245 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
246 * WebSocket. | |
247 * | |
248 * @return Returns <code>PP_FALSE</code> if called before the connection is | |
249 * closed. Otherwise, returns <code>PP_TRUE</code> if the connection was | |
250 * closed cleanly and returns <code>PP_FALSE</code> if the connection was | |
251 * closed by abnormal reasons. | |
252 */ | |
253 PP_Bool GetCloseWasClean([in] PP_Resource web_socket); | |
254 | |
255 /** | |
256 * GetExtensions() returns the extensions selected by the server for the | |
257 * specified WebSocket connection. | |
258 * | |
259 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
260 * WebSocket. | |
261 * | |
262 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the | |
263 * connection is established or called on an invalid resource, its data is | |
264 * empty string. | |
265 * Currently its data is always empty string. | |
266 */ | |
267 PP_Var GetExtensions([in] PP_Resource web_socket); | |
268 | |
269 /** | |
270 * GetProtocol() returns the sub-protocol chosen by the server for the | |
271 * specified WebSocket connection. | |
272 * | |
273 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
274 * WebSocket. | |
275 * | |
276 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the | |
277 * connection is established, or called on an invalid resource, its data is | |
278 * empty string. | |
279 */ | |
280 PP_Var GetProtocol([in] PP_Resource web_socket); | |
281 | |
282 /** | |
283 * GetReadyState() returns the ready state of the specified WebSocket | |
284 * connection. | |
285 * | |
286 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
287 * WebSocket. | |
288 * | |
289 * @return Returns <code>PP_WEBSOCKETREADYSTATE_CONNECTING</code> if called | |
290 * before the connection is established. | |
291 */ | |
292 PP_WebSocketReadyState_Dev GetReadyState([in] PP_Resource web_socket); | |
293 | |
294 /** | |
295 * GetURL() returns the URL associated with specified WebSocket connection. | |
296 * | |
297 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
298 * WebSocket. | |
299 * | |
300 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the | |
301 * connection is established, or called on an invalid resource, its data is | |
302 * empty string. | |
303 */ | |
304 PP_Var GetURL([in] PP_Resource web_socket); | |
305 }; | |
OLD | NEW |