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|. The instance is
+  // initially in PP_WEBSOCKETREADYSTATE_CONNECTING state (even before Connect
+  // method is called).
+  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-terminate |url| specifying |protocols|.

[tyoshino (SeeGerritForStatus), 2011/09/07 13:07:58]

terminated

[Yuzo, 2011/09/08 06:08:15]

Done.

+  // |protocols| points to an array of null-terminated protocol strings. In case

[tyoshino (SeeGerritForStatus), 2011/09/07 13:07:58]

protocol -> sub-protocol

[Yuzo, 2011/09/08 06:08:15]

Done: protocol strings -> sub-protocols.

+  // 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.
+  //
+  // Callers 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,
+                     int32_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. Returns PP_OK_COMPLETIONPENDING
+  // otherwise.

[tyoshino (SeeGerritForStatus), 2011/09/07 13:07:58]

If successful, it's notified only by callback? PP_OK is never returned even if
data is ready?

[Yuzo, 2011/09/08 06:08:15]

Good point.

Changed the method such that the number of bytes copied is returned in case a
message is already 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.
+  //
+  // Calls |callback| when the message is available. The message is copied to
+  // |*message_bytes| up to |message_byte_count| bytes. |message_bytes| can be

[tyoshino (SeeGerritForStatus), 2011/09/07 13:07:58]

remove *

[Yuzo, 2011/09/08 06:08:15]

Done.

+  // null only if |message_byte_count| is 0. The number of bytes copied is
+  // passed to the |callback| as its second argument. The number of remaining
+  // bytes, if any, or 0, if not, is set to |*remaining_message_byte_count| if
+  // |remaining_message_byte_count| is not null. The remaining message bytes are

[tyoshino (SeeGerritForStatus), 2011/09/07 13:07:58]

I'd suggest
s/remaining message bytes/remaining bytes of the message/

[Yuzo, 2011/09/08 06:08:15]

Done.

+  // returned for subsequent call(s) to this method. Bytes from a message are

[tyoshino (SeeGerritForStatus), 2011/09/07 13:07:58]

from -> of? I'm not sure.

[Yuzo, 2011/09/08 06:08:15]

I'm not sure either but changed to "of".

+  // never returned together with those from other messages. 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|, character boundary is not
+  // considered. Hence if the message is larger than |message_bytes|, the last
+  // character may have incomplete bytes, and subsequent call my return

[tyoshino (SeeGerritForStatus), 2011/09/07 13:07:58]

may

[tyoshino (SeeGerritForStatus), 2011/09/07 13:07:58]

Do you mean part of UTF-8 sequence by "incomplete bytes"? Some rephrasing to
make it clear is nice.

[Yuzo, 2011/09/08 06:08:15]

Done.

[Yuzo, 2011/09/08 06:08:15]

Rewrote as:

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.

[Yuzo, 2011/09/08 06:08:15]

Done.

[Yuzo, 2011/09/08 06:08:15]

Done.

[Yuzo, 2011/09/08 06:08:15]

Done.

+  // incomplete bytes for the first character.
+  //
+  // Callers responsibilities:

[tyoshino (SeeGerritForStatus), 2011/09/07 13:07:58]

Caller's

[Yuzo, 2011/09/08 06:08:15]

Done.

+  // - Caller must keep |message_bytes| and |message_type| valid until

[tyoshino (SeeGerritForStatus), 2011/09/07 13:07:58]

and remaining_message_bytes_count?

[Yuzo, 2011/09/08 06:08:15]

Good catch!
Done.

[Yuzo, 2011/09/08 06:08:15]

Done.

+  // |callback| 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);
+
+  // Gets the buffered (for sending) amount for |web_socket|.
+  uint64_t (*GetBufferedAmount)(PP_Resource web_socket);
+
+  // Gets the connection close code for |web_socket|.

[tyoshino (SeeGerritForStatus), 2011/09/07 13:07:58]

It would be nice if you add some text to say when this returns valid value.

[Yuzo, 2011/09/08 06:08:15]

Done.

+  uint16_t (*GetCloseCode)(PP_Resource web_socket);
+
+  // Gets the connection close reason for |web_socket|.

[tyoshino (SeeGerritForStatus), 2011/09/07 13:07:58]

ditto

[Yuzo, 2011/09/08 06:08:15]

Done.

+  PP_Var (*GetCloseReason)(PP_Resource web_socket);
+
+  // Gets if the connection was closed cleanly for |web_socket|.

[tyoshino (SeeGerritForStatus), 2011/09/07 13:07:58]

ditto

[Yuzo, 2011/09/08 06:08:15]

Done.

+  PP_Bool (*GetCloseWasClean)(PP_Resource web_socket);
+
+  // Gets the extension selected by the server for |web_socket|.
+  // Returns an empty string if called before the connection is established.
+  PP_Var (*GetExtensions)(PP_Resource web_socket);
+
+  // Gets the sub-protocol chosen by the server for |web_socket|.
+  // Returns an empty string if called before the connection is established.
+  PP_Var (*GetProtocol)(PP_Resource web_socket);
+
+  // Gets the ready state of |web_socket|.
+  PP_WebSocketReadyState_Dev (*GetReadyState)(PP_Resource web_socket);
+
+  // Gets the URL associated with |web_socket|.
+  // Returns an empty string if called before the connection is established.
+  PP_Var (*GetUrl)(PP_Resource web_socket);
+};
+
+#endif  // PPAPI_C_DEV_PPB_WEBSOCKET_DEV_H_