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