path: root/chromium/ppapi/api/extensions/dev/ppb_ext_socket_dev.idl

/* Copyright (c) 2013 The Chromium Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 */

/**
 * This file defines the Pepper equivalent of the <code>chrome.socket</code>
 * extension API.
 */

label Chrome {
  M28 = 0.1,
  M29 = 0.2
};

/**
 * A string <code>PP_Var</code> which has one of the following values:
 * - "tcp"
 * - "udp"
 */
typedef PP_Var PP_Ext_Socket_SocketType_Dev;

/**
 * A dictionary <code>PP_Var</code>.
 */
typedef PP_Var PP_Ext_Socket_CreateOptions_Dev;

/**
 * A dictionary <code>PP_Var</code> which contains
 * - "socketId" : integer <code>PP_Var</code>
 * The id of the newly created socket.
 */
typedef PP_Var PP_Ext_Socket_CreateInfo_Dev;

/**
 * A dictionary <code>PP_Var</code> which contains
 * - "resultCode" : integer <code>PP_Var</code>
 * - "socketId" : integer or undefined <code>PP_Var</code>
 * The id of the accepted socket.
 */
typedef PP_Var PP_Ext_Socket_AcceptInfo_Dev;

/**
 * A dictionary <code>PP_Var</code> which contains
 * - "resultCode" : integer <code>PP_Var</code>
 * The resultCode returned from the underlying read() call.
 * - "data" : array buffer <code>PP_Var</code>
 */
typedef PP_Var PP_Ext_Socket_ReadInfo_Dev;

/**
 * A dictionary <code>PP_Var</code> which contains
 * - "bytesWritten" : integer <code>PP_Var</code>
 * The number of bytes sent, or a negative error code.
 */
typedef PP_Var PP_Ext_Socket_WriteInfo_Dev;

/**
 * A dictionary <code>PP_Var</code> which contains
 * - "resultCode" : integer <code>PP_Var</code>
 * The resultCode returned from the underlying recvfrom() call.
 * - "data": array buffer <code>PP_Var</code>
 * - "address": string <code>PP_Var</code>
 * The address of the remote machine.
 * - "port": integer <code>PP_Var</code>
 */
typedef PP_Var PP_Ext_Socket_RecvFromInfo_Dev;

/**
 * A dictionary <code>PP_Var</code> which contains
 * - "socketType" : string <code>PP_Var</code> which matches the description of
 * <code>PP_Ext_Socket_SocketType_Dev</code>
 * The type of the passed socket. This will be <code>tcp</code> or
 * <code>udp</code>.
 * - "connected" : boolean <code>PP_Var</code>
 * Whether or not the underlying socket is connected.
 *
 * For <code>tcp</code> sockets, this will remain true even if the remote peer
 * has disconnected. Reading or writing to the socket may then result in an
 * error, hinting that this socket should be disconnected via
 * <code>Disconnect()</code>.
 *
 * For <code>udp</code> sockets, this just represents whether a default remote
 * address has been specified for reading and writing packets.
 * - "peerAddress" : string or undefined <code>PP_Var</code>
 * If the underlying socket is connected, contains the IPv4/6 address of the
 * peer.
 * - "peerPort" : integer or undefined <code>PP_Var</code>
 * If the underlying socket is connected, contains the port of the connected
 * peer.
 * - "localAddress" : string or undefined <code>PP_Var</code>
 * If the underlying socket is bound or connected, contains its local IPv4/6
 * address.
 * - "localPort" : integer or undefined <code>PP_Var</code>
 * If the underlying socket is bound or connected, contains its local port.
 */
typedef PP_Var PP_Ext_Socket_SocketInfo_Dev;

/**
 * A dictionary <code>PP_Var</code> which contains
 * - "name" : string <code>PP_Var</code>
 * The underlying name of the adapter. On *nix, this will typically be "eth0",
 * "lo", etc.
 * - "address": string <code>PP_Var</code>
 * The available IPv4/6 address.
 */
