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