Index: ppapi/c/dev/ppb_websocket_dev.h |
diff --git a/ppapi/c/dev/ppb_websocket_dev.h b/ppapi/c/dev/ppb_websocket_dev.h |
new file mode 100644 |
index 0000000000000000000000000000000000000000..047dd2372faec6b59234688d12ba3f6b49c4ba81 |
--- /dev/null |
+++ b/ppapi/c/dev/ppb_websocket_dev.h |
@@ -0,0 +1,186 @@ |
+/* 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_ |