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 */ 35 typedef 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; 69 PP_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 */ 87 struct 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 211 typedef struct PPB_UDPSocket_1_0 PPB_UDPSocket; 212 /** 213 * @} 214 */ 215 216 #endif /* PPAPI_C_PPB_UDP_SOCKET_H_ */ 217 218