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.sockets.tcpServer</code> API to create server
6 // applications using TCP connections. This API supersedes the TCP functionality
7 // previously found in the <code>chrome.socket</code> API.
8 namespace sockets.tcpServer
{
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 remains open when the event page of the
16 // 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>.
23 // An application-defined string associated with the socket.
27 // Result of <code>create</code> call.
28 dictionary CreateInfo
{
29 // The ID of the newly created server socket. Note that socket IDs created
30 // from this API are not compatible with socket IDs created from other APIs,
31 // such as the deprecated <code>$(ref:socket)</code> API.
35 // Callback from the <code>create</code> method.
36 // |createInfo| : The result of the socket creation.
37 callback CreateCallback
= void (CreateInfo createInfo
);
39 // Callback from the <code>listen</code> method.
40 // |result| : The result code returned from the underlying network call.
41 // A negative value indicates an error.
42 callback ListenCallback
= void (long result
);
44 // Callback from the <code>disconnect</code> method.
45 callback DisconnectCallback
= void ();
47 // Callback from the <code>close</code> method.
48 callback CloseCallback
= void ();
50 // Callback from the <code>update</code> method.
51 callback UpdateCallback
= void ();
53 // Callback from the <code>setPaused</code> method.
54 callback SetPausedCallback
= void ();
56 // Result of the <code>getInfo</code> method.
57 dictionary SocketInfo
{
58 // The socket identifier.
61 // Flag indicating if the socket remains open when the event page of the
62 // application is unloaded (see <code>SocketProperties.persistent</code>).
63 // The default value is "false".
66 // Application-defined string associated with the socket.
69 // Flag indicating whether connection requests on a listening socket are
70 // dispatched through the <code>onAccept</code> event or queued up in the
71 // listen queue backlog.
72 // See <code>setPaused</code>. The default value is "false".
75 // If the socket is listening, contains its local IPv4/6 address.
76 DOMString? localAddress
;
78 // If the socket is listening, contains its local port.
82 // Callback from the <code>getInfo</code> method.
83 // |socketInfo| : Object containing the socket information.
84 callback GetInfoCallback
= void (SocketInfo socketInfo
);
86 // Callback from the <code>getSockets</code> method.
87 // |socketInfos| : Array of object containing socket information.
88 callback GetSocketsCallback
= void (SocketInfo
[] socketInfos
);
90 // Data from an <code>onAccept</code> event.
91 dictionary AcceptInfo
{
92 // The server socket identifier.
95 // The client socket identifier, i.e. the socket identifier of the newly
96 // established connection. This socket identifier should be used only with
97 // functions from the <code>chrome.sockets.tcp</code> namespace. Note the
98 // client socket is initially paused and must be explictly un-paused by the
99 // application to start receiving data.
103 // Data from an <code>onAcceptError</code> event.
104 dictionary AcceptErrorInfo
{
105 // The server socket identifier.
108 // The result code returned from the underlying network call.
112 interface Functions
{
113 // Creates a TCP server socket.
114 // |properties| : The socket properties (optional).
115 // |callback| : Called when the socket has been created.
116 static
void create
(optional SocketProperties properties
,
117 CreateCallback
callback);
119 // Updates the socket properties.
120 // |socketId| : The socket identifier.
121 // |properties| : The properties to update.
122 // |callback| : Called when the properties are updated.
123 static
void update
(long socketId
,
124 SocketProperties properties
,
125 optional UpdateCallback
callback);
127 // Enables or disables a listening socket from accepting new connections.
128 // When paused, a listening socket accepts new connections until its backlog
129 // (see <code>listen</code> function) is full then refuses additional
130 // connection requests. <code>onAccept</code> events are raised only when
131 // the socket is un-paused.
132 static
void setPaused
(long socketId
,
134 optional SetPausedCallback
callback);
136 // Listens for connections on the specified port and address.
137 // If the port/address is in use, the callback indicates a failure.
138 // |socketId| : The socket identifier.
139 // |address| : The address of the local machine.
140 // |port| : The port of the local machine.
141 // |backlog| : Length of the socket's listen queue. The default value
142 // depends on the Operating System (SOMAXCONN), which ensures a reasonable
143 // queue length for most applications.
144 // |callback| : Called when listen operation completes.
145 static
void listen
(long socketId
,
148 optional long backlog
,
149 ListenCallback
callback);
151 // Disconnects the listening socket, i.e. stops accepting new connections
152 // and releases the address/port the socket is bound to. The socket
153 // identifier remains valid, e.g. it can be used with <code>listen</code> to
154 // accept connections on a new port and address.
155 // |socketId| : The socket identifier.
156 // |callback| : Called when the disconnect attempt is complete.
157 static
void disconnect
(long socketId
,
158 optional DisconnectCallback
callback);
160 // Disconnects and destroys the socket. Each socket created should be
161 // closed after use. The socket id is no longer valid as soon at the
162 // function is called. However, the socket is guaranteed to be closed only
163 // when the callback is invoked.
164 // |socketId| : The socket identifier.
165 // |callback| : Called when the <code>close</code> operation completes.
166 static
void close
(long socketId
,
167 optional CloseCallback
callback);
169 // Retrieves the state of the given socket.
170 // |socketId| : The socket identifier.
171 // |callback| : Called when the socket state is available.
172 static
void getInfo
(long socketId
,
173 GetInfoCallback
callback);
175 // Retrieves the list of currently opened sockets owned by the application.
176 // |callback| : Called when the list of sockets is available.
177 static
void getSockets
(GetSocketsCallback
callback);
181 // Event raised when a connection has been made to the server socket.
182 // |info| : The event data.
183 static
void onAccept
(AcceptInfo info
);
185 // Event raised when a network error occured while the runtime was waiting
186 // for new connections on the socket address and port. Once this event is
187 // raised, the socket is set to <code>paused</code> and no more
188 // <code>onAccept</code> events are raised for this socket until the socket
190 // |info| : The event data.
191 static
void onAcceptError
(AcceptErrorInfo info
);