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 [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_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    * This option can only be set after a successful <code>Connect()</code> call.
  25    */
  26   PP_TCPSOCKET_OPTION_NO_DELAY = 0,
  27
  28   /**
  29    * Specifies the total per-socket buffer space reserved for sends. Value's
  30    * type should be <code>PP_VARTYPE_INT32</code>.
  31    * This option can only be set after a successful <code>Connect()</code> call.
  32    *
  33    * Note: This is only treated as a hint for the browser to set the buffer
  34    * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
  35    * guarantee it will conform to the size.
  36    */
  37   PP_TCPSOCKET_OPTION_SEND_BUFFER_SIZE = 1,
  38
  39   /**
  40    * Specifies the total per-socket buffer space reserved for receives. Value's
  41    * type should be <code>PP_VARTYPE_INT32</code>.
  42    * This option can only be set after a successful <code>Connect()</code> call.
  43    *
  44    * Note: This is only treated as a hint for the browser to set the buffer
  45    * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
  46    * guarantee it will conform to the size.
  47    */
  48   PP_TCPSOCKET_OPTION_RECV_BUFFER_SIZE = 2
  49 };
  50
  51 /**
  52  * The <code>PPB_TCPSocket</code> interface provides TCP socket operations.
  53  *
  54  * Permissions: Apps permission <code>socket</code> with subrule
  55  * <code>tcp-connect</code> is required for <code>Connect()</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    * Connects the socket to the given address.
  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_NOACCESS</code>: the caller doesn't have required
  93    *   permissions.
  94    * - <code>PP_ERROR_ADDRESS_UNREACHABLE</code>: <code>addr</code> is
  95    *   unreachable.
  96    * - <code>PP_ERROR_CONNECTION_REFUSED</code>: the connection attempt was
  97    *   refused.
  98    * - <code>PP_ERROR_CONNECTION_FAILED</code>: the connection attempt failed.
  99    * - <code>PP_ERROR_CONNECTION_TIMEDOUT</code>: the connection attempt timed
 100    *   out.
 101    */
 102   int32_t Connect([in] PP_Resource tcp_socket,
 103                   [in] PP_Resource addr,
 104                   [in] PP_CompletionCallback callback);
 105
 106   /**
 107    * Gets the local address of the socket, if it is connected.
 108    *
 109    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 110    * socket.
 111    *
 112    * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure.
 113    */
 114   PP_Resource GetLocalAddress([in] PP_Resource tcp_socket);
 115
 116   /**
 117    * Gets the remote address of the socket, if it is connected.
 118    *
 119    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 120    * socket.
 121    *
 122    * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure.
 123    */
 124   PP_Resource GetRemoteAddress([in] PP_Resource tcp_socket);
 125
 126   /**
 127    * Reads data from the socket. The socket must be connected. It may perform a
 128    * partial read.
 129    *
 130    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 131    * socket.
 132    * @param[out] buffer The buffer to store the received data on success. It
 133    * must be at least as large as <code>bytes_to_read</code>.
 134    * @param[in] bytes_to_read The number of bytes to read.
 135    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 136    * completion.
 137    *
 138    * @return A non-negative number on success to indicate how many bytes have
 139    * been read, 0 means that end-of-file was reached; otherwise, an error code
 140    * from <code>pp_errors.h</code>.
 141    */
 142   int32_t Read([in] PP_Resource tcp_socket,
 143                [out] str_t buffer,
 144                [in] int32_t bytes_to_read,
 145                [in] PP_CompletionCallback callback);
 146
 147   /**
 148    * Writes data to the socket. The socket must be connected. It may perform a
 149    * partial write.
 150    *
 151    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 152    * socket.
 153    * @param[in] buffer The buffer containing the data to write.
 154    * @param[in] bytes_to_write The number of bytes to write.
 155    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 156    * completion.
 157    *
 158    * @return A non-negative number on success to indicate how many bytes have
 159    * been written; otherwise, an error code from <code>pp_errors.h</code>.
 160    */
 161   int32_t Write([in] PP_Resource tcp_socket,
 162                 [in] str_t buffer,
 163                 [in] int32_t bytes_to_write,
 164                 [in] PP_CompletionCallback callback);
 165
 166   /**
 167    * Cancels all pending reads and writes and disconnects the socket. Any
 168    * pending callbacks will still run, reporting <code>PP_ERROR_ABORTED</code>
 169    * if pending IO was interrupted. After a call to this method, no output
 170    * buffer pointers passed into previous <code>Read()</code> calls will be
 171    * accessed. It is not valid to call <code>Connect()</code> again.
 172    *
 173    * The socket is implicitly closed if it is destroyed, so you are not required
 174    * to call this method.
 175    *
 176    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 177    * socket.
 178    */
 179   void Close([in] PP_Resource tcp_socket);
 180
 181   /**
 182    * Sets a socket option on the TCP socket.
 183    * Please see the <code>PP_TCPSocket_Option</code> description for option
 184    * names, value types and allowed values.
 185    *
 186    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 187    * socket.
 188    * @param[in] name The option to set.
 189    * @param[in] value The option value to set.
 190    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 191    * completion.
 192    *
 193    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 194    */
 195   int32_t SetOption([in] PP_Resource tcp_socket,
 196                     [in] PP_TCPSocket_Option name,
 197                     [in] PP_Var value,
 198                     [in] PP_CompletionCallback callback);
 199 };