Prototype for copresenceSockets.

extensions/common/api/copresence_socket.idl

+// 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);
+  };
+};