Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | /* From ppb_websocket.idl modified Thu May 31 15:47:38 2012. */ |
| 7 | |
| 8 | #ifndef PPAPI_C_PPB_WEBSOCKET_H_ |
| 9 | #define PPAPI_C_PPB_WEBSOCKET_H_ |
| 10 | |
| 11 | #include "ppapi/c/pp_bool.h" |
| 12 | #include "ppapi/c/pp_completion_callback.h" |
| 13 | #include "ppapi/c/pp_instance.h" |
| 14 | #include "ppapi/c/pp_macros.h" |
| 15 | #include "ppapi/c/pp_resource.h" |
| 16 | #include "ppapi/c/pp_stdint.h" |
| 17 | #include "ppapi/c/pp_var.h" |
| 18 | |
| 19 | #define PPB_WEBSOCKET_INTERFACE_1_0 "PPB_WebSocket;1.0" |
| 20 | #define PPB_WEBSOCKET_INTERFACE PPB_WEBSOCKET_INTERFACE_1_0 |
| 21 | |
| 22 | /** |
| 23 | * @file |
| 24 | * This file defines the <code>PPB_WebSocket</code> interface providing |
| 25 | * bi-directional, full-duplex, communications over a single TCP socket. |
| 26 | */ |
| 27 | |
| 28 | |
| 29 | /** |
| 30 | * @addtogroup Enums |
| 31 | * @{ |
| 32 | */ |
| 33 | /** |
| 34 | * This enumeration contains the types representing the WebSocket ready state |
| 35 | * and these states are based on the JavaScript WebSocket API specification. |
| 36 | * GetReadyState() returns one of these states. |
| 37 | */ |
| 38 | typedef enum { |
| 39 | /** |
| 40 | * Ready state is queried on an invalid resource. |
| 41 | */ |
| 42 | PP_WEBSOCKETREADYSTATE_INVALID = -1, |
| 43 | /** |
| 44 | * Ready state that the connection has not yet been established. |
| 45 | */ |
| 46 | PP_WEBSOCKETREADYSTATE_CONNECTING = 0, |
| 47 | /** |
| 48 | * Ready state that the WebSocket connection is established and communication |
| 49 | * is possible. |
| 50 | */ |
| 51 | PP_WEBSOCKETREADYSTATE_OPEN = 1, |
| 52 | /** |
| 53 | * Ready state that the connection is going through the closing handshake. |
| 54 | */ |
| 55 | PP_WEBSOCKETREADYSTATE_CLOSING = 2, |
| 56 | /** |
| 57 | * Ready state that the connection has been closed or could not be opened. |
| 58 | */ |
| 59 | PP_WEBSOCKETREADYSTATE_CLOSED = 3 |
| 60 | } PP_WebSocketReadyState; |
| 61 | PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_WebSocketReadyState, 4); |
| 62 | |
| 63 | /** |
| 64 | * This enumeration contains status codes. These codes are used in Close() and |
| 65 | * GetCloseCode(). Refer to RFC 6455, The WebSocket Protocol, for further |
| 66 | * information. |
| 67 | * <code>PP_WEBSOCKETSTATUSCODE_NORMAL_CLOSURE</code> and codes in the range |
| 68 | * <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MIN</code> to |
| 69 | * <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MAX</code>, and |
| 70 | * <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MIN</code> to |
| 71 | * <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MAX</code> are valid for Close(). |
| 72 | */ |
| 73 | typedef enum { |
| 74 | /** |
| 75 | * Indicates to request closing connection without status code and reason. |
| 76 | * |
| 77 | * (Note that the code 1005 is forbidden to send in actual close frames by |
| 78 | * the RFC. PP_WebSocket reuses this code internally and the code will never |
| 79 | * appear in the actual close frames.) |
| 80 | */ |
| 81 | PP_WEBSOCKETSTATUSCODE_NOT_SPECIFIED = 1005, |
| 82 | /** |
| 83 | * Status codes in the range 0-999 are not used. |
| 84 | */ |
| 85 | /** |
| 86 | * Indicates a normal closure. |
| 87 | */ |
| 88 | PP_WEBSOCKETSTATUSCODE_NORMAL_CLOSURE = 1000, |
| 89 | /** |
| 90 | * Indicates that an endpoint is "going away", such as a server going down. |
| 91 | */ |
| 92 | PP_WEBSOCKETSTATUSCODE_GOING_AWAY = 1001, |
| 93 | /** |
| 94 | * Indicates that an endpoint is terminating the connection due to a protocol |
| 95 | * error. |
| 96 | */ |
| 97 | PP_WEBSOCKETSTATUSCODE_PROTOCOL_ERROR = 1002, |
| 98 | /** |
| 99 | * Indicates that an endpoint is terminating the connection because it has |
| 100 | * received a type of data it cannot accept. |
| 101 | */ |
| 102 | PP_WEBSOCKETSTATUSCODE_UNSUPPORTED_DATA = 1003, |
| 103 | /** |
| 104 | * Status code 1004 is reserved. |
| 105 | */ |
| 106 | /** |
| 107 | * Pseudo code to indicate that receiving close frame doesn't contain any |
| 108 | * status code. |
| 109 | */ |
| 110 | PP_WEBSOCKETSTATUSCODE_NO_STATUS_RECEIVED = 1005, |
| 111 | /** |
| 112 | * Pseudo code to indicate that connection was closed abnormally, e.g., |
| 113 | * without closing handshake. |
| 114 | */ |
| 115 | PP_WEBSOCKETSTATUSCODE_ABNORMAL_CLOSURE = 1006, |
| 116 | /** |
| 117 | * Indicates that an endpoint is terminating the connection because it has |
| 118 | * received data within a message that was not consistent with the type of |
| 119 | * the message (e.g., non-UTF-8 data within a text message). |
| 120 | */ |
| 121 | PP_WEBSOCKETSTATUSCODE_INVALID_FRAME_PAYLOAD_DATA = 1007, |
| 122 | /** |
| 123 | * Indicates that an endpoint is terminating the connection because it has |
| 124 | * received a message that violates its policy. |
| 125 | */ |
| 126 | PP_WEBSOCKETSTATUSCODE_POLICY_VIOLATION = 1008, |
| 127 | /** |
| 128 | * Indicates that an endpoint is terminating the connection because it has |
| 129 | * received a message that is too big for it to process. |
| 130 | */ |
| 131 | PP_WEBSOCKETSTATUSCODE_MESSAGE_TOO_BIG = 1009, |
| 132 | /** |
| 133 | * Indicates that an endpoint (client) is terminating the connection because |
| 134 | * it has expected the server to negotiate one or more extension, but the |
| 135 | * server didn't return them in the response message of the WebSocket |
| 136 | * handshake. |
| 137 | */ |
| 138 | PP_WEBSOCKETSTATUSCODE_MANDATORY_EXTENSION = 1010, |
| 139 | /** |
| 140 | * Indicates that a server is terminating the connection because it |
| 141 | * encountered an unexpected condition. |
| 142 | */ |
| 143 | PP_WEBSOCKETSTATUSCODE_INTERNAL_SERVER_ERROR = 1011, |
| 144 | /** |
| 145 | * Status codes in the range 1012-1014 are reserved. |
| 146 | */ |
| 147 | /** |
| 148 | * Pseudo code to indicate that the connection was closed due to a failure to |
| 149 | * perform a TLS handshake. |
| 150 | */ |
| 151 | PP_WEBSOCKETSTATUSCODE_TLS_HANDSHAKE = 1015, |
| 152 | /** |
| 153 | * Status codes in the range 1016-2999 are reserved. |
| 154 | */ |
| 155 | /** |
| 156 | * Status codes in the range 3000-3999 are reserved for use by libraries, |
| 157 | * frameworks, and applications. These codes are registered directly with |
| 158 | * IANA. |
| 159 | */ |
| 160 | PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MIN = 3000, |
| 161 | PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MAX = 3999, |
| 162 | /** |
| 163 | * Status codes in the range 4000-4999 are reserved for private use. |
| 164 | * Application can use these codes for application specific purposes freely. |
| 165 | */ |
| 166 | PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MIN = 4000, |
| 167 | PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MAX = 4999 |
| 168 | } PP_WebSocketCloseCode; |
| 169 | PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_WebSocketCloseCode, 4); |
| 170 | /** |
| 171 | * @} |
| 172 | */ |
| 173 | |
| 174 | /** |
| 175 | * @addtogroup Interfaces |
| 176 | * @{ |
| 177 | */ |
| 178 | /** |
| 179 | * The <code>PPB_WebSocket</code> interface provides bi-directional, |
| 180 | * full-duplex, communications over a single TCP socket. |
| 181 | */ |
| 182 | struct PPB_WebSocket_1_0 { |
| 183 | /** |
| 184 | * Create() creates a WebSocket instance. |
| 185 | * |
| 186 | * @param[in] instance A <code>PP_Instance</code> identifying the instance |
| 187 | * with the WebSocket. |
| 188 | * |
| 189 | * @return A <code>PP_Resource</code> corresponding to a WebSocket if |
| 190 | * successful. |
| 191 | */ |
| 192 | PP_Resource (*Create)(PP_Instance instance); |
| 193 | /** |
| 194 | * IsWebSocket() determines if the provided <code>resource</code> is a |
| 195 | * WebSocket instance. |
| 196 | * |
| 197 | * @param[in] resource A <code>PP_Resource</code> corresponding to a |
| 198 | * WebSocket. |
| 199 | * |
| 200 | * @return Returns <code>PP_TRUE</code> if <code>resource</code> is a |
| 201 | * <code>PPB_WebSocket</code>, <code>PP_FALSE</code> if the |
| 202 | * <code>resource</code> is invalid or some type other than |
| 203 | * <code>PPB_WebSocket</code>. |
| 204 | */ |
| 205 | PP_Bool (*IsWebSocket)(PP_Resource resource); |
| 206 | /** |
| 207 | * Connect() connects to the specified WebSocket server. You can call this |
| 208 | * function once for a <code>web_socket</code>. |
| 209 | * |
| 210 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 211 | * WebSocket. |
| 212 | * |
| 213 | * @param[in] url A <code>PP_Var</code> representing a WebSocket server URL. |
| 214 | * The <code>PP_VarType</code> must be <code>PP_VARTYPE_STRING</code>. |
| 215 | * |
| 216 | * @param[in] protocols A pointer to an array of <code>PP_Var</code> |
| 217 | * specifying sub-protocols. Each <code>PP_Var</code> represents one |
| 218 | * sub-protocol and its <code>PP_VarType</code> must be |
| 219 | * <code>PP_VARTYPE_STRING</code>. This argument can be null only if |
| 220 | * <code>protocol_count</code> is 0. |
| 221 | * |
| 222 | * @param[in] protocol_count The number of sub-protocols in |
| 223 | * <code>protocols</code>. |
| 224 | * |
| 225 | * @param[in] callback A <code>PP_CompletionCallback</code> called |
| 226 | * when a connection is established or an error occurs in establishing |
| 227 | * connection. |
| 228 | * |
| 229 | * @return An int32_t containing an error code from <code>pp_errors.h</code>. |
| 230 | * Returns <code>PP_ERROR_BADARGUMENT</code> if the specified |
| 231 | * <code>url</code>, or <code>protocols</code> contain an invalid string as |
| 232 | * defined in the WebSocket API specification. |
| 233 | * <code>PP_ERROR_BADARGUMENT</code> corresponds to a SyntaxError in the |
| 234 | * WebSocket API specification. |
| 235 | * Returns <code>PP_ERROR_NOACCESS</code> if the protocol specified in the |
| 236 | * <code>url</code> is not a secure protocol, but the origin of the caller |
| 237 | * has a secure scheme. Also returns <code>PP_ERROR_NOACCESS</code> if the |
| 238 | * port specified in the <code>url</code> is a port that the user agent |
| 239 | * is configured to block access to because it is a well-known port like |
| 240 | * SMTP. <code>PP_ERROR_NOACCESS</code> corresponds to a SecurityError of the |
| 241 | * specification. |
| 242 | * Returns <code>PP_ERROR_INPROGRESS</code> if this is not the first call to |
| 243 | * Connect(). |
| 244 | */ |
| 245 | int32_t (*Connect)(PP_Resource web_socket, |
| 246 | struct PP_Var url, |
| 247 | const struct PP_Var protocols[], |
| 248 | uint32_t protocol_count, |
| 249 | struct PP_CompletionCallback callback); |
| 250 | /** |
| 251 | * Close() closes the specified WebSocket connection by specifying |
| 252 | * <code>code</code> and <code>reason</code>. |
| 253 | * |
| 254 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 255 | * WebSocket. |
| 256 | * |
| 257 | * @param[in] code The WebSocket close code. This is ignored if it is |
| 258 | * <code>PP_WEBSOCKETSTATUSCODE_NOT_SPECIFIED</code>. |
| 259 | * <code>PP_WEBSOCKETSTATUSCODE_NORMAL_CLOSURE</code> must be used for the |
| 260 | * usual case. To indicate some specific error cases, codes in the range |
| 261 | * <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MIN</code> to |
| 262 | * <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MAX</code>, and in the range |
| 263 | * <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MIN</code> to |
| 264 | * <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MAX</code> are available. |
| 265 | * |
| 266 | * @param[in] reason A <code>PP_Var</code> representing the WebSocket |
| 267 | * close reason. This is ignored if it is <code>PP_VARTYPE_UNDEFINED</code>. |
| 268 | * Otherwise, its <code>PP_VarType</code> must be |
| 269 | * <code>PP_VARTYPE_STRING</code>. |
| 270 | * |
| 271 | * @param[in] callback A <code>PP_CompletionCallback</code> called |
| 272 | * when the connection is closed or an error occurs in closing the |
| 273 | * connection. |
| 274 | * |
| 275 | * @return An int32_t containing an error code from <code>pp_errors.h</code>. |
| 276 | * Returns <code>PP_ERROR_BADARGUMENT</code> if <code>reason</code> contains |
| 277 | * an invalid character as a UTF-8 string, or is longer than 123 bytes. |
| 278 | * <code>PP_ERROR_BADARGUMENT</code> corresponds to a JavaScript SyntaxError |
| 279 | * in the WebSocket API specification. |
| 280 | * Returns <code>PP_ERROR_NOACCESS</code> if the code is not an integer |
| 281 | * equal to 1000 or in the range 3000 to 4999. <code>PP_ERROR_NOACCESS</code> |
| 282 | * corresponds to an InvalidAccessError in the WebSocket API specification. |
| 283 | * Returns <code>PP_ERROR_INPROGRESS</code> if a previous call to Close() is |
| 284 | * not finished. |
| 285 | */ |
| 286 | int32_t (*Close)(PP_Resource web_socket, |
| 287 | uint16_t code, |
| 288 | struct PP_Var reason, |
| 289 | struct PP_CompletionCallback callback); |
| 290 | /** |
| 291 | * ReceiveMessage() receives a message from the WebSocket server. |
| 292 | * This interface only returns a single message. That is, this interface must |
| 293 | * be called at least N times to receive N messages, no matter the size of |
| 294 | * each message. |
| 295 | * |
| 296 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 297 | * WebSocket. |
| 298 | * |
| 299 | * @param[out] message The received message is copied to provided |
| 300 | * <code>message</code>. The <code>message</code> must remain valid until |
| 301 | * ReceiveMessage() completes. Its received <code>PP_VarType</code> will be |
| 302 | * <code>PP_VARTYPE_STRING</code> or <code>PP_VARTYPE_ARRAY_BUFFER</code>. |
| 303 | * |
| 304 | * @param[in] callback A <code>PP_CompletionCallback</code> called |
| 305 | * when ReceiveMessage() completes. This callback is ignored if |
| 306 | * ReceiveMessage() completes synchronously and returns <code>PP_OK</code>. |
| 307 | * |
| 308 | * @return An int32_t containing an error code from <code>pp_errors.h</code>. |
| 309 | * If an error is detected or connection is closed, ReceiveMessage() returns |
| 310 | * <code>PP_ERROR_FAILED</code> after all buffered messages are received. |
| 311 | * Until buffered message become empty, ReceiveMessage() continues to return |
| 312 | * <code>PP_OK</code> as if connection is still established without errors. |
| 313 | */ |
| 314 | int32_t (*ReceiveMessage)(PP_Resource web_socket, |
| 315 | struct PP_Var* message, |
| 316 | struct PP_CompletionCallback callback); |
| 317 | /** |
| 318 | * SendMessage() sends a message to the WebSocket server. |
| 319 | * |
| 320 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 321 | * WebSocket. |
| 322 | * |
| 323 | * @param[in] message A message to send. The message is copied to an internal |
| 324 | * buffer, so the caller can free <code>message</code> safely after returning |
| 325 | * from the function. Its sent <code>PP_VarType</code> must be |
| 326 | * <code>PP_VARTYPE_STRING</code> or <code>PP_VARTYPE_ARRAY_BUFFER</code>. |
| 327 | * |
| 328 | * @return An int32_t containing an error code from <code>pp_errors.h</code>. |
| 329 | * Returns <code>PP_ERROR_FAILED</code> if the ReadyState is |
| 330 | * <code>PP_WEBSOCKETREADYSTATE_CONNECTING</code>. |
| 331 | * <code>PP_ERROR_FAILED</code> corresponds to a JavaScript |
| 332 | * InvalidStateError in the WebSocket API specification. |
| 333 | * Returns <code>PP_ERROR_BADARGUMENT</code> if the provided |
| 334 | * <code>message</code> contains an invalid character as a UTF-8 string. |
| 335 | * <code>PP_ERROR_BADARGUMENT</code> corresponds to a JavaScript |
| 336 | * SyntaxError in the WebSocket API specification. |
| 337 | * Otherwise, returns <code>PP_OK</code>, which doesn't necessarily mean |
| 338 | * that the server received the message. |
| 339 | */ |
| 340 | int32_t (*SendMessage)(PP_Resource web_socket, struct PP_Var message); |
| 341 | /** |
| 342 | * GetBufferedAmount() returns the number of bytes of text and binary |
| 343 | * messages that have been queued for the WebSocket connection to send, but |
| 344 | * have not been transmitted to the network yet. |
| 345 | * |
| 346 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 347 | * WebSocket. |
| 348 | * |
| 349 | * @return Returns the number of bytes. |
| 350 | */ |
| 351 | uint64_t (*GetBufferedAmount)(PP_Resource web_socket); |
| 352 | /** |
| 353 | * GetCloseCode() returns the connection close code for the WebSocket |
| 354 | * connection. |
| 355 | * |
| 356 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 357 | * WebSocket. |
| 358 | * |
| 359 | * @return Returns 0 if called before the close code is set. |
| 360 | */ |
| 361 | uint16_t (*GetCloseCode)(PP_Resource web_socket); |
| 362 | /** |
| 363 | * GetCloseReason() returns the connection close reason for the WebSocket |
| 364 | * connection. |
| 365 | * |
| 366 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 367 | * WebSocket. |
| 368 | * |
| 369 | * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
| 370 | * close reason is set, the return value contains an empty string. Returns a |
| 371 | * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. |
| 372 | */ |
| 373 | struct PP_Var (*GetCloseReason)(PP_Resource web_socket); |
| 374 | /** |
| 375 | * GetCloseWasClean() returns if the connection was closed cleanly for the |
| 376 | * specified WebSocket connection. |
| 377 | * |
| 378 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 379 | * WebSocket. |
| 380 | * |
| 381 | * @return Returns <code>PP_FALSE</code> if called before the connection is |
| 382 | * closed, called on an invalid resource, or closed for abnormal reasons. |
| 383 | * Otherwise, returns <code>PP_TRUE</code> if the connection was closed |
| 384 | * cleanly. |
| 385 | */ |
| 386 | PP_Bool (*GetCloseWasClean)(PP_Resource web_socket); |
| 387 | /** |
| 388 | * GetExtensions() returns the extensions selected by the server for the |
| 389 | * specified WebSocket connection. |
| 390 | * |
| 391 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 392 | * WebSocket. |
| 393 | * |
| 394 | * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
| 395 | * connection is established, the var's data is an empty string. Returns a |
| 396 | * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. |
| 397 | */ |
| 398 | struct PP_Var (*GetExtensions)(PP_Resource web_socket); |
| 399 | /** |
| 400 | * GetProtocol() returns the sub-protocol chosen by the server for the |
| 401 | * specified WebSocket connection. |
| 402 | * |
| 403 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 404 | * WebSocket. |
| 405 | * |
| 406 | * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
| 407 | * connection is established, the var contains the empty string. Returns a |
| 408 | * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. |
| 409 | */ |
| 410 | struct PP_Var (*GetProtocol)(PP_Resource web_socket); |
| 411 | /** |
| 412 | * GetReadyState() returns the ready state of the specified WebSocket |
| 413 | * connection. |
| 414 | * |
| 415 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 416 | * WebSocket. |
| 417 | * |
| 418 | * @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID</code> if called |
| 419 | * before Connect() is called, or if this function is called on an |
| 420 | * invalid resource. |
| 421 | */ |
| 422 | PP_WebSocketReadyState (*GetReadyState)(PP_Resource web_socket); |
| 423 | /** |
| 424 | * GetURL() returns the URL associated with specified WebSocket connection. |
| 425 | * |
| 426 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 427 | * WebSocket. |
| 428 | * |
| 429 | * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
| 430 | * connection is established, the var contains the empty string. Returns a |
| 431 | * <code>PP_VARTYPE_UNDEFINED</code> if this function is called on an |
| 432 | * invalid resource. |
| 433 | */ |
| 434 | struct PP_Var (*GetURL)(PP_Resource web_socket); |
| 435 | }; |
| 436 | |
| 437 | typedef struct PPB_WebSocket_1_0 PPB_WebSocket; |
| 438 | /** |
| 439 | * @} |
| 440 | */ |
| 441 | |
| 442 | #endif /* PPAPI_C_PPB_WEBSOCKET_H_ */ |
| 443 | |