1/* Copyright (c) 2012 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/**
7 * This file defines the <code>PPB_WebSocket</code> interface providing
8 * bi-directional, full-duplex, communications over a single TCP socket.
9 */
10
11[generate_thunk]
12
13label Chrome {
14  M18 = 1.0
15};
16
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)]
23enum PP_WebSocketReadyState {
24  /**
25   * Ready state is queried on an invalid resource.
26   */
27  PP_WEBSOCKETREADYSTATE_INVALID = -1,
28
29  /**
30   * Ready state that the connection has not yet been established.
31   */
32  PP_WEBSOCKETREADYSTATE_CONNECTING = 0,
33
34  /**
35   * Ready state that the WebSocket connection is established and communication
36   * is possible.
37   */
38  PP_WEBSOCKETREADYSTATE_OPEN = 1,
39
40  /**
41   * Ready state that the connection is going through the closing handshake.
42   */
43  PP_WEBSOCKETREADYSTATE_CLOSING = 2,
44
45  /**
46   * Ready state that the connection has been closed or could not be opened.
47   */
48  PP_WEBSOCKETREADYSTATE_CLOSED = 3
49};
50
51/**
52 * This enumeration contains status codes. These codes are used in Close() and
53 * GetCloseCode(). Refer to RFC 6455, The WebSocket Protocol, for further
54 * information.
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)]
62enum PP_WebSocketCloseCode {
63  /**
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  /**
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
177/**
178 * The <code>PPB_WebSocket</code> interface provides bi-directional,
179 * full-duplex, communications over a single TCP socket.
180 */
181interface PPB_WebSocket {
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
201   * <code>PPB_WebSocket</code>, <code>PP_FALSE</code> if the
202   * <code>resource</code> is invalid or some type other than
203   * <code>PPB_WebSocket</code>.
204   */
205  PP_Bool IsWebSocket([in] PP_Resource resource);
206
207  /**
208   * Connect() connects to the specified WebSocket server. You can call this
209   * function once for a <code>web_socket</code>.
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   *
226   * @param[in] callback A <code>PP_CompletionCallback</code> called
227   * when a connection is established or an error occurs in establishing
228   * connection.
229   *
230   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
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.
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
238   * has a secure scheme. Also returns <code>PP_ERROR_NOACCESS</code> if the
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
241   * SMTP. <code>PP_ERROR_NOACCESS</code> corresponds to a SecurityError of the
242   * specification.
243   * Returns <code>PP_ERROR_INPROGRESS</code> if this is not the first call to
244   * Connect().
245   */
246  [report_errors=False]
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   *
260   * @param[in] code The WebSocket close code. This is ignored if it is
261   * <code>PP_WEBSOCKETSTATUSCODE_NOT_SPECIFIED</code>.
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.
268   *
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>.
271   * Otherwise, its <code>PP_VarType</code> must be
272   * <code>PP_VARTYPE_STRING</code>.
273   *
274   * @param[in] callback A <code>PP_CompletionCallback</code> called
275   * when the connection is closed or an error occurs in closing the
276   * connection.
277   *
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
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.
283   * Returns <code>PP_ERROR_NOACCESS</code> if the code is not an integer
284   * equal to 1000 or in the range 3000 to 4999. <code>PP_ERROR_NOACCESS</code>
285   * corresponds to an InvalidAccessError in the WebSocket API specification.
286   * Returns <code>PP_ERROR_INPROGRESS</code> if a previous call to Close() is
287   * not finished.
288   */
289  [report_errors=False]
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.
297   * This interface only returns a single message. That is, this interface must
298   * be called at least N times to receive N messages, no matter the size of
299   * each message.
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
305   * <code>message</code>. The <code>message</code> must remain valid until
306   * ReceiveMessage() completes. Its received <code>PP_VarType</code> will be
307   * <code>PP_VARTYPE_STRING</code> or <code>PP_VARTYPE_ARRAY_BUFFER</code>.
308   *
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>.
312   *
313   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
314   * If an error is detected or connection is closed, ReceiveMessage() returns
315   * <code>PP_ERROR_FAILED</code> after all buffered messages are received.
316   * Until buffered message become empty, ReceiveMessage() continues to return
317   * <code>PP_OK</code> as if connection is still established without errors.
318   */
319  [report_errors=False]
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   *
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
333   * <code>PP_VARTYPE_STRING</code> or <code>PP_VARTYPE_ARRAY_BUFFER</code>.
334   *
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
337   * <code>PP_WEBSOCKETREADYSTATE_CONNECTING</code>.
338   * <code>PP_ERROR_FAILED</code> corresponds to a JavaScript
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.
342   * <code>PP_ERROR_BADARGUMENT</code> corresponds to a JavaScript
343   * SyntaxError in the WebSocket API specification.
344   * Otherwise, returns <code>PP_OK</code>, which doesn't necessarily mean
345   * that the server received the message.
346   */
347  [report_errors=False]
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
353   * messages that have been queued for the WebSocket connection to send, but
354   * have not been transmitted to the network yet.
355   *
356   * @param[in] web_socket A <code>PP_Resource</code> corresponding to a
357   * WebSocket.
358   *
359   * @return Returns the number of bytes.
360   */
361  [report_errors=False]
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   */
373  [report_errors=False]
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   *
383   * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the
384   * close reason is set, the return value contains an empty string. Returns a
385   * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource.
386   */
387  [report_errors=False]
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
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.
401   */
402  [report_errors=False]
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
413   * connection is established, the var's data is an empty string. Returns a
414   * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource.
415   */
416  [report_errors=False]
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
427   * connection is established, the var contains the empty string. Returns a
428   * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource.
429   */
430  [report_errors=False]
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   *
440   * @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID</code> if called
441   * before Connect() is called, or if this function is called on an
442   * invalid resource.
443   */
444  [on_failure=PP_WEBSOCKETREADYSTATE_INVALID, report_errors=False]
445  PP_WebSocketReadyState GetReadyState([in] PP_Resource web_socket);
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
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.
457   */
458  [report_errors=False]
459  PP_Var GetURL([in] PP_Resource web_socket);
460};
461