ppapi/api/ppb_websocket.idl

   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 };