sockets_tcp_server.idl revision a1401311d1ab56c4ed0a474bd38c108f75cb0cd9 
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.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.
8namespace 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>.
21    boolean? persistent;
22
23    // An application-defined string associated with the socket.
24    DOMString? name;
25  };
26
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.
32    long socketId;
33  };
34
35  // Callback from the <code>create</code> method.
36  // |createInfo| : The result of the socket creation.
37  callback CreateCallback = void (CreateInfo createInfo);
38
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);
43
44  // Callback from the <code>disconnect</code> method.
45  callback DisconnectCallback = void ();
46
47  // Callback from the <code>close</code> method.
48  callback CloseCallback = void ();
49
50  // Callback from the <code>update</code> method.
51  callback UpdateCallback = void ();
52
53  // Callback from the <code>setPaused</code> method.
54  callback SetPausedCallback = void ();
55
56  // Result of the <code>getInfo</code> method.
57  dictionary SocketInfo {
58    // The socket identifier.
59    long socketId;
60
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".
64    boolean persistent;
65
66    // Application-defined string associated with the socket.
67    DOMString? name;
68
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".
73    boolean paused;
74
75    // If the socket is listening, contains its local IPv4/6 address.
76    DOMString? localAddress;
77
78    // If the socket is listening, contains its local port.
79    long? localPort;
80  };
81
82  // Callback from the <code>getInfo</code> method.
83  // |socketInfo| : Object containing the socket information.
84  callback GetInfoCallback = void (SocketInfo socketInfo);
85
86  // Callback from the <code>getSockets</code> method.
87  // |socketInfos| : Array of object containing socket information.
88  callback GetSocketsCallback = void (SocketInfo[] socketInfos);
89
90  // Data from an <code>onAccept</code> event.
91  dictionary AcceptInfo {
92    // The server socket identifier.
93    long socketId;
94
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.
100    long clientSocketId;
101  };
102
103  // Data from an <code>onAcceptError</code> event.
104  dictionary AcceptErrorInfo {
105    // The server socket identifier.
106    long socketId;
107
108    // The result code returned from the underlying network call.
109    long resultCode;
110  };
111
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);
118
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);
126
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,
133                          boolean paused,
134                          optional SetPausedCallback callback);
135
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,
146                       DOMString address,
147                       long port,
148                       optional long backlog,
149                       ListenCallback callback);
150
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);
159
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);
168
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);
174
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);
178  };
179
180  interface Events {
181    // Event raised when a connection has been made to the server socket.
182    // |info| : The event data.
183    static void onAccept(AcceptInfo info);
184
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
189    // is resumed.
190    // |info| : The event data.
191    static void onAcceptError(AcceptErrorInfo info);
192  };
193};
194