typedef PP_Var PP_Ext_Socket_NetworkInterface_Dev;

/**
 * An array <code>PP_Var</code> which contains elements of
 * <code>PP_Ext_Socket_NetworkInterface_Dev</code>.
 */
typedef PP_Var PP_Ext_Socket_NetworkInterface_Dev_Array;

interface PPB_Ext_Socket_Dev {
  /**
   * Creates a socket of the specified type that will connect to the specified
   * remote machine.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] type A <code>PP_Ext_Socket_SocketType_Dev</code>. The type of
   * socket to create. Must be <code>tcp</code> or <code>udp</code>.
   * @param[in] options An undefined <code>PP_Var</code> or
   * <code>PP_Ext_Socket_CreateOptions_Dev</code>. The socket options.
   * @param[out] create_info A <code>PP_Ext_Socket_CreateInfo_Dev</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  int32_t Create(
      [in] PP_Instance instance,
      [in] PP_Ext_Socket_SocketType_Dev type,
      [in] PP_Ext_Socket_CreateOptions_Dev options,
      [out] PP_Ext_Socket_CreateInfo_Dev create_info,
      [in] PP_CompletionCallback callback);

  /**
   * Destroys the socket. Each socket created should be destroyed after use.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   */
  void Destroy(
      [in] PP_Instance instance,
      [in] PP_Var socket_id);

  /**
   * Connects the socket to the remote machine (for a <code>tcp</code> socket).
   * For a <code>udp</code> socket, this sets the default address which packets
   * are sent to and read from for <code>Read()</code> and <code>Write()</code>
   * calls.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   * @param[in] hostname A string <code>PP_Var</code>. The hostname or IP
   * address of the remote machine.
   * @param[in] port An integer <code>PP_Var</code>. The port of the remote
   * machine.
   * @param[out] result An integer <code>PP_Var</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  int32_t Connect(
      [in] PP_Instance instance,
      [in] PP_Var socket_id,
      [in] PP_Var hostname,
      [in] PP_Var port,
      [out] PP_Var result,
      [in] PP_CompletionCallback callback);

  /**
   * Binds the local address for socket. Currently, it does not support TCP
   * socket.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   * @param[in] address A string <code>PP_Var</code>. The address of the local
   * machine.
   * @param[in] port An integer <code>PP_Var</code>. The port of the local
   * machine.
   * @param[out] result An integer <code>PP_Var</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  int32_t Bind(
      [in] PP_Instance instance,
      [in] PP_Var socket_id,
      [in] PP_Var address,
      [in] PP_Var port,
      [out] PP_Var result,
      [in] PP_CompletionCallback callback);

  /**
   * Disconnects the socket. For UDP sockets, <code>Disconnect</code> is a
   * non-operation but is safe to call.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   */
  void Disconnect(
      [in] PP_Instance instance,
      [in] PP_Var socket_id);

