ppapi/c/ppb_tcp_socket.h

   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 /* From ppb_tcp_socket.idl modified Sat Jun 22 11:17:34 2013. */
   7
   8 #ifndef PPAPI_C_PPB_TCP_SOCKET_H_
   9 #define PPAPI_C_PPB_TCP_SOCKET_H_
  10
  11 #include "ppapi/c/pp_bool.h"
  12 #include "ppapi/c/pp_completion_callback.h"
  13 #include "ppapi/c/pp_instance.h"
  14 #include "ppapi/c/pp_macros.h"
  15 #include "ppapi/c/pp_resource.h"
  16 #include "ppapi/c/pp_stdint.h"
  17 #include "ppapi/c/pp_var.h"
  18
  19 #define PPB_TCPSOCKET_INTERFACE_1_0 "PPB_TCPSocket;1.0"
  20 #define PPB_TCPSOCKET_INTERFACE PPB_TCPSOCKET_INTERFACE_1_0
  21
  22 /**
  23  * @file
  24  * This file defines the <code>PPB_TCPSocket</code> interface.
  25  */
  26
  27
  28 /**
  29  * @addtogroup Enums
  30  * @{
  31  */
  32 /**
  33  * Option names used by <code>SetOption()</code>.
  34  */
  35 typedef enum {
  36   /**
  37    * Disables coalescing of small writes to make TCP segments, and instead
  38    * delivers data immediately. Value's type is <code>PP_VARTYPE_BOOL</code>.
  39    * This option can only be set after a successful <code>Connect()</code> call.
  40    */
  41   PP_TCPSOCKET_OPTION_NO_DELAY = 0,
  42   /**
  43    * Specifies the total per-socket buffer space reserved for sends. Value's
  44    * type should be <code>PP_VARTYPE_INT32</code>.
  45    * This option can only be set after a successful <code>Connect()</code> call.
  46    *
  47    * Note: This is only treated as a hint for the browser to set the buffer
  48    * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
  49    * guarantee it will conform to the size.
  50    */
  51   PP_TCPSOCKET_OPTION_SEND_BUFFER_SIZE = 1,
  52   /**
  53    * Specifies the total per-socket buffer space reserved for receives. Value's
  54    * type should be <code>PP_VARTYPE_INT32</code>.
  55    * This option can only be set after a successful <code>Connect()</code> call.
  56    *
  57    * Note: This is only treated as a hint for the browser to set the buffer
  58    * size. Even if <code>SetOption()</code> succeeds, the browser doesn't
  59    * guarantee it will conform to the size.
  60    */
  61   PP_TCPSOCKET_OPTION_RECV_BUFFER_SIZE = 2
  62 } PP_TCPSocket_Option;
  63 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_TCPSocket_Option, 4);
  64 /**
  65  * @}
  66  */
  67
  68 /**
  69  * @addtogroup Interfaces
  70  * @{
  71  */
  72 /**
  73  * The <code>PPB_TCPSocket</code> interface provides TCP socket operations.
  74  *
  75  * Permissions: Apps permission <code>socket</code> with subrule
  76  * <code>tcp-connect</code> is required for <code>Connect()</code>.
  77  * For more details about network communication permissions, please see:
  78  * http://developer.chrome.com/apps/app_network.html
  79  */
  80 struct PPB_TCPSocket_1_0 {
  81   /**
  82    * Creates a TCP socket resource.
  83    *
  84    * @param[in] instance A <code>PP_Instance</code> identifying one instance of
  85    * a module.
  86    *
  87    * @return A <code>PP_Resource</code> corresponding to a TCP socket or 0
  88    * on failure.
  89    */
  90   PP_Resource (*Create)(PP_Instance instance);
  91   /**
  92    * Determines if a given resource is a TCP socket.
  93    *
  94    * @param[in] resource A <code>PP_Resource</code> to check.
  95    *
  96    * @return <code>PP_TRUE</code> if the input is a
  97    * <code>PPB_TCPSocket</code> resource; <code>PP_FALSE</code> otherwise.
  98    */
  99   PP_Bool (*IsTCPSocket)(PP_Resource resource);
 100   /**
 101    * Connects the socket to the given address.
 102    *
 103    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 104    * socket.
 105    * @param[in] addr A <code>PPB_NetAddress</code> resource.
 106    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 107    * completion.
 108    *
 109    * @return An int32_t containing an error code from <code>pp_errors.h</code>,
 110    * including (but not limited to):
 111    * - <code>PP_ERROR_NOACCESS</code>: the caller doesn't have required
 112    *   permissions.
 113    * - <code>PP_ERROR_ADDRESS_UNREACHABLE</code>: <code>addr</code> is
 114    *   unreachable.
 115    * - <code>PP_ERROR_CONNECTION_REFUSED</code>: the connection attempt was
 116    *   refused.
 117    * - <code>PP_ERROR_CONNECTION_FAILED</code>: the connection attempt failed.
 118    * - <code>PP_ERROR_CONNECTION_TIMEDOUT</code>: the connection attempt timed
 119    *   out.
 120    */
 121   int32_t (*Connect)(PP_Resource tcp_socket,
 122                      PP_Resource addr,
 123                      struct PP_CompletionCallback callback);
 124   /**
 125    * Gets the local address of the socket, if it is connected.
 126    *
 127    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 128    * socket.
 129    *
 130    * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure.
 131    */
 132   PP_Resource (*GetLocalAddress)(PP_Resource tcp_socket);
 133   /**
 134    * Gets the remote address of the socket, if it is connected.
 135    *
 136    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 137    * socket.
 138    *
 139    * @return A <code>PPB_NetAddress</code> resource on success or 0 on failure.
 140    */
 141   PP_Resource (*GetRemoteAddress)(PP_Resource tcp_socket);
 142   /**
 143    * Reads data from the socket. The socket must be connected. It may perform a
 144    * partial read.
 145    *
 146    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 147    * socket.
 148    * @param[out] buffer The buffer to store the received data on success. It
 149    * must be at least as large as <code>bytes_to_read</code>.
 150    * @param[in] bytes_to_read The number of bytes to read.
 151    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 152    * completion.
 153    *
 154    * @return A non-negative number on success to indicate how many bytes have
 155    * been read, 0 means that end-of-file was reached; otherwise, an error code
 156    * from <code>pp_errors.h</code>.
 157    */
 158   int32_t (*Read)(PP_Resource tcp_socket,
 159                   char* buffer,
 160                   int32_t bytes_to_read,
 161                   struct PP_CompletionCallback callback);
 162   /**
 163    * Writes data to the socket. The socket must be connected. It may perform a
 164    * partial write.
 165    *
 166    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 167    * socket.
 168    * @param[in] buffer The buffer containing the data to write.
 169    * @param[in] bytes_to_write The number of bytes to write.
 170    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 171    * completion.
 172    *
 173    * @return A non-negative number on success to indicate how many bytes have
 174    * been written; otherwise, an error code from <code>pp_errors.h</code>.
 175    */
 176   int32_t (*Write)(PP_Resource tcp_socket,
 177                    const char* buffer,
 178                    int32_t bytes_to_write,
 179                    struct PP_CompletionCallback callback);
 180   /**
 181    * Cancels all pending reads and writes and disconnects the socket. Any
 182    * pending callbacks will still run, reporting <code>PP_ERROR_ABORTED</code>
 183    * if pending IO was interrupted. After a call to this method, no output
 184    * buffer pointers passed into previous <code>Read()</code> calls will be
 185    * accessed. It is not valid to call <code>Connect()</code> again.
 186    *
 187    * The socket is implicitly closed if it is destroyed, so you are not required
 188    * to call this method.
 189    *
 190    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 191    * socket.
 192    */
 193   void (*Close)(PP_Resource tcp_socket);
 194   /**
 195    * Sets a socket option on the TCP socket.
 196    * Please see the <code>PP_TCPSocket_Option</code> description for option
 197    * names, value types and allowed values.
 198    *
 199    * @param[in] tcp_socket A <code>PP_Resource</code> corresponding to a TCP
 200    * socket.
 201    * @param[in] name The option to set.
 202    * @param[in] value The option value to set.
 203    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 204    * completion.
 205    *
 206    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 207    */
 208   int32_t (*SetOption)(PP_Resource tcp_socket,
 209                        PP_TCPSocket_Option name,
 210                        struct PP_Var value,
 211                        struct PP_CompletionCallback callback);
 212 };
 213
 214 typedef struct PPB_TCPSocket_1_0 PPB_TCPSocket;
 215 /**
 216  * @}
 217  */
 218
 219 #endif  /* PPAPI_C_PPB_TCP_SOCKET_H_ */
 220