IDL for WebSocket Pepper API.

ppapi/api/dev/ppb_websocket_dev.idl

Index: ppapi/api/dev/ppb_websocket_dev.idl
diff --git a/ppapi/api/dev/ppb_websocket_dev.idl b/ppapi/api/dev/ppb_websocket_dev.idl
new file mode 100644
index 0000000000000000000000000000000000000000..70a68716eaac264ab5470a6ae42f7b3c65efb9d1
--- /dev/null
+++ b/ppapi/api/dev/ppb_websocket_dev.idl
@@ -0,0 +1,397 @@
+/* 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.
+ */
+label Chrome {
+  M16 = 0.1

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

Note: We should plan to pull it out of dev for M17, but a different CL can do
that.

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

I guess IDL generator doesn't support M17 yet.
First, I try to define it as M17, but generator failed to generate C header.
Who should I ping about generator's M17 support?

[dmichael (off chromium), 2011/11/02 16:14:40]

noelallen

[Takashi Toyoshima, 2011/11/04 08:45:55]

Thanks.
I pinged him with change http://codereview.chromium.org/8460004/.

+};
+
+
+/**
+ * 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,

[dmichael (off chromium), 2011/11/01 21:03:24]

We've had problems in the past when transitioning out of Dev because enum names
collide. Maybe we should append _DEV to the enum names?

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

Done.

+
+  /**
+   * 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.
+   *
+   * @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);
+
+  /**
+   * 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([in] PP_Resource web_socket,

[darin (slow to review), 2011/11/01 17:40:53]

How about just passing a PP_CompletionCallback to Connect, and then eliminate
this SetOpenCallback method altogether?

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

I think Darin's suggest is good for IDL and C interface.
I could build JS like API on C++ using these C interfaces and it will satisfy
Christian's requirement.

So I'll revert to previous API definition which didn't have these Set*Callback
APIs.
And I'll add CompletionCallback to Connect.
I guess I can use ReceiveMessage's completion callback for C++ API to provide JS
like interfaces. Continuously call ReceiveMessage as async on background. In
this manner, we can notice frame receiving and unexpected close just in time.

[dmichael (off chromium), 2011/11/02 16:14:40]

I'm not sure what you mean, but it might be interesting to give it a shot. You
could also make the C++ look a lot like the JavaScript (if desired) by adding a
PPP interface with something like DidClose, DidReceiveMessage, DidReceiveError.
The C++ class could then allow end-developers to override appropriate virtual
methods. It might be more straightforward, if mirroring the JS API is important
to you.
I think that's a good approach too, though it has the downside that Christian
mentioned, and it might be more difficult to make the C++ look like the
JavaScript API.
What do you mean by 'async on background'? Are you going to chain ReceiveMessage
calls each time the completion callback is invoked?

Bear in mind it might be tricky to make completion callbacks in a C++ wrapper in
a thread-safe way. We currently don't have threading or synchronization
primitives available to the C++ layer. We might need to add them anyway, but it
feels like overkill for this if there are other ways.

[cstefansen, 2011/11/02 16:23:30]

Personally, I think having an API that is natural and idiomatic in C and C++ is
more important than mirroring JS exactly.

On 2011/11/02 16:14:40, dmichael wrote:

[Takashi Toyoshima, 2011/11/04 08:45:55]

Thank you for advices.
I understand that my previous Set*Callback APIs must be implemented by PPP
interface. But, I'd like to just cancel these APIs now.

About 'async on background', Dave's surmise is right. I meant the chain
ReceiveMessage calls.

By the way, I didn't understand which thread invoke each callback for now.

To my understanding, calling a pepper API (except for core API?) from non-main
thread in NaCl cause crash. So every valid API call must be done in main thread.
The main thread in NaCl seems to work in event driven model like JavaScript. So,
I guess the invoking callback task will be queued into main thread's event pool,
then main thread picks up and executes the callback function in main thread
context.
Is this understanding right?

[dmichael (off chromium), 2011/11/04 15:26:18]

This is true for now, but I'm (slowly) working on fixing that. All the APIs need
to be designed so that they can be called from background threads (even if it's
not supported right away).
Yes, I was a little confused. CompletionCallbacks will always be invoked on the
main thread. And I suppose that I'm going to have to support the creation of
CompletionCallback off of the main thread as part of the other threading work
anyway, so I think what you're describing is feasible.

It occurs to me that there might be some unfortunate performance implications of
doing it this way. By having the API require chaining the calls, we're adding an
RPC round-trip for each frame, since the plugin has to ask for each frame by
calling ReceiveMessage. It might be better if the server can just keep pushing
them to a PPP interface. Or am I misunderstanding something?

+                          [in] 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([in] PP_Resource web_socket,

[darin (slow to review), 2011/11/01 17:40:53]

Have you considered just passing a PP_CompletionCallback parameter to
ReceiveMessage?  Maybe you are concerned about the fact that ReceiveMessage
takes out-parameters?  Those would need to remain valid until the completion
callback runs.

Note: completion callbacks are one-shot.  Also, by placing the completion
callback on the method that might take time to complete, you create an API that
can either work asynchronously on the main thread (completion callback is
non-null) or synchronously on a background thread (completion callback is null).

[cstefansen, 2011/11/01 18:08:51]

This slightly incongruent with the JS version which has you register event
handlers (e.g., onmessage), but I think I like it – particularly given that
callbacks are one-shot, as you mention, so it won't work to register a general
onmessage callback.

On 2011/11/01 17:40:53, darin wrote:

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

See comment at SetOpenCallback.

+                             [in] 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([in] PP_Resource web_socket,

[darin (slow to review), 2011/11/01 17:40:53]

It seems like this should not be necessary.  errors can be reported by making
Connect, ReceiveMessage or SendMessage generate an error, right?  There could
also be a way to poll for the current connection state if being able to notice
errors after connect and before trying to read/write a message is useful.

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

See comment at SetOpenCallback.

+                           [in] 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([in] PP_Resource web_socket,

[darin (slow to review), 2011/11/01 17:40:53]

Ditto.  I'd just get rid of this in favor of using different error codes to
distinguish between different flavors of closing.

[cstefansen, 2011/11/01 18:08:51]

How would you know that the connection closed if you didn't initiate the
closure? Polling for status is not desirable, and you will often keep the
connection open for some time without sending or receiving, so you are not
necessarily calling those functions either.

On 2011/11/01 17:40:53, darin wrote:

[dmichael (off chromium), 2011/11/01 21:03:24]

Another thing to note, though, is that it doesn't make much sense to have >1
completion callback in response to a particular PPB call. At the very least, it
would make the return value ambiguous and give the caller several ways to mess
up.

Are you suggesting having both a 'Connected' and 'Close' callback passed to
'Connect'? I don't think we should.

It might make sense to have a PPP interface. That would make it easier to map to
the JavaScript API.

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

See comment at SetOpenCallback.

+                           [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>.
+   *
+   * @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([in] PP_Resource web_socket,
+                  [in] PP_Var url,
+                  [in, size_as=protocol_count] PP_Var[] protocols,
+                  [in] 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([in] PP_Resource web_socket,
+                [in] uint16_t code,
+                [in] 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.
+   * 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.
+   *
+   * @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([in] PP_Resource web_socket,
+                         [out,size_as=message_byte_count] void message_bytes,

[darin (slow to review), 2011/11/01 17:40:53]

in the comments, the out param for the message is represented as a PP_Var.  that
seems like a pretty good thing to me.  why did you decide to go with a raw byte
array instead?

[dmichael (off chromium), 2011/11/01 21:03:24]

Right. The JS spec uses MessageEvent, of which we probably only care about the
'data' field. But it's an 'any'. So it seems like it will be cleaner to use
PP_Var, so you can support the same kind of behavior as JS. The buffer of bytes
forces the recipient to know how to deserialize the data. It's probably
straightforward for Blob or ArrayBuffer, but for anything else, we'd have to
specify how we serialized it.

Of course, PP_Vars don't actually support ArrayBuffer, Blob, or objects yet :-).
But if it's important to get done soon, I can put that on the head of my queue.
I don't think it will take too long if I can focus on it.

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

Darin,
The only reason why I avoid to use PP_Var is that PP_Var currently doesn't
support ArrayBuffer and Blob. But, if Dave can fix it, I'll decide to use
PP_Var.

Dave,
I'm happy if you focus on updating PP_Var implementation.

+                         [in] int32_t message_byte_count,
+                         [out] int32_t remaining_message_byte_count,
+                         [out] PP_WebSocketMessageType_Dev message_type);

[dmichael (off chromium), 2011/11/01 21:03:24]

I think based on how I'm reading the spec, we need to provide the origin to the
plugin here as well. 5.3:
"""
Initialize event's origin attribute to the Unicode serialization of the origin
of the URL that was passed to the WebSocket object's constructor. 
"""

For PPx_Messaging, we talked about providing origin, but decided not to (at
least for now) since we can only load nexes from same-origin. In this case, it
appears that WebSocket can open a connection to any server, regardless of origin
(or am I reading it wrong?). Since the origin is specified to be the same as
what was passed to the constructor, maybe we can omit it?

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

In JS API, Chrome/WebKit appends origin field to the opening handshake
automatically. Then server decides if the specified origin is acceptable or not.
Only if server accept, the connection is established.

For Chrome Extension, origin will be the extension ID in URI format.

So, the origin field of MessageEvent is independent from connection limitation.
I think this field exists just for compatibility to HTML5's common MessageEvent
definition. We can omit it.

[dmichael (off chromium), 2011/11/02 16:14:40]

I suspect you're right, that it's not needed. I bring it up because the
MessageEvent definition in the Communications spec requires origin to be
provided for server-sent events:
http://www.whatwg.org/specs/web-apps/current-work/multipage/comms.html#dom-me...

Message events sent to Workers do leave origin as the empty string, but that's
what the spec requires for events that are neither server-sent nor
cross-document.

So...  we can consider deviating from the spec, since it really does seem
redundant in this case. But I want to get a third opinion (darin?)

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

[darin (slow to review), 2011/11/01 17:40:53]

ditto.  using PP_Var for the message seems like a good thing.

is this about the fact that PP_Var does not yet support byte arrays?  we plan to
make it support byte arrays.  maybe we should increase the priority of that
work.

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

Yes. I'd like to use PP_Var.
Please increase the priority.
Thanks!

+                      [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);

[darin (slow to review), 2011/11/01 17:40:53]

be mindful that all of these getters will need to be implemented using a cache
in the plugin process.  this is because we cannot have the plugin send
synchronous IPCs to the webkit main thread.

[cstefansen, 2011/11/01 18:08:51]

That doesn't seem very performant. Is there an alternative?

On 2011/11/01 17:40:53, darin wrote:

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

I see.
Do you have any plan to support synchronous IPC?

I need time to consider on following synchronous APIs.

[dmichael (off chromium), 2011/11/02 16:14:40]

We try to avoid using synchronous IPC in the proxy. But it seems in this case
that you don't need it, and the performance should be fine.

What you want to do is have the host side push data to the plugin side, where
the plugin side of the proxy will cache it. When a plugin calls
GetBufferedAmount, the proxy just asks its local buffer and returns without
using IPC. I think it should be fine.

[Takashi Toyoshima, 2011/11/04 08:45:55]

OK, I'll try to implement it without IPC.

I think I must increase the number of local buffer at SendMessage(),
and decrease it by the host pushing notification.

Because I must assure that an immediate GetBufferAmount() call after
SendMessage() returns the value including sending data size just now.
WebSocket users must take care that the bufferedAmount keep smaller value than
the limit value which depends browser implementation.
I should not return a mis-underestimated value.

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

[dmichael (off chromium), 2011/11/01 21:03:24]

It would probably be good to mention that this is always a string. You might
also mention that it will currently always be the empty string (as the WebSocket
spec states)

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

Oh, I see.
That will be better.

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

[dmichael (off chromium), 2011/11/01 21:03:24]

The spec says "must initially return the empty string" before the connection is
established. We should probably do the same, right?

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

Yes.

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

[dmichael (off chromium), 2011/11/01 21:03:24]

Same here, I would suggest returning the empty string to match the spec.

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

Ditto.

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

[darin (slow to review), 2011/11/01 17:40:53]

nit: GetURL

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

Done.

+};