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