OLD | NEW |
(Empty) | |
| 1 /* Copyright (c) 2011 The Chromium Authors. All rights reserved. |
| 2 * Use of this source code is governed by a BSD-style license that can be |
| 3 * found in the LICENSE file. |
| 4 */ |
| 5 |
| 6 /* From dev/ppb_websocket_dev.idl modified Mon Nov 7 15:21:42 2011. */ |
| 7 |
| 8 #ifndef PPAPI_C_DEV_PPB_WEBSOCKET_DEV_H_ |
| 9 #define PPAPI_C_DEV_PPB_WEBSOCKET_DEV_H_ |
| 10 |
| 11 #include "ppapi/c/pp_bool.h" |
| 12 #include "ppapi/c/pp_completion_callback.h" |
| 13 #include "ppapi/c/pp_instance.h" |
| 14 #include "ppapi/c/pp_macros.h" |
| 15 #include "ppapi/c/pp_resource.h" |
| 16 #include "ppapi/c/pp_stdint.h" |
| 17 #include "ppapi/c/pp_var.h" |
| 18 |
| 19 #define PPB_WEBSOCKET_DEV_INTERFACE_0_1 "PPB_WebSocket(Dev);0.1" |
| 20 #define PPB_WEBSOCKET_DEV_INTERFACE PPB_WEBSOCKET_DEV_INTERFACE_0_1 |
| 21 |
| 22 /** |
| 23 * @file |
| 24 * This file defines the <code>PPB_WebSocket_Dev</code> interface. |
| 25 */ |
| 26 |
| 27 |
| 28 /** |
| 29 * @addtogroup Enums |
| 30 * @{ |
| 31 */ |
| 32 /** |
| 33 * This enumeration contains the types representing the WebSocket ready state |
| 34 * and these states are based on the JavaScript WebSocket API specification. |
| 35 * GetReadyState() returns one of these states. |
| 36 */ |
| 37 typedef enum { |
| 38 /** |
| 39 * Ready state that the connection has not yet been established. |
| 40 */ |
| 41 PP_WEBSOCKETREADYSTATE_CONNECTING_DEV = 0, |
| 42 /** |
| 43 * Ready state that the WebSocket connection is established and communication |
| 44 * is possible. |
| 45 */ |
| 46 PP_WEBSOCKETREADYSTATE_OPEN_DEV = 1, |
| 47 /** |
| 48 * Ready state that the connection is going through the closing handshake. |
| 49 */ |
| 50 PP_WEBSOCKETREADYSTATE_CLOSING_DEV = 2, |
| 51 /** |
| 52 * Ready state that the connection has been closed or could not be opened. |
| 53 */ |
| 54 PP_WEBSOCKETREADYSTATE_CLOSED_DEV = 3 |
| 55 } PP_WebSocketReadyState_Dev; |
| 56 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_WebSocketReadyState_Dev, 4); |
| 57 |
| 58 /** |
| 59 * This enumeration contains the types representing the WebSocket message type |
| 60 * and these types are based on the JavaScript WebSocket API specification. |
| 61 * ReceiveMessage() and SendMessage() use them as a parameter to represent |
| 62 * handling message types. |
| 63 */ |
| 64 typedef enum { |
| 65 /** |
| 66 * Message type that represents a text message type. |
| 67 */ |
| 68 PP_WEBSOCKET_MESSAGE_TYPE_TEXT_DEV = 0, |
| 69 /** |
| 70 * Message type that represents a binary message type. |
| 71 */ |
| 72 PP_WEBSOCKET_MESSAGE_TYPE_BINARY_DEV = 1 |
| 73 } PP_WebSocketMessageType_Dev; |
| 74 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_WebSocketMessageType_Dev, 4); |
| 75 /** |
| 76 * @} |
| 77 */ |
| 78 |
| 79 /** |
| 80 * @addtogroup Interfaces |
| 81 * @{ |
| 82 */ |
| 83 struct PPB_WebSocket_Dev { |
| 84 /** |
| 85 * Create() creates a WebSocket instance. |
| 86 * |
| 87 * @param[in] instance A <code>PP_Instance</code> identifying the instance |
| 88 * with the WebSocket. |
| 89 * |
| 90 * @return A <code>PP_Resource</code> corresponding to a WebSocket if |
| 91 * successful. |
| 92 */ |
| 93 PP_Resource (*Create)(PP_Instance instance); |
| 94 /** |
| 95 * IsWebSocket() determines if the provided <code>resource</code> is a |
| 96 * WebSocket instance. |
| 97 * |
| 98 * @param[in] resource A <code>PP_Resource</code> corresponding to a |
| 99 * WebSocket. |
| 100 * |
| 101 * @return Returns <code>PP_TRUE</code> if <code>resource</code> is a |
| 102 * <code>PPB_WebSocket_Dev</code>, <code>PP_FALSE</code> if the |
| 103 * <code>resource</code> is invalid or some type other than |
| 104 * <code>PPB_WebSocket_Dev</code>. |
| 105 */ |
| 106 PP_Bool (*IsWebSocket)(PP_Resource resource); |
| 107 /** |
| 108 * Connect() connects to the specified WebSocket server. Caller can call this |
| 109 * method at most once for a <code>web_socket</code>. |
| 110 * |
| 111 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 112 * WebSocket. |
| 113 * |
| 114 * @param[in] url A <code>PP_Var</code> representing a WebSocket server URL. |
| 115 * The <code>PP_VarType</code> must be <code>PP_VARTYPE_STRING</code>. |
| 116 * |
| 117 * @param[in] protocols A pointer to an array of <code>PP_Var</code> |
| 118 * specifying sub-protocols. Each <code>PP_Var</code> represents one |
| 119 * sub-protocol and its <code>PP_VarType</code> must be |
| 120 * <code>PP_VARTYPE_STRING</code>. This argument can be null only if |
| 121 * <code>protocol_count</code> is 0. |
| 122 * |
| 123 * @param[in] protocol_count The number of sub-protocols in |
| 124 * <code>protocols</code>. |
| 125 * |
| 126 * @param[in] callback A <code>PP_CompletionCallback</code> which is called |
| 127 * when the connection is established or an error occurs in establishing |
| 128 * connection. |
| 129 * |
| 130 * @return In case of immediate failure, returns an error code as follows. |
| 131 * Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript |
| 132 * SyntaxError and <code>PP_ERROR_NOACCESS</code> corresponding to JavaScript |
| 133 * SecurityError. Otherwise, returns <code>PP_OK_COMPLETIONPENDING</code> |
| 134 * and invokes <code>callback</code> later. |
| 135 */ |
| 136 int32_t (*Connect)(PP_Resource web_socket, |
| 137 struct PP_Var url, |
| 138 const struct PP_Var protocols[], |
| 139 uint32_t protocol_count, |
| 140 struct PP_CompletionCallback callback); |
| 141 /** |
| 142 * Close() closes the specified WebSocket connection by specifying |
| 143 * <code>code</code> and <code>reason</code>. |
| 144 * |
| 145 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 146 * WebSocket. |
| 147 * |
| 148 * @param[in] code The WebSocket close code. Ignored if it is 0. |
| 149 * |
| 150 * @param[in] reason A <code>PP_Var</code> which represents the WebSocket |
| 151 * close reason. Ignored if it is <code>PP_VARTYPE_UNDEFINED</code>. |
| 152 * Otherwise, its <code>PP_VarType</code> must be |
| 153 * <code>PP_VARTYPE_STRING</code>. |
| 154 * |
| 155 * @param[in] callback A <code>PP_CompletionCallback</code> which is called |
| 156 * when the connection is closed or an error occurs in closing connection. |
| 157 * |
| 158 * @return In case of immediate failure, returns an error code as follows. |
| 159 * Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript |
| 160 * SyntaxError and <code>PP_ERROR_NOACCESS</code> corresponding to JavaScript |
| 161 * InvalidAccessError. Otherwise, returns |
| 162 * <code>PP_OK_COMPLETIONPENDING</code> and invokes <code>callback</code> |
| 163 * later. |
| 164 */ |
| 165 int32_t (*Close)(PP_Resource web_socket, |
| 166 uint16_t code, |
| 167 struct PP_Var reason, |
| 168 struct PP_CompletionCallback callback); |
| 169 /** |
| 170 * ReceiveMessage() receives a message from the WebSocket server. |
| 171 * This interface only returns bytes of a single message. That is, this |
| 172 * interface must be called at least N times to receive N messages, no matter |
| 173 * how small each message is. |
| 174 * |
| 175 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 176 * WebSocket. |
| 177 * |
| 178 * @param[out] message The received message is copied to provided |
| 179 * <code>message</code>. |
| 180 * |
| 181 * @param[in] callback A <code>PP_CompletionCallback</code> which is called |
| 182 * when the receiving message is completed. It is ignored when the function |
| 183 * return <code>PP_OK</code>. |
| 184 * |
| 185 * @return In case of immediate failure, returns |
| 186 * <code>PP_ERROR_FAILED</code>. If a message is currently available, returns |
| 187 * <code>PP_OK</code>. Otherwise, returns <PP_OK_COMPLETIONPENDING</code> |
| 188 * and invokes <code>callback</code> later. At that case, if GetReadyState() |
| 189 * returns <code>PP_WEBSOCKETREADYSTATE_OPEN</code>, the received |
| 190 * message is also copied to procided <code>message</code>. Otherwise, |
| 191 * the connection is closed and ReceiveMessage() failed to receive a message. |
| 192 */ |
| 193 int32_t (*ReceiveMessage)(PP_Resource web_socket, |
| 194 struct PP_Var* message, |
| 195 struct PP_CompletionCallback callback); |
| 196 /** |
| 197 * SendMessage() sends a message to the WebSocket server. |
| 198 * |
| 199 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 200 * WebSocket. |
| 201 * |
| 202 * @param[in] message A message to send. The message is copied to internal |
| 203 * buffer. So caller can free <code>message</code> safely after returning |
| 204 * from the function. |
| 205 * |
| 206 * @return In case of immediate failure, returns an error code as follows. |
| 207 * Returns <code>PP_ERROR_FAILED</code> corresponding to JavaScript |
| 208 * InvalidStateError and <code>PP_ERROR_BADARGUMENT</code> corresponding to |
| 209 * JavaScript SyntaxError. Otherwise, return <code>PP_OK</code>. |
| 210 * <code>PP_OK</code> doesn't necessarily mean that the server received the |
| 211 * message. |
| 212 */ |
| 213 int32_t (*SendMessage)(PP_Resource web_socket, struct PP_Var message); |
| 214 /** |
| 215 * GetBufferedAmount() returns the number of bytes of text and binary |
| 216 * messages that have been queued for the WebSocket connection to send but |
| 217 * have not been transmitted to the network yet. |
| 218 * |
| 219 * Note: This interface might not be able to return exact bytes in the first |
| 220 * release. Current WebSocket implementation can not estimate exact protocol |
| 221 * frame overheads. |
| 222 * |
| 223 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 224 * WebSocket. |
| 225 * |
| 226 * @return Returns the number of bytes. |
| 227 */ |
| 228 uint64_t (*GetBufferedAmount)(PP_Resource web_socket); |
| 229 /** |
| 230 * GetCloseCode() returns the connection close code for the WebSocket |
| 231 * connection. |
| 232 * |
| 233 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 234 * WebSocket. |
| 235 * |
| 236 * @return Returns 0 if called before the close code is set. |
| 237 */ |
| 238 uint16_t (*GetCloseCode)(PP_Resource web_socket); |
| 239 /** |
| 240 * GetCloseReason() returns the connection close reason for the WebSocket |
| 241 * connection. |
| 242 * |
| 243 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 244 * WebSocket. |
| 245 * |
| 246 * @return Returns a <code>PP_VARTYPE_NULL</code> var if called before the |
| 247 * close reason is set, or <code>PP_VARTYPE_UNDEFINED</code> if called on an |
| 248 * invalid resource. |
| 249 */ |
| 250 struct PP_Var (*GetCloseReason)(PP_Resource web_socket); |
| 251 /** |
| 252 * GetCloseWasClean() returns if the connection was closed cleanly for the |
| 253 * specified WebSocket connection. |
| 254 * |
| 255 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 256 * WebSocket. |
| 257 * |
| 258 * @return Returns <code>PP_FALSE</code> if called before the connection is |
| 259 * closed. Otherwise, returns <code>PP_TRUE</code> if the connection was |
| 260 * closed cleanly and returns <code>PP_FALSE</code> if the connection was |
| 261 * closed by abnormal reasons. |
| 262 */ |
| 263 PP_Bool (*GetCloseWasClean)(PP_Resource web_socket); |
| 264 /** |
| 265 * GetExtensions() returns the extensions selected by the server for the |
| 266 * specified WebSocket connection. |
| 267 * |
| 268 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 269 * WebSocket. |
| 270 * |
| 271 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
| 272 * connection is established or called on an invalid resource, its data is |
| 273 * empty string. |
| 274 * Currently its data is always empty string. |
| 275 */ |
| 276 struct PP_Var (*GetExtensions)(PP_Resource web_socket); |
| 277 /** |
| 278 * GetProtocol() returns the sub-protocol chosen by the server for the |
| 279 * specified WebSocket connection. |
| 280 * |
| 281 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 282 * WebSocket. |
| 283 * |
| 284 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
| 285 * connection is established, or called on an invalid resource, its data is |
| 286 * empty string. |
| 287 */ |
| 288 struct PP_Var (*GetProtocol)(PP_Resource web_socket); |
| 289 /** |
| 290 * GetReadyState() returns the ready state of the specified WebSocket |
| 291 * connection. |
| 292 * |
| 293 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 294 * WebSocket. |
| 295 * |
| 296 * @return Returns <code>PP_WEBSOCKETREADYSTATE_CONNECTING</code> if called |
| 297 * before the connection is established. |
| 298 */ |
| 299 PP_WebSocketReadyState_Dev (*GetReadyState)(PP_Resource web_socket); |
| 300 /** |
| 301 * GetURL() returns the URL associated with specified WebSocket connection. |
| 302 * |
| 303 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 304 * WebSocket. |
| 305 * |
| 306 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
| 307 * connection is established, or called on an invalid resource, its data is |
| 308 * empty string. |
| 309 */ |
| 310 struct PP_Var (*GetURL)(PP_Resource web_socket); |
| 311 }; |
| 312 /** |
| 313 * @} |
| 314 */ |
| 315 |
| 316 #endif /* PPAPI_C_DEV_PPB_WEBSOCKET_DEV_H_ */ |
| 317 |
OLD | NEW |