Ben Murdoch | eb525c5 | 2013-07-10 11:40:50 +0100 | [diff] [blame] | 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 | |