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.sockets.tcp</code> API to send and receive data over the
6// network using TCP connections. This API supersedes the TCP functionality
7// previously found in the <code>chrome.socket</code> API.
8namespace sockets.tcp {
9  // The socket properties specified in the <code>create</code> or
10  // <code>update</code> function. Each property is optional. If a property
11  // value is not specified, a default value is used when calling
12  // <code>create</code>, or the existing value if preserved when calling
13  // <code>update</code>.
14  dictionary SocketProperties {
15    // Flag indicating if the socket is left open when the event page of
16    // the application is unloaded (see
17    // <a href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App
18    // Lifecycle</a>). The default value is "false." When the application is
19    // loaded, any sockets previously opened with persistent=true can be fetched
20    // with <code>getSockets</code>.
21    boolean? persistent;
22
23    // An application-defined string associated with the socket.
24    DOMString? name;
25
26    // The size of the buffer used to receive data. The default value is 4096.
27    long? bufferSize;
28  };
29
30  // Result of <code>create</code> call.
31  dictionary CreateInfo {
32    // The ID of the newly created socket. Note that socket IDs created from
33    // this API are not compatible with socket IDs created from other APIs, such
34    // as the deprecated <code>$(ref:socket)</code> API.
35    long socketId;
36  };
37
38  // Callback from the <code>create</code> method.
39  // |createInfo| : The result of the socket creation.
40  callback CreateCallback = void (CreateInfo createInfo);
41
42  // Callback from the <code>connect</code> method.
43  // |result| : The result code returned from the underlying network call.
44  // A negative value indicates an error.
45  callback ConnectCallback = void (long result);
46
47  // Callback from the <code>disconnect</code> method.
48  callback DisconnectCallback = void ();
49
50  // Result of the <code>send</code> method.
51  dictionary SendInfo {
52    // The result code returned from the underlying network call.
53    // A negative value indicates an error.
54    long resultCode;
55
56    // The number of bytes sent (if result == 0)
57    long? bytesSent;
58  };
59
60  // Callback from the <code>send</code> method.
61  // |sendInfo| : Result of the <code>send</code> method.
62  callback SendCallback = void (SendInfo sendInfo);
63
64  // Callback from the <code>close</code> method.
65  callback CloseCallback = void ();
66
67  // Callback from the <code>update</code> method.
68  callback UpdateCallback = void ();
69
70  // Callback from the <code>setPaused</code> method.
71  callback SetPausedCallback = void ();
72
73  // Callback from the <code>setKeepAliveCallback</code> method.
74  // |result| : The result code returned from the underlying network call.
75  // A negative value indicates an error.
76  callback SetKeepAliveCallback = void (long result);
77
78  // Callback from the <code>setNodeDelay</code> method.
79  // |result| : The result code returned from the underlying network call.
80  // A negative value indicates an error.
81  callback SetNoDelayCallback = void (long result);
82
83  dictionary TLSVersionConstraints {
84    // The minimum and maximum acceptable versions of TLS. These will
85    // be <code>ssl3</code>, <code>tls1</code>, <code>tls1.1</code>,
86    // or <code>tls1.2</code>.
87    DOMString? min;
88    DOMString? max;
89  };
90
91  dictionary SecureOptions {
92    TLSVersionConstraints? tlsVersion;
93  };
94
95  callback SecureCallback = void (long result);
96
97  // Result of the <code>getInfo</code> method.
98  dictionary SocketInfo {
99    // The socket identifier.
100    long socketId;
101
102    // Flag indicating whether the socket is left open when the application is
103    // suspended (see <code>SocketProperties.persistent</code>).
104    boolean persistent;
105
106    // Application-defined string associated with the socket.
107    DOMString? name;
108
109    // The size of the buffer used to receive data. If no buffer size has been
110    // specified explictly, the value is not provided.
111    long? bufferSize;
112
113    // Flag indicating whether a connected socket blocks its peer from sending
114    // more data (see <code>setPaused</code>).
115    boolean paused;
116
117    // Flag indicating whether the socket is connected to a remote peer.
118    boolean connected;
119
120    // If the underlying socket is connected, contains its local IPv4/6 address.
121    DOMString? localAddress;
122
123    // If the underlying socket is connected, contains its local port.
124    long? localPort;
125
126    // If the underlying socket is connected, contains the peer/ IPv4/6 address.
127    DOMString? peerAddress;
128
129    // If the underlying socket is connected, contains the peer port.
130    long? peerPort;
131  };
132
133  // Callback from the <code>getInfo</code> method.
134  // |socketInfo| : Object containing the socket information.
135  callback GetInfoCallback = void (SocketInfo socketInfo);
136
137  // Callback from the <code>getSockets</code> method.
138  // |socketInfos| : Array of object containing socket information.
139  callback GetSocketsCallback = void (SocketInfo[] socketInfos);
140
141  // Data from an <code>onReceive</code> event.
142  dictionary ReceiveInfo {
143    // The socket identifier.
144    long socketId;
145
146    // The data received, with a maxium size of <code>bufferSize</code>.
147    ArrayBuffer data;
148  };
149
150  // Data from an <code>onReceiveError</code> event.
151  dictionary ReceiveErrorInfo {
152    // The socket identifier.
153    long socketId;
154
155     // The result code returned from the underlying network call.
156    long resultCode;
157  };
158
159  interface Functions {
160    // Creates a TCP socket.
161    // |properties| : The socket properties (optional).
162    // |callback| : Called when the socket has been created.
163    static void create(optional SocketProperties properties,
164                       CreateCallback callback);
165
166    // Updates the socket properties.
167    // |socketId| : The socket identifier.
168    // |properties| : The properties to update.
169    // |callback| : Called when the properties are updated.
170    static void update(long socketId,
171                       SocketProperties properties,
172                       optional UpdateCallback callback);
173
174    // Enables or disables the application from receiving messages from its
175    // peer. The default value is "false". Pausing a socket is typically used
176    // by an application to throttle data sent by its peer. When a socket is
177    // paused, no <code>onReceive</code> event is raised. When a socket is
178    // connected and un-paused, <code>onReceive</code> events are raised again
179    // when messages are received.
180    static void setPaused(long socketId,
181                          boolean paused,
182                          optional SetPausedCallback callback);
183
184    // Enables or disables the keep-alive functionality for a TCP connection.
185    // |socketId| : The socket identifier.
186    // |enable| : If true, enable keep-alive functionality.
187    // |delay| : Set the delay seconds between the last data packet received
188    // and the first keepalive probe. Default is 0.
189    // |callback| : Called when the setKeepAlive attempt is complete.
190    static void setKeepAlive(long socketId,
191                             boolean enable,
192                             optional long delay,
193                             SetKeepAliveCallback callback);
194
195    // Sets or clears <code>TCP_NODELAY</code> for a TCP connection. Nagle's
196    // algorithm will be disabled when <code>TCP_NODELAY</code> is set.
197    // |socketId| : The socket identifier.
198    // |noDelay| : If true, disables Nagle's algorithm.
199    // |callback| : Called when the setNoDelay attempt is complete.
200    static void setNoDelay(long socketId,
201                           boolean noDelay,
202                           SetNoDelayCallback callback);
203
204    // Connects the socket to a remote machine. When the <code>connect</code>
205    // operation completes successfully, <code>onReceive</code> events are
206    // raised when data is received from the peer. If a network error occurs
207    // while the runtime is receiving packets, a <code>onReceiveError</code>
208    // event is raised, at which point no more <code>onReceive</code> event will
209    // be raised for this socket until the <code>resume</code> method is called.
210    // |socketId| : The socket identifier.
211    // |peerAddress| : The address of the remote machine. DNS name, IPv4 and
212    //  IPv6 formats are supported.
213    // |peerPort| : The port of the remote machine.
214    // |callback| : Called when the connect attempt is complete.
215    static void connect(long socketId,
216                        DOMString peerAddress,
217                        long peerPort,
218                        ConnectCallback callback);
219
220    // Disconnects the socket.
221    // |socketId| : The socket identifier.
222    // |callback| : Called when the disconnect attempt is complete.
223    static void disconnect(long socketId,
224                           optional DisconnectCallback callback);
225
226    // Start a TLS client connection over the connected TCP client socket.
227    // |socketId| : The existing, connected socket to use.
228    // |options| : Constraints and parameters for the TLS connection.
229    // |callback| : Called when the connection attempt is complete.
230    static void secure(long socketId,
231                       optional SecureOptions options,
232                       SecureCallback callback);
233
234    // Sends data on the given TCP socket.
235    // |socketId| : The socket identifier.
236    // |data| : The data to send.
237    // |callback| : Called when the <code>send</code> operation completes.
238    static void send(long socketId,
239                     ArrayBuffer data,
240                     SendCallback callback);
241
242    // Closes the socket and releases the address/port the socket is bound to.
243    // Each socket created should be closed after use. The socket id is no
244    // no longer valid as soon at the function is called. However, the socket is
245    // guaranteed to be closed only when the callback is invoked.
246    // |socketId| : The socket identifier.
247    // |callback| : Called when the <code>close</code> operation completes.
248    static void close(long socketId,
249                      optional CloseCallback callback);
250
251    // Retrieves the state of the given socket.
252    // |socketId| : The socket identifier.
253    // |callback| : Called when the socket state is available.
254    static void getInfo(long socketId,
255                        GetInfoCallback callback);
256
257    // Retrieves the list of currently opened sockets owned by the application.
258    // |callback| : Called when the list of sockets is available.
259    static void getSockets(GetSocketsCallback callback);
260  };
261
262  interface Events {
263    // Event raised when data has been received for a given socket.
264    // |info| : The event data.
265    static void onReceive(ReceiveInfo info);
266
267    // Event raised when a network error occured while the runtime was waiting
268    // for data on the socket address and port. Once this event is raised, the
269    // socket is set to <code>paused</code> and no more <code>onReceive</code>
270    // events are raised for this socket.
271    // |info| : The event data.
272    static void onReceiveError(ReceiveErrorInfo info);
273  };
274};
275