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