| /* Copyright (c) 2012 The Chromium Authors. All rights reserved. |
| * Use of this source code is governed by a BSD-style license that can be |
| * found in the LICENSE file. |
| */ |
| |
| /* From ppb_websocket.idl modified Thu May 31 15:47:38 2012. */ |
| |
| #ifndef PPAPI_C_PPB_WEBSOCKET_H_ |
| #define PPAPI_C_PPB_WEBSOCKET_H_ |
| |
| #include "ppapi/c/pp_bool.h" |
| #include "ppapi/c/pp_completion_callback.h" |
| #include "ppapi/c/pp_instance.h" |
| #include "ppapi/c/pp_macros.h" |
| #include "ppapi/c/pp_resource.h" |
| #include "ppapi/c/pp_stdint.h" |
| #include "ppapi/c/pp_var.h" |
| |
| #define PPB_WEBSOCKET_INTERFACE_1_0 "PPB_WebSocket;1.0" |
| #define PPB_WEBSOCKET_INTERFACE PPB_WEBSOCKET_INTERFACE_1_0 |
| |
| /** |
| * @file |
| * This file defines the <code>PPB_WebSocket</code> interface providing |
| * bi-directional, full-duplex, communications over a single TCP socket. |
| */ |
| |
| |
| /** |
| * @addtogroup Enums |
| * @{ |
| */ |
| /** |
| * This enumeration contains the types representing the WebSocket ready state |
| * and these states are based on the JavaScript WebSocket API specification. |
| * GetReadyState() returns one of these states. |
| */ |
| typedef enum { |
| /** |
| * Ready state is queried on an invalid resource. |
| */ |
| PP_WEBSOCKETREADYSTATE_INVALID = -1, |
| /** |
| * Ready state that the connection has not yet been established. |
| */ |
| PP_WEBSOCKETREADYSTATE_CONNECTING = 0, |
| /** |
| * Ready state that the WebSocket connection is established and communication |
| * is possible. |
| */ |
| PP_WEBSOCKETREADYSTATE_OPEN = 1, |
| /** |
| * Ready state that the connection is going through the closing handshake. |
| */ |
| PP_WEBSOCKETREADYSTATE_CLOSING = 2, |
| /** |
| * Ready state that the connection has been closed or could not be opened. |
| */ |
| PP_WEBSOCKETREADYSTATE_CLOSED = 3 |
| } PP_WebSocketReadyState; |
| PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_WebSocketReadyState, 4); |
| |
| /** |
| * This enumeration contains status codes. These codes are used in Close() and |
| * GetCloseCode(). Refer to RFC 6455, The WebSocket Protocol, for further |
| * information. |
| * <code>PP_WEBSOCKETSTATUSCODE_NORMAL_CLOSURE</code> and codes in the range |
| * <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MIN</code> to |
| * <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MAX</code>, and |
| * <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MIN</code> to |
| * <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MAX</code> are valid for Close(). |
| */ |
| typedef enum { |
| /** |
| * Indicates to request closing connection without status code and reason. |
| * |
| * (Note that the code 1005 is forbidden to send in actual close frames by |
| * the RFC. PP_WebSocket reuses this code internally and the code will never |
| * appear in the actual close frames.) |
| */ |
| PP_WEBSOCKETSTATUSCODE_NOT_SPECIFIED = 1005, |
| /** |
| * Status codes in the range 0-999 are not used. |
| */ |
| /** |
| * Indicates a normal closure. |
| */ |
| PP_WEBSOCKETSTATUSCODE_NORMAL_CLOSURE = 1000, |
| /** |
| * Indicates that an endpoint is "going away", such as a server going down. |
| */ |
| PP_WEBSOCKETSTATUSCODE_GOING_AWAY = 1001, |
| /** |
| * Indicates that an endpoint is terminating the connection due to a protocol |
| * error. |
| */ |
| PP_WEBSOCKETSTATUSCODE_PROTOCOL_ERROR = 1002, |
| /** |
| * Indicates that an endpoint is terminating the connection because it has |
| * received a type of data it cannot accept. |
| */ |
| PP_WEBSOCKETSTATUSCODE_UNSUPPORTED_DATA = 1003, |
| /** |
| * Status code 1004 is reserved. |
| */ |
| /** |
| * Pseudo code to indicate that receiving close frame doesn't contain any |
| * status code. |
| */ |
| PP_WEBSOCKETSTATUSCODE_NO_STATUS_RECEIVED = 1005, |
| /** |
| * Pseudo code to indicate that connection was closed abnormally, e.g., |
| * without closing handshake. |
| */ |
| PP_WEBSOCKETSTATUSCODE_ABNORMAL_CLOSURE = 1006, |
| /** |
| * Indicates that an endpoint is terminating the connection because it has |
| * received data within a message that was not consistent with the type of |
| * the message (e.g., non-UTF-8 data within a text message). |
| */ |
| PP_WEBSOCKETSTATUSCODE_INVALID_FRAME_PAYLOAD_DATA = 1007, |
| /** |
| * Indicates that an endpoint is terminating the connection because it has |
| * received a message that violates its policy. |
| */ |
| PP_WEBSOCKETSTATUSCODE_POLICY_VIOLATION = 1008, |
| /** |
| * Indicates that an endpoint is terminating the connection because it has |
| * received a message that is too big for it to process. |
| */ |
| PP_WEBSOCKETSTATUSCODE_MESSAGE_TOO_BIG = 1009, |
| /** |
| * Indicates that an endpoint (client) is terminating the connection because |
| * it has expected the server to negotiate one or more extension, but the |
| * server didn't return them in the response message of the WebSocket |
| * handshake. |
| */ |
| PP_WEBSOCKETSTATUSCODE_MANDATORY_EXTENSION = 1010, |
| /** |
| * Indicates that a server is terminating the connection because it |
| * encountered an unexpected condition. |
| */ |
| PP_WEBSOCKETSTATUSCODE_INTERNAL_SERVER_ERROR = 1011, |
| /** |
| * Status codes in the range 1012-1014 are reserved. |
| */ |
| /** |
| * Pseudo code to indicate that the connection was closed due to a failure to |
| * perform a TLS handshake. |
| */ |
| PP_WEBSOCKETSTATUSCODE_TLS_HANDSHAKE = 1015, |
| /** |
| * Status codes in the range 1016-2999 are reserved. |
| */ |
| /** |
| * Status codes in the range 3000-3999 are reserved for use by libraries, |
| * frameworks, and applications. These codes are registered directly with |
| * IANA. |
| */ |
| PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MIN = 3000, |
| PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MAX = 3999, |
| /** |
| * Status codes in the range 4000-4999 are reserved for private use. |
| * Application can use these codes for application specific purposes freely. |
| */ |
| PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MIN = 4000, |
| PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MAX = 4999 |
| } PP_WebSocketCloseCode; |
| PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_WebSocketCloseCode, 4); |
| /** |
| * @} |
| */ |
| |
| /** |
| * @addtogroup Interfaces |
| * @{ |
| */ |
| /** |
| * The <code>PPB_WebSocket</code> interface provides bi-directional, |
| * full-duplex, communications over a single TCP socket. |
| */ |
| struct PPB_WebSocket_1_0 { |
| /** |
| * Create() creates a WebSocket instance. |
| * |
| * @param[in] instance A <code>PP_Instance</code> identifying the instance |
| * with the WebSocket. |
| * |
| * @return A <code>PP_Resource</code> corresponding to a WebSocket if |
| * successful. |
| */ |
| PP_Resource (*Create)(PP_Instance instance); |
| /** |
| * IsWebSocket() determines if the provided <code>resource</code> is a |
| * WebSocket instance. |
| * |
| * @param[in] resource A <code>PP_Resource</code> corresponding to a |
| * WebSocket. |
| * |
| * @return Returns <code>PP_TRUE</code> if <code>resource</code> is a |
| * <code>PPB_WebSocket</code>, <code>PP_FALSE</code> if the |
| * <code>resource</code> is invalid or some type other than |
| * <code>PPB_WebSocket</code>. |
| */ |
| PP_Bool (*IsWebSocket)(PP_Resource resource); |
| /** |
| * Connect() connects to the specified WebSocket server. You can call this |
| * function once for a <code>web_socket</code>. |
| * |
| * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| * WebSocket. |
| * |
| * @param[in] url A <code>PP_Var</code> representing a WebSocket server URL. |
| * The <code>PP_VarType</code> must be <code>PP_VARTYPE_STRING</code>. |
| * |
| * @param[in] protocols A pointer to an array of <code>PP_Var</code> |
| * specifying sub-protocols. Each <code>PP_Var</code> represents one |
| * sub-protocol and its <code>PP_VarType</code> must be |
| * <code>PP_VARTYPE_STRING</code>. This argument can be null only if |
| * <code>protocol_count</code> is 0. |
| * |
| * @param[in] protocol_count The number of sub-protocols in |
| * <code>protocols</code>. |
| * |
| * @param[in] callback A <code>PP_CompletionCallback</code> called |
| * when a connection is established or an error occurs in establishing |
| * connection. |
| * |
| * @return An int32_t containing an error code from <code>pp_errors.h</code>. |
| * Returns <code>PP_ERROR_BADARGUMENT</code> if the specified |
| * <code>url</code>, or <code>protocols</code> contain an invalid string as |
| * defined in the WebSocket API specification. |
| * <code>PP_ERROR_BADARGUMENT</code> corresponds to a SyntaxError in the |
| * WebSocket API specification. |
| * Returns <code>PP_ERROR_NOACCESS</code> if the protocol specified in the |
| * <code>url</code> is not a secure protocol, but the origin of the caller |
| * has a secure scheme. Also returns <code>PP_ERROR_NOACCESS</code> if the |
| * port specified in the <code>url</code> is a port that the user agent |
| * is configured to block access to because it is a well-known port like |
| * SMTP. <code>PP_ERROR_NOACCESS</code> corresponds to a SecurityError of the |
| * specification. |
| * Returns <code>PP_ERROR_INPROGRESS</code> if this is not the first call to |
| * Connect(). |
| */ |
| int32_t (*Connect)(PP_Resource web_socket, |
| struct PP_Var url, |
| const struct PP_Var protocols[], |
| uint32_t protocol_count, |
| struct PP_CompletionCallback callback); |
| /** |
| * Close() closes the specified WebSocket connection by specifying |
| * <code>code</code> and <code>reason</code>. |
| * |
| * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| * WebSocket. |
| * |
| * @param[in] code The WebSocket close code. This is ignored if it is |
| * <code>PP_WEBSOCKETSTATUSCODE_NOT_SPECIFIED</code>. |
| * <code>PP_WEBSOCKETSTATUSCODE_NORMAL_CLOSURE</code> must be used for the |
| * usual case. To indicate some specific error cases, codes in the range |
| * <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MIN</code> to |
| * <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MAX</code>, and in the range |
| * <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MIN</code> to |
| * <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MAX</code> are available. |
| * |
| * @param[in] reason A <code>PP_Var</code> representing the WebSocket |
| * close reason. This is ignored if it is <code>PP_VARTYPE_UNDEFINED</code>. |
| * Otherwise, its <code>PP_VarType</code> must be |
| * <code>PP_VARTYPE_STRING</code>. |
| * |
| * @param[in] callback A <code>PP_CompletionCallback</code> called |
| * when the connection is closed or an error occurs in closing the |
| * connection. |
| * |
| * @return An int32_t containing an error code from <code>pp_errors.h</code>. |
| * Returns <code>PP_ERROR_BADARGUMENT</code> if <code>reason</code> contains |
| * an invalid character as a UTF-8 string, or is longer than 123 bytes. |
| * <code>PP_ERROR_BADARGUMENT</code> corresponds to a JavaScript SyntaxError |
| * in the WebSocket API specification. |
| * Returns <code>PP_ERROR_NOACCESS</code> if the code is not an integer |
| * equal to 1000 or in the range 3000 to 4999. <code>PP_ERROR_NOACCESS</code> |
| * corresponds to an InvalidAccessError in the WebSocket API specification. |
| * Returns <code>PP_ERROR_INPROGRESS</code> if a previous call to Close() is |
| * not finished. |
| */ |
| int32_t (*Close)(PP_Resource web_socket, |
| uint16_t code, |
| struct PP_Var reason, |
| struct PP_CompletionCallback callback); |
| /** |
| * ReceiveMessage() receives a message from the WebSocket server. |
| * This interface only returns a single message. That is, this interface must |
| * be called at least N times to receive N messages, no matter the size of |
| * each message. |
| * |
| * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| * WebSocket. |
| * |
| * @param[out] message The received message is copied to provided |
| * <code>message</code>. The <code>message</code> must remain valid until |
| * ReceiveMessage() completes. Its received <code>PP_VarType</code> will be |
| * <code>PP_VARTYPE_STRING</code> or <code>PP_VARTYPE_ARRAY_BUFFER</code>. |
| * |
| * @param[in] callback A <code>PP_CompletionCallback</code> called |
| * when ReceiveMessage() completes. This callback is ignored if |
| * ReceiveMessage() completes synchronously and returns <code>PP_OK</code>. |
| * |
| * @return An int32_t containing an error code from <code>pp_errors.h</code>. |
| * If an error is detected or connection is closed, ReceiveMessage() returns |
| * <code>PP_ERROR_FAILED</code> after all buffered messages are received. |
| * Until buffered message become empty, ReceiveMessage() continues to return |
| * <code>PP_OK</code> as if connection is still established without errors. |
| */ |
| int32_t (*ReceiveMessage)(PP_Resource web_socket, |
| struct PP_Var* message, |
| struct PP_CompletionCallback callback); |
| /** |
| * SendMessage() sends a message to the WebSocket server. |
| * |
| * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| * WebSocket. |
| * |
| * @param[in] message A message to send. The message is copied to an internal |
| * buffer, so the caller can free <code>message</code> safely after returning |
| * from the function. Its sent <code>PP_VarType</code> must be |
| * <code>PP_VARTYPE_STRING</code> or <code>PP_VARTYPE_ARRAY_BUFFER</code>. |
| * |
| * @return An int32_t containing an error code from <code>pp_errors.h</code>. |
| * Returns <code>PP_ERROR_FAILED</code> if the ReadyState is |
| * <code>PP_WEBSOCKETREADYSTATE_CONNECTING</code>. |
| * <code>PP_ERROR_FAILED</code> corresponds to a JavaScript |
| * InvalidStateError in the WebSocket API specification. |
| * Returns <code>PP_ERROR_BADARGUMENT</code> if the provided |
| * <code>message</code> contains an invalid character as a UTF-8 string. |
| * <code>PP_ERROR_BADARGUMENT</code> corresponds to a JavaScript |
| * SyntaxError in the WebSocket API specification. |
| * Otherwise, returns <code>PP_OK</code>, which doesn't necessarily mean |
| * that the server received the message. |
| */ |
| int32_t (*SendMessage)(PP_Resource web_socket, struct PP_Var message); |
| /** |
| * GetBufferedAmount() returns the number of bytes of text and binary |
| * messages that have been queued for the WebSocket connection to send, but |
| * have not been transmitted to the network yet. |
| * |
| * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| * WebSocket. |
| * |
| * @return Returns the number of bytes. |
| */ |
| uint64_t (*GetBufferedAmount)(PP_Resource web_socket); |
| /** |
| * GetCloseCode() returns the connection close code for the WebSocket |
| * connection. |
| * |
| * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| * WebSocket. |
| * |
| * @return Returns 0 if called before the close code is set. |
| */ |
| uint16_t (*GetCloseCode)(PP_Resource web_socket); |
| /** |
| * GetCloseReason() returns the connection close reason for the WebSocket |
| * connection. |
| * |
| * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| * WebSocket. |
| * |
| * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
| * close reason is set, the return value contains an empty string. Returns a |
| * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. |
| */ |
| struct PP_Var (*GetCloseReason)(PP_Resource web_socket); |
| /** |
| * GetCloseWasClean() returns if the connection was closed cleanly for the |
| * specified WebSocket connection. |
| * |
| * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| * WebSocket. |
| * |
| * @return Returns <code>PP_FALSE</code> if called before the connection is |
| * closed, called on an invalid resource, or closed for abnormal reasons. |
| * Otherwise, returns <code>PP_TRUE</code> if the connection was closed |
| * cleanly. |
| */ |
| PP_Bool (*GetCloseWasClean)(PP_Resource web_socket); |
| /** |
| * GetExtensions() returns the extensions selected by the server for the |
| * specified WebSocket connection. |
| * |
| * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| * WebSocket. |
| * |
| * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
| * connection is established, the var's data is an empty string. Returns a |
| * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. |
| */ |
| struct PP_Var (*GetExtensions)(PP_Resource web_socket); |
| /** |
| * GetProtocol() returns the sub-protocol chosen by the server for the |
| * specified WebSocket connection. |
| * |
| * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| * WebSocket. |
| * |
| * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
| * connection is established, the var contains the empty string. Returns a |
| * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. |
| */ |
| struct PP_Var (*GetProtocol)(PP_Resource web_socket); |
| /** |
| * GetReadyState() returns the ready state of the specified WebSocket |
| * connection. |
| * |
| * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| * WebSocket. |
| * |
| * @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID</code> if called |
| * before Connect() is called, or if this function is called on an |
| * invalid resource. |
| */ |
| PP_WebSocketReadyState (*GetReadyState)(PP_Resource web_socket); |
| /** |
| * GetURL() returns the URL associated with specified WebSocket connection. |
| * |
| * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| * WebSocket. |
| * |
| * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
| * connection is established, the var contains the empty string. Returns a |
| * <code>PP_VARTYPE_UNDEFINED</code> if this function is called on an |
| * invalid resource. |
| */ |
| struct PP_Var (*GetURL)(PP_Resource web_socket); |
| }; |
| |
| typedef struct PPB_WebSocket_1_0 PPB_WebSocket; |
| /** |
| * @} |
| */ |
| |
| #endif /* PPAPI_C_PPB_WEBSOCKET_H_ */ |
| |