// Copyright 2014 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.

// Use the <code>chrome.copresenceSocket</code> API to create persistent
// sockets to send data to and receive from data nearby devices.
namespace copresenceSocket {

  enum TransportType {
    // Only use the Internet as the transport.
    online,
    // Only use an offline transport.
    offline
  };

  // The properties for the peer created by the $ref:createPeer function.
  [noinline_doc] dictionary ConnectionProperties {
    // Flag indicating whether the socket should use a low latency transport
    // (if available).
    boolean? lowLatency;

    // Flag to force the socket to use a particular type of transport.
    TransportType? type;
  };


  // Result of the <code>createPeer</code> call.
  [noinline_doc] dictionary PeerInfo {
    // The ID of the newly created peer.
    long peerId;

    // An opaque string containing the locator data for this peer. This
    // locator is needed to connect to this socket.
    DOMString locator;
  };

  // Data from an <code>onReceive</code> event.
  [noinline_doc] dictionary ReceiveInfo {
    // The socket identifier.
    long socketId;

    // The data received.
    ArrayBuffer data;
  };

  // Status of a socket operation.
  enum SocketStatus {
    // There was no error in the previous operation.
    no_error,

    // The socket was disconnected.
    disconnected,

    // The socket id provided is invalid.
    invalid_socket,

    // There was a failure during connection.
    connect_failure,

    // There was an error while trying to send data.
    send_failure,

    // There was an error while trying to receive data.
    receive_failure
  };

  // Callback from the <code>createPeer</code> method.
  // |peerInfo| : The result of the socket creation.
  callback CreateCallback = void (PeerInfo peerInfo);

  // Callback from the <code>connectToPeer</code> method.
  // |socketId| : ID of the socket created between the local and remote peers.
  //              This ID is only valid if status == no_error.
  // |status| : Status of the connect operation.
  callback ConnectCallback = void (long socketId, SocketStatus status);

  // Callback from the <code>send</code> method.
  // |status| : Status of the send operation.
  callback SendCallback = void (SocketStatus status);

  // Callback from the <code>disconnect</code> method.
  callback DisconnectCallback = void ();

  // These functions all report failures via chrome.runtime.lastError.
  interface Functions {
    // Peer functions.

    // Creates a peer that can be connected to by a nearby devices.
    // |callback| : Called when the peer has been created.
    static void createPeer(CreateCallback callback);

    // Destroys the peer. This will close any connections to this peer
    // from remote hosts and will prevent any further connections to it.
    // |peerId|: Peer ID returned by <code>createPeer</code>.
    static void destroyPeer(long peerId);

    // Socket functions.

    // Sends data on the given Copresence socket.
    // |socketId| : The socket identifier.
    // |data| : The data to send.
    // |callback| : Called when the <code>send</code> operation completes.
    static void send(long socketId, ArrayBuffer data,
                     optional SendCallback callback);

    // Disconnects and destroys a socket. The socket id is no longer valid and any
    // pending send callbacks are cancelled as soon at the function is called.
    // However, the connection is guaranteed to be closed only when the callback
    // is invoked.
    // |socketId| : The socket identifier.
    // |callback| : Called when the <code>disconnect</code> operation completes.
    static void disconnect(long socketId,
                           optional DisconnectCallback callback);
  };

  interface Events {
    // Event raised when data has been received for a given socket.
    // |info| : The event data.
    static void onReceive(ReceiveInfo info);

    // Event raised when a peer receives a new connection. A new socket is
    // created and the id is passed to this event via socketId.
    // |peerId| : ID of the peer that received this connection.
    // |socketId| : ID of the new socket that was created which can be used to
    //              communicate on this connection.
    static void onConnected(long peerId, long socketId);

    // Event raised when there is a status update for a socket. This can be an
    // error or disconnection. After event is raised, since there has either
    // been an error or disconnection, no more <code>onReceive</code> events
    // are raised for this socket and the socketId is invalidated.
    // |status| : The status update for the socket.
    static void onSocketStatusUpdated(long socketId, SocketStatus status);
  };
};