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.
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 {
10 // Only use the Internet as the transport.
12 // Only use an offline transport.
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
22 // Flag to force the socket to use a particular type of transport.
27 // Result of the <code>createPeer</code> call.
28 [noinline_doc] dictionary PeerInfo {
29 // The ID of the newly created peer.
32 // An opaque string containing the locator data for this peer. This
33 // locator is needed to connect to this socket.
37 // Data from an <code>onReceive</code> event.
38 [noinline_doc] dictionary ReceiveInfo {
39 // The socket identifier.
46 // Status of a socket operation.
48 // There was no error in the previous operation.
51 // The socket was disconnected.
54 // The socket id provided is invalid.
57 // There was a failure during connection.
60 // There was an error while trying to send data.
63 // There was an error while trying to receive data.
67 // Callback from the <code>createPeer</code> method.
68 // |peerInfo| : The result of the socket creation.
69 callback CreateCallback = void (PeerInfo peerInfo);
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);
77 // Callback from the <code>send</code> method.
78 // |status| : Status of the send operation.
79 callback SendCallback = void (SocketStatus status);
81 // Callback from the <code>disconnect</code> method.
82 callback DisconnectCallback = void ();
84 // These functions all report failures via chrome.runtime.lastError.
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);
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);
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);
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
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);
117 // Event raised when data has been received for a given socket.
118 // |info| : The event data.
119 static void onReceive(ReceiveInfo info);
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);
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);