OLD | NEW |
| (Empty) |
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 dev/ppb_websocket_dev.idl modified Fri Jan 27 10:09:34 2012. */ | |
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 is queried on an invalid resource. | |
40 */ | |
41 PP_WEBSOCKETREADYSTATE_INVALID_DEV = -1, | |
42 /** | |
43 * Ready state that the connection has not yet been established. | |
44 */ | |
45 PP_WEBSOCKETREADYSTATE_CONNECTING_DEV = 0, | |
46 /** | |
47 * Ready state that the WebSocket connection is established and communication | |
48 * is possible. | |
49 */ | |
50 PP_WEBSOCKETREADYSTATE_OPEN_DEV = 1, | |
51 /** | |
52 * Ready state that the connection is going through the closing handshake. | |
53 */ | |
54 PP_WEBSOCKETREADYSTATE_CLOSING_DEV = 2, | |
55 /** | |
56 * Ready state that the connection has been closed or could not be opened. | |
57 */ | |
58 PP_WEBSOCKETREADYSTATE_CLOSED_DEV = 3 | |
59 } PP_WebSocketReadyState_Dev; | |
60 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_WebSocketReadyState_Dev, 4); | |
61 /** | |
62 * @} | |
63 */ | |
64 | |
65 /** | |
66 * @addtogroup Interfaces | |
67 * @{ | |
68 */ | |
69 struct PPB_WebSocket_Dev_0_1 { | |
70 /** | |
71 * Create() creates a WebSocket instance. | |
72 * | |
73 * @param[in] instance A <code>PP_Instance</code> identifying the instance | |
74 * with the WebSocket. | |
75 * | |
76 * @return A <code>PP_Resource</code> corresponding to a WebSocket if | |
77 * successful. | |
78 */ | |
79 PP_Resource (*Create)(PP_Instance instance); | |
80 /** | |
81 * IsWebSocket() determines if the provided <code>resource</code> is a | |
82 * WebSocket instance. | |
83 * | |
84 * @param[in] resource A <code>PP_Resource</code> corresponding to a | |
85 * WebSocket. | |
86 * | |
87 * @return Returns <code>PP_TRUE</code> if <code>resource</code> is a | |
88 * <code>PPB_WebSocket_Dev</code>, <code>PP_FALSE</code> if the | |
89 * <code>resource</code> is invalid or some type other than | |
90 * <code>PPB_WebSocket_Dev</code>. | |
91 */ | |
92 PP_Bool (*IsWebSocket)(PP_Resource resource); | |
93 /** | |
94 * Connect() connects to the specified WebSocket server. Caller can call this | |
95 * method at most once for a <code>web_socket</code>. | |
96 * | |
97 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
98 * WebSocket. | |
99 * | |
100 * @param[in] url A <code>PP_Var</code> representing a WebSocket server URL. | |
101 * The <code>PP_VarType</code> must be <code>PP_VARTYPE_STRING</code>. | |
102 * | |
103 * @param[in] protocols A pointer to an array of <code>PP_Var</code> | |
104 * specifying sub-protocols. Each <code>PP_Var</code> represents one | |
105 * sub-protocol and its <code>PP_VarType</code> must be | |
106 * <code>PP_VARTYPE_STRING</code>. This argument can be null only if | |
107 * <code>protocol_count</code> is 0. | |
108 * | |
109 * @param[in] protocol_count The number of sub-protocols in | |
110 * <code>protocols</code>. | |
111 * | |
112 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | |
113 * when a connection is established or an error occurs in establishing | |
114 * connection. | |
115 * | |
116 * @return An int32_t containing an error code from <code>pp_errors.h</code>. | |
117 * Returns <code>PP_ERROR_BADARGUMENT</code> if specified <code>url</code>, | |
118 * or <code>protocols</code> contains invalid string as | |
119 * <code>The WebSocket API specification</code> defines. It corresponds to | |
120 * SyntaxError of the specification. | |
121 * Returns <code>PP_ERROR_NOACCESS</code> if the protocol specified in the | |
122 * <code>url</code> is not a secure protocol, but the origin of the caller | |
123 * has a secure scheme. Also returns it if the port specified in the | |
124 * <code>url</code> is a port to which the user agent is configured to block | |
125 * access because the port is a well-known port like SMTP. It corresponds to | |
126 * SecurityError of the specification. | |
127 * Returns <code>PP_ERROR_INPROGRESS</code> if the call is not the first | |
128 * time. | |
129 */ | |
130 int32_t (*Connect)(PP_Resource web_socket, | |
131 struct PP_Var url, | |
132 const struct PP_Var protocols[], | |
133 uint32_t protocol_count, | |
134 struct PP_CompletionCallback callback); | |
135 /** | |
136 * Close() closes the specified WebSocket connection by specifying | |
137 * <code>code</code> and <code>reason</code>. | |
138 * | |
139 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
140 * WebSocket. | |
141 * | |
142 * @param[in] code The WebSocket close code. Ignored if it is 0. | |
143 * | |
144 * @param[in] reason A <code>PP_Var</code> which represents the WebSocket | |
145 * close reason. Ignored if it is <code>PP_VARTYPE_UNDEFINED</code>. | |
146 * Otherwise, its <code>PP_VarType</code> must be | |
147 * <code>PP_VARTYPE_STRING</code>. | |
148 * | |
149 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | |
150 * when the connection is closed or an error occurs in closing the | |
151 * connection. | |
152 * | |
153 * @return An int32_t containing an error code from <code>pp_errors.h</code>. | |
154 * Returns <code>PP_ERROR_BADARGUMENT</code> if <code>reason</code> contains | |
155 * an invalid character as a UTF-8 string, or longer than 123 bytes. It | |
156 * corresponds to JavaScript SyntaxError of the specification. | |
157 * Returns <code>PP_ERROR_NOACCESS</code> if the code is not an integer | |
158 * equal to 1000 or in the range 3000 to 4999. It corresponds to | |
159 * InvalidAccessError of the specification. Returns | |
160 * <code>PP_ERROR_INPROGRESS</code> if the call is not the first time. | |
161 */ | |
162 int32_t (*Close)(PP_Resource web_socket, | |
163 uint16_t code, | |
164 struct PP_Var reason, | |
165 struct PP_CompletionCallback callback); | |
166 /** | |
167 * ReceiveMessage() receives a message from the WebSocket server. | |
168 * This interface only returns a single message. That is, this interface must | |
169 * be called at least N times to receive N messages, no matter how small each | |
170 * message is. | |
171 * | |
172 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
173 * WebSocket. | |
174 * | |
175 * @param[out] message The received message is copied to provided | |
176 * <code>message</code>. The <code>message</code> must remain valid until | |
177 * the ReceiveMessage operation completes. Its <code>PP_VarType</code> | |
178 * will be <code>PP_VARTYPE_STRING</code> or | |
179 * <code>PP_VARTYPE_ARRAY_BYFFER</code> on receiving. | |
180 * | |
181 * @param[in] callback A <code>PP_CompletionCallback</code> which is called | |
182 * when the receiving message is completed. It is ignored if ReceiveMessage | |
183 * completes synchronously and returns <code>PP_OK</code>. | |
184 * | |
185 * @return An int32_t containing an error code from <code>pp_errors.h</code>. | |
186 * If an error is detected or connection is closed, returns | |
187 * <code>PP_ERROR_FAILED</code> after all buffered messages are received. | |
188 * Until buffered message become empty, continues to returns | |
189 * <code>PP_OK</code> as if connection is still established without errors. | |
190 */ | |
191 int32_t (*ReceiveMessage)(PP_Resource web_socket, | |
192 struct PP_Var* message, | |
193 struct PP_CompletionCallback callback); | |
194 /** | |
195 * SendMessage() sends a message to the WebSocket server. | |
196 * | |
197 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
198 * WebSocket. | |
199 * | |
200 * @param[in] message A message to send. The message is copied to internal | |
201 * buffer. So caller can free <code>message</code> safely after returning | |
202 * from the function. Its <code>PP_VarType</code> must be | |
203 * <code>PP_VARTYPE_STRING</code> or <code>PP_VARTYPE_ARRAY_BUFFER</code>. | |
204 * | |
205 * @return An int32_t containing an error code from <code>pp_errors.h</code>. | |
206 * Returns <code>PP_ERROR_FAILED</code> if the ReadyState is | |
207 * <code>PP_WEBSOCKETREADYSTATE_CONNECTING_DEV</code>. It corresponds | |
208 * JavaScript InvalidStateError of the specification. | |
209 * Returns <code>PP_ERROR_BADARGUMENT</code> if provided <code>message</code> | |
210 * of string type contains an invalid character as a UTF-8 string. It | |
211 * corresponds to JavaScript SyntaxError of the specification. | |
212 * Otherwise, returns <code>PP_OK</code>, but it doesn't necessarily mean | |
213 * that the server received the message. | |
214 */ | |
215 int32_t (*SendMessage)(PP_Resource web_socket, struct PP_Var message); | |
216 /** | |
217 * GetBufferedAmount() returns the number of bytes of text and binary | |
218 * messages that have been queued for the WebSocket connection to send but | |
219 * have not been transmitted to the network yet. | |
220 * | |
221 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
222 * WebSocket. | |
223 * | |
224 * @return Returns the number of bytes. | |
225 */ | |
226 uint64_t (*GetBufferedAmount)(PP_Resource web_socket); | |
227 /** | |
228 * GetCloseCode() returns the connection close code for the WebSocket | |
229 * connection. | |
230 * | |
231 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
232 * WebSocket. | |
233 * | |
234 * @return Returns 0 if called before the close code is set. | |
235 */ | |
236 uint16_t (*GetCloseCode)(PP_Resource web_socket); | |
237 /** | |
238 * GetCloseReason() returns the connection close reason for the WebSocket | |
239 * connection. | |
240 * | |
241 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
242 * WebSocket. | |
243 * | |
244 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the | |
245 * close reason is set, it contains an empty string. Returns a | |
246 * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. | |
247 */ | |
248 struct PP_Var (*GetCloseReason)(PP_Resource web_socket); | |
249 /** | |
250 * GetCloseWasClean() returns if the connection was closed cleanly for the | |
251 * specified WebSocket connection. | |
252 * | |
253 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
254 * WebSocket. | |
255 * | |
256 * @return Returns <code>PP_FALSE</code> if called before the connection is | |
257 * closed, or called on an invalid resource. Otherwise, returns | |
258 * <code>PP_TRUE</code> if the connection was closed cleanly, or returns | |
259 * <code>PP_FALSE</code> if the connection was closed for abnormal reasons. | |
260 */ | |
261 PP_Bool (*GetCloseWasClean)(PP_Resource web_socket); | |
262 /** | |
263 * GetExtensions() returns the extensions selected by the server for the | |
264 * specified WebSocket connection. | |
265 * | |
266 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
267 * WebSocket. | |
268 * | |
269 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the | |
270 * connection is established, its data is an empty string. Returns a | |
271 * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. | |
272 * Currently its data for valid resources are always an empty string. | |
273 */ | |
274 struct PP_Var (*GetExtensions)(PP_Resource web_socket); | |
275 /** | |
276 * GetProtocol() returns the sub-protocol chosen by the server for the | |
277 * specified WebSocket connection. | |
278 * | |
279 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
280 * WebSocket. | |
281 * | |
282 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the | |
283 * connection is established, it contains the empty string. Returns a | |
284 * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. | |
285 */ | |
286 struct PP_Var (*GetProtocol)(PP_Resource web_socket); | |
287 /** | |
288 * GetReadyState() returns the ready state of the specified WebSocket | |
289 * connection. | |
290 * | |
291 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
292 * WebSocket. | |
293 * | |
294 * @return Returns <code>PP_WEBSOCKETREADYSTATE_INVALID_DEV</code> if called | |
295 * before connect() is called, or called on an invalid resource. | |
296 */ | |
297 PP_WebSocketReadyState_Dev (*GetReadyState)(PP_Resource web_socket); | |
298 /** | |
299 * GetURL() returns the URL associated with specified WebSocket connection. | |
300 * | |
301 * @param[in] web_socket A <code>PP_Resource</code> corresponding to a | |
302 * WebSocket. | |
303 * | |
304 * @return Returns a <code>PP_VARTYPE_STRING</code> var. If called before the | |
305 * connection is established, it contains the empty string. Return a | |
306 * <code>PP_VARTYPE_UNDEFINED</code> if called on an invalid resource. | |
307 */ | |
308 struct PP_Var (*GetURL)(PP_Resource web_socket); | |
309 }; | |
310 | |
311 typedef struct PPB_WebSocket_Dev_0_1 PPB_WebSocket_Dev; | |
312 /** | |
313 * @} | |
314 */ | |
315 | |
316 #endif /* PPAPI_C_DEV_PPB_WEBSOCKET_DEV_H_ */ | |
317 | |
OLD | NEW |