1 /* Copyright (c) 2013 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.
6 /* From extensions/dev/ppb_ext_socket_dev.idl,
7 * modified Tue May 21 16:00:11 2013.
10 #ifndef PPAPI_C_EXTENSIONS_DEV_PPB_EXT_SOCKET_DEV_H_
11 #define PPAPI_C_EXTENSIONS_DEV_PPB_EXT_SOCKET_DEV_H_
13 #include "ppapi/c/pp_bool.h"
14 #include "ppapi/c/pp_completion_callback.h"
15 #include "ppapi/c/pp_instance.h"
16 #include "ppapi/c/pp_macros.h"
17 #include "ppapi/c/pp_stdint.h"
18 #include "ppapi/c/pp_var.h"
20 #define PPB_EXT_SOCKET_DEV_INTERFACE_0_1 "PPB_Ext_Socket(Dev);0.1"
21 #define PPB_EXT_SOCKET_DEV_INTERFACE_0_2 "PPB_Ext_Socket(Dev);0.2"
22 #define PPB_EXT_SOCKET_DEV_INTERFACE PPB_EXT_SOCKET_DEV_INTERFACE_0_2
26 * This file defines the Pepper equivalent of the <code>chrome.socket</code>
32 * @addtogroup Typedefs
36 * A string <code>PP_Var</code> which has one of the following values:
40 typedef struct PP_Var PP_Ext_Socket_SocketType_Dev
;
43 * A dictionary <code>PP_Var</code>.
45 typedef struct PP_Var PP_Ext_Socket_CreateOptions_Dev
;
48 * A dictionary <code>PP_Var</code> which contains
49 * - "socketId" : integer <code>PP_Var</code>
50 * The id of the newly created socket.
52 typedef struct PP_Var PP_Ext_Socket_CreateInfo_Dev
;
55 * A dictionary <code>PP_Var</code> which contains
56 * - "resultCode" : integer <code>PP_Var</code>
57 * - "socketId" : integer or undefined <code>PP_Var</code>
58 * The id of the accepted socket.
60 typedef struct PP_Var PP_Ext_Socket_AcceptInfo_Dev
;
63 * A dictionary <code>PP_Var</code> which contains
64 * - "resultCode" : integer <code>PP_Var</code>
65 * The resultCode returned from the underlying read() call.
66 * - "data" : array buffer <code>PP_Var</code>
68 typedef struct PP_Var PP_Ext_Socket_ReadInfo_Dev
;
71 * A dictionary <code>PP_Var</code> which contains
72 * - "bytesWritten" : integer <code>PP_Var</code>
73 * The number of bytes sent, or a negative error code.
75 typedef struct PP_Var PP_Ext_Socket_WriteInfo_Dev
;
78 * A dictionary <code>PP_Var</code> which contains
79 * - "resultCode" : integer <code>PP_Var</code>
80 * The resultCode returned from the underlying recvfrom() call.
81 * - "data": array buffer <code>PP_Var</code>
82 * - "address": string <code>PP_Var</code>
83 * The address of the remote machine.
84 * - "port": integer <code>PP_Var</code>
86 typedef struct PP_Var PP_Ext_Socket_RecvFromInfo_Dev
;
89 * A dictionary <code>PP_Var</code> which contains
90 * - "socketType" : string <code>PP_Var</code> which matches the description of
91 * <code>PP_Ext_Socket_SocketType_Dev</code>
92 * The type of the passed socket. This will be <code>tcp</code> or
94 * - "connected" : boolean <code>PP_Var</code>
95 * Whether or not the underlying socket is connected.
97 * For <code>tcp</code> sockets, this will remain true even if the remote peer
98 * has disconnected. Reading or writing to the socket may then result in an
99 * error, hinting that this socket should be disconnected via
100 * <code>Disconnect()</code>.
102 * For <code>udp</code> sockets, this just represents whether a default remote
103 * address has been specified for reading and writing packets.
104 * - "peerAddress" : string or undefined <code>PP_Var</code>
105 * If the underlying socket is connected, contains the IPv4/6 address of the
107 * - "peerPort" : integer or undefined <code>PP_Var</code>
108 * If the underlying socket is connected, contains the port of the connected
110 * - "localAddress" : string or undefined <code>PP_Var</code>
111 * If the underlying socket is bound or connected, contains its local IPv4/6
113 * - "localPort" : integer or undefined <code>PP_Var</code>
114 * If the underlying socket is bound or connected, contains its local port.
116 typedef struct PP_Var PP_Ext_Socket_SocketInfo_Dev
;
119 * A dictionary <code>PP_Var</code> which contains
120 * - "name" : string <code>PP_Var</code>
121 * The underlying name of the adapter. On *nix, this will typically be "eth0",
123 * - "address": string <code>PP_Var</code>
124 * The available IPv4/6 address.
126 typedef struct PP_Var PP_Ext_Socket_NetworkInterface_Dev
;
129 * An array <code>PP_Var</code> which contains elements of
130 * <code>PP_Ext_Socket_NetworkInterface_Dev</code>.
132 typedef struct PP_Var PP_Ext_Socket_NetworkInterface_Dev_Array
;
138 * @addtogroup Interfaces
141 struct PPB_Ext_Socket_Dev_0_2
{
143 * Creates a socket of the specified type that will connect to the specified
146 * @param[in] instance A <code>PP_Instance</code>.
147 * @param[in] type A <code>PP_Ext_Socket_SocketType_Dev</code>. The type of
148 * socket to create. Must be <code>tcp</code> or <code>udp</code>.
149 * @param[in] options An undefined <code>PP_Var</code> or
150 * <code>PP_Ext_Socket_CreateOptions_Dev</code>. The socket options.
151 * @param[out] create_info A <code>PP_Ext_Socket_CreateInfo_Dev</code>.
152 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
155 * @return An error code from <code>pp_errors.h</code>.
157 int32_t (*Create
)(PP_Instance instance
,
158 PP_Ext_Socket_SocketType_Dev type
,
159 PP_Ext_Socket_CreateOptions_Dev options
,
160 PP_Ext_Socket_CreateInfo_Dev
* create_info
,
161 struct PP_CompletionCallback callback
);
163 * Destroys the socket. Each socket created should be destroyed after use.
165 * @param[in] instance A <code>PP_Instance</code>.
166 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
168 void (*Destroy
)(PP_Instance instance
, struct PP_Var socket_id
);
170 * Connects the socket to the remote machine (for a <code>tcp</code> socket).
171 * For a <code>udp</code> socket, this sets the default address which packets
172 * are sent to and read from for <code>Read()</code> and <code>Write()</code>
175 * @param[in] instance A <code>PP_Instance</code>.
176 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
177 * @param[in] hostname A string <code>PP_Var</code>. The hostname or IP
178 * address of the remote machine.
179 * @param[in] port An integer <code>PP_Var</code>. The port of the remote
181 * @param[out] result An integer <code>PP_Var</code>.
182 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
185 * @return An error code from <code>pp_errors.h</code>.
187 int32_t (*Connect
)(PP_Instance instance
,
188 struct PP_Var socket_id
,
189 struct PP_Var hostname
,
191 struct PP_Var
* result
,
192 struct PP_CompletionCallback callback
);
194 * Binds the local address for socket. Currently, it does not support TCP
197 * @param[in] instance A <code>PP_Instance</code>.
198 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
199 * @param[in] address A string <code>PP_Var</code>. The address of the local
201 * @param[in] port An integer <code>PP_Var</code>. The port of the local
203 * @param[out] result An integer <code>PP_Var</code>.
204 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
207 * @return An error code from <code>pp_errors.h</code>.
209 int32_t (*Bind
)(PP_Instance instance
,
210 struct PP_Var socket_id
,
211 struct PP_Var address
,
213 struct PP_Var
* result
,
214 struct PP_CompletionCallback callback
);
216 * Disconnects the socket. For UDP sockets, <code>Disconnect</code> is a
217 * non-operation but is safe to call.
219 * @param[in] instance A <code>PP_Instance</code>.
220 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
222 void (*Disconnect
)(PP_Instance instance
, struct PP_Var socket_id
);
224 * Reads data from the given connected socket.
226 * @param[in] instance A <code>PP_Instance</code>.
227 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
228 * @param[in] buffer_size An undefined or integer <code>PP_Var</code>. The
230 * @param[out] read_info A <code>PP_Ext_Socket_ReadInfo_Dev</code>.
231 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
234 * @return An error code from <code>pp_errors.h</code>.
236 int32_t (*Read
)(PP_Instance instance
,
237 struct PP_Var socket_id
,
238 struct PP_Var buffer_size
,
239 PP_Ext_Socket_ReadInfo_Dev
* read_info
,
240 struct PP_CompletionCallback callback
);
242 * Writes data on the given connected socket.
244 * @param[in] instance A <code>PP_Instance</code>.
245 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
246 * @param[in] data An array buffer <code>PP_Var</code>. The data to write.
247 * @param[out] write_info A <code>PP_Ext_Socket_WriteInfo_Dev</code>.
248 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
251 * @return An error code from <code>pp_errors.h</code>.
253 int32_t (*Write
)(PP_Instance instance
,
254 struct PP_Var socket_id
,
256 PP_Ext_Socket_WriteInfo_Dev
* write_info
,
257 struct PP_CompletionCallback callback
);
259 * Receives data from the given UDP socket.
261 * @param[in] instance A <code>PP_Instance</code>.
262 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
263 * @param[in] buffer_size An undefined or integer <code>PP_Var</code>. The
264 * receive buffer size.
265 * @param[out] recv_from_info A <code>PP_Ext_Socket_RecvFromInfo_Dev</code>.
266 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
269 * @return An error code from <code>pp_errors.h</code>.
271 int32_t (*RecvFrom
)(PP_Instance instance
,
272 struct PP_Var socket_id
,
273 struct PP_Var buffer_size
,
274 PP_Ext_Socket_RecvFromInfo_Dev
* recv_from_info
,
275 struct PP_CompletionCallback callback
);
277 * Sends data on the given UDP socket to the given address and port.
279 * @param[in] instance A <code>PP_Instance</code>.
280 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
281 * @param[in] data An array buffer <code>PP_Var</code>.
282 * @param[in] address A string <code>PP_Var</code>. The address of the remote
284 * @param[in] port An integer <code>PP_Var</code>. The port of the remote
286 * @param[out] write_info A <code>PP_Ext_Socket_WriteInfo_Dev</code>.
287 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
290 * @return An error code from <code>pp_errors.h</code>.
292 int32_t (*SendTo
)(PP_Instance instance
,
293 struct PP_Var socket_id
,
295 struct PP_Var address
,
297 PP_Ext_Socket_WriteInfo_Dev
* write_info
,
298 struct PP_CompletionCallback callback
);
300 * This method applies to TCP sockets only.
301 * Listens for connections on the specified port and address. This effectively
302 * makes this a server socket, and client socket functions (Connect, Read,
303 * Write) can no longer be used on this socket.
305 * @param[in] instance A <code>PP_Instance</code>.
306 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
307 * @param[in] address A string <code>PP_Var</code>. The address of the local
309 * @param[in] port An integer <code>PP_Var</code>. The port of the local
311 * @param[in] backlog An undefined or integer <code>PP_Var</code>. Length of
312 * the socket's listen queue.
313 * @param[out] result An integer <code>PP_Var</code>.
314 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
317 * @return An error code from <code>pp_errors.h</code>.
319 int32_t (*Listen
)(PP_Instance instance
,
320 struct PP_Var socket_id
,
321 struct PP_Var address
,
323 struct PP_Var backlog
,
324 struct PP_Var
* result
,
325 struct PP_CompletionCallback callback
);
327 * This method applies to TCP sockets only.
328 * Registers a callback function to be called when a connection is accepted on
329 * this listening server socket. Listen must be called first.
330 * If there is already an active accept callback, this callback will be
331 * invoked immediately with an error as the resultCode.
333 * @param[in] instance A <code>PP_Instance</code>.
334 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
335 * @param[out] accept_info A <code>PP_Ext_Socket_AcceptInfo_Dev</code>.
336 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
339 * @return An error code from <code>pp_errors.h</code>.
341 int32_t (*Accept
)(PP_Instance instance
,
342 struct PP_Var socket_id
,
343 PP_Ext_Socket_AcceptInfo_Dev
* accept_info
,
344 struct PP_CompletionCallback callback
);
346 * Enables or disables the keep-alive functionality for a TCP connection.
348 * @param[in] instance A <code>PP_Instance</code>.
349 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
350 * @param[in] enable A boolean <code>PP_Var</code>. If true, enable keep-alive
352 * @param[in] delay An undefined or integer <code>PP_Var</code>. Set the delay
353 * seconds between the last data packet received and the first keepalive
354 * probe. Default is 0.
355 * @param[out] result A boolean <code>PP_Var</code>.
356 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
359 * @return An error code from <code>pp_errors.h</code>.
361 int32_t (*SetKeepAlive
)(PP_Instance instance
,
362 struct PP_Var socket_id
,
363 struct PP_Var enable
,
365 struct PP_Var
* result
,
366 struct PP_CompletionCallback callback
);
368 * Sets or clears <code>TCP_NODELAY</code> for a TCP connection. Nagle's
369 * algorithm will be disabled when <code>TCP_NODELAY</code> is set.
371 * @param[in] instance A <code>PP_Instance</code>.
372 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
373 * @param[in] no_delay A boolean <code>PP_Var</code>.
374 * @param[out] result A boolean <code>PP_Var</code>.
375 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
378 * @return An error code from <code>pp_errors.h</code>.
380 int32_t (*SetNoDelay
)(PP_Instance instance
,
381 struct PP_Var socket_id
,
382 struct PP_Var no_delay
,
383 struct PP_Var
* result
,
384 struct PP_CompletionCallback callback
);
386 * Retrieves the state of the given socket.
388 * @param[in] instance A <code>PP_Instance</code>.
389 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
390 * @param[out] result A <code>PP_Ext_Socket_SocketInfo_Dev</code>.
391 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
394 * @return An error code from <code>pp_errors.h</code>.
396 int32_t (*GetInfo
)(PP_Instance instance
,
397 struct PP_Var socket_id
,
398 PP_Ext_Socket_SocketInfo_Dev
* result
,
399 struct PP_CompletionCallback callback
);
401 * Retrieves information about local adapters on this system.
403 * @param[in] instance A <code>PP_Instance</code>.
404 * @param[out] result A <code>PP_Ext_Socket_NetworkInterface_Dev_Array</code>.
405 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
408 * @return An error code from <code>pp_errors.h</code>.
410 int32_t (*GetNetworkList
)(PP_Instance instance
,
411 PP_Ext_Socket_NetworkInterface_Dev_Array
* result
,
412 struct PP_CompletionCallback callback
);
414 * Joins the multicast group and starts to receive packets from that group.
415 * The socket must be of UDP type and must be bound to a local port before
416 * calling this method.
418 * @param[in] instance A <code>PP_Instance</code>.
419 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
420 * @param[in] address A string <code>PP_Var</code>. The group address to join.
421 * Domain names are not supported.
422 * @param[out] result An integer <code>PP_Var</code>.
423 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
426 * @return An error code from <code>pp_errors.h</code>.
428 int32_t (*JoinGroup
)(PP_Instance instance
,
429 struct PP_Var socket_id
,
430 struct PP_Var address
,
431 struct PP_Var
* result
,
432 struct PP_CompletionCallback callback
);
434 * Leaves the multicast group previously joined using <code>JoinGroup</code>.
435 * It's not necessary to leave the multicast group before destroying the
436 * socket or exiting. This is automatically called by the OS.
438 * Leaving the group will prevent the router from sending multicast datagrams
439 * to the local host, presuming no other process on the host is still joined
442 * @param[in] instance A <code>PP_Instance</code>.
443 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
444 * @param[in] address A string <code>PP_Var</code>. The group address to
445 * leave. Domain names are not supported.
446 * @param[out] result An integer <code>PP_Var</code>.
447 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
450 * @return An error code from <code>pp_errors.h</code>.
452 int32_t (*LeaveGroup
)(PP_Instance instance
,
453 struct PP_Var socket_id
,
454 struct PP_Var address
,
455 struct PP_Var
* result
,
456 struct PP_CompletionCallback callback
);
458 * Sets the time-to-live of multicast packets sent to the multicast group.
460 * Calling this method does not require multicast permissions.
462 * @param[in] instance A <code>PP_Instance</code>.
463 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
464 * @param[in] ttl An integer <code>PP_Var</code>. The time-to-live value.
465 * @param[out] result An integer <code>PP_Var</code>.
466 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
469 * @return An error code from <code>pp_errors.h</code>.
471 int32_t (*SetMulticastTimeToLive
)(PP_Instance instance
,
472 struct PP_Var socket_id
,
474 struct PP_Var
* result
,
475 struct PP_CompletionCallback callback
);
477 * Sets whether multicast packets sent from the host to the multicast group
478 * will be looped back to the host.
480 * Note: the behavior of <code>SetMulticastLoopbackMode</code> is slightly
481 * different between Windows and Unix-like systems. The inconsistency
482 * happens only when there is more than one application on the same host
483 * joined to the same multicast group while having different settings on
484 * multicast loopback mode. On Windows, the applications with loopback off
485 * will not RECEIVE the loopback packets; while on Unix-like systems, the
486 * applications with loopback off will not SEND the loopback packets to
487 * other applications on the same host. See MSDN: http://goo.gl/6vqbj
489 * Calling this method does not require multicast permissions.
491 * @param[in] instance A <code>PP_Instance</code>.
492 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
493 * @param[in] enabled A boolean <code>PP_Var</code>. Indicates whether to
494 * enable loopback mode.
495 * @param[out] result An integer <code>PP_Var</code>.
496 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
499 * @return An error code from <code>pp_errors.h</code>.
501 int32_t (*SetMulticastLoopbackMode
)(PP_Instance instance
,
502 struct PP_Var socket_id
,
503 struct PP_Var enabled
,
504 struct PP_Var
* result
,
505 struct PP_CompletionCallback callback
);
507 * Gets the multicast group addresses the socket is currently joined to.
509 * @param[in] instance A <code>PP_Instance</code>.
510 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
511 * @param[out] groups An array <code>PP_Var</code> of string
512 * <code>PP_Var</code>s.
513 * @param[in] callback A <code>PP_CompletionCallback</code> to be called
516 * @return An error code from <code>pp_errors.h</code>.
518 int32_t (*GetJoinedGroups
)(PP_Instance instance
,
519 struct PP_Var socket_id
,
520 struct PP_Var
* groups
,
521 struct PP_CompletionCallback callback
);
524 typedef struct PPB_Ext_Socket_Dev_0_2 PPB_Ext_Socket_Dev
;
526 struct PPB_Ext_Socket_Dev_0_1
{
527 int32_t (*Create
)(PP_Instance instance
,
528 PP_Ext_Socket_SocketType_Dev type
,
529 PP_Ext_Socket_CreateOptions_Dev options
,
530 PP_Ext_Socket_CreateInfo_Dev
* create_info
,
531 struct PP_CompletionCallback callback
);
532 void (*Destroy
)(PP_Instance instance
, struct PP_Var socket_id
);
533 int32_t (*Connect
)(PP_Instance instance
,
534 struct PP_Var socket_id
,
535 struct PP_Var hostname
,
537 struct PP_Var
* result
,
538 struct PP_CompletionCallback callback
);
539 int32_t (*Bind
)(PP_Instance instance
,
540 struct PP_Var socket_id
,
541 struct PP_Var address
,
543 struct PP_Var
* result
,
544 struct PP_CompletionCallback callback
);
545 void (*Disconnect
)(PP_Instance instance
, struct PP_Var socket_id
);
546 int32_t (*Read
)(PP_Instance instance
,
547 struct PP_Var socket_id
,
548 struct PP_Var buffer_size
,
549 PP_Ext_Socket_ReadInfo_Dev
* read_info
,
550 struct PP_CompletionCallback callback
);
551 int32_t (*Write
)(PP_Instance instance
,
552 struct PP_Var socket_id
,
554 PP_Ext_Socket_WriteInfo_Dev
* write_info
,
555 struct PP_CompletionCallback callback
);
556 int32_t (*RecvFrom
)(PP_Instance instance
,
557 struct PP_Var socket_id
,
558 struct PP_Var buffer_size
,
559 PP_Ext_Socket_RecvFromInfo_Dev
* recv_from_info
,
560 struct PP_CompletionCallback callback
);
561 int32_t (*SendTo
)(PP_Instance instance
,
562 struct PP_Var socket_id
,
564 struct PP_Var address
,
566 PP_Ext_Socket_WriteInfo_Dev
* write_info
,
567 struct PP_CompletionCallback callback
);
568 int32_t (*Listen
)(PP_Instance instance
,
569 struct PP_Var socket_id
,
570 struct PP_Var address
,
572 struct PP_Var backlog
,
573 struct PP_Var
* result
,
574 struct PP_CompletionCallback callback
);
575 int32_t (*Accept
)(PP_Instance instance
,
576 struct PP_Var socket_id
,
577 PP_Ext_Socket_AcceptInfo_Dev
* accept_info
,
578 struct PP_CompletionCallback callback
);
579 int32_t (*SetKeepAlive
)(PP_Instance instance
,
580 struct PP_Var socket_id
,
581 struct PP_Var enable
,
583 struct PP_Var
* result
,
584 struct PP_CompletionCallback callback
);
585 int32_t (*SetNoDelay
)(PP_Instance instance
,
586 struct PP_Var socket_id
,
587 struct PP_Var no_delay
,
588 struct PP_Var
* result
,
589 struct PP_CompletionCallback callback
);
590 int32_t (*GetInfo
)(PP_Instance instance
,
591 struct PP_Var socket_id
,
592 PP_Ext_Socket_SocketInfo_Dev
* result
,
593 struct PP_CompletionCallback callback
);
594 int32_t (*GetNetworkList
)(PP_Instance instance
,
595 PP_Ext_Socket_NetworkInterface_Dev_Array
* result
,
596 struct PP_CompletionCallback callback
);
602 #endif /* PPAPI_C_EXTENSIONS_DEV_PPB_EXT_SOCKET_DEV_H_ */