WebSocket Pepper C API. In this change, only the C interface is defined and no

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.
+ */
+#ifndef PPAPI_C_DEV_PPB_WEBSOCKET_DEV_H_
+#define PPAPI_C_DEV_PPB_WEBSOCKET_DEV_H_
+
+#include "ppapi/c/pp_instance.h"
+#include "ppapi/c/pp_macros.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
+
+typedef enum {
+  PP_WEBSOCKETREADYSTATE_CONNECTING = 0,
+  PP_WEBSOCKETREADYSTATE_OPEN = 1,
+  PP_WEBSOCKETREADYSTATE_CLOSING = 2,
+  PP_WEBSOCKETREADYSTATE_CLOSED = 3
+} PP_WebSocketReadyState_Dev;
+PP_COMPILE_ASSERT_ENUM_SIZE_IN_BYTES(PP_WebSocketReadyState_Dev, 4);
+
+typedef enum {
+  PP_WEBSOCKET_MESSAGE_TYPE_TEXT = 0,
+  PP_WEBSOCKET_MESSAGE_TYPE_BINARY = 1
+} PP_WebSocketMessageType_Dev;
+PP_COMPILE_ASSERT_ENUM_SIZE_IN_BYTES(PP_WebSocketMessageType_Dev, 4);
+
+struct PPB_WebSocket_Dev {
+  // 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
+  // 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.
+
+  // Creates a WebSocket instance for plugin module |instance|.
+  PP_Resource (*Create)(PP_Instance instance);
+
+  // Returns PP_TRUE if |resource| is a WebSocket instance, PP_FALSE otherwise.
+  PP_Bool (*IsWebSocket)(PP_Resource resource);
+
+  // Connects |web_socket| to null-terminated |url| specifying |protocols|.
+  // |protocols| points to an array of null-terminated sub-protocols. In case of
+  // immediate failure, returns an error code as specified above. Returns
+  // PP_OK_COMPLETIONPENDING otherwise. Calls |callback| when the connection is
+  // established or an error occurs.
+  //
+  // Caller's responsibilities:
+  // - Caller can call this method at most once for a |web_socket|.
+  // - |protocols| can be null only if |protocol_count| is 0.
+  int32_t (*Connect)(PP_Resource web_socket,
+                     const char* url,
+                     const char* const* protocols,
+                     uint32_t protocol_count,
+                     PP_CompletionCallback callback);
+
+  // Closes |web_socket| specifying |code| and null-terminated |reason|. |code|
+  // is ignored if it is 0. |reason| is ignored if it is null. In case of
+  // immediate failure, returns an error code as specified above. Returns
+  // PP_OK_COMPLETIONPENDING otherwise. Calls |callback| when the connection is
+  // closed or an error occurs.
+  int32_t (*Close)(PP_Resource web_socket,
+                   uint16_t code,
+                   const char* reason,
+                   PP_CompletionCallback callback);
+
+  // Receives a message from |web_socket|. In case of immediate failure, returns
+  // an error code as specified above. If a message is currently available,
+  // returns the number of bytes copied to |message_bytes| (see below).
+  // Otherwise, returns PP_OK_COMPLETIONPENDING and calls |callback| 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, |web_socket| is closed and messages are
+  // discarded.
+  //
+  // The message is copied to |message_bytes| up to |message_byte_count| bytes.
+  // |message_bytes| can be null only if |message_byte_count| is 0. The number
+  // of bytes copied is passed to the |callback| as its second argument in case
+  // PP_OK_COMPLETIONPENDING has been returned. The number of remaining bytes,
+  // if any, is set to |*remaining_message_byte_count| if
+  // |remaining_message_byte_count| is not null. The remaining bytes of the
+  // message are returned for subsequent call(s) to this method.
+  // This function only returns bytes of a single message.
+  // That is,
+  // this method must be called at least N times to receive N messages, no
+  // matter how small each message is.
+  //
+  // The message type is set to
+  // |*message_type| if |message_type| is not null. If the message is text, it
+  // is encoded in UTF-8.
+  //
+  // In copying message to |message_bytes|, UTF-8 byte
+  // sequence boundaries are not considered. Hence if the message is larger than
+  // |message_bytes|, the last byte sequence may end prematurely. Likewise, the
+  // first sequence of the bytes returned for the subsequent call may start in
+  // the middle.
+  //
+  // Caller's responsibilities:
+  // - Caller must keep |message_bytes|, |remaining_message_byte_count|, and
+  // |message_type| valid until |callback| is issued or Close() is called.
+  // - |message_bytes| can be null only if |message_byte_count| is 0.
+  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,
+                            PP_CompletionCallback callback);
+
+  // Sends a message to |web_socket|. In case of immediate failure, returns an
+  // error code as specified above. Returns PP_OK otherwise. PP_OK doesn't
+  // necessarily mean that the server received the message.
+  //
+  // Message is specified as |message_bytes| of |message_type| whose length is
+  // |message_byte_count|.
+  int32_t (*SendMessage)(PP_Resource web_socket,
+                         void* message_bytes,
+                         int32_t message_byte_count,
+                         PP_WebSocketMessageType_Dev message_type);
+
+  // Returns the number of bytes of text and binary messages that have been
+  // queued for |web_socket| for sending but have not been transmitted to the
+  // network yet.
+  uint64_t (*GetBufferedAmount)(PP_Resource web_socket);
+
+  // Returns the connection close code for |web_socket|. Returns 0 if called
+  // before the close code is set.
+  uint16_t (*GetCloseCode)(PP_Resource web_socket);
+
+  // Returns the connection close reason for |web_socket|. Returns a
+  // PP_VARTYPE_NULL var if called before the close reason is set, or
+  // PP_VARTYPE_UNDEFINED if called on an invalid resource.
+  PP_Var (*GetCloseReason)(PP_Resource web_socket);
+
+  // Returns if the connection was closed cleanly for |web_socket|. Returns
+  // false if called before the connection is closed.
+  PP_Bool (*GetCloseWasClean)(PP_Resource web_socket);
+
+  // Returns the extension selected by the server for |web_socket|. Returns a
+  // PP_VARTYPE_NULL var if called before the connection is established, or
+  // PP_VARTYPE_UNDEFINED if called on an invalid resource.
+  PP_Var (*GetExtensions)(PP_Resource web_socket);
+
+  // Returns the sub-protocol chosen by the server for |web_socket|. Returns a
+  // PP_VARTYPE_NULL var if called before the connection is established, or
+  // PP_VARTYPE_UNDEFINED if called on an invalid resource.
+  PP_Var (*GetProtocol)(PP_Resource web_socket);
+
+  // Returns the ready state of |web_socket|. Returns
+  // PP_WEBSOCKETREADYSTATE_CONNECTING if called before the connection is
+  // established.
+  PP_WebSocketReadyState_Dev (*GetReadyState)(PP_Resource web_socket);
+
+  // Returns the URL associated with |web_socket|. Returns an empty string if
+  // Returns a PP_VARTYPE_NULL var if called before the connection is
+  // established, or PP_VARTYPE_UNDEFINED if called on an invalid resource.
+  PP_Var (*GetUrl)(PP_Resource web_socket);
+};
+
+#endif  // PPAPI_C_DEV_PPB_WEBSOCKET_DEV_H_