Home | History | Annotate | Download | only in api
      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 };
    197