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 Wed Oct 26 11:19:37 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 * Note on the differences from JavaScript WebSocket API |
| 27 * http://dev.w3.org/html5/websockets/ |
| 28 * |
| 29 * This interface has some differences from its JavaScript counterpart mainly |
| 30 * to make best use of PP_CompletionCallback and be consistent with other |
| 31 * interfaces such as PPB_Transport_Dev. |
| 32 * |
| 33 * - Constructor doesn't take URL or protocols and there is a method to |
| 34 * establish connection. |
| 35 * |
| 36 * - Error handlers or close handlers cannot be registered. (A callback can be |
| 37 * specified on explicitly closing a connection.) To detect an error or |
| 38 * connection closure, ready state, closure cleanness, closure code, and |
| 39 * closure reason should be queried instead. |
| 40 * |
| 41 * - Message size is represented as int32_t rather than uint64_t. |
| 42 * PP_CompletionCallback handles int32_t better. Messages out of that range |
| 43 * are too large to handle efficiently anyway. |
| 44 * |
| 45 * Note on error codes. |
| 46 * |
| 47 * Methods that take PP_CompletionCallback can return error codes. They |
| 48 * correspond to JavaScript exceptions as follows: |
| 49 * |
| 50 * PP_ERROR_BADARGUMENT: SYNTAX_ERR |
| 51 * PP_ERROR_NOACCESS: SECURITY_ERR, INVALID_ACCESS_ERR |
| 52 * PP_ERROR_FAILED: INVALID_STATE_ERR |
| 53 * |
| 54 * Other error codes such as PP_ERROR_ABORTED and PP_ERROR_BADRESOURCE can |
| 55 * also be returned. |
| 56 */ |
| 57 |
| 58 |
| 59 /** |
| 60 * @addtogroup Enums |
| 61 * @{ |
| 62 */ |
| 63 /** |
| 64 * This enumeration contains the types representing the WebSocket ready state |
| 65 * and these states are based on the JavaScript WebSocket API specification. |
| 66 * GetReadyState() returns one of these states. |
| 67 */ |
| 68 typedef enum { |
| 69 /** |
| 70 * Ready state that the connection has not yet been established. |
| 71 */ |
| 72 PP_WEBSOCKETREADYSTATE_CONNECTING = 0, |
| 73 /** |
| 74 * Ready state that the WebSocket connection is established and communication |
| 75 * is possible. |
| 76 */ |
| 77 PP_WEBSOCKETREADYSTATE_OPEN = 1, |
| 78 /** |
| 79 * Ready state that the connection is going through the closing handshake. |
| 80 */ |
| 81 PP_WEBSOCKETREADYSTATE_CLOSING = 2, |
| 82 /** |
| 83 * Ready state that the connection has been closed or could not be opened. |
| 84 */ |
| 85 PP_WEBSOCKETREADYSTATE_CLOSED = 3 |
| 86 } PP_WebSocketReadyState_Dev; |
| 87 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_WebSocketReadyState_Dev, 4); |
| 88 |
| 89 /** |
| 90 * This enumeration contains the types representing the WebSocket message type |
| 91 * and these types are based on the JavaScript WebSocket API specification. |
| 92 * ReceiveMessage() and SendMessage() use them as a parameter to represent |
| 93 * handling message types. |
| 94 */ |
| 95 typedef enum { |
| 96 /** |
| 97 * Message type that represents a text message type. |
| 98 */ |
| 99 PP_WEBSOCKET_MESSAGE_TYPE_TEXT = 0, |
| 100 /** |
| 101 * Message type that represents a binary message type. |
| 102 */ |
| 103 PP_WEBSOCKET_MESSAGE_TYPE_BINARY = 1 |
| 104 } PP_WebSocketMessageType_Dev; |
| 105 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_WebSocketMessageType_Dev, 4); |
| 106 /** |
| 107 * @} |
| 108 */ |
| 109 |
| 110 /** |
| 111 * @addtogroup Interfaces |
| 112 * @{ |
| 113 */ |
| 114 struct PPB_WebSocket_Dev { |
| 115 /** |
| 116 * Create() Creates a WebSocket instance. |
| 117 * |
| 118 * @param[in] instance A <code>PP_Instance</code> identifying the instance |
| 119 * with the WebSocket. |
| 120 * |
| 121 * @return A <code>PP_Resource</code> corresponding to a WebSocket if |
| 122 * successful. |
| 123 */ |
| 124 PP_Resource (*Create)(PP_Instance instance); |
| 125 /** |
| 126 * IsWebSocket() determines if the provided <code>resource</code> is a |
| 127 * WebSocket instance. |
| 128 * |
| 129 * @param[in] resource A <code>PP_Resource</code> corresponding to a |
| 130 * WebSocket. |
| 131 * |
| 132 * @return Returns <code>PP_TRUE</code> if <code>resource</code> is a |
| 133 * <code>PPB_WebSocket_Dev</code>, <code>PP_FALSE</code> if the |
| 134 * <code>resource</code> is invalid or some type other than |
| 135 * <code>PPB_WebSocket_Dev</code>. |
| 136 */ |
| 137 PP_Bool (*IsWebSocket)(PP_Resource resource); |
| 138 /** |
| 139 * SetCloseCallback() sets the callback which is called when the WebSocket |
| 140 * connection is closed. |
| 141 * Closure code and reason should be queried via each interface. |
| 142 * Caller can call this method safely only before calling Connect(). |
| 143 * |
| 144 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 145 * WebSocket. |
| 146 * |
| 147 * @param[in] callback A <code>PP_CompletionCallback</code> which is called |
| 148 * when the connection is closed. |
| 149 * |
| 150 * @return Returns <code>PP_OK</code>. |
| 151 */ |
| 152 int32_t (*SetCloseCallback)(PP_Resource web_socket, |
| 153 struct PP_CompletionCallback callback); |
| 154 /** |
| 155 * Connect() connects to the specified WebSocket server. Caller can call this |
| 156 * method at most once for a <code>web_socket</code>. |
| 157 * |
| 158 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 159 * WebSocket. |
| 160 * |
| 161 * @param[in] url A <code>PP_Var</code> representing a WebSocket server URL. |
| 162 * The <code>PP_VarType</code> must be <code>PP_VARTYPE_STRING</code>. |
| 163 * |
| 164 * @param[in] protocols A pointer to an array of <code>PP_Var</code> |
| 165 * specifying sub-protocols. Each <code>PP_Var</code> represents one |
| 166 * sub-protocol and its <code>PP_VarType</code> must be |
| 167 * <code>PP_VARTYPE_STRING</code>. This argument can be null only if |
| 168 * <code>protocol_count</code> is 0. |
| 169 * |
| 170 * @param[in] protocol_count The number of sub-protocols in |
| 171 * <code>protocols</code>. |
| 172 * |
| 173 * @param[in] callback A <code>PP_CompletionCallback</code> which is called |
| 174 * when the connection is established or an error occurs. |
| 175 * |
| 176 * @return In case of immediate failure, returns an error code as follows. |
| 177 * Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript |
| 178 * SyntaxError and <code>PP_ERROR_NOACCESS</code> corresponding to JavaScript |
| 179 * SecurityError. Otherwise, returns <code>PP_OK_COMPLETIONPENDING</code>. |
| 180 */ |
| 181 int32_t (*Connect)(PP_Resource web_socket, |
| 182 struct PP_Var url, |
| 183 const struct PP_Var protocols[], |
| 184 uint32_t protocol_count, |
| 185 struct PP_CompletionCallback callback); |
| 186 /** |
| 187 * Close() closes the specified WebSocket connection by specifying |
| 188 * <code>code</code> and <code>reason</code>. |
| 189 * |
| 190 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 191 * WebSocket. |
| 192 * |
| 193 * @param[in] code The WebSocket closure status code. Ignored if it is 0. |
| 194 * |
| 195 * @param[in] reason A <code>PP_Var</code> which represents the WebSocket |
| 196 * closure reason. Ignored if it is <code>PP_VARTYPE_UNDEFINED</code>. |
| 197 * Otherwise, its <code>PP_VarType</code> must be |
| 198 * <code>PP_VARTYPE_STRING</code>. |
| 199 * |
| 200 * @param[in] callback A <code>PP_CompletionCallback</code> which is called |
| 201 * when the connection is closed or an error occurs. |
| 202 * |
| 203 * @return In case of immediate failure, returns an error code as follows. |
| 204 * Returns <code>PP_ERROR_BADARGUMENT</code> corresponding to JavaScript |
| 205 * SyntaxError and <code>PP_ERROR_FAILED</code> corresponding to JavaScript |
| 206 * InvalidStateError. Otherwise, returns |
| 207 * <code>PP_OK_COMPLETIONPENDING</code>. |
| 208 */ |
| 209 int32_t (*Close)(PP_Resource web_socket, |
| 210 uint16_t code, |
| 211 struct PP_Var reason, |
| 212 struct PP_CompletionCallback callback); |
| 213 /** |
| 214 * ReceiveMessage() receives a message from the WebSocket server. |
| 215 * Caller must keep <code>message_bytes</code>, |
| 216 * <code>remaining_message_byte_count</code>, and <code>message_type</code> |
| 217 * valid until <code>callback</code> is issued or Close() is called. |
| 218 * |
| 219 * Note: This interface might be changed as follows. |
| 220 * int32_t ReceiveMessage([in] PP_Resource web_socket, |
| 221 * [out] PP_Var message, |
| 222 * [out] int32_t remaining_message_byte_count, |
| 223 * [in] PP_CompletionCallback callback); |
| 224 * |
| 225 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 226 * WebSocket. |
| 227 * |
| 228 * @param[out] message_bytes The message is copied to provided |
| 229 * <code>message_bytes</code> up to <code>message_byte_count</code> bytes. |
| 230 * <code>message_bytes</code> can be null only if |
| 231 * <code>message_byte_count</code> is 0. |
| 232 * In copying message to <code>message_bytes</code>, UTF-8 byte sequence |
| 233 * boundaries are not considered. Hence if the message is larger than |
| 234 * <code>message_bytes</code>, the last byte sequence may end prematurely. |
| 235 * Likewise, the first sequence of the bytes returned for the subsequent call |
| 236 * may start in the middle. |
| 237 * |
| 238 * @param[in] message_bytes_count The maximum receiving size in bytes. |
| 239 * |
| 240 * @param[out] remaining_byte_count The number of remaining bytes, if any, is |
| 241 * set to <code>remaining_message_byte_count</code> if |
| 242 * <code>remaining_message_byte_count</code> is not null. The remaining bytes |
| 243 * of the message are returned for subsequent call(s) to this method. |
| 244 * |
| 245 * @param[out] message_type A <code>PP_WebSocketMessageType_Dev</code> |
| 246 * representing the message type is set to <code>message_type</code> if |
| 247 * <code>message_type</code> is not null. If the message is text, it is |
| 248 * encoded in UTF-8. |
| 249 * |
| 250 * @param[in] callback A <code>PP_CompletionCallback</code> which is called |
| 251 * if the interface has been returned<code>PP_OK_COMPLETIONPENDING</code>. |
| 252 * The number of bytes copied is passed as the second argument. |
| 253 * |
| 254 * @return If a message is currently available, returns the number of bytes |
| 255 * copied to <code>message_bytes</code>. Otherwise, returns |
| 256 * <code>PP_OK_COMPLETIONPENDING</code> and calls <code>callback</code> when |
| 257 * the message is available. |
| 258 * Messages are queued internally. Hence this method can be called either |
| 259 * before or after a message is received by the browser. If the queue grows |
| 260 * beyond the browser-dependent limit, <code>web_socket</code> is closed and |
| 261 * messages are discarded. |
| 262 * This interface only returns bytes of a single message. That is, this |
| 263 * interface must be called at least N times to receive N messages, no matter |
| 264 * how small each message is. |
| 265 */ |
| 266 int32_t (*ReceiveMessage)(PP_Resource web_socket, |
| 267 void* message_bytes, |
| 268 int32_t message_byte_count, |
| 269 int32_t* remaining_message_byte_count, |
| 270 PP_WebSocketMessageType_Dev* message_type, |
| 271 struct PP_CompletionCallback callback); |
| 272 /** |
| 273 * SendMessage() sends a message to the WebSocket server. |
| 274 * |
| 275 * Note: This interface might be changed as follows. |
| 276 * int32_t SendMessage([in] PP_Resource web_socket, |
| 277 * [in] PP_Var message); |
| 278 * |
| 279 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 280 * WebSocket. |
| 281 * |
| 282 * @param[in] message_bytes A message to send. The message is copied to |
| 283 * internal buffer. So caller can free <code>message_bytes</code> safely |
| 284 * after returning from the function. |
| 285 * |
| 286 * @param[in] message_byte_count The length of the message in bytes. |
| 287 * |
| 288 * @param[in] message_type A <code>PP_WebSocketMessageType_Dev</code> |
| 289 * representing the message type of the <code>message</code>. |
| 290 * |
| 291 * @return In case of immediate failure, returns an error code as follows. |
| 292 * Returns <code>PP_ERROR_FAILED</code> corresponding JavaScript |
| 293 * InvalidStateError and <code>PP_ERROR_BADARGUMENT</code> corresponding |
| 294 * JavaScript SyntaxError. Otherwise, return <code>PP_OK</code>. |
| 295 * <code>PP_OK</code> doesn't necessarily mean that the server received the |
| 296 * message. |
| 297 */ |
| 298 int32_t (*SendMessage)(PP_Resource web_socket, |
| 299 const void message_bytes[], |
| 300 int32_t message_byte_count, |
| 301 PP_WebSocketMessageType_Dev message_type); |
| 302 /** |
| 303 * GetBufferedAmount() returns the number of bytes of text and binary |
| 304 * messages that have been queued for the WebSocket connection to send but |
| 305 * have not been transmitted to the network yet. |
| 306 * |
| 307 * Note: This interface might not be able to return exact bytes in the first |
| 308 * release. |
| 309 * |
| 310 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 311 * WebSocket. |
| 312 * |
| 313 * @return Returns the number of bytes. |
| 314 */ |
| 315 uint64_t (*GetBufferedAmount)(PP_Resource web_socket); |
| 316 /** |
| 317 * GetCloseCode() returns the connection close code for the WebSocket |
| 318 * connection. |
| 319 * |
| 320 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 321 * WebSocket. |
| 322 * |
| 323 * @return Returns 0 if called before the close code is set. |
| 324 */ |
| 325 uint16_t (*GetCloseCode)(PP_Resource web_socket); |
| 326 /** |
| 327 * GetCloseReason() returns the connection close reason for the WebSocket |
| 328 * connection. |
| 329 * |
| 330 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 331 * WebSocket. |
| 332 * |
| 333 * @return Returns a <code>PP_VARTYPE_NULL</code> var if called before the |
| 334 * close reason is set, or <code>PP_VARTYPE_UNDEFINED</code> if called on an |
| 335 * invalid resource. |
| 336 */ |
| 337 struct PP_Var (*GetCloseReason)(PP_Resource web_socket); |
| 338 /** |
| 339 * GetCloseWasClean() returns if the connection was closed cleanly for the |
| 340 * specified WebSocket connection. |
| 341 * |
| 342 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 343 * WebSocket. |
| 344 * |
| 345 * @return Returns <code>PP_FALSE</code> if called before the connection is |
| 346 * closed. Otherwise, returns <code>PP_TRUE</code> if the connection was |
| 347 * closed cleanly and returns <code>PP_FALSE</code> if the connection was |
| 348 * closed by abnormal reasons. |
| 349 */ |
| 350 PP_Bool (*GetCloseWasClean)(PP_Resource web_socket); |
| 351 /** |
| 352 * GetExtensions() returns the extensions selected by the server for the |
| 353 * specified WebSocket connection. |
| 354 * |
| 355 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 356 * WebSocket. |
| 357 * |
| 358 * @return Returns a <code>PP_VARTYPE_NULL</code> var if called before the |
| 359 * connection is established, or <code>PP_VARTYPE_UNDEFINED</code> if called |
| 360 * on an invalid resource. |
| 361 */ |
| 362 struct PP_Var (*GetExtensions)(PP_Resource web_socket); |
| 363 /** |
| 364 * GetProtocol() returns the sub-protocol chosen by the server for the |
| 365 * specified WebSocket connection. |
| 366 * |
| 367 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 368 * WebSocket. |
| 369 * |
| 370 * @return Returns a <code>PP_VARTYPE_NULL</code> var if called before the |
| 371 * connection is established, or <code>PP_VARTYPE_UNDEFINED</code> if called |
| 372 * on an invalid resource. |
| 373 */ |
| 374 struct PP_Var (*GetProtocol)(PP_Resource web_socket); |
| 375 /** |
| 376 * GetReadyState() returns the ready state of the specified WebSocket |
| 377 * connection. |
| 378 * |
| 379 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 380 * WebSocket. |
| 381 * |
| 382 * @return Returns <code>PP_WEBSOCKETREADYSTATE_CONNECTING</code> if called |
| 383 * before the connection is established. |
| 384 */ |
| 385 PP_WebSocketReadyState_Dev (*GetReadyState)(PP_Resource web_socket); |
| 386 /** |
| 387 * GetUrl() returns the URL associated with specified WebSocket connection. |
| 388 * |
| 389 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 390 * WebSocket. |
| 391 * |
| 392 * @return Returns a <code>PP_VARTYPE_NULL</code> var if called before the |
| 393 * connection is established, or <code>PP_VARTYPE_UNDEFINED</code> if called |
| 394 * on an invalid resource. |
| 395 */ |
| 396 struct PP_Var (*GetUrl)(PP_Resource web_socket); |
| 397 }; |
| 398 /** |
| 399 * @} |
| 400 */ |
| 401 |
| 402 #endif /* PPAPI_C_DEV_PPB_WEBSOCKET_DEV_H_ */ |
| 403 |
OLD | NEW |