blob: c26d854b646f27cf491afe833ada8e37b190f726 [file] [log] [blame]
// 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);
};
};