ppb_websocket.idl

/* 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.
 */

/**
 * This file defines the <code>PPB_WebSocket</code> interface providing
 * bi-directional, full-duplex, communications over a single TCP socket.
 */
label Chrome {
  M18 = 1.0
};


/**
 * 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.
 */
[assert_size(4)]
enum PP_WebSocketReadyState {
  /**
   * 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
};

/**
 * 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().
 */
[assert_size(4)]
enum PP_WebSocketCloseCode {
  /**
   * 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
};

/** 
 * The <code>PPB_WebSocket</code> interface provides bi-directional,
 * full-duplex, communications over a single TCP socket.
 */
interface PPB_WebSocket {
  /**
   * 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([in] 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([in] 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 SecurityError of the
   * specification.
   * Returns <code>PP_ERROR_INPROGRESS</code> if this is not the first call to
   * Connect().
   */
  int32_t Connect([in] PP_Resource web_socket,
                  [in] PP_Var url,
                  [in, size_as=protocol_count] PP_Var[] protocols,
                  [in] uint32_t protocol_count,
                  [in] 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. Ignored if it is 0.
   * <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 InvalidAccessError of the specification. Returns
   * <code>PP_ERROR_INPROGRESS</code> if this is not the first call to
   * Close().
   */
  int32_t Close([in] PP_Resource web_socket,
                [in] uint16_t code,
                [in] PP_Var reason,
                [in] 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([in] PP_Resource web_socket,
                         [out] PP_Var message,
                         [in] 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 the 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 the 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([in] PP_Resource web_socket,
                      [in] 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([in] 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([in] 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.
   */
  PP_Var GetCloseReason([in] 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([in] 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.
   */
  PP_Var GetExtensions([in] 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.
   */
  PP_Var GetProtocol([in] 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([in] 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.
   */
  PP_Var GetURL([in] PP_Resource web_socket);
};