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 * Note on the differences from JavaScript WebSocket API | |
10 * http://dev.w3.org/html5/websockets/ | |
11 * | |
12 * This interface has some differences from its JavaScript counterpart mainly | |
13 * to make best use of PP_CompletionCallback and be consistent with other | |
14 * interfaces such as PPB_Transport_Dev. | |
15 * | |
16 * - Constructor doesn't take URL or protocols and there is a method to | |
17 * establish connection. | |
18 * | |
19 * - Error handlers or close handlers cannot be registered. (A callback can be | |
20 * specified on explicitly closing a connection.) To detect an error or | |
21 * connection close, ready state, close cleanness, close code, and close reason | |
22 * should be queried instead. | |
23 * | |
24 * - Message size is represented as int32_t rather than uint64_t. | |
25 * PP_CompletionCallback handles int32_t better. Messages out of that range | |
26 * are too large to handle efficiently anyway. | |
27 * | |
28 * Note on error codes. | |
29 * | |
30 * Methods that take PP_CompletionCallback can return error codes. They | |
31 * correspond to JavaScript exceptions as follows: | |
32 * | |
33 * PP_ERROR_BADARGUMENT: SyntaxError | |
34 * PP_ERROR_NOACCESS: SecurityError, InvalidAccessError | |
35 * PP_ERROR_FAILED: InvalidStateError | |
36 * | |
37 * Other error codes such as PP_ERROR_ABORTED and PP_ERROR_BADRESOURCE can | |
38 * also be returned. | |
39 */ | |
40 label Chrome { | |
41 M16 = 0.1 | |
42 }; | |
43 | |
44 | |
45 /** | |
46 * This enumeration contains the types representing the WebSocket ready state | |
47 * and these states are based on the JavaScript WebSocket API specification. | |
48 * GetReadyState() returns one of these states. | |
49 */ | |
50 [assert_size(4)] | |
51 enum PP_WebSocketReadyState_Dev { | |
52 /** | |
53 * Ready state that the connection has not yet been established. | |
54 */ | |
55 PP_WEBSOCKETREADYSTATE_CONNECTING = 0, | |
56 | |
57 /** | |
58 * Ready state that the WebSocket connection is established and communication | |
59 * is possible. | |
60 */ | |
61 PP_WEBSOCKETREADYSTATE_OPEN = 1, | |
62 | |
63 /** | |
64 * Ready state that the connection is going through the closing handshake. | |
65 */ | |
66 PP_WEBSOCKETREADYSTATE_CLOSING = 2, | |
67 | |
68 /** | |
69 * Ready state that the connection has been closed or could not be opened. | |
70 */ | |
71 PP_WEBSOCKETREADYSTATE_CLOSED = 3 | |
72 }; | |
73 | |
74 /** | |
75 * This enumeration contains the types representing the WebSocket message type | |
76 * and these types are based on the JavaScript WebSocket API specification. | |
77 * ReceiveMessage() and SendMessage() use them as a parameter to represent | |
78 * handling message types. | |
79 */ | |
80 [assert_size(4)] | |
81 enum PP_WebSocketMessageType_Dev { | |
82 /** | |
83 * Message type that represents a text message type. | |
84 */ | |
85 PP_WEBSOCKET_MESSAGE_TYPE_TEXT = 0, | |
86 | |
87 /** | |
88 * Message type that represents a binary message type. | |
89 */ | |
90 PP_WEBSOCKET_MESSAGE_TYPE_BINARY = 1 | |
91 }; | |
92 | |
93 [version=0.1, macro="PPB_WEBSOCKET_DEV_INTERFACE"] | |
94 interface PPB_WebSocket_Dev { | |
95 /** | |
96 * Create() creates a WebSocket instance. | |
97 * | |
98 * @param[in] instance A <code>PP_Instance</code> identifying the instance | |
99 * with the WebSocket. | |
100 * | |
101 * @return A <code>PP_Resource</code> corresponding to a WebSocket if | |
102 * successful. | |
103 */ | |
104 PP_Resource Create([in] PP_Instance instance); | |
105 | |
106 /** | |
107 * IsWebSocket() determines if the provided <code>resource</code> is a | |
108 * WebSocket instance. | |
109 * | |
110 * @param[in] resource A <code>PP_Resource</code> corresponding to a | |
111 * WebSocket. | |
112 * | |
113 * @return Returns <code>PP_TRUE</code> if <code>resource</code> is a | |
114 * <code>PPB_WebSocket_Dev</code>, <code>PP_FALSE</code> if the | |
115 * <code>resource</code> is invalid or some type other than | |
116 * <code>PPB_WebSocket_Dev</code>. | |
117 */ | |
118 PP_Bool IsWebSocket([in] PP_Resource resource); | |
119 | |
120 /** | |
121 * SetCloseCallback() sets the callback which is called when the WebSocket | |
122 * connection is closed. | |
123 * Close code and reason should be queried via each interface. | |
124 * Caller can call this method safely only before calling Connect(). | |
125 * | |
126 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
127 * WebSocket. | |
128 * | |
129 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | |
130 * when the connection is closed. | |
131 * | |
132 * @return Returns <code>PP_OK</code>. | |
133 */ | |
134 int32_t SetCloseCallback([in] PP_Resource web_socket, | |
135 [in] PP_CompletionCallback callback); | |
136 | |
137 /** | |
138 * Connect() connects to the specified WebSocket server. Caller can call this | |
139 * method at most once for a <code>web_socket</code>. | |
140 * | |
141 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
142 * WebSocket. | |
143 * | |
144 * @param[in] url A <code>PP_Var</code> representing a WebSocket server URL. | |
145 * The <code>PP_VarType</code> must be <code>PP_VARTYPE_STRING</code>. | |
146 * | |
147 * @param[in] protocols A pointer to an array of <code>PP_Var</code> | |
148 * specifying sub-protocols. Each <code>PP_Var</code> represents one | |
149 * sub-protocol and its <code>PP_VarType</code> must be | |
150 * <code>PP_VARTYPE_STRING</code>. This argument can be null only if | |
151 * <code>protocol_count</code> is 0. | |
152 * | |
153 * @param[in] protocol_count The number of sub-protocols in | |
154 * <code>protocols</code>. | |
155 * | |
156 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | |
157 * when the connection is established or an error occurs. | |
158 * | |
159 * @return In case of immediate failure, returns an error code as follows. | |
160 * Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript | |
161 * SyntaxError and <code>PP_ERROR_NOACCESS</code> corresponding to JavaScript | |
162 * SecurityError. Otherwise, returns <code>PP_OK_COMPLETIONPENDING</code>. | |
163 */ | |
164 int32_t Connect([in] PP_Resource web_socket, | |
165 [in] PP_Var url, | |
166 [in, size_as=protocol_count] PP_Var[] protocols, | |
167 [in] uint32_t protocol_count, | |
168 [in] PP_CompletionCallback callback); | |
169 | |
170 /** | |
171 * Close() closes the specified WebSocket connection by specifying | |
172 * <code>code</code> and <code>reason</code>. | |
173 * | |
174 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
175 * WebSocket. | |
176 * | |
177 * @param[in] code The WebSocket close code. Ignored if it is 0. | |
178 * | |
179 * @param[in] reason A <code>PP_Var</code> which represents the WebSocket | |
180 * close reason. Ignored if it is <code>PP_VARTYPE_UNDEFINED</code>. | |
181 * Otherwise, its <code>PP_VarType</code> must be | |
182 * <code>PP_VARTYPE_STRING</code>. | |
183 * | |
184 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | |
185 * when the connection is closed or an error occurs. | |
186 * | |
187 * @return In case of immediate failure, returns an error code as follows. | |
188 * Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript | |
189 * SyntaxError and <code>PP_ERROR_NOACCESS</code> corresponding to JavaScript | |
Takashi Toyoshima
2011/10/27 09:07:38
fixed as spec says
| |
190 * InvalidAccessError. Otherwise, returns | |
191 * <code>PP_OK_COMPLETIONPENDING</code>. | |
192 */ | |
193 int32_t Close([in] PP_Resource web_socket, | |
194 [in] uint16_t code, | |
195 [in] PP_Var reason, | |
196 [in] PP_CompletionCallback callback); | |
197 | |
198 /** | |
199 * ReceiveMessage() receives a message from the WebSocket server. | |
200 * Caller must keep <code>message_bytes</code>, | |
201 * <code>remaining_message_byte_count</code>, and <code>message_type</code> | |
202 * valid until <code>callback</code> is issued or Close() is called. | |
203 * | |
204 * Note: This interface might be changed as follows. | |
205 * int32_t ReceiveMessage([in] PP_Resource web_socket, | |
206 * [out] PP_Var message, | |
207 * [out] int32_t remaining_message_byte_count, | |
208 * [in] PP_CompletionCallback callback); | |
209 * | |
210 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
211 * WebSocket. | |
212 * | |
213 * @param[out] message_bytes The message is copied to provided | |
214 * <code>message_bytes</code> up to <code>message_byte_count</code> bytes. | |
215 * <code>message_bytes</code> can be null only if | |
216 * <code>message_byte_count</code> is 0. | |
217 * In copying message to <code>message_bytes</code>, UTF-8 byte sequence | |
218 * boundaries are not considered. Hence if the message is larger than | |
219 * <code>message_bytes</code>, the last byte sequence may end prematurely. | |
220 * Likewise, the first sequence of the bytes returned for the subsequent call | |
221 * may start in the middle. | |
222 * | |
223 * @param[in] message_bytes_count The maximum receiving size in bytes. | |
224 * | |
225 * @param[out] remaining_byte_count The number of remaining bytes, if any, is | |
226 * set to <code>remaining_message_byte_count</code> if | |
227 * <code>remaining_message_byte_count</code> is not null. The remaining bytes | |
228 * of the message are returned for subsequent call(s) to this method. | |
229 * | |
230 * @param[out] message_type A <code>PP_WebSocketMessageType_Dev</code> | |
231 * representing the message type is set to <code>message_type</code> if | |
232 * <code>message_type</code> is not null. If the message is text, it is | |
233 * encoded in UTF-8. | |
234 * | |
235 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | |
236 * if the interface has been returned<code>PP_OK_COMPLETIONPENDING</code>. | |
237 * The number of bytes copied is passed as the second argument. | |
238 * | |
239 * @return If a message is currently available, returns the number of bytes | |
240 * copied to <code>message_bytes</code>. Otherwise, returns | |
241 * <code>PP_OK_COMPLETIONPENDING</code> and calls <code>callback</code> when | |
242 * the message is available. | |
243 * Messages are queued internally. Hence this method can be called either | |
244 * before or after a message is received by the browser. If the queue grows | |
245 * beyond the browser-dependent limit, <code>web_socket</code> is closed and | |
246 * messages are discarded. | |
247 * This interface only returns bytes of a single message. That is, this | |
248 * interface must be called at least N times to receive N messages, no matter | |
249 * how small each message is. | |
250 */ | |
251 int32_t ReceiveMessage([in] PP_Resource web_socket, | |
252 [out,size_as=message_byte_count] void message_bytes, | |
253 [in] int32_t message_byte_count, | |
254 [out] int32_t remaining_message_byte_count, | |
255 [out] PP_WebSocketMessageType_Dev message_type, | |
256 [in] PP_CompletionCallback callback); | |
257 | |
258 /** | |
259 * SendMessage() sends a message to the WebSocket server. | |
260 * | |
261 * Note: This interface might be changed as follows. | |
262 * int32_t SendMessage([in] PP_Resource web_socket, | |
263 * [in] PP_Var message); | |
264 * | |
265 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
266 * WebSocket. | |
267 * | |
268 * @param[in] message_bytes A message to send. The message is copied to | |
269 * internal buffer. So caller can free <code>message_bytes</code> safely | |
270 * after returning from the function. | |
271 * | |
272 * @param[in] message_byte_count The length of the message in bytes. | |
273 * | |
274 * @param[in] message_type A <code>PP_WebSocketMessageType_Dev</code> | |
275 * representing the message type of the <code>message</code>. | |
276 * | |
277 * @return In case of immediate failure, returns an error code as follows. | |
278 * Returns <code>PP_ERROR_FAILED</code> corresponding JavaScript | |
279 * InvalidStateError and <code>PP_ERROR_BADARGUMENT</code> corresponding | |
280 * JavaScript SyntaxError. Otherwise, return <code>PP_OK</code>. | |
281 * <code>PP_OK</code> doesn't necessarily mean that the server received the | |
282 * message. | |
283 */ | |
284 int32_t SendMessage([in] PP_Resource web_socket, | |
285 [in,size_as=message_byte_count] void[] message_bytes, | |
286 [in] int32_t message_byte_count, | |
287 [in] PP_WebSocketMessageType_Dev message_type); | |
288 | |
289 /** | |
290 * GetBufferedAmount() returns the number of bytes of text and binary | |
291 * messages that have been queued for the WebSocket connection to send but | |
292 * have not been transmitted to the network yet. | |
293 * | |
294 * Note: This interface might not be able to return exact bytes in the first | |
295 * release. | |
296 * | |
297 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
298 * WebSocket. | |
299 * | |
300 * @return Returns the number of bytes. | |
301 */ | |
302 uint64_t GetBufferedAmount([in] PP_Resource web_socket); | |
303 | |
304 /** | |
305 * GetCloseCode() returns the connection close code for the WebSocket | |
306 * connection. | |
307 * | |
308 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
309 * WebSocket. | |
310 * | |
311 * @return Returns 0 if called before the close code is set. | |
312 */ | |
313 uint16_t GetCloseCode([in] PP_Resource web_socket); | |
314 | |
315 /** | |
316 * GetCloseReason() returns the connection close reason for the WebSocket | |
317 * connection. | |
318 * | |
319 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
320 * WebSocket. | |
321 * | |
322 * @return Returns a <code>PP_VARTYPE_NULL</code> var if called before the | |
323 * close reason is set, or <code>PP_VARTYPE_UNDEFINED</code> if called on an | |
324 * invalid resource. | |
325 */ | |
326 PP_Var GetCloseReason([in] PP_Resource web_socket); | |
327 | |
328 /** | |
329 * GetCloseWasClean() returns if the connection was closed cleanly for the | |
330 * specified WebSocket connection. | |
331 * | |
332 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
333 * WebSocket. | |
334 * | |
335 * @return Returns <code>PP_FALSE</code> if called before the connection is | |
336 * closed. Otherwise, returns <code>PP_TRUE</code> if the connection was | |
337 * closed cleanly and returns <code>PP_FALSE</code> if the connection was | |
338 * closed by abnormal reasons. | |
339 */ | |
340 PP_Bool GetCloseWasClean([in] PP_Resource web_socket); | |
341 | |
342 /** | |
343 * GetExtensions() returns the extensions selected by the server for the | |
344 * specified WebSocket connection. | |
345 * | |
346 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
347 * WebSocket. | |
348 * | |
349 * @return Returns a <code>PP_VARTYPE_NULL</code> var if called before the | |
350 * connection is established, or <code>PP_VARTYPE_UNDEFINED</code> if called | |
351 * on an invalid resource. | |
352 */ | |
353 PP_Var GetExtensions([in] PP_Resource web_socket); | |
354 | |
355 /** | |
356 * GetProtocol() returns the sub-protocol chosen by the server for the | |
357 * specified WebSocket connection. | |
358 * | |
359 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
360 * WebSocket. | |
361 * | |
362 * @return Returns a <code>PP_VARTYPE_NULL</code> var if called before the | |
363 * connection is established, or <code>PP_VARTYPE_UNDEFINED</code> if called | |
364 * on an invalid resource. | |
365 */ | |
366 PP_Var GetProtocol([in] PP_Resource web_socket); | |
367 | |
368 /** | |
369 * GetReadyState() returns the ready state of the specified WebSocket | |
370 * connection. | |
371 * | |
372 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
373 * WebSocket. | |
374 * | |
375 * @return Returns <code>PP_WEBSOCKETREADYSTATE_CONNECTING</code> if called | |
376 * before the connection is established. | |
377 */ | |
378 PP_WebSocketReadyState_Dev GetReadyState([in] PP_Resource web_socket); | |
379 | |
380 /** | |
381 * GetUrl() returns the URL associated with specified WebSocket connection. | |
382 * | |
383 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
384 * WebSocket. | |
385 * | |
386 * @return Returns a <code>PP_VARTYPE_NULL</code> var if called before the | |
387 * connection is established, or <code>PP_VARTYPE_UNDEFINED</code> if called | |
388 * on an invalid resource. | |
389 */ | |
390 PP_Var GetUrl([in] PP_Resource web_socket); | |
391 }; | |
OLD | NEW |