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 444