ppapi/api/extensions/dev/ppb_ext_socket_dev.idl

   1 /* Copyright (c) 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 Pepper equivalent of the <code>chrome.socket</code>
   8  * extension API.
   9  */
  10
  11 label Chrome {
  12   M28 = 0.1
  13 };
  14
  15 /**
  16  * A string <code>PP_Var</code> which has one of the following values:
  17  * - "tcp"
  18  * - "udp"
  19  */
  20 typedef PP_Var PP_Ext_Socket_SocketType_Dev;
  21
  22 /**
  23  * A dictionary <code>PP_Var</code>.
  24  */
  25 typedef PP_Var PP_Ext_Socket_CreateOptions_Dev;
  26
  27 /**
  28  * A dictionary <code>PP_Var</code> which contains
  29  * - "socketId" : integer <code>PP_Var</code>
  30  * The id of the newly created socket.
  31  */
  32 typedef PP_Var PP_Ext_Socket_CreateInfo_Dev;
  33
  34 /**
  35  * A dictionary <code>PP_Var</code> which contains
  36  * - "resultCode" : integer <code>PP_Var</code>
  37  * - "socketId" : integer or undefined <code>PP_Var</code>
  38  * The id of the accepted socket.
  39  */
  40 typedef PP_Var PP_Ext_Socket_AcceptInfo_Dev;
  41
  42 /**
  43  * A dictionary <code>PP_Var</code> which contains
  44  * - "resultCode" : integer <code>PP_Var</code>
  45  * The resultCode returned from the underlying read() call.
  46  * - "data" : array buffer <code>PP_Var</code>
  47  */
  48 typedef PP_Var PP_Ext_Socket_ReadInfo_Dev;
  49
  50 /**
  51  * A dictionary <code>PP_Var</code> which contains
  52  * - "bytesWritten" : integer <code>PP_Var</code>
  53  * The number of bytes sent, or a negative error code.
  54  */
  55 typedef PP_Var PP_Ext_Socket_WriteInfo_Dev;
  56
  57 /**
  58  * A dictionary <code>PP_Var</code> which contains
  59  * - "resultCode" : integer <code>PP_Var</code>
  60  * The resultCode returned from the underlying recvfrom() call.
  61  * - "data": array buffer <code>PP_Var</code>
  62  * - "address": string <code>PP_Var</code>
  63  * The address of the remote machine.
  64  * - "port": integer <code>PP_Var</code>
  65  */
  66 typedef PP_Var PP_Ext_Socket_RecvFromInfo_Dev;
  67
  68 /**
  69  * A dictionary <code>PP_Var</code> which contains
  70  * - "socketType" : string <code>PP_Var</code> which matches the description of
  71  * <code>PP_Ext_Socket_SocketType_Dev</code>
  72  * The type of the passed socket. This will be <code>tcp</code> or
  73  * <code>udp</code>.
  74  * - "connected" : boolean <code>PP_Var</code>
  75  * Whether or not the underlying socket is connected.
  76  *
  77  * For <code>tcp</code> sockets, this will remain true even if the remote peer
  78  * has disconnected. Reading or writing to the socket may then result in an
  79  * error, hinting that this socket should be disconnected via
  80  * <code>Disconnect()</code>.
  81  *
  82  * For <code>udp</code> sockets, this just represents whether a default remote
  83  * address has been specified for reading and writing packets.
  84  * - "peerAddress" : string or undefined <code>PP_Var</code>
  85  * If the underlying socket is connected, contains the IPv4/6 address of the
  86  * peer.
  87  * - "peerPort" : integer or undefined <code>PP_Var</code>
  88  * If the underlying socket is connected, contains the port of the connected
  89  * peer.
  90  * - "localAddress" : string or undefined <code>PP_Var</code>
  91  * If the underlying socket is bound or connected, contains its local IPv4/6
  92  * address.
  93  * - "localPort" : integer or undefined <code>PP_Var</code>
  94  * If the underlying socket is bound or connected, contains its local port.
  95  */
  96 typedef PP_Var PP_Ext_Socket_SocketInfo_Dev;
  97
  98 /**
  99  * A dictionary <code>PP_Var</code> which contains
 100  * - "name" : string <code>PP_Var</code>
 101  * The underlying name of the adapter. On *nix, this will typically be "eth0",
 102  * "lo", etc.
 103  * - "address": string <code>PP_Var</code>
 104  * The available IPv4/6 address.
 105  */
 106 typedef PP_Var PP_Ext_Socket_NetworkInterface_Dev;
 107
 108 /**
 109  * An array <code>PP_Var</code> which contains elements of
 110  * <code>PP_Ext_Socket_NetworkInterface_Dev</code>.
 111  */
 112 typedef PP_Var PP_Ext_Socket_NetworkInterface_Dev_Array;
 113
 114 interface PPB_Ext_Socket_Dev {
 115   /**
 116    * Creates a socket of the specified type that will connect to the specified
 117    * remote machine.
 118    *
 119    * @param[in] instance A <code>PP_Instance</code>.
 120    * @param[in] type A <code>PP_Ext_Socket_SocketType_Dev</code>. The type of
 121    * socket to create. Must be <code>tcp</code> or <code>udp</code>.
 122    * @param[in] options An undefined <code>PP_Var</code> or
 123    * <code>PP_Ext_Socket_CreateOptions_Dev</code>. The socket options.
 124    * @param[out] create_info A <code>PP_Ext_Socket_CreateInfo_Dev</code>.
 125    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 126    * upon completion.
 127    *
 128    * @return An error code from <code>pp_errors.h</code>.
 129    */
 130   int32_t Create(
 131       [in] PP_Instance instance,
 132       [in] PP_Ext_Socket_SocketType_Dev type,
 133       [in] PP_Ext_Socket_CreateOptions_Dev options,
 134       [out] PP_Ext_Socket_CreateInfo_Dev create_info,
 135       [in] PP_CompletionCallback callback);
 136
 137   /**
 138    * Destroys the socket. Each socket created should be destroyed after use.
 139    *
 140    * @param[in] instance A <code>PP_Instance</code>.
 141    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 142    */
 143   void Destroy(
 144       [in] PP_Instance instance,
 145       [in] PP_Var socket_id);
 146
 147   /**
 148    * Connects the socket to the remote machine (for a <code>tcp</code> socket).
 149    * For a <code>udp</code> socket, this sets the default address which packets
 150    * are sent to and read from for <code>Read()</code> and <code>Write()</code>
 151    * calls.
 152    *
 153    * @param[in] instance A <code>PP_Instance</code>.
 154    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 155    * @param[in] hostname A string <code>PP_Var</code>. The hostname or IP
 156    * address of the remote machine.
 157    * @param[in] port An integer <code>PP_Var</code>. The port of the remote
 158    * machine.
 159    * @param[out] result An integer <code>PP_Var</code>.
 160    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 161    * upon completion.
 162    *
 163    * @return An error code from <code>pp_errors.h</code>.
 164    */
 165   int32_t Connect(
 166       [in] PP_Instance instance,
 167       [in] PP_Var socket_id,
 168       [in] PP_Var hostname,
 169       [in] PP_Var port,
 170       [out] PP_Var result,
 171       [in] PP_CompletionCallback callback);
 172
 173   /**
 174    * Binds the local address for socket. Currently, it does not support TCP
 175    * socket.
 176    *
 177    * @param[in] instance A <code>PP_Instance</code>.
 178    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 179    * @param[in] address A string <code>PP_Var</code>. The address of the local
 180    * machine.
 181    * @param[in] port An integer <code>PP_Var</code>. The port of the local
 182    * machine.
 183    * @param[out] result An integer <code>PP_Var</code>.
 184    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 185    * upon completion.
 186    *
 187    * @return An error code from <code>pp_errors.h</code>.
 188    */
 189   int32_t Bind(
 190       [in] PP_Instance instance,
 191       [in] PP_Var socket_id,
 192       [in] PP_Var address,
 193       [in] PP_Var port,
 194       [out] PP_Var result,
 195       [in] PP_CompletionCallback callback);
 196
 197   /**
 198    * Disconnects the socket. For UDP sockets, <code>Disconnect</code> is a
 199    * non-operation but is safe to call.
 200    *
 201    * @param[in] instance A <code>PP_Instance</code>.
 202    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 203    */
 204   void Disconnect(
 205       [in] PP_Instance instance,
 206       [in] PP_Var socket_id);
 207
 208   /**
 209    * Reads data from the given connected socket.
 210    *
 211    * @param[in] instance A <code>PP_Instance</code>.
 212    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 213    * @param[in] buffer_size An undefined or integer <code>PP_Var</code>. The
 214    * read buffer size.
 215    * @param[out] read_info A <code>PP_Ext_Socket_ReadInfo_Dev</code>.
 216    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 217    * upon completion.
 218    *
 219    * @return An error code from <code>pp_errors.h</code>.
 220    */
 221   int32_t Read(
 222       [in] PP_Instance instance,
 223       [in] PP_Var socket_id,
 224       [in] PP_Var buffer_size,
 225       [out] PP_Ext_Socket_ReadInfo_Dev read_info,
 226       [in] PP_CompletionCallback callback);
 227
 228   /**
 229    * Writes data on the given connected socket.
 230    *
 231    * @param[in] instance A <code>PP_Instance</code>.
 232    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 233    * @param[in] data An array buffer <code>PP_Var</code>. The data to write.
 234    * @param[out] write_info A <code>PP_Ext_Socket_WriteInfo_Dev</code>.
 235    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 236    * upon completion.
 237    *
 238    * @return An error code from <code>pp_errors.h</code>.
 239    */
 240   int32_t Write(
 241       [in] PP_Instance instance,
 242       [in] PP_Var socket_id,
 243       [in] PP_Var data,
 244       [out] PP_Ext_Socket_WriteInfo_Dev write_info,
 245       [in] PP_CompletionCallback callback);
 246
 247   /**
 248    * Receives data from the given UDP socket.
 249    *
 250    * @param[in] instance A <code>PP_Instance</code>.
 251    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 252    * @param[in] buffer_size An undefined or integer <code>PP_Var</code>. The
 253    * receive buffer size.
 254    * @param[out] recv_from_info A <code>PP_Ext_Socket_RecvFromInfo_Dev</code>.
 255    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 256    * upon completion.
 257    *
 258    * @return An error code from <code>pp_errors.h</code>.
 259    */
 260   int32_t RecvFrom(
 261       [in] PP_Instance instance,
 262       [in] PP_Var socket_id,
 263       [in] PP_Var buffer_size,
 264       [out] PP_Ext_Socket_RecvFromInfo_Dev recv_from_info,
 265       [in] PP_CompletionCallback callback);
 266
 267   /**
 268    * Sends data on the given UDP socket to the given address and port.
 269    *
 270    * @param[in] instance A <code>PP_Instance</code>.
 271    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 272    * @param[in] data An array buffer <code>PP_Var</code>.
 273    * @param[in] address A string <code>PP_Var</code>. The address of the remote
 274    * machine.
 275    * @param[in] port An integer <code>PP_Var</code>. The port of the remote
 276    * machine.
 277    * @param[out] write_info A <code>PP_Ext_Socket_WriteInfo_Dev</code>.
 278    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 279    * upon completion.
 280    *
 281    * @return An error code from <code>pp_errors.h</code>.
 282    */
 283   int32_t SendTo(
 284       [in] PP_Instance instance,
 285       [in] PP_Var socket_id,
 286       [in] PP_Var data,
 287       [in] PP_Var address,
 288       [in] PP_Var port,
 289       [out] PP_Ext_Socket_WriteInfo_Dev write_info,
 290       [in] PP_CompletionCallback callback);
 291
 292   /**
 293    * This method applies to TCP sockets only.
 294    * Listens for connections on the specified port and address. This effectively
 295    * makes this a server socket, and client socket functions (Connect, Read,
 296    * Write) can no longer be used on this socket.
 297    *
 298    * @param[in] instance A <code>PP_Instance</code>.
 299    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 300    * @param[in] address A string <code>PP_Var</code>. The address of the local
 301    * machine.
 302    * @param[in] port An integer <code>PP_Var</code>. The port of the local
 303    * machine.
 304    * @param[in] backlog An undefined or integer <code>PP_Var</code>. Length of
 305    * the socket's listen queue.
 306    * @param[out] result An integer <code>PP_Var</code>.
 307    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 308    * upon completion.
 309    *
 310    * @return An error code from <code>pp_errors.h</code>.
 311    */
 312   int32_t Listen(
 313       [in] PP_Instance instance,
 314       [in] PP_Var socket_id,
 315       [in] PP_Var address,
 316       [in] PP_Var port,
 317       [in] PP_Var backlog,
 318       [out] PP_Var result,
 319       [in] PP_CompletionCallback callback);
 320
 321   /**
 322    * This method applies to TCP sockets only.
 323    * Registers a callback function to be called when a connection is accepted on
 324    * this listening server socket. Listen must be called first.
 325    * If there is already an active accept callback, this callback will be
 326    * invoked immediately with an error as the resultCode.
 327    *
 328    * @param[in] instance A <code>PP_Instance</code>.
 329    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 330    * @param[out] accept_info A <code>PP_Ext_Socket_AcceptInfo_Dev</code>.
 331    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 332    * upon completion.
 333    *
 334    * @return An error code from <code>pp_errors.h</code>.
 335    */
 336   int32_t Accept(
 337       [in] PP_Instance instance,
 338       [in] PP_Var socket_id,
 339       [out] PP_Ext_Socket_AcceptInfo_Dev accept_info,
 340       [in] PP_CompletionCallback callback);
 341
 342   /**
 343    * Enables or disables the keep-alive functionality for a TCP connection.
 344    *
 345    * @param[in] instance A <code>PP_Instance</code>.
 346    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 347    * @param[in] enable A boolean <code>PP_Var</code>. If true, enable keep-alive
 348    * functionality.
 349    * @param[in] delay An undefined or integer <code>PP_Var</code>. Set the delay
 350    * seconds between the last data packet received and the first keepalive
 351    * probe. Default is 0.
 352    * @param[out] result A boolean <code>PP_Var</code>.
 353    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 354    * upon completion.
 355    *
 356    * @return An error code from <code>pp_errors.h</code>.
 357    */
 358   int32_t SetKeepAlive(
 359       [in] PP_Instance instance,
 360       [in] PP_Var socket_id,
 361       [in] PP_Var enable,
 362       [in] PP_Var delay,
 363       [out] PP_Var result,
 364       [in] PP_CompletionCallback callback);
 365
 366   /**
 367    * Sets or clears <code>TCP_NODELAY</code> for a TCP connection. Nagle's
 368    * algorithm will be disabled when <code>TCP_NODELAY</code> is set.
 369    *
 370    * @param[in] instance A <code>PP_Instance</code>.
 371    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 372    * @param[in] no_delay A boolean <code>PP_Var</code>.
 373    * @param[out] result A boolean <code>PP_Var</code>.
 374    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 375    * upon completion.
 376    *
 377    * @return An error code from <code>pp_errors.h</code>.
 378    */
 379   int32_t SetNoDelay(
 380       [in] PP_Instance instance,
 381       [in] PP_Var socket_id,
 382       [in] PP_Var no_delay,
 383       [out] PP_Var result,
 384       [in] PP_CompletionCallback callback);
 385
 386   /**
 387    * Retrieves the state of the given socket.
 388    *
 389    * @param[in] instance A <code>PP_Instance</code>.
 390    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 391    * @param[out] result A <code>PP_Ext_Socket_SocketInfo_Dev</code>.
 392    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 393    * upon completion.
 394    *
 395    * @return An error code from <code>pp_errors.h</code>.
 396    */
 397   int32_t GetInfo(
 398       [in] PP_Instance instance,
 399       [in] PP_Var socket_id,
 400       [out] PP_Ext_Socket_SocketInfo_Dev result,
 401       [in] PP_CompletionCallback callback);
 402
 403   /**
 404    * Retrieves information about local adapters on this system.
 405    *
 406    * @param[in] instance A <code>PP_Instance</code>.
 407    * @param[out] result A <code>PP_Ext_Socket_NetworkInterface_Dev_Array</code>.
 408    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 409    * upon completion.
 410    *
 411    * @return An error code from <code>pp_errors.h</code>.
 412    */
 413   int32_t GetNetworkList(
 414       [in] PP_Instance instance,
 415       [out] PP_Ext_Socket_NetworkInterface_Dev_Array result,
 416       [in] PP_CompletionCallback callback);
 417 };