extensions/common/api/copresence_socket.idl

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Use the <code>chrome.copresenceSocket</code> API to create persistent
   6 // sockets to send data to and receive from data nearby devices.
   7 namespace copresenceSocket {
   8
   9   enum TransportType {
  10     // Only use the Internet as the transport.
  11     online,
  12     // Only use an offline transport.
  13     offline
  14   };
  15
  16   // The properties for the peer created by the $ref:createPeer function.
  17   [noinline_doc] dictionary ConnectionProperties {
  18     // Flag indicating whether the socket should use a low latency transport
  19     // (if available).
  20     boolean? lowLatency;
  21
  22     // Flag to force the socket to use a particular type of transport.
  23     TransportType? type;
  24   };
  25
  26
  27   // Result of the <code>createPeer</code> call.
  28   [noinline_doc] dictionary PeerInfo {
  29     // The ID of the newly created peer.
  30     long peerId;
  31
  32     // An opaque string containing the locator data for this peer. This
  33     // locator is needed to connect to this socket.
  34     DOMString locator;
  35   };
  36
  37   // Data from an <code>onReceive</code> event.
  38   [noinline_doc] dictionary ReceiveInfo {
  39     // The socket identifier.
  40     long socketId;
  41
  42     // The data received.
  43     ArrayBuffer data;
  44   };
  45
  46   // Status of a socket operation.
  47   enum SocketStatus {
  48     // There was no error in the previous operation.
  49     no_error,
  50
  51     // The socket was disconnected.
  52     disconnected,
  53
  54     // The socket id provided is invalid.
  55     invalid_socket,
  56
  57     // There was a failure during connection.
  58     connect_failure,
  59
  60     // There was an error while trying to send data.
  61     send_failure,
  62
  63     // There was an error while trying to receive data.
  64     receive_failure
  65   };
  66
  67   // Callback from the <code>createPeer</code> method.
  68   // |peerInfo| : The result of the socket creation.
  69   callback CreateCallback = void (PeerInfo peerInfo);
  70
  71   // Callback from the <code>connectToPeer</code> method.
  72   // |socketId| : ID of the socket created between the local and remote peers.
  73   //              This ID is only valid if status == no_error.
  74   // |status| : Status of the connect operation.
  75   callback ConnectCallback = void (long socketId, SocketStatus status);
  76
  77   // Callback from the <code>send</code> method.
  78   // |status| : Status of the send operation.
  79   callback SendCallback = void (SocketStatus status);
  80
  81   // Callback from the <code>disconnect</code> method.
  82   callback DisconnectCallback = void ();
  83
  84   // These functions all report failures via chrome.runtime.lastError.
  85   interface Functions {
  86     // Peer functions.
  87
  88     // Creates a peer that can be connected to by a nearby devices.
  89     // |callback| : Called when the peer has been created.
  90     static void createPeer(CreateCallback callback);
  91
  92     // Destroys the peer. This will close any connections to this peer
  93     // from remote hosts and will prevent any further connections to it.
  94     // |peerId|: Peer ID returned by <code>createPeer</code>.
  95     static void destroyPeer(long peerId);
  96
  97     // Socket functions.
  98
  99     // Sends data on the given Copresence socket.
 100     // |socketId| : The socket identifier.
 101     // |data| : The data to send.
 102     // |callback| : Called when the <code>send</code> operation completes.
 103     static void send(long socketId, ArrayBuffer data,
 104                      optional SendCallback callback);
 105
 106     // Disconnects and destroys a socket. The socket id is no longer valid and any
 107     // pending send callbacks are cancelled as soon at the function is called.
 108     // However, the connection is guaranteed to be closed only when the callback
 109     // is invoked.
 110     // |socketId| : The socket identifier.
 111     // |callback| : Called when the <code>disconnect</code> operation completes.
 112     static void disconnect(long socketId,
 113                            optional DisconnectCallback callback);
 114   };
 115
 116   interface Events {
 117     // Event raised when data has been received for a given socket.
 118     // |info| : The event data.
 119     static void onReceive(ReceiveInfo info);
 120
 121     // Event raised when a peer receives a new connection. A new socket is
 122     // created and the id is passed to this event via socketId.
 123     // |peerId| : ID of the peer that received this connection.
 124     // |socketId| : ID of the new socket that was created which can be used to
 125     //              communicate on this connection.
 126     static void onConnected(long peerId, long socketId);
 127
 128     // Event raised when there is a status update for a socket. This can be an
 129     // error or disconnection. After event is raised, since there has either
 130     // been an error or disconnection, no more <code>onReceive</code> events
 131     // are raised for this socket and the socketId is invalidated.
 132     // |status| : The status update for the socket.
 133     static void onSocketStatusUpdated(long socketId, SocketStatus status);
 134   };
 135 };