1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
// Copyright 2014 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// Use the <code>chrome.sockets.tcpServer</code> API to create server
// applications using TCP connections. This API supersedes the TCP functionality
// previously found in the <code>chrome.socket</code> API.
namespace sockets.tcpServer {
// The socket properties specified in the <code>create</code> or
// <code>update</code> function. Each property is optional. If a property
// value is not specified, a default value is used when calling
// <code>create</code>, or the existing value if preserved when calling
// <code>update</code>.
dictionary SocketProperties {
// Flag indicating if the socket remains open when the event page of the
// application is unloaded (see
// <a href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App
// Lifecycle</a>). The default value is "false." When the application is
// loaded, any sockets previously opened with persistent=true can be fetched
// with <code>getSockets</code>.
boolean? persistent;
// An application-defined string associated with the socket.
DOMString? name;
};
// Result of <code>create</code> call.
dictionary CreateInfo {
// The ID of the newly created server socket. Note that socket IDs created
// from this API are not compatible with socket IDs created from other APIs,
// such as the deprecated <code>$(ref:socket)</code> API.
long socketId;
};
// Callback from the <code>create</code> method.
// |createInfo| : The result of the socket creation.
callback CreateCallback = void (CreateInfo createInfo);
// Callback from the <code>listen</code> method.
// |result| : The result code returned from the underlying network call.
// A negative value indicates an error.
callback ListenCallback = void (long result);
// Callback from the <code>disconnect</code> method.
callback DisconnectCallback = void ();
// Callback from the <code>close</code> method.
callback CloseCallback = void ();
// Callback from the <code>update</code> method.
callback UpdateCallback = void ();
// Callback from the <code>setPaused</code> method.
callback SetPausedCallback = void ();
// Result of the <code>getInfo</code> method.
dictionary SocketInfo {
// The socket identifier.
long socketId;
// Flag indicating if the socket remains open when the event page of the
// application is unloaded (see <code>SocketProperties.persistent</code>).
// The default value is "false".
boolean persistent;
// Application-defined string associated with the socket.
DOMString? name;
// Flag indicating whether connection requests on a listening socket are
// dispatched through the <code>onAccept</code> event or queued up in the
// listen queue backlog.
// See <code>setPaused</code>. The default value is "false".
boolean paused;
// If the socket is listening, contains its local IPv4/6 address.
DOMString? localAddress;
// If the socket is listening, contains its local port.
long? localPort;
};
// Callback from the <code>getInfo</code> method.
// |socketInfo| : Object containing the socket information.
callback GetInfoCallback = void (SocketInfo socketInfo);
// Callback from the <code>getSockets</code> method.
// |socketInfos| : Array of object containing socket information.
callback GetSocketsCallback = void (SocketInfo[] socketInfos);
// Data from an <code>onAccept</code> event.
dictionary AcceptInfo {
// The server socket identifier.
long socketId;
// The client socket identifier, i.e. the socket identifier of the newly
// established connection. This socket identifier should be used only with
// functions from the <code>chrome.sockets.tcp</code> namespace. Note the
// client socket is initially paused and must be explictly un-paused by the
// application to start receiving data.
long clientSocketId;
};
// Data from an <code>onAcceptError</code> event.
dictionary AcceptErrorInfo {
// The server socket identifier.
long socketId;
// The result code returned from the underlying network call.
long resultCode;
};
interface Functions {
// Creates a TCP server socket.
// |properties| : The socket properties (optional).
// |callback| : Called when the socket has been created.
static void create(optional SocketProperties properties,
CreateCallback callback);
// Updates the socket properties.
// |socketId| : The socket identifier.
// |properties| : The properties to update.
// |callback| : Called when the properties are updated.
static void update(long socketId,
SocketProperties properties,
optional UpdateCallback callback);
// Enables or disables a listening socket from accepting new connections.
// When paused, a listening socket accepts new connections until its backlog
// (see <code>listen</code> function) is full then refuses additional
// connection requests. <code>onAccept</code> events are raised only when
// the socket is un-paused.
static void setPaused(long socketId,
boolean paused,
optional SetPausedCallback callback);
// Listens for connections on the specified port and address.
// If the port/address is in use, the callback indicates a failure.
// |socketId| : The socket identifier.
// |address| : The address of the local machine.
// |port| : The port of the local machine. When set to <code>0</code>, a
// free port is chosen dynamically. The dynamically allocated port can be
// found by calling <code>getInfo</code>.
// |backlog| : Length of the socket's listen queue. The default value
// depends on the Operating System (SOMAXCONN), which ensures a reasonable
// queue length for most applications.
// |callback| : Called when listen operation completes.
static void listen(long socketId,
DOMString address,
long port,
optional long backlog,
ListenCallback callback);
// Disconnects the listening socket, i.e. stops accepting new connections
// and releases the address/port the socket is bound to. The socket
// identifier remains valid, e.g. it can be used with <code>listen</code> to
// accept connections on a new port and address.
// |socketId| : The socket identifier.
// |callback| : Called when the disconnect attempt is complete.
static void disconnect(long socketId,
optional DisconnectCallback callback);
// Disconnects and destroys the socket. Each socket created should be
// closed after use. The socket id is no longer valid as soon at the
// function is called. However, the socket is guaranteed to be closed only
// when the callback is invoked.
// |socketId| : The socket identifier.
// |callback| : Called when the <code>close</code> operation completes.
static void close(long socketId,
optional CloseCallback callback);
// Retrieves the state of the given socket.
// |socketId| : The socket identifier.
// |callback| : Called when the socket state is available.
static void getInfo(long socketId,
GetInfoCallback callback);
// Retrieves the list of currently opened sockets owned by the application.
// |callback| : Called when the list of sockets is available.
static void getSockets(GetSocketsCallback callback);
};
interface Events {
// Event raised when a connection has been made to the server socket.
// |info| : The event data.
static void onAccept(AcceptInfo info);
// Event raised when a network error occured while the runtime was waiting
// for new connections on the socket address and port. Once this event is
// raised, the socket is set to <code>paused</code> and no more
// <code>onAccept</code> events are raised for this socket until the socket
// is resumed.
// |info| : The event data.
static void onAcceptError(AcceptErrorInfo info);
};
};
|
