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   M29 = 0.2
  14 };
  15
  16 /**
  17  * A string <code>PP_Var</code> which has one of the following values:
  18  * - "tcp"
  19  * - "udp"
  20  */
  21 typedef PP_Var PP_Ext_Socket_SocketType_Dev;
  22
  23 /**
  24  * A dictionary <code>PP_Var</code>.
  25  */
  26 typedef PP_Var PP_Ext_Socket_CreateOptions_Dev;
  27
  28 /**
  29  * A dictionary <code>PP_Var</code> which contains
  30  * - "socketId" : integer <code>PP_Var</code>
  31  * The id of the newly created socket.
  32  */
  33 typedef PP_Var PP_Ext_Socket_CreateInfo_Dev;
  34
  35 /**
  36  * A dictionary <code>PP_Var</code> which contains
  37  * - "resultCode" : integer <code>PP_Var</code>
  38  * - "socketId" : integer or undefined <code>PP_Var</code>
  39  * The id of the accepted socket.
  40  */
  41 typedef PP_Var PP_Ext_Socket_AcceptInfo_Dev;
  42
  43 /**
  44  * A dictionary <code>PP_Var</code> which contains
  45  * - "resultCode" : integer <code>PP_Var</code>
  46  * The resultCode returned from the underlying read() call.
  47  * - "data" : array buffer <code>PP_Var</code>
  48  */
  49 typedef PP_Var PP_Ext_Socket_ReadInfo_Dev;
  50
  51 /**
  52  * A dictionary <code>PP_Var</code> which contains
  53  * - "bytesWritten" : integer <code>PP_Var</code>
  54  * The number of bytes sent, or a negative error code.
  55  */
  56 typedef PP_Var PP_Ext_Socket_WriteInfo_Dev;
  57
  58 /**
  59  * A dictionary <code>PP_Var</code> which contains
  60  * - "resultCode" : integer <code>PP_Var</code>
  61  * The resultCode returned from the underlying recvfrom() call.
  62  * - "data": array buffer <code>PP_Var</code>
  63  * - "address": string <code>PP_Var</code>
  64  * The address of the remote machine.
  65  * - "port": integer <code>PP_Var</code>
  66  */
  67 typedef PP_Var PP_Ext_Socket_RecvFromInfo_Dev;
  68
  69 /**
  70  * A dictionary <code>PP_Var</code> which contains
  71  * - "socketType" : string <code>PP_Var</code> which matches the description of
  72  * <code>PP_Ext_Socket_SocketType_Dev</code>
  73  * The type of the passed socket. This will be <code>tcp</code> or
  74  * <code>udp</code>.
  75  * - "connected" : boolean <code>PP_Var</code>
  76  * Whether or not the underlying socket is connected.
  77  *
  78  * For <code>tcp</code> sockets, this will remain true even if the remote peer
  79  * has disconnected. Reading or writing to the socket may then result in an
  80  * error, hinting that this socket should be disconnected via
  81  * <code>Disconnect()</code>.
  82  *
  83  * For <code>udp</code> sockets, this just represents whether a default remote
  84  * address has been specified for reading and writing packets.
  85  * - "peerAddress" : string or undefined <code>PP_Var</code>
  86  * If the underlying socket is connected, contains the IPv4/6 address of the
  87  * peer.
  88  * - "peerPort" : integer or undefined <code>PP_Var</code>
  89  * If the underlying socket is connected, contains the port of the connected
  90  * peer.
  91  * - "localAddress" : string or undefined <code>PP_Var</code>
  92  * If the underlying socket is bound or connected, contains its local IPv4/6
  93  * address.
  94  * - "localPort" : integer or undefined <code>PP_Var</code>
  95  * If the underlying socket is bound or connected, contains its local port.
  96  */
  97 typedef PP_Var PP_Ext_Socket_SocketInfo_Dev;
  98
  99 /**
 100  * A dictionary <code>PP_Var</code> which contains
 101  * - "name" : string <code>PP_Var</code>
 102  * The underlying name of the adapter. On *nix, this will typically be "eth0",
 103  * "lo", etc.
 104  * - "address": string <code>PP_Var</code>
 105  * The available IPv4/6 address.
 106  */
 107 typedef PP_Var PP_Ext_Socket_NetworkInterface_Dev;
 108
 109 /**
 110  * An array <code>PP_Var</code> which contains elements of
 111  * <code>PP_Ext_Socket_NetworkInterface_Dev</code>.
 112  */
 113 typedef PP_Var PP_Ext_Socket_NetworkInterface_Dev_Array;
 114
 115 interface PPB_Ext_Socket_Dev {
 116   /**
 117    * Creates a socket of the specified type that will connect to the specified
 118    * remote machine.
 119    *
 120    * @param[in] instance A <code>PP_Instance</code>.
 121    * @param[in] type A <code>PP_Ext_Socket_SocketType_Dev</code>. The type of
 122    * socket to create. Must be <code>tcp</code> or <code>udp</code>.
 123    * @param[in] options An undefined <code>PP_Var</code> or
 124    * <code>PP_Ext_Socket_CreateOptions_Dev</code>. The socket options.
 125    * @param[out] create_info A <code>PP_Ext_Socket_CreateInfo_Dev</code>.
 126    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 127    * upon completion.
 128    *
 129    * @return An error code from <code>pp_errors.h</code>.
 130    */
 131   int32_t Create(
 132       [in] PP_Instance instance,
 133       [in] PP_Ext_Socket_SocketType_Dev type,
 134       [in] PP_Ext_Socket_CreateOptions_Dev options,
 135       [out] PP_Ext_Socket_CreateInfo_Dev create_info,
 136       [in] PP_CompletionCallback callback);
 137
 138   /**
 139    * Destroys the socket. Each socket created should be destroyed after use.
 140    *
 141    * @param[in] instance A <code>PP_Instance</code>.
 142    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 143    */
 144   void Destroy(
 145       [in] PP_Instance instance,
 146       [in] PP_Var socket_id);
 147
 148   /**
 149    * Connects the socket to the remote machine (for a <code>tcp</code> socket).
 150    * For a <code>udp</code> socket, this sets the default address which packets
 151    * are sent to and read from for <code>Read()</code> and <code>Write()</code>
 152    * calls.
 153    *
 154    * @param[in] instance A <code>PP_Instance</code>.
 155    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 156    * @param[in] hostname A string <code>PP_Var</code>. The hostname or IP
 157    * address of the remote machine.
 158    * @param[in] port An integer <code>PP_Var</code>. The port of the remote
 159    * machine.
 160    * @param[out] result An integer <code>PP_Var</code>.
 161    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 162    * upon completion.
 163    *
 164    * @return An error code from <code>pp_errors.h</code>.
 165    */
 166   int32_t Connect(
 167       [in] PP_Instance instance,
 168       [in] PP_Var socket_id,
 169       [in] PP_Var hostname,
 170       [in] PP_Var port,
 171       [out] PP_Var result,
 172       [in] PP_CompletionCallback callback);
 173
 174   /**
 175    * Binds the local address for socket. Currently, it does not support TCP
 176    * socket.
 177    *
 178    * @param[in] instance A <code>PP_Instance</code>.
 179    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 180    * @param[in] address A string <code>PP_Var</code>. The address of the local
 181    * machine.
 182    * @param[in] port An integer <code>PP_Var</code>. The port of the local
 183    * machine.
 184    * @param[out] result An integer <code>PP_Var</code>.
 185    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 186    * upon completion.
 187    *
 188    * @return An error code from <code>pp_errors.h</code>.
 189    */
 190   int32_t Bind(
 191       [in] PP_Instance instance,
 192       [in] PP_Var socket_id,
 193       [in] PP_Var address,
 194       [in] PP_Var port,
 195       [out] PP_Var result,
 196       [in] PP_CompletionCallback callback);
 197
 198   /**
 199    * Disconnects the socket. For UDP sockets, <code>Disconnect</code> is a
 200    * non-operation but is safe to call.
 201    *
 202    * @param[in] instance A <code>PP_Instance</code>.
 203    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 204    */
 205   void Disconnect(
 206       [in] PP_Instance instance,
 207       [in] PP_Var socket_id);
 208
 209   /**
 210    * Reads data from the given connected socket.
 211    *
 212    * @param[in] instance A <code>PP_Instance</code>.
 213    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 214    * @param[in] buffer_size An undefined or integer <code>PP_Var</code>. The
 215    * read buffer size.
 216    * @param[out] read_info A <code>PP_Ext_Socket_ReadInfo_Dev</code>.
 217    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 218    * upon completion.
 219    *
 220    * @return An error code from <code>pp_errors.h</code>.
 221    */
 222   int32_t Read(
 223       [in] PP_Instance instance,
 224       [in] PP_Var socket_id,
 225       [in] PP_Var buffer_size,
 226       [out] PP_Ext_Socket_ReadInfo_Dev read_info,
 227       [in] PP_CompletionCallback callback);
 228
 229   /**
 230    * Writes data on the given connected socket.
 231    *
 232    * @param[in] instance A <code>PP_Instance</code>.
 233    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 234    * @param[in] data An array buffer <code>PP_Var</code>. The data to write.
 235    * @param[out] write_info A <code>PP_Ext_Socket_WriteInfo_Dev</code>.
 236    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 237    * upon completion.
 238    *
 239    * @return An error code from <code>pp_errors.h</code>.
 240    */
 241   int32_t Write(
 242       [in] PP_Instance instance,
 243       [in] PP_Var socket_id,
 244       [in] PP_Var data,
 245       [out] PP_Ext_Socket_WriteInfo_Dev write_info,
 246       [in] PP_CompletionCallback callback);
 247
 248   /**
 249    * Receives data from the given UDP socket.
 250    *
 251    * @param[in] instance A <code>PP_Instance</code>.
 252    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 253    * @param[in] buffer_size An undefined or integer <code>PP_Var</code>. The
 254    * receive buffer size.
 255    * @param[out] recv_from_info A <code>PP_Ext_Socket_RecvFromInfo_Dev</code>.
 256    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 257    * upon completion.
 258    *
 259    * @return An error code from <code>pp_errors.h</code>.
 260    */
 261   int32_t RecvFrom(
 262       [in] PP_Instance instance,
 263       [in] PP_Var socket_id,
 264       [in] PP_Var buffer_size,
 265       [out] PP_Ext_Socket_RecvFromInfo_Dev recv_from_info,
 266       [in] PP_CompletionCallback callback);
 267
 268   /**
 269    * Sends data on the given UDP socket to the given address and port.
 270    *
 271    * @param[in] instance A <code>PP_Instance</code>.
 272    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 273    * @param[in] data An array buffer <code>PP_Var</code>.
 274    * @param[in] address A string <code>PP_Var</code>. The address of the remote
 275    * machine.
 276    * @param[in] port An integer <code>PP_Var</code>. The port of the remote
 277    * machine.
 278    * @param[out] write_info A <code>PP_Ext_Socket_WriteInfo_Dev</code>.
 279    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 280    * upon completion.
 281    *
 282    * @return An error code from <code>pp_errors.h</code>.
 283    */
 284   int32_t SendTo(
 285       [in] PP_Instance instance,
 286       [in] PP_Var socket_id,
 287       [in] PP_Var data,
 288       [in] PP_Var address,
 289       [in] PP_Var port,
 290       [out] PP_Ext_Socket_WriteInfo_Dev write_info,
 291       [in] PP_CompletionCallback callback);
 292
 293   /**
 294    * This method applies to TCP sockets only.
 295    * Listens for connections on the specified port and address. This effectively
 296    * makes this a server socket, and client socket functions (Connect, Read,
 297    * Write) can no longer be used on this socket.
 298    *
 299    * @param[in] instance A <code>PP_Instance</code>.
 300    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 301    * @param[in] address A string <code>PP_Var</code>. The address of the local
 302    * machine.
 303    * @param[in] port An integer <code>PP_Var</code>. The port of the local
 304    * machine.
 305    * @param[in] backlog An undefined or integer <code>PP_Var</code>. Length of
 306    * the socket's listen queue.
 307    * @param[out] result An integer <code>PP_Var</code>.
 308    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 309    * upon completion.
 310    *
 311    * @return An error code from <code>pp_errors.h</code>.
 312    */
 313   int32_t Listen(
 314       [in] PP_Instance instance,
 315       [in] PP_Var socket_id,
 316       [in] PP_Var address,
 317       [in] PP_Var port,
 318       [in] PP_Var backlog,
 319       [out] PP_Var result,
 320       [in] PP_CompletionCallback callback);
 321
 322   /**
 323    * This method applies to TCP sockets only.
 324    * Registers a callback function to be called when a connection is accepted on
 325    * this listening server socket. Listen must be called first.
 326    * If there is already an active accept callback, this callback will be
 327    * invoked immediately with an error as the resultCode.
 328    *
 329    * @param[in] instance A <code>PP_Instance</code>.
 330    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 331    * @param[out] accept_info A <code>PP_Ext_Socket_AcceptInfo_Dev</code>.
 332    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 333    * upon completion.
 334    *
 335    * @return An error code from <code>pp_errors.h</code>.
 336    */
 337   int32_t Accept(
 338       [in] PP_Instance instance,
 339       [in] PP_Var socket_id,
 340       [out] PP_Ext_Socket_AcceptInfo_Dev accept_info,
 341       [in] PP_CompletionCallback callback);
 342
 343   /**
 344    * Enables or disables the keep-alive functionality for a TCP connection.
 345    *
 346    * @param[in] instance A <code>PP_Instance</code>.
 347    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 348    * @param[in] enable A boolean <code>PP_Var</code>. If true, enable keep-alive
 349    * functionality.
 350    * @param[in] delay An undefined or integer <code>PP_Var</code>. Set the delay
 351    * seconds between the last data packet received and the first keepalive
 352    * probe. Default is 0.
 353    * @param[out] result A boolean <code>PP_Var</code>.
 354    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 355    * upon completion.
 356    *
 357    * @return An error code from <code>pp_errors.h</code>.
 358    */
 359   int32_t SetKeepAlive(
 360       [in] PP_Instance instance,
 361       [in] PP_Var socket_id,
 362       [in] PP_Var enable,
 363       [in] PP_Var delay,
 364       [out] PP_Var result,
 365       [in] PP_CompletionCallback callback);
 366
 367   /**
 368    * Sets or clears <code>TCP_NODELAY</code> for a TCP connection. Nagle's
 369    * algorithm will be disabled when <code>TCP_NODELAY</code> is set.
 370    *
 371    * @param[in] instance A <code>PP_Instance</code>.
 372    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 373    * @param[in] no_delay A boolean <code>PP_Var</code>.
 374    * @param[out] result A boolean <code>PP_Var</code>.
 375    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 376    * upon completion.
 377    *
 378    * @return An error code from <code>pp_errors.h</code>.
 379    */
 380   int32_t SetNoDelay(
 381       [in] PP_Instance instance,
 382       [in] PP_Var socket_id,
 383       [in] PP_Var no_delay,
 384       [out] PP_Var result,
 385       [in] PP_CompletionCallback callback);
 386
 387   /**
 388    * Retrieves the state of the given socket.
 389    *
 390    * @param[in] instance A <code>PP_Instance</code>.
 391    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 392    * @param[out] result A <code>PP_Ext_Socket_SocketInfo_Dev</code>.
 393    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 394    * upon completion.
 395    *
 396    * @return An error code from <code>pp_errors.h</code>.
 397    */
 398   int32_t GetInfo(
 399       [in] PP_Instance instance,
 400       [in] PP_Var socket_id,
 401       [out] PP_Ext_Socket_SocketInfo_Dev result,
 402       [in] PP_CompletionCallback callback);
 403
 404   /**
 405    * Retrieves information about local adapters on this system.
 406    *
 407    * @param[in] instance A <code>PP_Instance</code>.
 408    * @param[out] result A <code>PP_Ext_Socket_NetworkInterface_Dev_Array</code>.
 409    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 410    * upon completion.
 411    *
 412    * @return An error code from <code>pp_errors.h</code>.
 413    */
 414   int32_t GetNetworkList(
 415       [in] PP_Instance instance,
 416       [out] PP_Ext_Socket_NetworkInterface_Dev_Array result,
 417       [in] PP_CompletionCallback callback);
 418
 419   /**
 420    * Joins the multicast group and starts to receive packets from that group.
 421    * The socket must be of UDP type and must be bound to a local port before
 422    * calling this method.
 423    *
 424    * @param[in] instance A <code>PP_Instance</code>.
 425    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 426    * @param[in] address A string <code>PP_Var</code>. The group address to join.
 427    * Domain names are not supported.
 428    * @param[out] result An integer <code>PP_Var</code>.
 429    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 430    * upon completion.
 431    *
 432    * @return An error code from <code>pp_errors.h</code>.
 433    */
 434   [version=0.2]
 435   int32_t JoinGroup(
 436       [in] PP_Instance instance,
 437       [in] PP_Var socket_id,
 438       [in] PP_Var address,
 439       [out] PP_Var result,
 440       [in] PP_CompletionCallback callback);
 441
 442   /**
 443    * Leaves the multicast group previously joined using <code>JoinGroup</code>.
 444    * It's not necessary to leave the multicast group before destroying the
 445    * socket or exiting. This is automatically called by the OS.
 446    *
 447    * Leaving the group will prevent the router from sending multicast datagrams
 448    * to the local host, presuming no other process on the host is still joined
 449    * to the group.
 450    *
 451    * @param[in] instance A <code>PP_Instance</code>.
 452    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 453    * @param[in] address A string <code>PP_Var</code>. The group address to
 454    * leave. Domain names are not supported.
 455    * @param[out] result An integer <code>PP_Var</code>.
 456    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 457    * upon completion.
 458    *
 459    * @return An error code from <code>pp_errors.h</code>.
 460    */
 461   [version=0.2]
 462   int32_t LeaveGroup(
 463       [in] PP_Instance instance,
 464       [in] PP_Var socket_id,
 465       [in] PP_Var address,
 466       [out] PP_Var result,
 467       [in] PP_CompletionCallback callback);
 468
 469   /**
 470    * Sets the time-to-live of multicast packets sent to the multicast group.
 471    *
 472    * Calling this method does not require multicast permissions.
 473    *
 474    * @param[in] instance A <code>PP_Instance</code>.
 475    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 476    * @param[in] ttl An integer <code>PP_Var</code>. The time-to-live value.
 477    * @param[out] result An integer <code>PP_Var</code>.
 478    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 479    * upon completion.
 480    *
 481    * @return An error code from <code>pp_errors.h</code>.
 482    */
 483   [version=0.2]
 484   int32_t SetMulticastTimeToLive(
 485       [in] PP_Instance instance,
 486       [in] PP_Var socket_id,
 487       [in] PP_Var ttl,
 488       [out] PP_Var result,
 489       [in] PP_CompletionCallback callback);
 490
 491   /**
 492    * Sets whether multicast packets sent from the host to the multicast group
 493    * will be looped back to the host.
 494    *
 495    * Note: the behavior of <code>SetMulticastLoopbackMode</code> is slightly
 496    * different between Windows and Unix-like systems. The inconsistency
 497    * happens only when there is more than one application on the same host
 498    * joined to the same multicast group while having different settings on
 499    * multicast loopback mode. On Windows, the applications with loopback off
 500    * will not RECEIVE the loopback packets; while on Unix-like systems, the
 501    * applications with loopback off will not SEND the loopback packets to
 502    * other applications on the same host. See MSDN: http://goo.gl/6vqbj
 503    *
 504    * Calling this method does not require multicast permissions.
 505    *
 506    * @param[in] instance A <code>PP_Instance</code>.
 507    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 508    * @param[in] enabled A boolean <code>PP_Var</code>. Indicates whether to
 509    * enable loopback mode.
 510    * @param[out] result An integer <code>PP_Var</code>.
 511    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 512    * upon completion.
 513    *
 514    * @return An error code from <code>pp_errors.h</code>.
 515    */
 516   [version=0.2]
 517   int32_t SetMulticastLoopbackMode(
 518       [in] PP_Instance instance,
 519       [in] PP_Var socket_id,
 520       [in] PP_Var enabled,
 521       [out] PP_Var result,
 522       [in] PP_CompletionCallback callback);
 523
 524   /**
 525    * Gets the multicast group addresses the socket is currently joined to.
 526    *
 527    * @param[in] instance A <code>PP_Instance</code>.
 528    * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
 529    * @param[out] groups An array <code>PP_Var</code> of string
 530    * <code>PP_Var</code>s.
 531    * @param[in] callback A <code>PP_CompletionCallback</code> to be called
 532    * upon completion.
 533    *
 534    * @return An error code from <code>pp_errors.h</code>.
 535    */
 536   [version=0.2]
 537   int32_t GetJoinedGroups(
 538       [in] PP_Instance instance,
 539       [in] PP_Var socket_id,
 540       [out] PP_Var groups,
 541       [in] PP_CompletionCallback callback);
 542 };