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