ppapi/c/ppb_udp_socket.h

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