OLD | NEW |
1 /* Copyright (c) 2011 The Chromium Authors. All rights reserved. | 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 | 2 * Use of this source code is governed by a BSD-style license that can be |
3 * found in the LICENSE file. | 3 * found in the LICENSE file. |
4 */ | 4 */ |
5 | 5 |
6 /** | 6 /** |
7 * This file defines the <code>PPB_WebSocket_Dev</code> interface. | 7 * This file defines the <code>PPB_WebSocket_Dev</code> interface. |
8 */ | 8 */ |
9 label Chrome { | 9 label Chrome { |
10 M17 = 0.1 | 10 M17 = 0.1 |
(...skipping 92 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
103 * @param[in] protocols A pointer to an array of <code>PP_Var</code> | 103 * @param[in] protocols A pointer to an array of <code>PP_Var</code> |
104 * specifying sub-protocols. Each <code>PP_Var</code> represents one | 104 * specifying sub-protocols. Each <code>PP_Var</code> represents one |
105 * sub-protocol and its <code>PP_VarType</code> must be | 105 * sub-protocol and its <code>PP_VarType</code> must be |
106 * <code>PP_VARTYPE_STRING</code>. This argument can be null only if | 106 * <code>PP_VARTYPE_STRING</code>. This argument can be null only if |
107 * <code>protocol_count</code> is 0. | 107 * <code>protocol_count</code> is 0. |
108 * | 108 * |
109 * @param[in] protocol_count The number of sub-protocols in | 109 * @param[in] protocol_count The number of sub-protocols in |
110 * <code>protocols</code>. | 110 * <code>protocols</code>. |
111 * | 111 * |
112 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | 112 * @param[in] callback A <code>PP_CompletionCallback</code> which is called |
113 * when the connection is established or an error occurs in establishing | 113 * when a connection is established or an error occurs in establishing |
114 * connection. | 114 * connection. |
115 * | 115 * |
116 * @return In case of immediate failure, returns an error code as follows. | 116 * @return An int32_t containing an error code from <code>pp_errors.h</code>. |
117 * Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript | 117 * Returns <code>PP_ERROR_BADARGUMENT</code> if specified <code>url</code>, |
118 * SyntaxError and <code>PP_ERROR_NOACCESS</code> corresponding to JavaScript | 118 * or <code>protocols</code> contains invalid string as |
119 * SecurityError. Otherwise, returns <code>PP_OK_COMPLETIONPENDING</code> | 119 * <code>The WebSocket API specification</code> defines. It corresponds to |
120 * and invokes <code>callback</code> later. | 120 * SyntaxError of the specification. |
| 121 * Returns <code>PP_ERROR_NOACCESS</code> if the protocol specified in the |
| 122 * <code>url</code> is not a secure protocol, but the origin of the caller |
| 123 * has a secure scheme. Also returns it if the port specified in the |
| 124 * <code>url</code> is a port to which the user agent is configured to block |
| 125 * access because the port is a well-known port like SMTP. It corresponds to |
| 126 * SecurityError of the specification. |
| 127 * Returns <code>PP_ERROR_INPROGRESS</code> if the call is not the first |
| 128 * time. |
121 */ | 129 */ |
122 int32_t Connect([in] PP_Resource web_socket, | 130 int32_t Connect([in] PP_Resource web_socket, |
123 [in] PP_Var url, | 131 [in] PP_Var url, |
124 [in, size_as=protocol_count] PP_Var[] protocols, | 132 [in, size_as=protocol_count] PP_Var[] protocols, |
125 [in] uint32_t protocol_count, | 133 [in] uint32_t protocol_count, |
126 [in] PP_CompletionCallback callback); | 134 [in] PP_CompletionCallback callback); |
127 | 135 |
128 /** | 136 /** |
129 * Close() closes the specified WebSocket connection by specifying | 137 * Close() closes the specified WebSocket connection by specifying |
130 * <code>code</code> and <code>reason</code>. | 138 * <code>code</code> and <code>reason</code>. |
131 * | 139 * |
132 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | 140 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
133 * WebSocket. | 141 * WebSocket. |
134 * | 142 * |
135 * @param[in] code The WebSocket close code. Ignored if it is 0. | 143 * @param[in] code The WebSocket close code. Ignored if it is 0. |
136 * | 144 * |
137 * @param[in] reason A <code>PP_Var</code> which represents the WebSocket | 145 * @param[in] reason A <code>PP_Var</code> which represents the WebSocket |
138 * close reason. Ignored if it is <code>PP_VARTYPE_UNDEFINED</code>. | 146 * close reason. Ignored if it is <code>PP_VARTYPE_UNDEFINED</code>. |
139 * Otherwise, its <code>PP_VarType</code> must be | 147 * Otherwise, its <code>PP_VarType</code> must be |
140 * <code>PP_VARTYPE_STRING</code>. | 148 * <code>PP_VARTYPE_STRING</code>. |
141 * | 149 * |
142 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | 150 * @param[in] callback A <code>PP_CompletionCallback</code> which is called |
143 * when the connection is closed or an error occurs in closing connection. | 151 * when the connection is closed or an error occurs in closing the |
| 152 * connection. |
144 * | 153 * |
145 * @return In case of immediate failure, returns an error code as follows. | 154 * @return An int32_t containing an error code from <code>pp_errors.h</code>. |
146 * Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript | 155 * Returns <code>PP_ERROR_BADARGUMENT</code> if <code>reason</code> contains |
147 * SyntaxError and <code>PP_ERROR_NOACCESS</code> corresponding to JavaScript | 156 * an invalid character as a UTF-8 string, or longer than 123 bytes. It |
148 * InvalidAccessError. Otherwise, returns | 157 * corresponds to JavaScript SyntaxError of the specification. |
149 * <code>PP_OK_COMPLETIONPENDING</code> and invokes <code>callback</code> | 158 * Returns <code>PP_ERROR_NOACCESS</code> if the code is not an integer |
150 * later. | 159 * equal to 1000 or in the range 3000 to 4999. It corresponds to |
| 160 * InvalidAccessError of the specification. Returns |
| 161 * <code>PP_ERROR_INPROGRESS</code> if the call is not the first time. |
151 */ | 162 */ |
152 int32_t Close([in] PP_Resource web_socket, | 163 int32_t Close([in] PP_Resource web_socket, |
153 [in] uint16_t code, | 164 [in] uint16_t code, |
154 [in] PP_Var reason, | 165 [in] PP_Var reason, |
155 [in] PP_CompletionCallback callback); | 166 [in] PP_CompletionCallback callback); |
156 | 167 |
157 /** | 168 /** |
158 * ReceiveMessage() receives a message from the WebSocket server. | 169 * ReceiveMessage() receives a message from the WebSocket server. |
159 * This interface only returns bytes of a single message. That is, this | 170 * This interface only returns a single message. That is, this interface must |
160 * interface must be called at least N times to receive N messages, no matter | 171 * be called at least N times to receive N messages, no matter how small each |
161 * how small each message is. | 172 * message is. |
162 * | 173 * |
163 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | 174 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
164 * WebSocket. | 175 * WebSocket. |
165 * | 176 * |
166 * @param[out] message The received message is copied to provided | 177 * @param[out] message The received message is copied to provided |
167 * <code>message</code>. | 178 * <code>message</code>. The <code>message</code> must remain valid until |
| 179 * the ReceiveMessage operation completes. |
168 * | 180 * |
169 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | 181 * @param[in] callback A <code>PP_CompletionCallback</code> which is called |
170 * when the receiving message is completed. It is ignored when the function | 182 * when the receiving message is completed. It is ignored if ReceiveMessage |
171 * return <code>PP_OK</code>. | 183 * completes synchronously and returns <code>PP_OK</code>. |
172 * | 184 * |
173 * @return In case of immediate failure, returns | 185 * @return An int32_t containing an error code from <code>pp_errors.h</code>. |
174 * <code>PP_ERROR_FAILED</code>. If a message is currently available, returns | 186 * If an error is detected or connection is closed, returns |
175 * <code>PP_OK</code>. Otherwise, returns <PP_OK_COMPLETIONPENDING</code> | 187 * <code>PP_ERROR_FAILED</code> after all buffered messages are received. |
176 * and invokes <code>callback</code> later. At that case, if GetReadyState() | 188 * Until buffered message become empty, continues to returns |
177 * returns <code>PP_WEBSOCKETREADYSTATE_OPEN</code>, the received | 189 * <code>PP_OK</code> as if connection is still established without errors. |
178 * message is also copied to procided <code>message</code>. Otherwise, | |
179 * the connection is closed and ReceiveMessage() failed to receive a message. | |
180 */ | 190 */ |
181 int32_t ReceiveMessage([in] PP_Resource web_socket, | 191 int32_t ReceiveMessage([in] PP_Resource web_socket, |
182 [out] PP_Var message, | 192 [out] PP_Var message, |
183 [in] PP_CompletionCallback callback); | 193 [in] PP_CompletionCallback callback); |
184 | 194 |
185 /** | 195 /** |
186 * SendMessage() sends a message to the WebSocket server. | 196 * SendMessage() sends a message to the WebSocket server. |
187 * | 197 * |
188 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | 198 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
189 * WebSocket. | 199 * WebSocket. |
190 * | 200 * |
191 * @param[in] message A message to send. The message is copied to internal | 201 * @param[in] message A message to send. The message is copied to internal |
192 * buffer. So caller can free <code>message</code> safely after returning | 202 * buffer. So caller can free <code>message</code> safely after returning |
193 * from the function. | 203 * from the function. |
194 * | 204 * |
195 * @return In case of immediate failure, returns an error code as follows. | 205 * @return An int32_t containing an error code from <code>pp_errors.h</code>. |
196 * Returns <code>PP_ERROR_FAILED</code> corresponding to JavaScript | 206 * Returns <code>PP_ERROR_FAILED</code> if the ReadyState is |
197 * InvalidStateError and <code>PP_ERROR_BADARGUMENT</code> corresponding to | 207 * <code>PP_WEBSOCKETREADYSTATE_CONNECTING_DEV</code>. It corresponds |
198 * JavaScript SyntaxError. Otherwise, return <code>PP_OK</code>. | 208 * JavaScript InvalidStateError of the specification. |
199 * <code>PP_OK</code> doesn't necessarily mean that the server received the | 209 * Returns <code>PP_ERROR_BADARGUMENT</code> if provided <code>message</code> |
200 * message. | 210 * of string type contains an invalid character as a UTF-8 string. It |
| 211 * corresponds to JavaScript SyntaxError of the specification. |
| 212 * Otherwise, returns <code>PP_OK</code>, but it doesn't necessarily mean |
| 213 * that the server received the message. |
201 */ | 214 */ |
202 int32_t SendMessage([in] PP_Resource web_socket, | 215 int32_t SendMessage([in] PP_Resource web_socket, |
203 [in] PP_Var message); | 216 [in] PP_Var message); |
204 | 217 |
205 /** | 218 /** |
206 * GetBufferedAmount() returns the number of bytes of text and binary | 219 * GetBufferedAmount() returns the number of bytes of text and binary |
207 * messages that have been queued for the WebSocket connection to send but | 220 * messages that have been queued for the WebSocket connection to send but |
208 * have not been transmitted to the network yet. | 221 * have not been transmitted to the network yet. |
209 * | 222 * |
210 * Note: This interface might not be able to return exact bytes in the first | |
211 * release. Current WebSocket implementation can not estimate exact protocol | |
212 * frame overheads. | |
213 * | |
214 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | 223 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
215 * WebSocket. | 224 * WebSocket. |
216 * | 225 * |
217 * @return Returns the number of bytes. | 226 * @return Returns the number of bytes. |
218 */ | 227 */ |
219 uint64_t GetBufferedAmount([in] PP_Resource web_socket); | 228 uint64_t GetBufferedAmount([in] PP_Resource web_socket); |
220 | 229 |
221 /** | 230 /** |
222 * GetCloseCode() returns the connection close code for the WebSocket | 231 * GetCloseCode() returns the connection close code for the WebSocket |
223 * connection. | 232 * connection. |
224 * | 233 * |
225 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | 234 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
226 * WebSocket. | 235 * WebSocket. |
227 * | 236 * |
228 * @return Returns 0 if called before the close code is set. | 237 * @return Returns 0 if called before the close code is set. |
229 */ | 238 */ |
230 uint16_t GetCloseCode([in] PP_Resource web_socket); | 239 uint16_t GetCloseCode([in] PP_Resource web_socket); |
231 | 240 |
232 /** | 241 /** |
233 * GetCloseReason() returns the connection close reason for the WebSocket | 242 * GetCloseReason() returns the connection close reason for the WebSocket |
234 * connection. | 243 * connection. |
235 * | 244 * |
236 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | 245 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
237 * WebSocket. | 246 * WebSocket. |
238 * | 247 * |
239 * @return Returns a <code>PP_VARTYPE_STRING</code> var. if called before the | 248 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
240 * close reason is set, its data is empty string. Returns a | 249 * close reason is set, it contains an empty string. Returns a |
241 * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. | 250 * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. |
242 */ | 251 */ |
243 PP_Var GetCloseReason([in] PP_Resource web_socket); | 252 PP_Var GetCloseReason([in] PP_Resource web_socket); |
244 | 253 |
245 /** | 254 /** |
246 * GetCloseWasClean() returns if the connection was closed cleanly for the | 255 * GetCloseWasClean() returns if the connection was closed cleanly for the |
247 * specified WebSocket connection. | 256 * specified WebSocket connection. |
248 * | 257 * |
249 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | 258 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
250 * WebSocket. | 259 * WebSocket. |
251 * | 260 * |
252 * @return Returns <code>PP_FALSE</code> if called before the connection is | 261 * @return Returns <code>PP_FALSE</code> if called before the connection is |
253 * closed, or called on an invalid resource. Otherwise, returns | 262 * closed, or called on an invalid resource. Otherwise, returns |
254 * <code>PP_TRUE</code> if the connection was closed cleanly, or returns | 263 * <code>PP_TRUE</code> if the connection was closed cleanly, or returns |
255 * <code>PP_FALSE</code> if the connection was closed by abnormal reasons. | 264 * <code>PP_FALSE</code> if the connection was closed for abnormal reasons. |
256 */ | 265 */ |
257 PP_Bool GetCloseWasClean([in] PP_Resource web_socket); | 266 PP_Bool GetCloseWasClean([in] PP_Resource web_socket); |
258 | 267 |
259 /** | 268 /** |
260 * GetExtensions() returns the extensions selected by the server for the | 269 * GetExtensions() returns the extensions selected by the server for the |
261 * specified WebSocket connection. | 270 * specified WebSocket connection. |
262 * | 271 * |
263 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | 272 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
264 * WebSocket. | 273 * WebSocket. |
265 * | 274 * |
266 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the | 275 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
267 * connection is established, its data is empty string. Returns a | 276 * connection is established, its data is an empty string. Returns a |
268 * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. | 277 * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. |
269 * Currently its data for valid resources are always empty string. | 278 * Currently its data for valid resources are always an empty string. |
270 */ | 279 */ |
271 PP_Var GetExtensions([in] PP_Resource web_socket); | 280 PP_Var GetExtensions([in] PP_Resource web_socket); |
272 | 281 |
273 /** | 282 /** |
274 * GetProtocol() returns the sub-protocol chosen by the server for the | 283 * GetProtocol() returns the sub-protocol chosen by the server for the |
275 * specified WebSocket connection. | 284 * specified WebSocket connection. |
276 * | 285 * |
277 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | 286 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
278 * WebSocket. | 287 * WebSocket. |
279 * | 288 * |
280 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the | 289 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
281 * connection is established, its data is empty string. Returns a | 290 * connection is established, it contains the empty string. Returns a |
282 * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. | 291 * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. |
283 */ | 292 */ |
284 PP_Var GetProtocol([in] PP_Resource web_socket); | 293 PP_Var GetProtocol([in] PP_Resource web_socket); |
285 | 294 |
286 /** | 295 /** |
287 * GetReadyState() returns the ready state of the specified WebSocket | 296 * GetReadyState() returns the ready state of the specified WebSocket |
288 * connection. | 297 * connection. |
289 * | 298 * |
290 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | 299 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
291 * WebSocket. | 300 * WebSocket. |
292 * | 301 * |
293 * @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID_DEV</code> if called | 302 * @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID_DEV</code> if called |
294 * before connect() is called, or called on an invalid resource. | 303 * before connect() is called, or called on an invalid resource. |
295 */ | 304 */ |
296 PP_WebSocketReadyState_Dev GetReadyState([in] PP_Resource web_socket); | 305 PP_WebSocketReadyState_Dev GetReadyState([in] PP_Resource web_socket); |
297 | 306 |
298 /** | 307 /** |
299 * GetURL() returns the URL associated with specified WebSocket connection. | 308 * GetURL() returns the URL associated with specified WebSocket connection. |
300 * | 309 * |
301 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | 310 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
302 * WebSocket. | 311 * WebSocket. |
303 * | 312 * |
304 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the | 313 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
305 * connection is established, its data is empty string. Return a | 314 * connection is established, it contains the empty string. Return a |
306 * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. | 315 * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. |
307 */ | 316 */ |
308 PP_Var GetURL([in] PP_Resource web_socket); | 317 PP_Var GetURL([in] PP_Resource web_socket); |
309 }; | 318 }; |
OLD | NEW |