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