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 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