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