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