Disable view source for Developer Tools.
[chromium-blink-merge.git] / chrome / common / extensions / api / sockets_tcp.idl
blob3dc7d5c7337f07a1aa4d718977f8b93488a68c16
1 // Copyright 2013 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.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.
8 namespace 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;
23 // An application-defined string associated with the socket.
24 DOMString? name;
26 // The size of the buffer used to receive data. The default value is 4096.
27 long? bufferSize;
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;
38 // Callback from the <code>create</code> method.
39 // |createInfo| : The result of the socket creation.
40 callback CreateCallback = void (CreateInfo createInfo);
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);
47 // Callback from the <code>disconnect</code> method.
48 callback DisconnectCallback = void ();
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;
56 // The number of bytes sent (if result == 0)
57 long? bytesSent;
60 // Callback from the <code>send</code> method.
61 // |sendInfo| : Result of the <code>send</code> method.
62 callback SendCallback = void (SendInfo sendInfo);
64 // Callback from the <code>close<code> method.
65 callback CloseCallback = void ();
67 // Callback from the <code>update</code> method.
68 callback UpdateCallback = void ();
70 // Callback from the <code>setPaused<code> method.
71 callback SetPausedCallback = void ();
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);
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);
83 // Result of the <code>getInfo</code> method.
84 dictionary SocketInfo {
85 // The socket identifier.
86 long socketId;
88 // Flag indicating whether the socket is left open when the application is
89 // suspended (see <code>SocketProperties.persistent</code>).
90 boolean persistent;
92 // Application-defined string associated with the socket.
93 DOMString? name;
95 // The size of the buffer used to receive data. If no buffer size has been
96 // specified explictly, the value is not provided.
97 long? bufferSize;
99 // Flag indicating whether a connected socket blocks its peer from sending
100 // more data (see <code>setPaused</code>).
101 boolean paused;
103 // Flag indicating whether the socket is connected to a remote peer.
104 boolean connected;
106 // If the underlying socket is connected, contains its local IPv4/6 address.
107 DOMString? localAddress;
109 // If the underlying socket is connected, contains its local port.
110 long? localPort;
112 // If the underlying socket is connected, contains the peer/ IPv4/6 address.
113 DOMString? peerAddress;
115 // If the underlying socket is connected, contains the peer port.
116 long? peerPort;
119 // Callback from the <code>getInfo</code> method.
120 // |socketInfo| : Object containing the socket information.
121 callback GetInfoCallback = void (SocketInfo socketInfo);
123 // Callback from the <code>getSockets</code> method.
124 // |socketInfos| : Array of object containing socket information.
125 callback GetSocketsCallback = void (SocketInfo[] socketInfos);
127 // Data from an <code>onReceive</code> event.
128 dictionary ReceiveInfo {
129 // The socket identifier.
130 long socketId;
132 // The data received, with a maxium size of <code>bufferSize</code>.
133 ArrayBuffer data;
136 // Data from an <code>onReceiveError</code> event.
137 dictionary ReceiveErrorInfo {
138 // The socket identifier.
139 long socketId;
141 // The result code returned from the underlying network call.
142 long resultCode;
145 interface Functions {
146 // Creates a TCP socket.
147 // |properties| : The socket properties (optional).
148 // |callback| : Called when the socket has been created.
149 static void create(optional SocketProperties properties,
150 CreateCallback callback);
152 // Updates the socket properties.
153 // |socketId| : The socket identifier.
154 // |properties| : The properties to update.
155 // |callback| : Called when the properties are updated.
156 static void update(long socketId,
157 SocketProperties properties,
158 optional UpdateCallback callback);
160 // Enables or disables the application from receiving messages from its
161 // peer. The default value is "false". Pausing a socket is typically used
162 // by an application to throttle data sent by its peer. When a socket is
163 // paused, no <code>onReceive<code> event is raised. When a socket is
164 // connected and un-paused, <code>onReceive<code> events are raised again
165 // when messages are received.
166 static void setPaused(long socketId,
167 boolean paused,
168 optional SetPausedCallback callback);
170 // Enables or disables the keep-alive functionality for a TCP connection.
171 // |socketId| : The socket identifier.
172 // |enable| : If true, enable keep-alive functionality.
173 // |delay| : Set the delay seconds between the last data packet received
174 // and the first keepalive probe. Default is 0.
175 // |callback| : Called when the setKeepAlive attempt is complete.
176 static void setKeepAlive(long socketId,
177 boolean enable,
178 optional long delay,
179 SetKeepAliveCallback callback);
181 // Sets or clears <code>TCP_NODELAY</code> for a TCP connection. Nagle's
182 // algorithm will be disabled when <code>TCP_NODELAY</code> is set.
183 // |socketId| : The socket identifier.
184 // |noDelay| : If true, disables Nagle's algorithm.
185 // |callback| : Called when the setNoDelay attempt is complete.
186 static void setNoDelay(long socketId,
187 boolean noDelay,
188 SetNoDelayCallback callback);
190 // Connects the socket to a remote machine. When the <code>connect</code>
191 // operation completes successfully, <code>onReceive</code> events are
192 // raised when data is received from the peer. If a network error occurs
193 // while the runtime is receiving packets, a <code>onReceiveError</code>
194 // event is raised, at which point no more <code>onReceive</code> event will
195 // be raised for this socket until the <code>resume</code> method is called.
196 // |socketId| : The socket identifier.
197 // |peerAddress| : The address of the remote machine. DNS name, IPv4 and
198 // IPv6 formats are supported.
199 // |peerPort| : The port of the remote machine.
200 // |callback| : Called when the connect attempt is complete.
201 static void connect(long socketId,
202 DOMString peerAddress,
203 long peerPort,
204 ConnectCallback callback);
206 // Disconnects the socket.
207 // |socketId| : The socket identifier.
208 // |callback| : Called when the disconnect attempt is complete.
209 static void disconnect(long socketId,
210 optional DisconnectCallback callback);
212 // Sends data on the given TCP socket.
213 // |socketId| : The socket identifier.
214 // |data| : The data to send.
215 // |callback| : Called when the <code>send</code> operation completes.
216 static void send(long socketId,
217 ArrayBuffer data,
218 SendCallback callback);
220 // Closes the socket and releases the address/port the socket is bound to.
221 // Each socket created should be closed after use. The socket id is no
222 // no longer valid as soon at the function is called. However, the socket is
223 // guaranteed to be closed only when the callback is invoked.
224 // |socketId| : The socket identifier.
225 // |callback| : Called when the <code>close</code> operation completes.
226 static void close(long socketId,
227 optional CloseCallback callback);
229 // Retrieves the state of the given socket.
230 // |socketId| : The socket identifier.
231 // |callback| : Called when the socket state is available.
232 static void getInfo(long socketId,
233 GetInfoCallback callback);
235 // Retrieves the list of currently opened sockets owned by the application.
236 // |callback| : Called when the list of sockets is available.
237 static void getSockets(GetSocketsCallback callback);
240 interface Events {
241 // Event raised when data has been received for a given socket.
242 // |info| : The event data.
243 static void onReceive(ReceiveInfo info);
245 // Event raised when a network error occured while the runtime was waiting
246 // for data on the socket address and port. Once this event is raised, the
247 // socket is set to <code>paused</code> and no more <code>onReceive</code>
248 // events are raised for this socket.
249 // |info| : The event data.
250 static void onReceiveError(ReceiveErrorInfo info);