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