[email protected] | 25651387 | 2012-01-05 15:41:52 | [diff] [blame] | 1 | /* Copyright (c) 2012 The Chromium Authors. All rights reserved. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 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 | /** |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 7 | * This file defines the <code>PPB_WebSocket</code> interface providing |
| 8 | * bi-directional, full-duplex, communications over a single TCP socket. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 9 | */ |
[email protected] | f9116d11 | 2012-12-21 21:17:25 | [diff] [blame] | 10 | |
| 11 | [generate_thunk] |
| 12 | |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 13 | label Chrome { |
[email protected] | 5350822 | 2012-01-27 09:42:41 | [diff] [blame] | 14 | M18 = 1.0 |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 15 | }; |
| 16 | |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 17 | /** |
| 18 | * This enumeration contains the types representing the WebSocket ready state |
| 19 | * and these states are based on the JavaScript WebSocket API specification. |
| 20 | * GetReadyState() returns one of these states. |
| 21 | */ |
| 22 | [assert_size(4)] |
[email protected] | 5350822 | 2012-01-27 09:42:41 | [diff] [blame] | 23 | enum PP_WebSocketReadyState { |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 24 | /** |
[email protected] | 4454db0 | 2011-11-16 05:25:01 | [diff] [blame] | 25 | * Ready state is queried on an invalid resource. |
| 26 | */ |
[email protected] | 5350822 | 2012-01-27 09:42:41 | [diff] [blame] | 27 | PP_WEBSOCKETREADYSTATE_INVALID = -1, |
[email protected] | fade7dbc | 2012-03-13 22:48:07 | [diff] [blame] | 28 | |
[email protected] | 4454db0 | 2011-11-16 05:25:01 | [diff] [blame] | 29 | /** |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 30 | * Ready state that the connection has not yet been established. |
| 31 | */ |
[email protected] | 5350822 | 2012-01-27 09:42:41 | [diff] [blame] | 32 | PP_WEBSOCKETREADYSTATE_CONNECTING = 0, |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 33 | |
| 34 | /** |
| 35 | * Ready state that the WebSocket connection is established and communication |
| 36 | * is possible. |
| 37 | */ |
[email protected] | 5350822 | 2012-01-27 09:42:41 | [diff] [blame] | 38 | PP_WEBSOCKETREADYSTATE_OPEN = 1, |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 39 | |
| 40 | /** |
| 41 | * Ready state that the connection is going through the closing handshake. |
| 42 | */ |
[email protected] | 5350822 | 2012-01-27 09:42:41 | [diff] [blame] | 43 | PP_WEBSOCKETREADYSTATE_CLOSING = 2, |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 44 | |
| 45 | /** |
| 46 | * Ready state that the connection has been closed or could not be opened. |
| 47 | */ |
[email protected] | 5350822 | 2012-01-27 09:42:41 | [diff] [blame] | 48 | PP_WEBSOCKETREADYSTATE_CLOSED = 3 |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 49 | }; |
| 50 | |
[email protected] | 7d107f3 | 2012-02-06 07:06:25 | [diff] [blame] | 51 | /** |
| 52 | * This enumeration contains status codes. These codes are used in Close() and |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 53 | * GetCloseCode(). Refer to RFC 6455, The WebSocket Protocol, for further |
| 54 | * information. |
[email protected] | 7d107f3 | 2012-02-06 07:06:25 | [diff] [blame] | 55 | * <code>PP_WEBSOCKETSTATUSCODE_NORMAL_CLOSURE</code> and codes in the range |
| 56 | * <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MIN</code> to |
| 57 | * <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MAX</code>, and |
| 58 | * <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MIN</code> to |
| 59 | * <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MAX</code> are valid for Close(). |
| 60 | */ |
| 61 | [assert_size(4)] |
| 62 | enum PP_WebSocketCloseCode { |
| 63 | /** |
[email protected] | b6b90fe | 2012-05-31 09:25:45 | [diff] [blame] | 64 | * Indicates to request closing connection without status code and reason. |
| 65 | * |
| 66 | * (Note that the code 1005 is forbidden to send in actual close frames by |
| 67 | * the RFC. PP_WebSocket reuses this code internally and the code will never |
| 68 | * appear in the actual close frames.) |
| 69 | */ |
| 70 | PP_WEBSOCKETSTATUSCODE_NOT_SPECIFIED = 1005, |
| 71 | |
| 72 | /** |
[email protected] | 7d107f3 | 2012-02-06 07:06:25 | [diff] [blame] | 73 | * Status codes in the range 0-999 are not used. |
| 74 | */ |
| 75 | |
| 76 | /** |
| 77 | * Indicates a normal closure. |
| 78 | */ |
| 79 | PP_WEBSOCKETSTATUSCODE_NORMAL_CLOSURE = 1000, |
| 80 | |
| 81 | /** |
| 82 | * Indicates that an endpoint is "going away", such as a server going down. |
| 83 | */ |
| 84 | PP_WEBSOCKETSTATUSCODE_GOING_AWAY = 1001, |
| 85 | |
| 86 | /** |
| 87 | * Indicates that an endpoint is terminating the connection due to a protocol |
| 88 | * error. |
| 89 | */ |
| 90 | PP_WEBSOCKETSTATUSCODE_PROTOCOL_ERROR = 1002, |
| 91 | |
| 92 | /** |
| 93 | * Indicates that an endpoint is terminating the connection because it has |
| 94 | * received a type of data it cannot accept. |
| 95 | */ |
| 96 | PP_WEBSOCKETSTATUSCODE_UNSUPPORTED_DATA = 1003, |
| 97 | |
| 98 | /** |
| 99 | * Status code 1004 is reserved. |
| 100 | */ |
| 101 | |
| 102 | /** |
| 103 | * Pseudo code to indicate that receiving close frame doesn't contain any |
| 104 | * status code. |
| 105 | */ |
| 106 | PP_WEBSOCKETSTATUSCODE_NO_STATUS_RECEIVED = 1005, |
| 107 | |
| 108 | /** |
| 109 | * Pseudo code to indicate that connection was closed abnormally, e.g., |
| 110 | * without closing handshake. |
| 111 | */ |
| 112 | PP_WEBSOCKETSTATUSCODE_ABNORMAL_CLOSURE = 1006, |
| 113 | |
| 114 | /** |
| 115 | * Indicates that an endpoint is terminating the connection because it has |
| 116 | * received data within a message that was not consistent with the type of |
| 117 | * the message (e.g., non-UTF-8 data within a text message). |
| 118 | */ |
| 119 | PP_WEBSOCKETSTATUSCODE_INVALID_FRAME_PAYLOAD_DATA = 1007, |
| 120 | |
| 121 | /** |
| 122 | * Indicates that an endpoint is terminating the connection because it has |
| 123 | * received a message that violates its policy. |
| 124 | */ |
| 125 | PP_WEBSOCKETSTATUSCODE_POLICY_VIOLATION = 1008, |
| 126 | |
| 127 | /** |
| 128 | * Indicates that an endpoint is terminating the connection because it has |
| 129 | * received a message that is too big for it to process. |
| 130 | */ |
| 131 | PP_WEBSOCKETSTATUSCODE_MESSAGE_TOO_BIG = 1009, |
| 132 | |
| 133 | /** |
| 134 | * Indicates that an endpoint (client) is terminating the connection because |
| 135 | * it has expected the server to negotiate one or more extension, but the |
| 136 | * server didn't return them in the response message of the WebSocket |
| 137 | * handshake. |
| 138 | */ |
| 139 | PP_WEBSOCKETSTATUSCODE_MANDATORY_EXTENSION = 1010, |
| 140 | |
| 141 | /** |
| 142 | * Indicates that a server is terminating the connection because it |
| 143 | * encountered an unexpected condition. |
| 144 | */ |
| 145 | PP_WEBSOCKETSTATUSCODE_INTERNAL_SERVER_ERROR = 1011, |
| 146 | |
| 147 | /** |
| 148 | * Status codes in the range 1012-1014 are reserved. |
| 149 | */ |
| 150 | |
| 151 | /** |
| 152 | * Pseudo code to indicate that the connection was closed due to a failure to |
| 153 | * perform a TLS handshake. |
| 154 | */ |
| 155 | PP_WEBSOCKETSTATUSCODE_TLS_HANDSHAKE = 1015, |
| 156 | |
| 157 | /** |
| 158 | * Status codes in the range 1016-2999 are reserved. |
| 159 | */ |
| 160 | |
| 161 | /** |
| 162 | * Status codes in the range 3000-3999 are reserved for use by libraries, |
| 163 | * frameworks, and applications. These codes are registered directly with |
| 164 | * IANA. |
| 165 | */ |
| 166 | PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MIN = 3000, |
| 167 | PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MAX = 3999, |
| 168 | |
| 169 | /** |
| 170 | * Status codes in the range 4000-4999 are reserved for private use. |
| 171 | * Application can use these codes for application specific purposes freely. |
| 172 | */ |
| 173 | PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MIN = 4000, |
| 174 | PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MAX = 4999 |
| 175 | }; |
| 176 | |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 177 | /** |
| 178 | * The <code>PPB_WebSocket</code> interface provides bi-directional, |
| 179 | * full-duplex, communications over a single TCP socket. |
| 180 | */ |
[email protected] | 5350822 | 2012-01-27 09:42:41 | [diff] [blame] | 181 | interface PPB_WebSocket { |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 182 | /** |
| 183 | * Create() creates a WebSocket instance. |
| 184 | * |
| 185 | * @param[in] instance A <code>PP_Instance</code> identifying the instance |
| 186 | * with the WebSocket. |
| 187 | * |
| 188 | * @return A <code>PP_Resource</code> corresponding to a WebSocket if |
| 189 | * successful. |
| 190 | */ |
| 191 | PP_Resource Create([in] PP_Instance instance); |
| 192 | |
| 193 | /** |
| 194 | * IsWebSocket() determines if the provided <code>resource</code> is a |
| 195 | * WebSocket instance. |
| 196 | * |
| 197 | * @param[in] resource A <code>PP_Resource</code> corresponding to a |
| 198 | * WebSocket. |
| 199 | * |
| 200 | * @return Returns <code>PP_TRUE</code> if <code>resource</code> is a |
[email protected] | 5350822 | 2012-01-27 09:42:41 | [diff] [blame] | 201 | * <code>PPB_WebSocket</code>, <code>PP_FALSE</code> if the |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 202 | * <code>resource</code> is invalid or some type other than |
[email protected] | 5350822 | 2012-01-27 09:42:41 | [diff] [blame] | 203 | * <code>PPB_WebSocket</code>. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 204 | */ |
| 205 | PP_Bool IsWebSocket([in] PP_Resource resource); |
| 206 | |
| 207 | /** |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 208 | * Connect() connects to the specified WebSocket server. You can call this |
| 209 | * function once for a <code>web_socket</code>. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 210 | * |
| 211 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 212 | * WebSocket. |
| 213 | * |
| 214 | * @param[in] url A <code>PP_Var</code> representing a WebSocket server URL. |
| 215 | * The <code>PP_VarType</code> must be <code>PP_VARTYPE_STRING</code>. |
| 216 | * |
| 217 | * @param[in] protocols A pointer to an array of <code>PP_Var</code> |
| 218 | * specifying sub-protocols. Each <code>PP_Var</code> represents one |
| 219 | * sub-protocol and its <code>PP_VarType</code> must be |
| 220 | * <code>PP_VARTYPE_STRING</code>. This argument can be null only if |
| 221 | * <code>protocol_count</code> is 0. |
| 222 | * |
| 223 | * @param[in] protocol_count The number of sub-protocols in |
| 224 | * <code>protocols</code>. |
| 225 | * |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 226 | * @param[in] callback A <code>PP_CompletionCallback</code> called |
[email protected] | 3e919cb | 2011-12-16 07:28:21 | [diff] [blame] | 227 | * when a connection is established or an error occurs in establishing |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 228 | * connection. |
| 229 | * |
[email protected] | 3e919cb | 2011-12-16 07:28:21 | [diff] [blame] | 230 | * @return An int32_t containing an error code from <code>pp_errors.h</code>. |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 231 | * Returns <code>PP_ERROR_BADARGUMENT</code> if the specified |
| 232 | * <code>url</code>, or <code>protocols</code> contain an invalid string as |
| 233 | * defined in the WebSocket API specification. |
| 234 | * <code>PP_ERROR_BADARGUMENT</code> corresponds to a SyntaxError in the |
| 235 | * WebSocket API specification. |
[email protected] | 3e919cb | 2011-12-16 07:28:21 | [diff] [blame] | 236 | * Returns <code>PP_ERROR_NOACCESS</code> if the protocol specified in the |
| 237 | * <code>url</code> is not a secure protocol, but the origin of the caller |
[email protected] | e0aa9cf | 2012-03-27 19:11:49 | [diff] [blame] | 238 | * has a secure scheme. Also returns <code>PP_ERROR_NOACCESS</code> if the |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 239 | * port specified in the <code>url</code> is a port that the user agent |
| 240 | * is configured to block access to because it is a well-known port like |
[email protected] | e0aa9cf | 2012-03-27 19:11:49 | [diff] [blame] | 241 | * SMTP. <code>PP_ERROR_NOACCESS</code> corresponds to a SecurityError of the |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 242 | * specification. |
| 243 | * Returns <code>PP_ERROR_INPROGRESS</code> if this is not the first call to |
| 244 | * Connect(). |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 245 | */ |
[email protected] | f9116d11 | 2012-12-21 21:17:25 | [diff] [blame] | 246 | [report_errors=False] |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 247 | int32_t Connect([in] PP_Resource web_socket, |
| 248 | [in] PP_Var url, |
| 249 | [in, size_as=protocol_count] PP_Var[] protocols, |
| 250 | [in] uint32_t protocol_count, |
| 251 | [in] PP_CompletionCallback callback); |
| 252 | |
| 253 | /** |
| 254 | * Close() closes the specified WebSocket connection by specifying |
| 255 | * <code>code</code> and <code>reason</code>. |
| 256 | * |
| 257 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 258 | * WebSocket. |
| 259 | * |
[email protected] | b6b90fe | 2012-05-31 09:25:45 | [diff] [blame] | 260 | * @param[in] code The WebSocket close code. This is ignored if it is |
| 261 | * <code>PP_WEBSOCKETSTATUSCODE_NOT_SPECIFIED</code>. |
[email protected] | 7d107f3 | 2012-02-06 07:06:25 | [diff] [blame] | 262 | * <code>PP_WEBSOCKETSTATUSCODE_NORMAL_CLOSURE</code> must be used for the |
| 263 | * usual case. To indicate some specific error cases, codes in the range |
| 264 | * <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MIN</code> to |
| 265 | * <code>PP_WEBSOCKETSTATUSCODE_USER_REGISTERED_MAX</code>, and in the range |
| 266 | * <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MIN</code> to |
| 267 | * <code>PP_WEBSOCKETSTATUSCODE_USER_PRIVATE_MAX</code> are available. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 268 | * |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 269 | * @param[in] reason A <code>PP_Var</code> representing the WebSocket |
| 270 | * close reason. This is ignored if it is <code>PP_VARTYPE_UNDEFINED</code>. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 271 | * Otherwise, its <code>PP_VarType</code> must be |
| 272 | * <code>PP_VARTYPE_STRING</code>. |
| 273 | * |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 274 | * @param[in] callback A <code>PP_CompletionCallback</code> called |
[email protected] | 3e919cb | 2011-12-16 07:28:21 | [diff] [blame] | 275 | * when the connection is closed or an error occurs in closing the |
| 276 | * connection. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 277 | * |
[email protected] | 3e919cb | 2011-12-16 07:28:21 | [diff] [blame] | 278 | * @return An int32_t containing an error code from <code>pp_errors.h</code>. |
| 279 | * Returns <code>PP_ERROR_BADARGUMENT</code> if <code>reason</code> contains |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 280 | * an invalid character as a UTF-8 string, or is longer than 123 bytes. |
| 281 | * <code>PP_ERROR_BADARGUMENT</code> corresponds to a JavaScript SyntaxError |
| 282 | * in the WebSocket API specification. |
[email protected] | 3e919cb | 2011-12-16 07:28:21 | [diff] [blame] | 283 | * Returns <code>PP_ERROR_NOACCESS</code> if the code is not an integer |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 284 | * equal to 1000 or in the range 3000 to 4999. <code>PP_ERROR_NOACCESS</code> |
[email protected] | e0aa9cf | 2012-03-27 19:11:49 | [diff] [blame] | 285 | * corresponds to an InvalidAccessError in the WebSocket API specification. |
[email protected] | 9c8b2fd | 2012-04-25 11:39:07 | [diff] [blame] | 286 | * Returns <code>PP_ERROR_INPROGRESS</code> if a previous call to Close() is |
| 287 | * not finished. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 288 | */ |
[email protected] | f9116d11 | 2012-12-21 21:17:25 | [diff] [blame] | 289 | [report_errors=False] |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 290 | int32_t Close([in] PP_Resource web_socket, |
| 291 | [in] uint16_t code, |
| 292 | [in] PP_Var reason, |
| 293 | [in] PP_CompletionCallback callback); |
| 294 | |
| 295 | /** |
| 296 | * ReceiveMessage() receives a message from the WebSocket server. |
[email protected] | 3e919cb | 2011-12-16 07:28:21 | [diff] [blame] | 297 | * This interface only returns a single message. That is, this interface must |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 298 | * be called at least N times to receive N messages, no matter the size of |
| 299 | * each message. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 300 | * |
| 301 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 302 | * WebSocket. |
| 303 | * |
| 304 | * @param[out] message The received message is copied to provided |
[email protected] | 3e919cb | 2011-12-16 07:28:21 | [diff] [blame] | 305 | * <code>message</code>. The <code>message</code> must remain valid until |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 306 | * ReceiveMessage() completes. Its received <code>PP_VarType</code> will be |
| 307 | * <code>PP_VARTYPE_STRING</code> or <code>PP_VARTYPE_ARRAY_BUFFER</code>. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 308 | * |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 309 | * @param[in] callback A <code>PP_CompletionCallback</code> called |
| 310 | * when ReceiveMessage() completes. This callback is ignored if |
| 311 | * ReceiveMessage() completes synchronously and returns <code>PP_OK</code>. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 312 | * |
[email protected] | 3e919cb | 2011-12-16 07:28:21 | [diff] [blame] | 313 | * @return An int32_t containing an error code from <code>pp_errors.h</code>. |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 314 | * If an error is detected or connection is closed, ReceiveMessage() returns |
[email protected] | 3e919cb | 2011-12-16 07:28:21 | [diff] [blame] | 315 | * <code>PP_ERROR_FAILED</code> after all buffered messages are received. |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 316 | * Until buffered message become empty, ReceiveMessage() continues to return |
[email protected] | 3e919cb | 2011-12-16 07:28:21 | [diff] [blame] | 317 | * <code>PP_OK</code> as if connection is still established without errors. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 318 | */ |
[email protected] | f9116d11 | 2012-12-21 21:17:25 | [diff] [blame] | 319 | [report_errors=False] |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 320 | int32_t ReceiveMessage([in] PP_Resource web_socket, |
| 321 | [out] PP_Var message, |
| 322 | [in] PP_CompletionCallback callback); |
| 323 | |
| 324 | /** |
| 325 | * SendMessage() sends a message to the WebSocket server. |
| 326 | * |
| 327 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 328 | * WebSocket. |
| 329 | * |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 330 | * @param[in] message A message to send. The message is copied to an internal |
| 331 | * buffer, so the caller can free <code>message</code> safely after returning |
| 332 | * from the function. Its sent <code>PP_VarType</code> must be |
[email protected] | dc909a9 | 2012-01-27 06:07:25 | [diff] [blame] | 333 | * <code>PP_VARTYPE_STRING</code> or <code>PP_VARTYPE_ARRAY_BUFFER</code>. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 334 | * |
[email protected] | 3e919cb | 2011-12-16 07:28:21 | [diff] [blame] | 335 | * @return An int32_t containing an error code from <code>pp_errors.h</code>. |
| 336 | * Returns <code>PP_ERROR_FAILED</code> if the ReadyState is |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 337 | * <code>PP_WEBSOCKETREADYSTATE_CONNECTING</code>. |
[email protected] | e0aa9cf | 2012-03-27 19:11:49 | [diff] [blame] | 338 | * <code>PP_ERROR_FAILED</code> corresponds to a JavaScript |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 339 | * InvalidStateError in the WebSocket API specification. |
| 340 | * Returns <code>PP_ERROR_BADARGUMENT</code> if the provided |
| 341 | * <code>message</code> contains an invalid character as a UTF-8 string. |
[email protected] | e0aa9cf | 2012-03-27 19:11:49 | [diff] [blame] | 342 | * <code>PP_ERROR_BADARGUMENT</code> corresponds to a JavaScript |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 343 | * SyntaxError in the WebSocket API specification. |
| 344 | * Otherwise, returns <code>PP_OK</code>, which doesn't necessarily mean |
[email protected] | 3e919cb | 2011-12-16 07:28:21 | [diff] [blame] | 345 | * that the server received the message. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 346 | */ |
[email protected] | f9116d11 | 2012-12-21 21:17:25 | [diff] [blame] | 347 | [report_errors=False] |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 348 | int32_t SendMessage([in] PP_Resource web_socket, |
| 349 | [in] PP_Var message); |
| 350 | |
| 351 | /** |
| 352 | * GetBufferedAmount() returns the number of bytes of text and binary |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 353 | * messages that have been queued for the WebSocket connection to send, but |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 354 | * have not been transmitted to the network yet. |
| 355 | * |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 356 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 357 | * WebSocket. |
| 358 | * |
| 359 | * @return Returns the number of bytes. |
| 360 | */ |
[email protected] | f9116d11 | 2012-12-21 21:17:25 | [diff] [blame] | 361 | [report_errors=False] |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 362 | uint64_t GetBufferedAmount([in] PP_Resource web_socket); |
| 363 | |
| 364 | /** |
| 365 | * GetCloseCode() returns the connection close code for the WebSocket |
| 366 | * connection. |
| 367 | * |
| 368 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 369 | * WebSocket. |
| 370 | * |
| 371 | * @return Returns 0 if called before the close code is set. |
| 372 | */ |
[email protected] | f9116d11 | 2012-12-21 21:17:25 | [diff] [blame] | 373 | [report_errors=False] |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 374 | uint16_t GetCloseCode([in] PP_Resource web_socket); |
| 375 | |
| 376 | /** |
| 377 | * GetCloseReason() returns the connection close reason for the WebSocket |
| 378 | * connection. |
| 379 | * |
| 380 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 381 | * WebSocket. |
| 382 | * |
[email protected] | 3e919cb | 2011-12-16 07:28:21 | [diff] [blame] | 383 | * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 384 | * close reason is set, the return value contains an empty string. Returns a |
[email protected] | 4454db0 | 2011-11-16 05:25:01 | [diff] [blame] | 385 | * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 386 | */ |
[email protected] | f9116d11 | 2012-12-21 21:17:25 | [diff] [blame] | 387 | [report_errors=False] |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 388 | PP_Var GetCloseReason([in] PP_Resource web_socket); |
| 389 | |
| 390 | /** |
| 391 | * GetCloseWasClean() returns if the connection was closed cleanly for the |
| 392 | * specified WebSocket connection. |
| 393 | * |
| 394 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 395 | * WebSocket. |
| 396 | * |
| 397 | * @return Returns <code>PP_FALSE</code> if called before the connection is |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 398 | * closed, called on an invalid resource, or closed for abnormal reasons. |
| 399 | * Otherwise, returns <code>PP_TRUE</code> if the connection was closed |
| 400 | * cleanly. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 401 | */ |
[email protected] | f9116d11 | 2012-12-21 21:17:25 | [diff] [blame] | 402 | [report_errors=False] |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 403 | PP_Bool GetCloseWasClean([in] PP_Resource web_socket); |
| 404 | |
| 405 | /** |
| 406 | * GetExtensions() returns the extensions selected by the server for the |
| 407 | * specified WebSocket connection. |
| 408 | * |
| 409 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 410 | * WebSocket. |
| 411 | * |
| 412 | * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 413 | * connection is established, the var's data is an empty string. Returns a |
[email protected] | 4454db0 | 2011-11-16 05:25:01 | [diff] [blame] | 414 | * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 415 | */ |
[email protected] | f9116d11 | 2012-12-21 21:17:25 | [diff] [blame] | 416 | [report_errors=False] |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 417 | PP_Var GetExtensions([in] PP_Resource web_socket); |
| 418 | |
| 419 | /** |
| 420 | * GetProtocol() returns the sub-protocol chosen by the server for the |
| 421 | * specified WebSocket connection. |
| 422 | * |
| 423 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 424 | * WebSocket. |
| 425 | * |
| 426 | * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 427 | * connection is established, the var contains the empty string. Returns a |
[email protected] | 4454db0 | 2011-11-16 05:25:01 | [diff] [blame] | 428 | * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 429 | */ |
[email protected] | f9116d11 | 2012-12-21 21:17:25 | [diff] [blame] | 430 | [report_errors=False] |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 431 | PP_Var GetProtocol([in] PP_Resource web_socket); |
| 432 | |
| 433 | /** |
| 434 | * GetReadyState() returns the ready state of the specified WebSocket |
| 435 | * connection. |
| 436 | * |
| 437 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 438 | * WebSocket. |
| 439 | * |
[email protected] | 5350822 | 2012-01-27 09:42:41 | [diff] [blame] | 440 | * @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID</code> if called |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 441 | * before Connect() is called, or if this function is called on an |
| 442 | * invalid resource. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 443 | */ |
[email protected] | f9116d11 | 2012-12-21 21:17:25 | [diff] [blame] | 444 | [on_failure=PP_WEBSOCKETREADYSTATE_INVALID, report_errors=False] |
[email protected] | 5350822 | 2012-01-27 09:42:41 | [diff] [blame] | 445 | PP_WebSocketReadyState GetReadyState([in] PP_Resource web_socket); |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 446 | |
| 447 | /** |
| 448 | * GetURL() returns the URL associated with specified WebSocket connection. |
| 449 | * |
| 450 | * @param[in] web_socket A <code>PP_Resource</code> corresponding to a |
| 451 | * WebSocket. |
| 452 | * |
| 453 | * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the |
[email protected] | a4b1438 | 2012-02-24 02:22:07 | [diff] [blame] | 454 | * connection is established, the var contains the empty string. Returns a |
| 455 | * <code>PP_VARTYPE_UNDEFINED</code> if this function is called on an |
| 456 | * invalid resource. |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 457 | */ |
[email protected] | f9116d11 | 2012-12-21 21:17:25 | [diff] [blame] | 458 | [report_errors=False] |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 459 | PP_Var GetURL([in] PP_Resource web_socket); |
[email protected] | f88c2e0 | 2011-11-11 05:50:59 | [diff] [blame] | 460 | }; |