ppapi/c/ppb_websocket.h

   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