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 M16 = 0.1 | |
cstefansen
2011/11/01 17:58:15
Note: We should plan to pull it out of dev for M17
Takashi Toyoshima
2011/11/02 09:23:42
I guess IDL generator doesn't support M17 yet.
Fir
dmichael (off chromium)
2011/11/02 16:14:40
noelallen
Takashi Toyoshima
2011/11/04 08:45:55
Thanks.
I pinged him with change http://codereview
| |
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 = 0, | |
dmichael (off chromium)
2011/11/01 21:03:24
We've had problems in the past when transitioning
Takashi Toyoshima
2011/11/02 09:23:42
Done.
| |
25 | |
26 /** | |
27 * Ready state that the WebSocket connection is established and communication | |
28 * is possible. | |
29 */ | |
30 PP_WEBSOCKETREADYSTATE_OPEN = 1, | |
31 | |
32 /** | |
33 * Ready state that the connection is going through the closing handshake. | |
34 */ | |
35 PP_WEBSOCKETREADYSTATE_CLOSING = 2, | |
36 | |
37 /** | |
38 * Ready state that the connection has been closed or could not be opened. | |
39 */ | |
40 PP_WEBSOCKETREADYSTATE_CLOSED = 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 = 0, | |
55 | |
56 /** | |
57 * Message type that represents a binary message type. | |
58 */ | |
59 PP_WEBSOCKET_MESSAGE_TYPE_BINARY = 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 * SetOpenCallback() sets the callback which is called when the WebSocket | |
91 * connection is opened. This callback corresponds to onopen event of | |
92 * JavaScript API. | |
93 * Caller can call this method safely only before calling Connect(). | |
94 * | |
95 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
96 * WebSocket. | |
97 * | |
98 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | |
99 * when the connection is opened. | |
100 * | |
101 * @return Returns <code>PP_OK</code>. | |
102 */ | |
103 int32_t SetOpenCallback([in] PP_Resource web_socket, | |
darin (slow to review)
2011/11/01 17:40:53
How about just passing a PP_CompletionCallback to
Takashi Toyoshima
2011/11/02 09:23:42
I think Darin's suggest is good for IDL and C inte
dmichael (off chromium)
2011/11/02 16:14:40
I'm not sure what you mean, but it might be intere
cstefansen
2011/11/02 16:23:30
Personally, I think having an API that is natural
Takashi Toyoshima
2011/11/04 08:45:55
Thank you for advices.
I understand that my previo
dmichael (off chromium)
2011/11/04 15:26:18
This is true for now, but I'm (slowly) working on
| |
104 [in] PP_CompletionCallback callback); | |
105 | |
106 /** | |
107 * SetMessageCallback() sets the callback which is called when the WebSocket | |
108 * connection receives a frame. This callback corresponds to onmessage event | |
109 * of JavaScript API. | |
110 * Callback is invoked when the next frame can be read via ReceiveMessage(). | |
111 * Caller can call this method safely only before calling Connect(). | |
112 * | |
113 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
114 * WebSocket. | |
115 * | |
116 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | |
117 * when the connection receives a frame. | |
118 * | |
119 * @return Returns <code>PP_OK</code>. | |
120 */ | |
121 int32_t SetMessageCallback([in] PP_Resource web_socket, | |
darin (slow to review)
2011/11/01 17:40:53
Have you considered just passing a PP_CompletionCa
cstefansen
2011/11/01 18:08:51
This slightly incongruent with the JS version whic
Takashi Toyoshima
2011/11/02 09:23:42
See comment at SetOpenCallback.
| |
122 [in] PP_CompletionCallback callback); | |
123 | |
124 /** | |
125 * SetErrorCallback() sets the callback which is called when the WebSocket | |
126 * connection is closed with prejudice. This callback corresponds to onclose | |
127 * event of JavaScript API. | |
128 * Caller can call this method safely only before calling Connect(). | |
129 * | |
130 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
131 * WebSocket. | |
132 * | |
133 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | |
134 * when the connection receives a frame. | |
135 * | |
136 * @return Returns <code>PP_OK</code>. | |
137 */ | |
138 int32_t SetErrorCallback([in] PP_Resource web_socket, | |
darin (slow to review)
2011/11/01 17:40:53
It seems like this should not be necessary. error
Takashi Toyoshima
2011/11/02 09:23:42
See comment at SetOpenCallback.
| |
139 [in] PP_CompletionCallback callback); | |
140 | |
141 /** | |
142 * SetCloseCallback() sets the callback which is called when the WebSocket | |
143 * connection is closed. This callback corresponds to onclose event of | |
144 * JavaScript API. | |
145 * Close code and reason should be queried via each interface. | |
146 * Caller can call this method safely only before calling Connect(). | |
147 * | |
148 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
149 * WebSocket. | |
150 * | |
151 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | |
152 * when the connection is closed. | |
153 * | |
154 * @return Returns <code>PP_OK</code>. | |
155 */ | |
156 int32_t SetCloseCallback([in] PP_Resource web_socket, | |
darin (slow to review)
2011/11/01 17:40:53
Ditto. I'd just get rid of this in favor of using
cstefansen
2011/11/01 18:08:51
How would you know that the connection closed if y
dmichael (off chromium)
2011/11/01 21:03:24
Another thing to note, though, is that it doesn't
Takashi Toyoshima
2011/11/02 09:23:42
See comment at SetOpenCallback.
| |
157 [in] PP_CompletionCallback callback); | |
158 | |
159 /** | |
160 * Connect() connects to the specified WebSocket server. Caller can call this | |
161 * method at most once for a <code>web_socket</code>. | |
162 * | |
163 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
164 * WebSocket. | |
165 * | |
166 * @param[in] url A <code>PP_Var</code> representing a WebSocket server URL. | |
167 * The <code>PP_VarType</code> must be <code>PP_VARTYPE_STRING</code>. | |
168 * | |
169 * @param[in] protocols A pointer to an array of <code>PP_Var</code> | |
170 * specifying sub-protocols. Each <code>PP_Var</code> represents one | |
171 * sub-protocol and its <code>PP_VarType</code> must be | |
172 * <code>PP_VARTYPE_STRING</code>. This argument can be null only if | |
173 * <code>protocol_count</code> is 0. | |
174 * | |
175 * @param[in] protocol_count The number of sub-protocols in | |
176 * <code>protocols</code>. | |
177 * | |
178 * @return In case of immediate failure, returns an error code as follows. | |
179 * Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript | |
180 * SyntaxError and <code>PP_ERROR_NOACCESS</code> corresponding to JavaScript | |
181 * SecurityError. Otherwise, returns <code>PP_OK</code>. | |
182 */ | |
183 int32_t Connect([in] PP_Resource web_socket, | |
184 [in] PP_Var url, | |
185 [in, size_as=protocol_count] PP_Var[] protocols, | |
186 [in] uint32_t protocol_count); | |
187 | |
188 /** | |
189 * Close() closes the specified WebSocket connection by specifying | |
190 * <code>code</code> and <code>reason</code>. | |
191 * | |
192 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
193 * WebSocket. | |
194 * | |
195 * @param[in] code The WebSocket close code. Ignored if it is 0. | |
196 * | |
197 * @param[in] reason A <code>PP_Var</code> which represents the WebSocket | |
198 * close reason. Ignored if it is <code>PP_VARTYPE_UNDEFINED</code>. | |
199 * Otherwise, its <code>PP_VarType</code> must be | |
200 * <code>PP_VARTYPE_STRING</code>. | |
201 * | |
202 * @return In case of immediate failure, returns an error code as follows. | |
203 * Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript | |
204 * SyntaxError and <code>PP_ERROR_NOACCESS</code> corresponding to JavaScript | |
205 * InvalidAccessError. Otherwise, returns | |
206 * <code>PP_OK</code>. | |
207 */ | |
208 int32_t Close([in] PP_Resource web_socket, | |
209 [in] uint16_t code, | |
210 [in] PP_Var reason); | |
211 | |
212 /** | |
213 * ReceiveMessage() receives a message from the WebSocket server. | |
214 * This interface only returns bytes of a single message. That is, this | |
215 * interface must be called at least N times to receive N messages, no matter | |
216 * how small each message is. | |
217 * | |
218 * Note: This interface might be changed as follows. | |
219 * int32_t ReceiveMessage([in] PP_Resource web_socket, | |
220 * [out] PP_Var message, | |
221 * [out] int32_t remaining_message_byte_count); | |
222 * | |
223 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
224 * WebSocket. | |
225 * | |
226 * @param[out] message_bytes The message is copied to provided | |
227 * <code>message_bytes</code> up to <code>message_byte_count</code> bytes. | |
228 * <code>message_bytes</code> can be null only if | |
229 * <code>message_byte_count</code> is 0. | |
230 * In copying message to <code>message_bytes</code>, UTF-8 byte sequence | |
231 * boundaries are not considered. Hence if the message is larger than | |
232 * <code>message_bytes</code>, the last byte sequence may end prematurely. | |
233 * Likewise, the first sequence of the bytes returned for the subsequent call | |
234 * may start in the middle. | |
235 * | |
236 * @param[in] message_bytes_count The maximum receiving size in bytes. | |
237 * | |
238 * @param[out] remaining_byte_count The number of remaining bytes, if any, is | |
239 * set to <code>remaining_message_byte_count</code> if | |
240 * <code>remaining_message_byte_count</code> is not null. The remaining bytes | |
241 * of the message are returned for subsequent call(s) to this method. | |
242 * | |
243 * @param[out] message_type A <code>PP_WebSocketMessageType_Dev</code> | |
244 * representing the message type is set to <code>message_type</code> if | |
245 * <code>message_type</code> is not null. If the message is text, it is | |
246 * encoded in UTF-8. | |
247 * | |
248 * @return If a message is currently available, returns the number of bytes | |
249 * copied to <code>message_bytes</code>. Otherwise, returns 0. | |
250 * Frame boundaries must be detected by <code>remaining_byte_count</code>. | |
251 * If the next message is available as a result, registerd callback by | |
252 * SetMessageCallback() will be invoked. | |
253 * Messages are queued internally. Hence this method can be called either | |
254 * before or after a message is received by the browser. If the queue grows | |
255 * beyond the browser-dependent limit, <code>web_socket</code> is closed and | |
256 * messages are discarded. | |
257 */ | |
258 int32_t ReceiveMessage([in] PP_Resource web_socket, | |
259 [out,size_as=message_byte_count] void message_bytes, | |
darin (slow to review)
2011/11/01 17:40:53
in the comments, the out param for the message is
dmichael (off chromium)
2011/11/01 21:03:24
Right. The JS spec uses MessageEvent, of which we
Takashi Toyoshima
2011/11/02 09:23:42
Darin,
The only reason why I avoid to use PP_Var i
| |
260 [in] int32_t message_byte_count, | |
261 [out] int32_t remaining_message_byte_count, | |
262 [out] PP_WebSocketMessageType_Dev message_type); | |
dmichael (off chromium)
2011/11/01 21:03:24
I think based on how I'm reading the spec, we need
Takashi Toyoshima
2011/11/02 09:23:42
In JS API, Chrome/WebKit appends origin field to t
dmichael (off chromium)
2011/11/02 16:14:40
I suspect you're right, that it's not needed. I br
| |
263 | |
264 /** | |
265 * SendMessage() sends a message to the WebSocket server. | |
266 * | |
267 * Note: This interface might be changed as follows. | |
268 * int32_t SendMessage([in] PP_Resource web_socket, | |
269 * [in] PP_Var message); | |
270 * | |
271 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
272 * WebSocket. | |
273 * | |
274 * @param[in] message_bytes A message to send. The message is copied to | |
275 * internal buffer. So caller can free <code>message_bytes</code> safely | |
276 * after returning from the function. | |
277 * | |
278 * @param[in] message_byte_count The length of the message in bytes. | |
279 * | |
280 * @param[in] message_type A <code>PP_WebSocketMessageType_Dev</code> | |
281 * representing the message type of the <code>message</code>. | |
282 * | |
283 * @return In case of immediate failure, returns an error code as follows. | |
284 * Returns <code>PP_ERROR_FAILED</code> corresponding JavaScript | |
285 * InvalidStateError and <code>PP_ERROR_BADARGUMENT</code> corresponding | |
286 * JavaScript SyntaxError. Otherwise, return <code>PP_OK</code>. | |
287 * <code>PP_OK</code> doesn't necessarily mean that the server received the | |
288 * message. | |
289 */ | |
290 int32_t SendMessage([in] PP_Resource web_socket, | |
291 [in,size_as=message_byte_count] void[] message_bytes, | |
292 [in] int32_t message_byte_count, | |
darin (slow to review)
2011/11/01 17:40:53
ditto. using PP_Var for the message seems like a
Takashi Toyoshima
2011/11/02 09:23:42
Yes. I'd like to use PP_Var.
Please increase the p
| |
293 [in] PP_WebSocketMessageType_Dev message_type); | |
294 | |
295 /** | |
296 * GetBufferedAmount() returns the number of bytes of text and binary | |
297 * messages that have been queued for the WebSocket connection to send but | |
298 * have not been transmitted to the network yet. | |
299 * | |
300 * Note: This interface might not be able to return exact bytes in the first | |
301 * release. | |
302 * | |
303 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
304 * WebSocket. | |
305 * | |
306 * @return Returns the number of bytes. | |
307 */ | |
308 uint64_t GetBufferedAmount([in] PP_Resource web_socket); | |
darin (slow to review)
2011/11/01 17:40:53
be mindful that all of these getters will need to
cstefansen
2011/11/01 18:08:51
That doesn't seem very performant. Is there an alt
Takashi Toyoshima
2011/11/02 09:23:42
I see.
Do you have any plan to support synchronous
dmichael (off chromium)
2011/11/02 16:14:40
We try to avoid using synchronous IPC in the proxy
Takashi Toyoshima
2011/11/04 08:45:55
OK, I'll try to implement it without IPC.
I think
| |
309 | |
310 /** | |
311 * GetCloseCode() returns the connection close code for the WebSocket | |
312 * connection. | |
313 * | |
314 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
315 * WebSocket. | |
316 * | |
317 * @return Returns 0 if called before the close code is set. | |
318 */ | |
319 uint16_t GetCloseCode([in] PP_Resource web_socket); | |
320 | |
321 /** | |
322 * GetCloseReason() returns the connection close reason for the WebSocket | |
323 * connection. | |
324 * | |
325 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
326 * WebSocket. | |
327 * | |
328 * @return Returns a <code>PP_VARTYPE_NULL</code> var if called before the | |
329 * close reason is set, or <code>PP_VARTYPE_UNDEFINED</code> if called on an | |
330 * invalid resource. | |
331 */ | |
332 PP_Var GetCloseReason([in] PP_Resource web_socket); | |
333 | |
334 /** | |
335 * GetCloseWasClean() returns if the connection was closed cleanly for the | |
336 * specified WebSocket connection. | |
337 * | |
338 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
339 * WebSocket. | |
340 * | |
341 * @return Returns <code>PP_FALSE</code> if called before the connection is | |
342 * closed. Otherwise, returns <code>PP_TRUE</code> if the connection was | |
343 * closed cleanly and returns <code>PP_FALSE</code> if the connection was | |
344 * closed by abnormal reasons. | |
345 */ | |
346 PP_Bool GetCloseWasClean([in] PP_Resource web_socket); | |
347 | |
348 /** | |
349 * GetExtensions() returns the extensions selected by the server for the | |
350 * specified WebSocket connection. | |
dmichael (off chromium)
2011/11/01 21:03:24
It would probably be good to mention that this is
Takashi Toyoshima
2011/11/02 09:23:42
Oh, I see.
That will be better.
| |
351 * | |
352 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
353 * WebSocket. | |
354 * | |
355 * @return Returns a <code>PP_VARTYPE_NULL</code> var if called before the | |
dmichael (off chromium)
2011/11/01 21:03:24
The spec says "must initially return the empty str
Takashi Toyoshima
2011/11/02 09:23:42
Yes.
| |
356 * connection is established, or <code>PP_VARTYPE_UNDEFINED</code> if called | |
357 * on an invalid resource. | |
358 */ | |
359 PP_Var GetExtensions([in] PP_Resource web_socket); | |
360 | |
361 /** | |
362 * GetProtocol() returns the sub-protocol chosen by the server for the | |
363 * specified WebSocket connection. | |
364 * | |
365 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
366 * WebSocket. | |
367 * | |
368 * @return Returns a <code>PP_VARTYPE_NULL</code> var if called before the | |
dmichael (off chromium)
2011/11/01 21:03:24
Same here, I would suggest returning the empty str
Takashi Toyoshima
2011/11/02 09:23:42
Ditto.
| |
369 * connection is established, or <code>PP_VARTYPE_UNDEFINED</code> if called | |
370 * on an invalid resource. | |
371 */ | |
372 PP_Var GetProtocol([in] PP_Resource web_socket); | |
373 | |
374 /** | |
375 * GetReadyState() returns the ready state of the specified WebSocket | |
376 * connection. | |
377 * | |
378 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
379 * WebSocket. | |
380 * | |
381 * @return Returns <code>PP_WEBSOCKETREADYSTATE_CONNECTING</code> if called | |
382 * before the connection is established. | |
383 */ | |
384 PP_WebSocketReadyState_Dev GetReadyState([in] PP_Resource web_socket); | |
385 | |
386 /** | |
387 * GetUrl() returns the URL associated with specified WebSocket connection. | |
388 * | |
389 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
390 * WebSocket. | |
391 * | |
392 * @return Returns a <code>PP_VARTYPE_NULL</code> var if called before the | |
393 * connection is established, or <code>PP_VARTYPE_UNDEFINED</code> if called | |
394 * on an invalid resource. | |
395 */ | |
396 PP_Var GetUrl([in] PP_Resource web_socket); | |
darin (slow to review)
2011/11/01 17:40:53
nit: GetURL
Takashi Toyoshima
2011/11/02 09:23:42
Done.
| |
397 }; | |
OLD | NEW |