IDL for WebSocket Pepper API.

ppapi/api/dev/ppb_websocket_dev.idl

+/* Copyright (c) 2011 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_Dev</code> interface.
+ *
+ * Note on the differences from JavaScript WebSocket API
+ * http://dev.w3.org/html5/websockets/
+ *
+ * This interface has some differences from its JavaScript counterpart mainly
+ * to make best use of PP_CompletionCallback and be consistent with other
+ * interfaces such as PPB_Transport_Dev.
+ *
+ * - Constructor doesn't take URL or protocols and there is a method to
+ * establish connection.
+ *
+ * - Error handlers or close handlers cannot be registered. (A callback can be
+ * specified on explicitly closing a connection.) To detect an error or
+ * connection closure, ready state, closure cleanness, closure code, and
+ * closure reason should be queried instead.
+ *
+ * - Message size is represented as int32_t rather than uint64_t.
+ * PP_CompletionCallback handles int32_t better. Messages out of that range
+ * are too large to handle efficiently anyway.
+ *
+ * Note on error codes.
+ *
+ * Methods that take PP_CompletionCallback can return error codes. They
+ * correspond to JavaScript exceptions as follows:
+ *
+ * PP_ERROR_BADARGUMENT: SYNTAX_ERR

[tyoshino (SeeGerritForStatus), 2011/10/26 17:56:35]

Use new style exception symbols? e.g. here, SyntaxError

[Takashi Toyoshima, 2011/10/27 09:07:38]

Done.

+ * PP_ERROR_NOACCESS: SECURITY_ERR, INVALID_ACCESS_ERR
+ * PP_ERROR_FAILED: INVALID_STATE_ERR
+ *
+ * Other error codes such as PP_ERROR_ABORTED and PP_ERROR_BADRESOURCE can
+ * also be returned.
+ */
+label Chrome {
+  M16 = 0.1
+};
+
+
+/**
+ * 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_Dev {
+  /**
+   * 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 the types representing the WebSocket message type
+ * and these types are based on the JavaScript WebSocket API specification.
+ * ReceiveMessage() and SendMessage() use them as a parameter to represent
+ * handling message types.
+ */
+[assert_size(4)]
+enum PP_WebSocketMessageType_Dev {
+  /**
+   * Message type that represents a text message type.
+   */
+  PP_WEBSOCKET_MESSAGE_TYPE_TEXT = 0,
+
+  /**
+   * Message type that represents a binary message type.
+   */
+  PP_WEBSOCKET_MESSAGE_TYPE_BINARY = 1
+};
+
+[version=0.1, macro="PPB_WEBSOCKET_DEV_INTERFACE"]
+interface PPB_WebSocket_Dev {
+  /**
+   * Create() Creates a WebSocket instance.

[tyoshino (SeeGerritForStatus), 2011/10/26 17:56:35]

creates

[Takashi Toyoshima, 2011/10/27 09:07:38]

Done.

+   *
+   * @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_Dev</code>, <code>PP_FALSE</code> if the
+   * <code>resource</code> is invalid or some type other than
+   * <code>PPB_WebSocket_Dev</code>.
+   */
+  PP_Bool IsWebSocket([in] PP_Resource resource);
+
+  /**
+   * SetCloseCallback() sets the callback which is called when the WebSocket
+   * connection is closed.
+   * Closure code and reason should be queried via each interface.

[tyoshino (SeeGerritForStatus), 2011/10/26 17:56:35]

how about using the same term as the spec? closure status code -> close code
closure reason -> close reason

[Takashi Toyoshima, 2011/10/27 09:07:38]

Done.

+   * Caller can call this method safely only before calling Connect().
+   *
+   * @param[in] web_socket A <code>PP_Resource</code> corresponding to a
+   * WebSocket.
+   *
+   * @param[in] callback A <code>PP_CompletionCallback</code> which is called
+   * when the connection is closed.
+   *
+   * @return Returns <code>PP_OK</code>.
+   */
+  int32_t SetCloseCallback([in] PP_Resource web_socket,
+                           [in] PP_CompletionCallback callback);
+
+  /**
+   * Connect() connects to the specified WebSocket server. Caller can call this
+   * method at most 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> which is called
+   * when the connection is established or an error occurs.
+   *
+   * @return In case of immediate failure, returns an error code as follows.
+   * Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript
+   * SyntaxError and <code>PP_ERROR_NOACCESS</code> corresponding to JavaScript
+   * SecurityError. Otherwise, returns <code>PP_OK_COMPLETIONPENDING</code>.
+   */
+  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 closure status code. Ignored if it is 0.
+   *
+   * @param[in] reason A <code>PP_Var</code> which represents the WebSocket
+   * closure reason. 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> which is called
+   * when the connection is closed or an error occurs.
+   *
+   * @return In case of immediate failure, returns an error code as follows.
+   * Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript
+   * SyntaxError and <code>PP_ERROR_FAILED</code> corresponding to JavaScript
+   * InvalidStateError. Otherwise, returns
+   * <code>PP_OK_COMPLETIONPENDING</code>.
+   */
+  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.
+   * Caller must keep <code>message_bytes</code>,
+   * <code>remaining_message_byte_count</code>, and <code>message_type</code>
+   * valid until <code>callback</code> is issued or Close() is called.
+   *
+   * Note: This interface might be changed as follows.
+   * int32_t ReceiveMessage([in] PP_Resource web_socket,
+   *                        [out] PP_Var message,
+   *                        [out] int32_t remaining_message_byte_count,
+   *                        [in] PP_CompletionCallback callback);
+   *
+   * @param[in] web_socket A <code>PP_Resource</code> corresponding to a
+   * WebSocket.
+   *
+   * @param[out] message_bytes The message is copied to provided
+   * <code>message_bytes</code> up to <code>message_byte_count</code> bytes.
+   * <code>message_bytes</code> can be null only if
+   * <code>message_byte_count</code> is 0.
+   * In copying message to <code>message_bytes</code>, UTF-8 byte sequence
+   * boundaries are not considered. Hence if the message is larger than
+   * <code>message_bytes</code>, the last byte sequence may end prematurely.
+   * Likewise, the first sequence of the bytes returned for the subsequent call
+   * may start in the middle.
+   *
+   * @param[in] message_bytes_count The maximum receiving size in bytes.
+   *
+   * @param[out] remaining_byte_count The number of remaining bytes, if any, is
+   * set to <code>remaining_message_byte_count</code> if
+   * <code>remaining_message_byte_count</code> is not null. The remaining bytes
+   * of the message are returned for subsequent call(s) to this method.
+   *
+   * @param[out] message_type A <code>PP_WebSocketMessageType_Dev</code>
+   * representing the message type is set to <code>message_type</code> if
+   * <code>message_type</code> is not null. If the message is text, it is
+   * encoded in UTF-8.
+   *
+   * @param[in] callback A <code>PP_CompletionCallback</code> which is called
+   * if the interface has been returned<code>PP_OK_COMPLETIONPENDING</code>.
+   * The number of bytes copied is passed as the second argument.
+   *
+   * @return If a message is currently available, returns the number of bytes
+   * copied to <code>message_bytes</code>. Otherwise, returns
+   * <code>PP_OK_COMPLETIONPENDING</code> and calls <code>callback</code> when
+   * the message is available.
+   * Messages are queued internally. Hence this method can be called either
+   * before or after a message is received by the browser. If the queue grows
+   * beyond the browser-dependent limit, <code>web_socket</code> is closed and
+   * messages are discarded.
+   * This interface only returns bytes of a single message. That is, this
+   * interface must be called at least N times to receive N messages, no matter
+   * how small each message is.
+   */
+  int32_t ReceiveMessage([in] PP_Resource web_socket,
+                         [out,size_as=message_byte_count] void message_bytes,
+                         [in] int32_t message_byte_count,
+                         [out] int32_t remaining_message_byte_count,
+                         [out] PP_WebSocketMessageType_Dev message_type,
+                         [in] PP_CompletionCallback callback);
+
+  /**
+   * SendMessage() sends a message to the WebSocket server.
+   *
+   * Note: This interface might be changed as follows.
+   * int32_t SendMessage([in] PP_Resource web_socket,
+   *                     [in] PP_Var message);
+   *
+   * @param[in] web_socket A <code>PP_Resource</code> corresponding to a
+   * WebSocket.
+   *
+   * @param[in] message_bytes A message to send. The message is copied to
+   * internal buffer. So caller can free <code>message_bytes</code> safely
+   * after returning from the function.
+   *
+   * @param[in] message_byte_count The length of the message in bytes.
+   *
+   * @param[in] message_type A <code>PP_WebSocketMessageType_Dev</code>
+   * representing the message type of the <code>message</code>.
+   *
+   * @return In case of immediate failure, returns an error code as follows.
+   * Returns <code>PP_ERROR_FAILED</code> corresponding JavaScript
+   * InvalidStateError and <code>PP_ERROR_BADARGUMENT</code> corresponding
+   * JavaScript SyntaxError. Otherwise, return <code>PP_OK</code>.
+   * <code>PP_OK</code> doesn't necessarily mean that the server received the
+   * message.
+   */
+  int32_t SendMessage([in] PP_Resource web_socket,
+                      [in,size_as=message_byte_count] void[] message_bytes,
+                      [in] int32_t message_byte_count,
+                      [in] PP_WebSocketMessageType_Dev message_type);
+
+  /**
+   * 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.
+   *
+   * Note: This interface might not be able to return exact bytes in the first
+   * release.
+   *
+   * @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_NULL</code> var if called before the
+   * close reason is set, or <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. Otherwise, returns <code>PP_TRUE</code> if the connection was
+   * closed cleanly and returns <code>PP_FALSE</code> if the connection was
+   * closed by abnormal reasons.
+   */
+  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_NULL</code> var if called before the
+   * connection is established, or <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_NULL</code> var if called before the
+   * connection is established, or <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_CONNECTING</code> if called
+   * before the connection is established.
+   */
+  PP_WebSocketReadyState_Dev 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_NULL</code> var if called before the
+   * connection is established, or <code>PP_VARTYPE_UNDEFINED</code> if called
+   * on an invalid resource.
+   */
+  PP_Var GetUrl([in] PP_Resource web_socket);
+};