/* Copyright (c) 2012 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 <code>PPB_Transport_Dev</code> interface.
 */
label Chrome {
  M14 = 0.7
};

[assert_size(4)]
enum PP_TransportType {
  PP_TRANSPORTTYPE_DATAGRAM = 0,
  PP_TRANSPORTTYPE_STREAM = 1
};

[assert_size(4)]
enum PP_TransportProperty {
  /**
   * STUN server address and port, e.g "stun.example.com:19302".
   */
  PP_TRANSPORTPROPERTY_STUN_SERVER = 0,

  /**
   * Relay server address and port, e.g. "relay.example.com:12344".
   */
  PP_TRANSPORTPROPERTY_RELAY_SERVER = 1,

  /**
   * Username for the relay server.
   */
  PP_TRANSPORTPROPERTY_RELAY_USERNAME = 2,

  /**
   * Password for the relay server.
   */
  PP_TRANSPORTPROPERTY_RELAY_PASSWORD = 3,

  /**
   * Type of Relay server. Must be one of the PP_TransportRelayMode values. By
   * default is set to PP_TRANSPORTRELAYMODE_TURN.
   */
  PP_TRANSPORTPROPERTY_RELAY_MODE = 4,

  /**
   * TCP receive window in bytes. Takes effect only for PseudoTCP connections.
   */
  PP_TRANSPORTPROPERTY_TCP_RECEIVE_WINDOW = 5,

  /**
   * TCP send window in bytes. Takes effect only for PseudoTCP connections.
   */
  PP_TRANSPORTPROPERTY_TCP_SEND_WINDOW = 6,

  /**
   * Boolean value that disables Neagle's algorithm when set to true. When
   * Neagle's algorithm is disabled, all outgoing packets are sent as soon as
   * possible. When set to false (by default) data may be buffered until there
   * is a sufficient amount to send.
   */
  PP_TRANSPORTPROPERTY_TCP_NO_DELAY = 7,

  /**
   * Delay for ACK packets in milliseconds. By default set to 100ms.
   */
  PP_TRANSPORTPROPERTY_TCP_ACK_DELAY = 8,

  /**
   * Boolean value that disables TCP-based transports when set to true. By
   * default set to false.
   */
  PP_TRANSPORTPROPERTY_DISABLE_TCP_TRANSPORT = 9
};

[assert_size(4)]
enum PP_TransportRelayMode {
  /**
   * RFC5766 compliant relay server.
   */
  PP_TRANSPORTRELAYMODE_TURN = 0,

  /**
   * Legacy Google relay server.
   */
  PP_TRANSPORTRELAYMODE_GOOGLE = 1
};

/**
 * The transport interface provides peer-to-peer communication.
 *
 * TODO(juberti): other getters/setters
 * connect state
 * connect type, protocol
 * RTT
 */
interface PPB_Transport_Dev {
  /**
   * Creates a new transport object with the specified name using the
   * specified protocol.
   */
  PP_Resource CreateTransport(
      [in] PP_Instance instance,
      [in] str_t name,
      [in] PP_TransportType type);

  /**
   * Returns PP_TRUE if resource is a Transport, PP_FALSE otherwise.
   */
  PP_Bool IsTransport(
      [in] PP_Resource resource);

  /**
   * Returns PP_TRUE if the transport is currently writable (i.e. can
   * send data to the remote peer), PP_FALSE otherwise.
   */
  PP_Bool IsWritable(
      [in] PP_Resource transport);

  /**
   * Sets various configuration properties of the transport.
   */
  int32_t SetProperty(
      [in] PP_Resource transport,
      [in] PP_TransportProperty property,
      [in] PP_Var value);

  /**
   * Establishes a connection to the remote peer.  Returns
   * PP_OK_COMPLETIONPENDING and notifies on |cb| when connectivity is
   * established (or timeout occurs).
   */
  int32_t Connect(
      [in] PP_Resource transport,
      [in] PP_CompletionCallback cb);

  /**
   * Obtains another ICE candidate address to be provided to the
   * remote peer. Returns PP_OK_COMPLETIONPENDING if there are no more
   * addresses to be sent. After the callback is called
   * GetNextAddress() must be called again to get the address.
   */
  int32_t GetNextAddress(
      [in] PP_Resource transport,
      [out] PP_Var address,
      [in] PP_CompletionCallback cb);

  /**
   * Provides an ICE candidate address that was received from the remote peer.
   */
  int32_t ReceiveRemoteAddress(
      [in] PP_Resource transport,
      [in] PP_Var address);

  /**
   * Like recv(), receives data. Returns PP_OK_COMPLETIONPENDING if there is
   * currently no data to receive. In that case, the |data| pointer should
   * remain valid until the callback is called.
   */
  int32_t Recv(
      [in] PP_Resource transport,
      [out] mem_t data,
      [in] uint32_t len,
      [in] PP_CompletionCallback cb);

  /**
   * Like send(), sends data. Returns PP_OK_COMPLETIONPENDING if the socket is
   * currently flow-controlled. In that case, the |data| pointer should remain
   * valid until the callback is called.
   */
  int32_t Send(
      [in] PP_Resource transport,
      [in] mem_t data,
      [in] uint32_t len,
      [in] PP_CompletionCallback cb);

  /**
   * Disconnects from the remote peer.
   */
  int32_t Close(
      [in] PP_Resource transport);
};