ppapi/api/ppb_tcp_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_TCPSocket</code> interface.
   8  */
   9
  10 label Chrome {
  11   M29 = 1.0,
  12   M31 = 1.1
  13 };
  14
  15 /**
  16  * Option names used by <code>SetOption()</code>.
  17  */
  18 [assert_size(4)]
  19 enum PP_TCPSocket_Option {
  20   /**
  21    * Disables coalescing of small writes to make TCP segments, and instead
  22    * delivers data immediately. Value's type is <code>PP_VARTYPE_BOOL</code>.
  23    * This option can only be set after a successful <code>Connect()</code> call.
  24    */
  25   PP_TCPSOCKET_OPTION_NO_DELAY = 0,
  26
  27   /**
  28    * Specifies the total per-socket buffer space reserved for sends. Value's
  29    * type should be <code>PP_VARTYPE_INT32</code>.
  30    * This option can only be set after a successful <code>Connect()</code> call.
  31    *
  32    * Note: This is only treated as a hint for the browser to set the buffer
  33    * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
  34    * guarantee it will conform to the size.
  35    */
  36   PP_TCPSOCKET_OPTION_SEND_BUFFER_SIZE = 1,
  37
  38   /**
  39    * Specifies the total per-socket buffer space reserved for receives. Value's
  40    * type should be <code>PP_VARTYPE_INT32</code>.
  41    * This option can only be set after a successful <code>Connect()</code> call.
  42    *
  43    * Note: This is only treated as a hint for the browser to set the buffer
  44    * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
  45    * guarantee it will conform to the size.
  46    */
  47   PP_TCPSOCKET_OPTION_RECV_BUFFER_SIZE = 2
  48 };
  49
  50 /**
  51  * The <code>PPB_TCPSocket</code> interface provides TCP socket operations.
  52  *
  53  * Permissions: Apps permission <code>socket</code> with subrule
  54  * <code>tcp-connect</code> is required for <code>Connect()</code>; subrule
  55  * <code>tcp-listen</code> is required for <code>Listen()</code>.
  56  * For more details about network communication permissions, please see:
  57  * http://developer.chrome.com/apps/app_network.html
  58  */
  59 interface PPB_TCPSocket {
  60   /**
  61    * Creates a TCP socket resource.
  62    *
  63    * @param[in] instance A <code>PP_Instance</code> identifying one instance of
  64    * a module.
  65    *
  66    * @return A <code>PP_Resource</code> corresponding to a TCP socket or 0
  67    * on failure.
  68    */
  69   PP_Resource Create([in] PP_Instance instance);
  70
  71   /**
  72    * Determines if a given resource is a TCP socket.
  73    *
  74    * @param[in] resource A <code>PP_Resource</code> to check.
  75    *
  76    * @return <code>PP_TRUE</code> if the input is a
  77    * <code>PPB_TCPSocket</code> resource; <code>PP_FALSE</code> otherwise.
  78    */
  79   PP_Bool IsTCPSocket([in] PP_Resource resource);
  80
  81   /**
  82    * Binds the socket to the given address. The socket must not be bound.
  83    *
  84    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
  85    * socket.
  86    * @param[in] addr A <code>PPB_NetAddress</code> resource.
  87    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
  88    * completion.
  89    *
  90    * @return An int32_t containing an error code from <code>pp_errors.h</code>,
  91    * including (but not limited to):
  92    * - <code>PP_ERROR_ADDRESS_IN_USE</code>: the address is already in use.
  93    * - <code>PP_ERROR_ADDRESS_INVALID</code>: the address is invalid.
  94    */
  95   [version=1.1]
  96   int32_t Bind([in] PP_Resource tcp_socket,
  97                [in] PP_Resource addr,
  98                [in] PP_CompletionCallback callback);
  99
 100   /**
 101    * Connects the socket to the given address. The socket must not be listening.
 102    * Binding the socket beforehand is optional.
 103    *
 104    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 105    * socket.
 106    * @param[in] addr A <code>PPB_NetAddress</code> resource.
 107    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 108    * completion.
 109    *
 110    * @return An int32_t containing an error code from <code>pp_errors.h</code>,
 111    * including (but not limited to):
 112    * - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required
 113    *   permissions.
 114    * - <code>PP_ERROR_ADDRESS_UNREACHABLE</code>: <code>addr</code> is
 115    *   unreachable.
 116    * - <code>PP_ERROR_CONNECTION_REFUSED</code>: the connection attempt was
 117    *   refused.
 118    * - <code>PP_ERROR_CONNECTION_FAILED</code>: the connection attempt failed.
 119    * - <code>PP_ERROR_CONNECTION_TIMEDOUT</code>: the connection attempt timed
 120    *   out.
 121    *
 122    * Since version 1.1, if the socket is listening/connected or has a pending
 123    * listen/connect request, <code>Connect()</code> will fail without starting a
 124    * connection attempt; otherwise, any failure during the connection attempt
 125    * will cause the socket to be closed.
 126    */
 127   int32_t Connect([in] PP_Resource tcp_socket,
 128                   [in] PP_Resource addr,
 129                   [in] PP_CompletionCallback callback);
 130
 131   /**
 132    * Gets the local address of the socket, if it is bound.
 133    *
 134    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 135    * socket.
 136    *
 137    * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure.
 138    */
 139   PP_Resource GetLocalAddress([in] PP_Resource tcp_socket);
 140
 141   /**
 142    * Gets the remote address of the socket, if it is connected.
 143    *
 144    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 145    * socket.
 146    *
 147    * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure.
 148    */
 149   PP_Resource GetRemoteAddress([in] PP_Resource tcp_socket);
 150
 151   /**
 152    * Reads data from the socket. The socket must be connected. It may perform a
 153    * partial read.
 154    *
 155    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 156    * socket.
 157    * @param[out] buffer The buffer to store the received data on success. It
 158    * must be at least as large as <code>bytes_to_read</code>.
 159    * @param[in] bytes_to_read The number of bytes to read.
 160    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 161    * completion.
 162    *
 163    * @return A non-negative number on success to indicate how many bytes have
 164    * been read, 0 means that end-of-file was reached; otherwise, an error code
 165    * from <code>pp_errors.h</code>.
 166    */
 167   int32_t Read([in] PP_Resource tcp_socket,
 168                [out] str_t buffer,
 169                [in] int32_t bytes_to_read,
 170                [in] PP_CompletionCallback callback);
 171
 172   /**
 173    * Writes data to the socket. The socket must be connected. It may perform a
 174    * partial write.
 175    *
 176    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 177    * socket.
 178    * @param[in] buffer The buffer containing the data to write.
 179    * @param[in] bytes_to_write The number of bytes to write.
 180    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 181    * completion.
 182    *
 183    * @return A non-negative number on success to indicate how many bytes have
 184    * been written; otherwise, an error code from <code>pp_errors.h</code>.
 185    */
 186   int32_t Write([in] PP_Resource tcp_socket,
 187                 [in] str_t buffer,
 188                 [in] int32_t bytes_to_write,
 189                 [in] PP_CompletionCallback callback);
 190   /**
 191    * Starts listening. The socket must be bound and not connected.
 192    *
 193    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 194    * socket.
 195    * @param[in] backlog A hint to determine the maximum length to which the
 196    * queue of pending connections may grow.
 197    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 198    * completion.
 199    *
 200    * @return An int32_t containing an error code from <code>pp_errors.h</code>,
 201    * including (but not limited to):
 202    * - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required
 203    *   permissions.
 204    * - <code>PP_ERROR_ADDRESS_IN_USE</code>: Another socket is already listening
 205    *   on the same port.
 206    */
 207   [version=1.1]
 208   int32_t Listen([in] PP_Resource tcp_socket,
 209                  [in] int32_t backlog,
 210                  [in] PP_CompletionCallback callback);
 211
 212   /**
 213    * Accepts a connection. The socket must be listening.
 214    *
 215    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 216    * socket.
 217    * @param[out] accepted_tcp_socket Stores the accepted TCP socket on success.
 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    * including (but not limited to):
 223    * - <code>PP_ERROR_CONNECTION_ABORTED</code>: A connection has been aborted.
 224    */
 225   [version=1.1]
 226   int32_t Accept([in] PP_Resource tcp_socket,
 227                  [out] PP_Resource accepted_tcp_socket,
 228                  [in] PP_CompletionCallback callback);
 229
 230   /**
 231    * Cancels all pending operations and closes the socket. Any pending callbacks
 232    * will still run, reporting <code>PP_ERROR_ABORTED</code> if pending IO was
 233    * interrupted. After a call to this method, no output buffer pointers passed
 234    * into previous <code>Read()</code> or <code>Accept()</code> calls will be
 235    * accessed. It is not valid to call <code>Connect()</code> or
 236    * <code>Listen()</code> again.
 237    *
 238    * The socket is implicitly closed if it is destroyed, so you are not required
 239    * to call this method.
 240    *
 241    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 242    * socket.
 243    */
 244   void Close([in] PP_Resource tcp_socket);
 245
 246   /**
 247    * Sets a socket option on the TCP socket.
 248    * Please see the <code>PP_TCPSocket_Option</code> description for option
 249    * names, value types and allowed values.
 250    *
 251    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 252    * socket.
 253    * @param[in] name The option to set.
 254    * @param[in] value The option value to set.
 255    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 256    * completion.
 257    *
 258    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 259    */
 260   int32_t SetOption([in] PP_Resource tcp_socket,
 261                     [in] PP_TCPSocket_Option name,
 262                     [in] PP_Var value,
 263                     [in] PP_CompletionCallback callback);
 264 };