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

[brettw, 2011/09/08 16:39:36]

This is a nice comment.

[Yuzo, 2011/09/29 06:20:31]

Thank you!

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

[brettw, 2011/09/08 16:39:36]

I don't want to hold up this patch, but probably the step after you check this
in is to convert to IDL. This should be easy, and you can do it in parallel with
the implementation.

IDL generation has in other places found inconsistencies (like passing a PP_Var
by pointer instead of value) that affect the API. In this case, I think it will
end up looking like PPP_Instance.DidCreate which will be "const char*
protocols[]"

You don't have to change this now.

[Yuzo, 2011/09/29 06:20:31]

Sure, I'll write the IDL later.

+                     int32_t protocol_count,

[brettw, 2011/09/08 16:39:36]

Can you use uint32_t here? We're using unsigned types for lengths in most of the
APIs.

[Yuzo, 2011/09/29 06:20:31]

Done.

+                     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, or 0, if not, is set to |*remaining_message_byte_count| if

[brettw, 2011/09/08 16:39:36]

I think you can remove "or 0, if not," since I think this is implied and makes
it kind of difficult to parse this sentence.

[Yuzo, 2011/09/29 06:20:31]

Done.

+  // |remaining_message_byte_count| is not null. The remaining bytes of the
+  // message are returned for subsequent call(s) to this method. Bytes of a

[brettw, 2011/09/08 16:39:36]

I'd rephrase your "Bytes of a message..." sentence as "This function only
returns bytes of a single message."

[Yuzo, 2011/09/29 06:20:31]

Done.

+  // message are never returned together with those of 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

[brettw, 2011/09/08 16:39:36]

Can you insert a blank line before "The message type...", this paragraph is
getting kind of long.

[Yuzo, 2011/09/29 06:20:31]

Done.

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

[brettw, 2011/09/08 16:39:36]

I'd also add a blank line before "In copying..." since this is kind of a new
topic.

[Yuzo, 2011/09/29 06:20:31]

Done.

+  // 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 called.

[brettw, 2011/09/08 16:39:36]

Can you say "...until |callback| is issued or Close() is called."

[Yuzo, 2011/09/29 06:20:31]

Done.

+  // - |message_bytes| can be null only if |message_byte_count| is 0.
+  int32_t (*ReceiveMessage)(PP_Resource web_socket,

[brettw, 2011/09/08 16:39:36]

This function is kind of complicated to call. I don't see any way around that.
One of the next steps after this patch will be to provide a C++ wrapper around
this class. I think this should be in two separate layers: the first layer would
be a straightforward wrapper around this API using C++ primitives
(pp::CompletionCallback).

It seems like it would be nice to provide a high-level layer on top of that,
where you can imagine what would be most convenient to most callers. It seems
like converting the completion callbacks and buffers to some kind of virtual
function call that passes an entire message as a vector<char> to the plugin
would be most convenient, saving the plugin from having to implement all the
buffer and callback management.

I would probably implement this in parallel with the Pepper implementation. For
testing, I'd write a sample app and just design the high-level C++ wrapper in
parallel to be as convenient to use as possible from the perspective of your
test plugin.

[Yuzo, 2011/09/29 06:20:31]

I agree that this method should be simplified if possible.

+                            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 an empty

[brettw, 2011/09/08 16:39:36]

Can you change this to "Returns a PP_VARTYPE_NULL var if called before the close
reason is set, or PP_VARTYPE_UNDEFINED if called on an invalid resource." I
think this is also a good rule for the later functions that return PP_Var,
rather than returning an empty string.

[Yuzo, 2011/09/29 06:20:31]

Done, for all the methods that return PP_Var.

+  // string if called before the close reason is set.
+  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 an empty string if called before the connection is established.
+  PP_Var (*GetExtensions)(PP_Resource web_socket);
+
+  // Returns 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);
+
+  // 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
+  // called before the connection is established.
+  PP_Var (*GetUrl)(PP_Resource web_socket);
+};
+
+#endif  // PPAPI_C_DEV_PPB_WEBSOCKET_DEV_H_