ppapi/api/ppb_udp_socket.idl

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