OLD | NEW |
| (Empty) |
1 /* Copyright (c) 2012 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 M18 = 0.9 | |
12 }; | |
13 | |
14 | |
15 /** | |
16 * This enumeration contains the types representing the WebSocket ready state | |
17 * and these states are based on the JavaScript WebSocket API specification. | |
18 * GetReadyState() returns one of these states. | |
19 */ | |
20 [assert_size(4)] | |
21 enum PP_WebSocketReadyState_Dev { | |
22 /** | |
23 * Ready state is queried on an invalid resource. | |
24 */ | |
25 PP_WEBSOCKETREADYSTATE_INVALID_DEV = -1, | |
26 /** | |
27 * Ready state that the connection has not yet been established. | |
28 */ | |
29 PP_WEBSOCKETREADYSTATE_CONNECTING_DEV = 0, | |
30 | |
31 /** | |
32 * Ready state that the WebSocket connection is established and communication | |
33 * is possible. | |
34 */ | |
35 PP_WEBSOCKETREADYSTATE_OPEN_DEV = 1, | |
36 | |
37 /** | |
38 * Ready state that the connection is going through the closing handshake. | |
39 */ | |
40 PP_WEBSOCKETREADYSTATE_CLOSING_DEV = 2, | |
41 | |
42 /** | |
43 * Ready state that the connection has been closed or could not be opened. | |
44 */ | |
45 PP_WEBSOCKETREADYSTATE_CLOSED_DEV = 3 | |
46 }; | |
47 | |
48 /** | |
49 * This enumeration contains the types representing the WebSocket binary type | |
50 * to receive frames. These types are based on the JavaScript WebSocket API | |
51 * specification. | |
52 */ | |
53 [assert_size(4)] | |
54 enum PP_WebSocketBinaryType_Dev { | |
55 /** | |
56 * Binary type is queried on an invalid resource. | |
57 */ | |
58 PP_WEBSOCKETBINARYTYPE_INVALID = -1, | |
59 | |
60 /** | |
61 * Binary type that represents Blob objects. | |
62 */ | |
63 PP_WEBSOCKETBINARYTYPE_BLOB_DEV = 0, | |
64 | |
65 /** | |
66 * Binary type that represents ArrayBuffer objects. | |
67 */ | |
68 PP_WEBSOCKETBINARYTYPE_ARRAYBUFFER_DEV = 1 | |
69 }; | |
70 | |
71 interface PPB_WebSocket_Dev { | |
72 /** | |
73 * Create() creates a WebSocket instance. | |
74 * | |
75 * @param[in] instance A <code>PP_Instance</code> identifying the instance | |
76 * with the WebSocket. | |
77 * | |
78 * @return A <code>PP_Resource</code> corresponding to a WebSocket if | |
79 * successful. | |
80 */ | |
81 PP_Resource Create([in] PP_Instance instance); | |
82 | |
83 /** | |
84 * IsWebSocket() determines if the provided <code>resource</code> is a | |
85 * WebSocket instance. | |
86 * | |
87 * @param[in] resource A <code>PP_Resource</code> corresponding to a | |
88 * WebSocket. | |
89 * | |
90 * @return Returns <code>PP_TRUE</code> if <code>resource</code> is a | |
91 * <code>PPB_WebSocket_Dev</code>, <code>PP_FALSE</code> if the | |
92 * <code>resource</code> is invalid or some type other than | |
93 * <code>PPB_WebSocket_Dev</code>. | |
94 */ | |
95 PP_Bool IsWebSocket([in] PP_Resource resource); | |
96 | |
97 /** | |
98 * Connect() connects to the specified WebSocket server. Caller can call this | |
99 * method at most once for a <code>web_socket</code>. | |
100 * | |
101 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
102 * WebSocket. | |
103 * | |
104 * @param[in] url A <code>PP_Var</code> representing a WebSocket server URL. | |
105 * The <code>PP_VarType</code> must be <code>PP_VARTYPE_STRING</code>. | |
106 * | |
107 * @param[in] protocols A pointer to an array of <code>PP_Var</code> | |
108 * specifying sub-protocols. Each <code>PP_Var</code> represents one | |
109 * sub-protocol and its <code>PP_VarType</code> must be | |
110 * <code>PP_VARTYPE_STRING</code>. This argument can be null only if | |
111 * <code>protocol_count</code> is 0. | |
112 * | |
113 * @param[in] protocol_count The number of sub-protocols in | |
114 * <code>protocols</code>. | |
115 * | |
116 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | |
117 * when a connection is established or an error occurs in establishing | |
118 * connection. | |
119 * | |
120 * @return An int32_t containing an error code from <code>pp_errors.h</code>. | |
121 * Returns <code>PP_ERROR_BADARGUMENT</code> if specified <code>url</code>, | |
122 * or <code>protocols</code> contains invalid string as | |
123 * <code>The WebSocket API specification</code> defines. It corresponds to | |
124 * SyntaxError of the specification. | |
125 * Returns <code>PP_ERROR_NOACCESS</code> if the protocol specified in the | |
126 * <code>url</code> is not a secure protocol, but the origin of the caller | |
127 * has a secure scheme. Also returns it if the port specified in the | |
128 * <code>url</code> is a port to which the user agent is configured to block | |
129 * access because the port is a well-known port like SMTP. It corresponds to | |
130 * SecurityError of the specification. | |
131 * Returns <code>PP_ERROR_INPROGRESS</code> if the call is not the first | |
132 * time. | |
133 */ | |
134 int32_t Connect([in] PP_Resource web_socket, | |
135 [in] PP_Var url, | |
136 [in, size_as=protocol_count] PP_Var[] protocols, | |
137 [in] uint32_t protocol_count, | |
138 [in] PP_CompletionCallback callback); | |
139 | |
140 /** | |
141 * Close() closes the specified WebSocket connection by specifying | |
142 * <code>code</code> and <code>reason</code>. | |
143 * | |
144 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
145 * WebSocket. | |
146 * | |
147 * @param[in] code The WebSocket close code. Ignored if it is 0. | |
148 * | |
149 * @param[in] reason A <code>PP_Var</code> which represents the WebSocket | |
150 * close reason. Ignored if it is <code>PP_VARTYPE_UNDEFINED</code>. | |
151 * Otherwise, its <code>PP_VarType</code> must be | |
152 * <code>PP_VARTYPE_STRING</code>. | |
153 * | |
154 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | |
155 * when the connection is closed or an error occurs in closing the | |
156 * connection. | |
157 * | |
158 * @return An int32_t containing an error code from <code>pp_errors.h</code>. | |
159 * Returns <code>PP_ERROR_BADARGUMENT</code> if <code>reason</code> contains | |
160 * an invalid character as a UTF-8 string, or longer than 123 bytes. It | |
161 * corresponds to JavaScript SyntaxError of the specification. | |
162 * Returns <code>PP_ERROR_NOACCESS</code> if the code is not an integer | |
163 * equal to 1000 or in the range 3000 to 4999. It corresponds to | |
164 * InvalidAccessError of the specification. Returns | |
165 * <code>PP_ERROR_INPROGRESS</code> if the call is not the first time. | |
166 */ | |
167 int32_t Close([in] PP_Resource web_socket, | |
168 [in] uint16_t code, | |
169 [in] PP_Var reason, | |
170 [in] PP_CompletionCallback callback); | |
171 | |
172 /** | |
173 * ReceiveMessage() receives a message from the WebSocket server. | |
174 * This interface only returns a single message. That is, this interface must | |
175 * be called at least N times to receive N messages, no matter how small each | |
176 * message is. | |
177 * | |
178 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
179 * WebSocket. | |
180 * | |
181 * @param[out] message The received message is copied to provided | |
182 * <code>message</code>. The <code>message</code> must remain valid until | |
183 * the ReceiveMessage operation completes. | |
184 * | |
185 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | |
186 * when the receiving message is completed. It is ignored if ReceiveMessage | |
187 * completes synchronously and returns <code>PP_OK</code>. | |
188 * | |
189 * @return An int32_t containing an error code from <code>pp_errors.h</code>. | |
190 * If an error is detected or connection is closed, returns | |
191 * <code>PP_ERROR_FAILED</code> after all buffered messages are received. | |
192 * Until buffered message become empty, continues to returns | |
193 * <code>PP_OK</code> as if connection is still established without errors. | |
194 */ | |
195 int32_t ReceiveMessage([in] PP_Resource web_socket, | |
196 [out] PP_Var message, | |
197 [in] PP_CompletionCallback callback); | |
198 | |
199 /** | |
200 * SendMessage() sends a message to the WebSocket server. | |
201 * | |
202 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
203 * WebSocket. | |
204 * | |
205 * @param[in] message A message to send. The message is copied to internal | |
206 * buffer. So caller can free <code>message</code> safely after returning | |
207 * from the function. | |
208 * | |
209 * @return An int32_t containing an error code from <code>pp_errors.h</code>. | |
210 * Returns <code>PP_ERROR_FAILED</code> if the ReadyState is | |
211 * <code>PP_WEBSOCKETREADYSTATE_CONNECTING_DEV</code>. It corresponds | |
212 * JavaScript InvalidStateError of the specification. | |
213 * Returns <code>PP_ERROR_BADARGUMENT</code> if provided <code>message</code> | |
214 * of string type contains an invalid character as a UTF-8 string. It | |
215 * corresponds to JavaScript SyntaxError of the specification. | |
216 * Otherwise, returns <code>PP_OK</code>, but it doesn't necessarily mean | |
217 * that the server received the message. | |
218 */ | |
219 int32_t SendMessage([in] PP_Resource web_socket, | |
220 [in] PP_Var message); | |
221 | |
222 /** | |
223 * GetBufferedAmount() returns the number of bytes of text and binary | |
224 * messages that have been queued for the WebSocket connection to send but | |
225 * have not been transmitted to the network yet. | |
226 * | |
227 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
228 * WebSocket. | |
229 * | |
230 * @return Returns the number of bytes. | |
231 */ | |
232 uint64_t GetBufferedAmount([in] PP_Resource web_socket); | |
233 | |
234 /** | |
235 * GetCloseCode() returns the connection close code for the WebSocket | |
236 * connection. | |
237 * | |
238 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
239 * WebSocket. | |
240 * | |
241 * @return Returns 0 if called before the close code is set. | |
242 */ | |
243 uint16_t GetCloseCode([in] PP_Resource web_socket); | |
244 | |
245 /** | |
246 * GetCloseReason() returns the connection close reason for the WebSocket | |
247 * connection. | |
248 * | |
249 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
250 * WebSocket. | |
251 * | |
252 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the | |
253 * close reason is set, it contains an empty string. Returns a | |
254 * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. | |
255 */ | |
256 PP_Var GetCloseReason([in] PP_Resource web_socket); | |
257 | |
258 /** | |
259 * GetCloseWasClean() returns if the connection was closed cleanly for the | |
260 * specified WebSocket connection. | |
261 * | |
262 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
263 * WebSocket. | |
264 * | |
265 * @return Returns <code>PP_FALSE</code> if called before the connection is | |
266 * closed, or called on an invalid resource. Otherwise, returns | |
267 * <code>PP_TRUE</code> if the connection was closed cleanly, or returns | |
268 * <code>PP_FALSE</code> if the connection was closed for abnormal reasons. | |
269 */ | |
270 PP_Bool GetCloseWasClean([in] PP_Resource web_socket); | |
271 | |
272 /** | |
273 * GetExtensions() returns the extensions selected by the server for the | |
274 * specified WebSocket connection. | |
275 * | |
276 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
277 * WebSocket. | |
278 * | |
279 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the | |
280 * connection is established, its data is an empty string. Returns a | |
281 * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. | |
282 * Currently its data for valid resources are always an empty string. | |
283 */ | |
284 PP_Var GetExtensions([in] PP_Resource web_socket); | |
285 | |
286 /** | |
287 * GetProtocol() returns the sub-protocol chosen by the server for the | |
288 * specified WebSocket connection. | |
289 * | |
290 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
291 * WebSocket. | |
292 * | |
293 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the | |
294 * connection is established, it contains the empty string. Returns a | |
295 * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. | |
296 */ | |
297 PP_Var GetProtocol([in] PP_Resource web_socket); | |
298 | |
299 /** | |
300 * GetReadyState() returns the ready state of the specified WebSocket | |
301 * connection. | |
302 * | |
303 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
304 * WebSocket. | |
305 * | |
306 * @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID_DEV</code> if called | |
307 * before connect() is called, or called on an invalid resource. | |
308 */ | |
309 PP_WebSocketReadyState_Dev GetReadyState([in] PP_Resource web_socket); | |
310 | |
311 /** | |
312 * GetURL() returns the URL associated with specified WebSocket connection. | |
313 * | |
314 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
315 * WebSocket. | |
316 * | |
317 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the | |
318 * connection is established, it contains the empty string. Return a | |
319 * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. | |
320 */ | |
321 PP_Var GetURL([in] PP_Resource web_socket); | |
322 | |
323 /** | |
324 * SetBinaryType() specifies the binary object type for receiving binary | |
325 * frames representation. Receiving text frames are always mapped to | |
326 * <PP_VARTYPE_STRING</code> var regardless of this attribute. | |
327 * This function should be called before Connect() to ensure receiving all | |
328 * incoming binary frames as the specified binary object type. | |
329 * Default type is <code>PP_WEBSOCKETBINARYTYPE_BLOB_DEV</code>. | |
330 * | |
331 * Currently, Blob bindings is not supported in Pepper, so receiving binary | |
332 * type is always ArrayBuffer. To ensure backward compatibility, you must | |
333 * call this function with | |
334 * <code>PP_WEBSOCKETBINARYTYPE_ARRAYBUFFER_DEV</code> to use binary frames. | |
335 * | |
336 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
337 * WebSocket. | |
338 * | |
339 * @param[in] binary_type Binary object type for receiving binary frames | |
340 * representation. | |
341 * | |
342 * @return Returns <code>PP_FALSE</code> if the specified type is not | |
343 * supported. Otherwise, returns <code>PP_TRUE</code>. | |
344 */ | |
345 [version=0.9] | |
346 PP_Bool SetBinaryType([in] PP_Resource web_socket, | |
347 [in] PP_WebSocketBinaryType_Dev binary_type); | |
348 | |
349 /** | |
350 * GetBinaryType() returns the currently specified binary object type for | |
351 * receiving binary frames. | |
352 * | |
353 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
354 * WebSocket. | |
355 * | |
356 * @return Returns <code>PP_WebSocketBinaryType_Dev</code> represents the | |
357 * current binary object type. | |
358 */ | |
359 [version=0.9] | |
360 PP_WebSocketBinaryType_Dev GetBinaryType([in] PP_Resource web_socket); | |
361 }; | |
OLD | NEW |