ppb_udp_socket.h revision eb525c5499e34cc9c4b825d6d9e75bb07cc06ace
1/* Copyright 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.
4 */
5
6/* From ppb_udp_socket.idl modified Sat Jun 22 10:56:26 2013. */
7
8#ifndef PPAPI_C_PPB_UDP_SOCKET_H_
9#define PPAPI_C_PPB_UDP_SOCKET_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_UDPSOCKET_INTERFACE_1_0 "PPB_UDPSocket;1.0"
20#define PPB_UDPSOCKET_INTERFACE PPB_UDPSOCKET_INTERFACE_1_0
21
22/**
23 * @file
24 * This file defines the <code>PPB_UDPSocket</code> interface.
25 */
26
27
28/**
29 * @addtogroup Enums
30 * @{
31 */
32/**
33 * Option names used by <code>SetOption()</code>.
34 */
35typedef enum {
36  /**
37   * Allows the socket to share the local address to which it will be bound with
38   * other processes. Value's type should be <code>PP_VARTYPE_BOOL</code>.
39   * This option can only be set before calling <code>Bind()</code>.
40   */
41  PP_UDPSOCKET_OPTION_ADDRESS_REUSE = 0,
42  /**
43   * Allows sending and receiving packets to and from broadcast addresses.
44   * Value's type should be <code>PP_VARTYPE_BOOL</code>.
45   * This option can only be set before calling <code>Bind()</code>.
46   */
47  PP_UDPSOCKET_OPTION_BROADCAST = 1,
48  /**
49   * Specifies the total per-socket buffer space reserved for sends. Value's
50   * type should be <code>PP_VARTYPE_INT32</code>.
51   * This option can only be set after a successful <code>Bind()</code> call.
52   *
53   * Note: This is only treated as a hint for the browser to set the buffer
54   * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
55   * guarantee it will conform to the size.
56   */
57  PP_UDPSOCKET_OPTION_SEND_BUFFER_SIZE = 2,
58  /**
59   * Specifies the total per-socket buffer space reserved for receives. Value's
60   * type should be <code>PP_VARTYPE_INT32</code>.
61   * This option can only be set after a successful <code>Bind()</code> call.
62   *
63   * Note: This is only treated as a hint for the browser to set the buffer
64   * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
65   * guarantee it will conform to the size.
66   */
67  PP_UDPSOCKET_OPTION_RECV_BUFFER_SIZE = 3
68} PP_UDPSocket_Option;
69PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_UDPSocket_Option, 4);
70/**
71 * @}
72 */
73
74/**
75 * @addtogroup Interfaces
76 * @{
77 */
78/**
79 * The <code>PPB_UDPSocket</code> interface provides UDP socket operations.
80 *
81 * Permissions: Apps permission <code>socket</code> with subrule
82 * <code>udp-bind</code> is required for <code>Bind()</code>; subrule
83 * <code>udp-send-to</code> is required for <code>SendTo()</code>.
84 * For more details about network communication permissions, please see:
85 * http://developer.chrome.com/apps/app_network.html
86 */
87struct PPB_UDPSocket_1_0 {
88  /**
89   * Creates a UDP socket resource.
90   *
91   * @param[in] instance A <code>PP_Instance</code> identifying one instance of
92   * a module.
93   *
94   * @return A <code>PP_Resource</code> corresponding to a UDP socket or 0
95   * on failure.
96   */
97  PP_Resource (*Create)(PP_Instance instance);
98  /**
99   * Determines if a given resource is a UDP socket.
100   *
101   * @param[in] resource A <code>PP_Resource</code> to check.
102   *
103   * @return <code>PP_TRUE</code> if the input is a <code>PPB_UDPSocket</code>
104   * resource; <code>PP_FALSE</code> otherwise.
105   */
106  PP_Bool (*IsUDPSocket)(PP_Resource resource);
107  /**
108   * Binds the socket to the given address.
109   *
110   * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP
111   * socket.
112   * @param[in] addr A <code>PPB_NetAddress</code> resource.
113   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
114   * completion.
115   *
116   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
117   * <code>PP_ERROR_NOACCESS</code> will be returned if the caller doesn't have
118   * required permissions. <code>PP_ERROR_ADDRESS_IN_USE</code> will be returned
119   * if the address is already in use.
120   */
121  int32_t (*Bind)(PP_Resource udp_socket,
122                  PP_Resource addr,
123                  struct PP_CompletionCallback callback);
124  /**
125   * Gets the address that the socket is bound to. The socket must be bound.
126   *
127   * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP
128   * socket.
129   *
130   * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure.
131   */
132  PP_Resource (*GetBoundAddress)(PP_Resource udp_socket);
133  /**
134   * Receives data from the socket and stores the source address. The socket
135   * must be bound.
136   *
137   * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP
138   * socket.
139   * @param[out] buffer The buffer to store the received data on success. It
140   * must be at least as large as <code>num_bytes</code>.
141   * @param[in] num_bytes The number of bytes to receive.
142   * @param[out] addr A <code>PPB_NetAddress</code> resource to store the source
143   * address on success.
144   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
145   * completion.
146   *
147   * @return A non-negative number on success to indicate how many bytes have
148   * been received; otherwise, an error code from <code>pp_errors.h</code>.
149   */
150  int32_t (*RecvFrom)(PP_Resource udp_socket,
151                      char* buffer,
152                      int32_t num_bytes,
153                      PP_Resource* addr,
154                      struct PP_CompletionCallback callback);
155  /**
156   * Sends data to a specific destination. The socket must be bound.
157   *
158   * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP
159   * socket.
160   * @param[in] buffer The buffer containing the data to send.
161   * @param[in] num_bytes The number of bytes to send.
162   * @param[in] addr A <code>PPB_NetAddress</code> resource holding the
163   * destination address.
164   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
165   * completion.
166   *
167   * @return A non-negative number on success to indicate how many bytes have
168   * been sent; otherwise, an error code from <code>pp_errors.h</code>.
169   * <code>PP_ERROR_NOACCESS</code> will be returned if the caller doesn't have
170   * required permissions.
171   */
172  int32_t (*SendTo)(PP_Resource udp_socket,
173                    const char* buffer,
174                    int32_t num_bytes,
175                    PP_Resource addr,
176                    struct PP_CompletionCallback callback);
177  /**
178   * Cancels all pending reads and writes, and closes the socket. Any pending
179   * callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> if
180   * pending IO was interrupted. After a call to this method, no output
181   * parameters passed into previous <code>RecvFrom()</code> calls will be
182   * accessed. It is not valid to call <code>Bind()</code> again.
183   *
184   * The socket is implicitly closed if it is destroyed, so you are not
185   * required to call this method.
186   *
187   * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP
188   * socket.
189   */
190  void (*Close)(PP_Resource udp_socket);
191  /**
192   * Sets a socket option on the UDP socket.
193   * Please see the <code>PP_UDPSocket_Option</code> description for option
194   * names, value types and allowed values.
195   *
196   * @param[in] udp_socket A <code>PP_Resource</code> corresponding to a UDP
197   * socket.
198   * @param[in] name The option to set.
199   * @param[in] value The option value to set.
200   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
201   * completion.
202   *
203   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
204   */
205  int32_t (*SetOption)(PP_Resource udp_socket,
206                       PP_UDPSocket_Option name,
207                       struct PP_Var value,
208                       struct PP_CompletionCallback callback);
209};
210
211typedef struct PPB_UDPSocket_1_0 PPB_UDPSocket;
212/**
213 * @}
214 */
215
216#endif  /* PPAPI_C_PPB_UDP_SOCKET_H_ */
217
218