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