  /**
   * Reads data from the given connected socket.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   * @param[in] buffer_size An undefined or integer <code>PP_Var</code>. The
   * read buffer size.
   * @param[out] read_info A <code>PP_Ext_Socket_ReadInfo_Dev</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  int32_t Read(
      [in] PP_Instance instance,
      [in] PP_Var socket_id,
      [in] PP_Var buffer_size,
      [out] PP_Ext_Socket_ReadInfo_Dev read_info,
      [in] PP_CompletionCallback callback);

  /**
   * Writes data on the given connected socket.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   * @param[in] data An array buffer <code>PP_Var</code>. The data to write.
   * @param[out] write_info A <code>PP_Ext_Socket_WriteInfo_Dev</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  int32_t Write(
      [in] PP_Instance instance,
      [in] PP_Var socket_id,
      [in] PP_Var data,
      [out] PP_Ext_Socket_WriteInfo_Dev write_info,
      [in] PP_CompletionCallback callback);

  /**
   * Receives data from the given UDP socket.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   * @param[in] buffer_size An undefined or integer <code>PP_Var</code>. The
   * receive buffer size.
   * @param[out] recv_from_info A <code>PP_Ext_Socket_RecvFromInfo_Dev</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  int32_t RecvFrom(
      [in] PP_Instance instance,
      [in] PP_Var socket_id,
      [in] PP_Var buffer_size,
      [out] PP_Ext_Socket_RecvFromInfo_Dev recv_from_info,
      [in] PP_CompletionCallback callback);

  /**
   * Sends data on the given UDP socket to the given address and port.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   * @param[in] data An array buffer <code>PP_Var</code>.
   * @param[in] address A string <code>PP_Var</code>. The address of the remote
   * machine.
   * @param[in] port An integer <code>PP_Var</code>. The port of the remote
   * machine.
   * @param[out] write_info A <code>PP_Ext_Socket_WriteInfo_Dev</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  int32_t SendTo(
      [in] PP_Instance instance,
      [in] PP_Var socket_id,
      [in] PP_Var data,
      [in] PP_Var address,
      [in] PP_Var port,
      [out] PP_Ext_Socket_WriteInfo_Dev write_info,
      [in] PP_CompletionCallback callback);

  /**
   * This method applies to TCP sockets only.
   * Listens for connections on the specified port and address. This effectively
   * makes this a server socket, and client socket functions (Connect, Read,
   * Write) can no longer be used on this socket.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   * @param[in] address A string <code>PP_Var</code>. The address of the local
   * machine.
   * @param[in] port An integer <code>PP_Var</code>. The port of the local
   * machine.
   * @param[in] backlog An undefined or integer <code>PP_Var</code>. Length of
   * the socket's listen queue.
   * @param[out] result An integer <code>PP_Var</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  int32_t Listen(
      [in] PP_Instance instance,
      [in] PP_Var socket_id,
      [in] PP_Var address,
      [in] PP_Var port,
      [in] PP_Var backlog,
      [out] PP_Var result,
      [in] PP_CompletionCallback callback);

  /**
   * This method applies to TCP sockets only.
   * Registers a callback function to be called when a connection is accepted on
   * this listening server socket. Listen must be called first.
   * If there is already an active accept callback, this callback will be
   * invoked immediately with an error as the resultCode.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   * @param[out] accept_info A <code>PP_Ext_Socket_AcceptInfo_Dev</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  int32_t Accept(
      [in] PP_Instance instance,
      [in] PP_Var socket_id,
      [out] PP_Ext_Socket_AcceptInfo_Dev accept_info,
      [in] PP_CompletionCallback callback);

  /**
   * Enables or disables the keep-alive functionality for a TCP connection.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   * @param[in] enable A boolean <code>PP_Var</code>. If true, enable keep-alive
   * functionality.
   * @param[in] delay An undefined or integer <code>PP_Var</code>. Set the delay
   * seconds between the last data packet received and the first keepalive
   * probe. Default is 0.
   * @param[out] result A boolean <code>PP_Var</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  int32_t SetKeepAlive(
      [in] PP_Instance instance,
      [in] PP_Var socket_id,
      [in] PP_Var enable,
      [in] PP_Var delay,
      [out] PP_Var result,
      [in] PP_CompletionCallback callback);

  /**
   * Sets or clears <code>TCP_NODELAY</code> for a TCP connection. Nagle's
   * algorithm will be disabled when <code>TCP_NODELAY</code> is set.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   * @param[in] no_delay A boolean <code>PP_Var</code>.
   * @param[out] result A boolean <code>PP_Var</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  int32_t SetNoDelay(
      [in] PP_Instance instance,
      [in] PP_Var socket_id,
      [in] PP_Var no_delay,
      [out] PP_Var result,
      [in] PP_CompletionCallback callback);

  /**
   * Retrieves the state of the given socket.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   * @param[out] result A <code>PP_Ext_Socket_SocketInfo_Dev</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  int32_t GetInfo(
      [in] PP_Instance instance,
      [in] PP_Var socket_id,
      [out] PP_Ext_Socket_SocketInfo_Dev result,
      [in] PP_CompletionCallback callback);

  /**
   * Retrieves information about local adapters on this system.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[out] result A <code>PP_Ext_Socket_NetworkInterface_Dev_Array</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  int32_t GetNetworkList(
      [in] PP_Instance instance,
      [out] PP_Ext_Socket_NetworkInterface_Dev_Array result,
      [in] PP_CompletionCallback callback);

  /**
   * Joins the multicast group and starts to receive packets from that group.
   * The socket must be of UDP type and must be bound to a local port before
   * calling this method.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   * @param[in] address A string <code>PP_Var</code>. The group address to join.
   * Domain names are not supported.
   * @param[out] result An integer <code>PP_Var</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  [version=0.2]
  int32_t JoinGroup(
      [in] PP_Instance instance,
      [in] PP_Var socket_id,
      [in] PP_Var address,
      [out] PP_Var result,
      [in] PP_CompletionCallback callback);

  /**
   * Leaves the multicast group previously joined using <code>JoinGroup</code>.
   * It's not necessary to leave the multicast group before destroying the
   * socket or exiting. This is automatically called by the OS.
   *
   * Leaving the group will prevent the router from sending multicast datagrams
   * to the local host, presuming no other process on the host is still joined
   * to the group.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   * @param[in] address A string <code>PP_Var</code>. The group address to
   * leave. Domain names are not supported.
   * @param[out] result An integer <code>PP_Var</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  [version=0.2]
  int32_t LeaveGroup(
      [in] PP_Instance instance,
      [in] PP_Var socket_id,
      [in] PP_Var address,
      [out] PP_Var result,
      [in] PP_CompletionCallback callback);

  /**
   * Sets the time-to-live of multicast packets sent to the multicast group.
   *
   * Calling this method does not require multicast permissions.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   * @param[in] ttl An integer <code>PP_Var</code>. The time-to-live value.
   * @param[out] result An integer <code>PP_Var</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  [version=0.2]
  int32_t SetMulticastTimeToLive(
      [in] PP_Instance instance,
      [in] PP_Var socket_id,
      [in] PP_Var ttl,
      [out] PP_Var result,
      [in] PP_CompletionCallback callback);

  /**
   * Sets whether multicast packets sent from the host to the multicast group
   * will be looped back to the host.
   *
   * Note: the behavior of <code>SetMulticastLoopbackMode</code> is slightly
   * different between Windows and Unix-like systems. The inconsistency
   * happens only when there is more than one application on the same host
   * joined to the same multicast group while having different settings on
   * multicast loopback mode. On Windows, the applications with loopback off
   * will not RECEIVE the loopback packets; while on Unix-like systems, the
   * applications with loopback off will not SEND the loopback packets to
   * other applications on the same host. See MSDN: http://goo.gl/6vqbj
   *
   * Calling this method does not require multicast permissions.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   * @param[in] enabled A boolean <code>PP_Var</code>. Indicates whether to
   * enable loopback mode.
   * @param[out] result An integer <code>PP_Var</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  [version=0.2]
  int32_t SetMulticastLoopbackMode(
      [in] PP_Instance instance,
      [in] PP_Var socket_id,
      [in] PP_Var enabled,
      [out] PP_Var result,
      [in] PP_CompletionCallback callback);

  /**
   * Gets the multicast group addresses the socket is currently joined to.
   *
   * @param[in] instance A <code>PP_Instance</code>.
   * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID.
   * @param[out] groups An array <code>PP_Var</code> of string
   * <code>PP_Var</code>s.
   * @param[in] callback A <code>PP_CompletionCallback</code> to be called
   * upon completion.
   *
   * @return An error code from <code>pp_errors.h</code>.
   */
  [version=0.2]
  int32_t GetJoinedGroups(
      [in] PP_Instance instance,
      [in] PP_Var socket_id,
      [out] PP_Var groups,
      [in] PP_CompletionCallback callback);
};