IDL for WebSocket Pepper API.

ppapi/c/dev/ppb_websocket_dev.h

+/* 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.
+ */
+
+/* From dev/ppb_websocket_dev.idl modified Thu Oct 27 22:42:42 2011. */
+
+#ifndef PPAPI_C_DEV_PPB_WEBSOCKET_DEV_H_
+#define PPAPI_C_DEV_PPB_WEBSOCKET_DEV_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_DEV_INTERFACE_0_1 "PPB_WebSocket(Dev);0.1"
+#define PPB_WEBSOCKET_DEV_INTERFACE PPB_WEBSOCKET_DEV_INTERFACE_0_1
+
+/**
+ * @file
+ * This file defines the <code>PPB_WebSocket_Dev</code> interface.
+ */
+
+
+/**
+ * @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 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_Dev;
+PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_WebSocketReadyState_Dev, 4);
+
+/**
+ * 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.
+ */
+typedef enum {
+  /**
+   * 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
+} PP_WebSocketMessageType_Dev;
+PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_WebSocketMessageType_Dev, 4);
+/**
+ * @}
+ */
+
+/**
+ * @addtogroup Interfaces
+ * @{
+ */
+struct PPB_WebSocket_Dev {
+  /**
+   * 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_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)(PP_Resource resource);
+  /**
+   * SetOpenCallback() sets the callback which is called when the WebSocket
+   * connection is opened. This callback corresponds to onopen event of
+   * JavaScript API.
+   * 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 opened.
+   *
+   * @return Returns <code>PP_OK</code>.
+   */
+  int32_t (*SetOpenCallback)(PP_Resource web_socket,
+                             struct PP_CompletionCallback callback);
+  /**
+   * SetMessageCallback() sets the callback which is called when the WebSocket
+   * connection receives a frame. This callback corresponds to onmessage event
+   * of JavaScript API.
+   * Callback is invoked when the next frame can be read via ReceiveMessage().
+   * 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 receives a frame.
+   *
+   * @return Returns <code>PP_OK</code>.
+   */
+  int32_t (*SetMessageCallback)(PP_Resource web_socket,
+                                struct PP_CompletionCallback callback);
+  /**
+   * SetErrorCallback() sets the callback which is called when the WebSocket
+   * connection is closed with prejudice. This callback corresponds to onclose
+   * event of JavaScript API.
+   * 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 receives a frame.
+   *
+   * @return Returns <code>PP_OK</code>.
+   */
+  int32_t (*SetErrorCallback)(PP_Resource web_socket,
+                              struct PP_CompletionCallback callback);
+  /**
+   * SetCloseCallback() sets the callback which is called when the WebSocket
+   * connection is closed. This callback corresponds to onclose event of
+   * JavaScript API.
+   * Close code and reason should be queried via each interface.
+   * 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)(PP_Resource web_socket,
+                              struct 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>.
+   *
+   * @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</code>.
+   */
+  int32_t (*Connect)(PP_Resource web_socket,
+                     struct PP_Var url,
+                     const struct PP_Var protocols[],
+                     uint32_t protocol_count);
+  /**
+   * 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.
+   *
+   * @param[in] reason A <code>PP_Var</code> which represents the WebSocket
+   * close reason. Ignored if it is <code>PP_VARTYPE_UNDEFINED</code>.
+   * Otherwise, its <code>PP_VarType</code> must be
+   * <code>PP_VARTYPE_STRING</code>.
+   *
+   * @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
+   * InvalidAccessError. Otherwise, returns
+   * <code>PP_OK</code>.
+   */
+  int32_t (*Close)(PP_Resource web_socket, uint16_t code, struct PP_Var reason);
+  /**
+   * ReceiveMessage() receives a message from the WebSocket server.
+   * 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.
+   *
+   * 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);
+   *
+   * @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.

[cstefansen, 2011/11/01 17:58:15]

What would be the purpose of calling ReceiveMessage with message_byte_count = 0?
Is this just meant as a convenience to avoid special casing?

[Takashi Toyoshima, 2011/11/02 09:23:42]

This header file is generated from IDL automatically, so I think it would be
better to comment to IDL itself.
Anyway, I make responses here.

Calling with message_byte_count = 0 can be used to know the incoming next frame
size.
First, call it with empty buffer to know the size of frame, then allocate a
buffer with the size. Finally, we can get the whole one frame data by one call.
Win32 API sometime prefer such kind of API to receive unknown size data via API.

+   * 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

[cstefansen, 2011/11/01 17:58:15]

This sounds a bit inconvenient for the API user. Is there another reason for
doing this than simply convenience for the implementor?

[Takashi Toyoshima, 2011/11/02 09:23:42]

Now, I think we must define minimum C API which is necessary and sufficient. We
can define convenient C++ API over them.

+   * 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.
+   *
+   * @return If a message is currently available, returns the number of bytes
+   * copied to <code>message_bytes</code>. Otherwise, returns 0.
+   * Frame boundaries must be detected by <code>remaining_byte_count</code>.
+   * If the next message is available as a result, registerd callback by
+   * SetMessageCallback() will be invoked.
+   * 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.
+   */
+  int32_t (*ReceiveMessage)(PP_Resource web_socket,
+                            void* message_bytes,
+                            int32_t message_byte_count,
+                            int32_t* remaining_message_byte_count,
+                            PP_WebSocketMessageType_Dev* message_type);

[cstefansen, 2011/11/01 17:58:15]

To receive a message one would have to (a) receive a callback on the register
callback (see SetMessageCallback) and (b) call ReceiveMessage. I think this is
fine, but I'd like us to make sure that we can perform these two steps without
having to make several RPC calls in the out-of-process case, as this would
adversely affect performance. Thoughts?

[Takashi Toyoshima, 2011/11/02 09:23:42]

OK.
I'll take care on it for next revision.

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

[cstefansen, 2011/11/01 17:58:15]

Nit: corresponding -> corresponding to

[Takashi Toyoshima, 2011/11/02 09:23:42]

Done.

+   * InvalidStateError and <code>PP_ERROR_BADARGUMENT</code> corresponding

[cstefansen, 2011/11/01 17:58:15]

Same here.

[Takashi Toyoshima, 2011/11/02 09:23:42]

Done.

+   * 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)(PP_Resource web_socket,
+                         const void message_bytes[],
+                         int32_t message_byte_count,
+                         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.

[cstefansen, 2011/11/01 17:58:15]

Could you elaborate?

[Takashi Toyoshima, 2011/11/02 09:23:42]

Done.

+   *
+   * @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_NULL</code> var if called before the
+   * close reason is set, or <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. 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)(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.
+   */
+  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_NULL</code> var if called before the
+   * connection is established, or <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_CONNECTING</code> if called
+   * before the connection is established.
+   */
+  PP_WebSocketReadyState_Dev (*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_NULL</code> var if called before the
+   * connection is established, or <code>PP_VARTYPE_UNDEFINED</code> if called
+   * on an invalid resource.
+   */
+  struct PP_Var (*GetUrl)(PP_Resource web_socket);
+};
+/**
+ * @}
+ */
+
+#endif  /* PPAPI_C_DEV_PPB_WEBSOCKET_DEV_H_ */
+