1 // Copyright (c) 2012 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.socket</code> API to send and receive data over the
6 // network using TCP and UDP connections.
13 // The socket options.
14 dictionary CreateOptions {
17 dictionary CreateInfo {
18 // The id of the newly created socket.
22 callback CreateCallback = void (CreateInfo createInfo);
24 callback ConnectCallback = void (long result);
26 callback BindCallback = void (long result);
28 callback ListenCallback = void (long result);
30 dictionary AcceptInfo {
32 // The id of the accepted socket.
36 callback AcceptCallback = void (AcceptInfo acceptInfo);
39 // The resultCode returned from the underlying read() call.
45 callback ReadCallback = void (ReadInfo readInfo);
47 dictionary WriteInfo {
48 // The number of bytes sent, or a negative error code.
52 callback WriteCallback = void (WriteInfo writeInfo);
54 dictionary RecvFromInfo {
55 // The resultCode returned from the underlying recvfrom() call.
60 // The address of the remote machine.
66 dictionary SocketInfo {
67 // The type of the passed socket. This will be <code>tcp</code> or
69 SocketType socketType;
71 // Whether or not the underlying socket is connected.
73 // For <code>tcp</code> sockets, this will remain true even if the remote
74 // peer has disconnected. Reading or writing to the socket may then result
75 // in an error, hinting that this socket should be disconnected via
76 // <code>disconnect()</code>.
78 // For <code>udp</code> sockets, this just represents whether a default
79 // remote address has been specified for reading and writing packets.
82 // If the underlying socket is connected, contains the IPv4/6 address of
84 DOMString? peerAddress;
86 // If the underlying socket is connected, contains the port of the
90 // If the underlying socket is bound or connected, contains its local
92 DOMString? localAddress;
94 // If the underlying socket is bound or connected, contains its local port.
98 dictionary NetworkInterface {
99 // The underlying name of the adapter. On *nix, this will typically be
100 // "eth0", "lo", etc.
103 // The available IPv4/6 address.
107 callback RecvFromCallback = void (RecvFromInfo recvFromInfo);
109 callback SendToCallback = void (WriteInfo writeInfo);
111 callback SetKeepAliveCallback = void (boolean result);
113 callback SetNoDelayCallback = void (boolean result);
115 callback GetInfoCallback = void (SocketInfo result);
117 callback GetNetworkCallback = void (NetworkInterface[] result);
119 callback JoinGroupCallback = void (long result);
121 callback LeaveGroupCallback = void (long result);
123 callback SetMulticastTimeToLiveCallback = void (long result);
125 callback SetMulticastLoopbackModeCallback = void (long result);
127 callback GetJoinedGroupsCallback = void (DOMString[] groups);
129 interface Functions {
130 // Creates a socket of the specified type that will connect to the specified
132 // |type| : The type of socket to create. Must be <code>tcp</code> or
134 // |options| : The socket options.
135 // |callback| : Called when the socket has been created.
136 static void create(SocketType type,
137 optional CreateOptions options,
138 CreateCallback callback);
140 // Destroys the socket. Each socket created should be destroyed after use.
141 // |socketId| : The socketId.
142 static void destroy(long socketId);
144 // Connects the socket to the remote machine (for a <code>tcp</code>
145 // socket). For a <code>udp</code> socket, this sets the default address
146 // which packets are sent to and read from for <code>read()</code>
147 // and <code>write()</code> calls.
148 // |socketId| : The socketId.
149 // |hostname| : The hostname or IP address of the remote machine.
150 // |port| : The port of the remote machine.
151 // |callback| : Called when the connection attempt is complete.
152 static void connect(long socketId,
155 ConnectCallback callback);
157 // Binds the local address for socket. Currently, it does not support
159 // |socketId| : The socketId.
160 // |address| : The address of the local machine.
161 // |port| : The port of the local machine.
162 // |callback| : Called when the bind attempt is complete.
163 static void bind(long socketId,
166 BindCallback callback);
168 // Disconnects the socket. For UDP sockets, <code>disconnect</code> is a
169 // non-operation but is safe to call.
170 // |socketId| : The socketId.
171 static void disconnect(long socketId);
173 // Reads data from the given connected socket.
174 // |socketId| : The socketId.
175 // |bufferSize| : The read buffer size.
176 // |callback| : Delivers data that was available to be read without
178 static void read(long socketId,
179 optional long bufferSize,
180 ReadCallback callback);
182 // Writes data on the given connected socket.
183 // |socketId| : The socketId.
184 // |data| : The data to write.
185 // |callback| : Called when the write operation completes without blocking
186 // or an error occurs.
187 static void write(long socketId,
189 WriteCallback callback);
191 // Receives data from the given UDP socket.
192 // |socketId| : The socketId.
193 // |bufferSize| : The receive buffer size.
194 // |callback| : Returns result of the recvFrom operation.
195 static void recvFrom(long socketId,
196 optional long bufferSize,
197 RecvFromCallback callback);
199 // Sends data on the given UDP socket to the given address and port.
200 // |socketId| : The socketId.
201 // |data| : The data to write.
202 // |address| : The address of the remote machine.
203 // |port| : The port of the remote machine.
204 // |callback| : Called when the send operation completes without blocking
205 // or an error occurs.
206 static void sendTo(long socketId,
210 SendToCallback callback);
212 // This method applies to TCP sockets only.
213 // Listens for connections on the specified port and address. This
214 // effectively makes this a server socket, and client socket
215 // functions (connect, read, write) can no longer be used on this socket.
216 // |socketId| : The socketId.
217 // |address| : The address of the local machine.
218 // |port| : The port of the local machine.
219 // |backlog| : Length of the socket's listen queue.
220 // |callback| : Called when listen operation completes.
221 static void listen(long socketId,
224 optional long backlog,
225 ListenCallback callback);
227 // This method applies to TCP sockets only.
228 // Registers a callback function to be called when a connection is
229 // accepted on this listening server socket. Listen must be called first.
230 // If there is already an active accept callback, this callback will be
231 // invoked immediately with an error as the resultCode.
232 // |socketId| : The socketId.
233 // |callback| : The callback is invoked when a new socket is accepted.
234 static void accept(long socketId,
235 AcceptCallback callback);
237 // Enables or disables the keep-alive functionality for a TCP connection.
238 // |socketId| : The socketId.
239 // |enable| : If true, enable keep-alive functionality.
240 // |delay| : Set the delay seconds between the last data packet received
241 // and the first keepalive probe. Default is 0.
242 // |callback| : Called when the setKeepAlive attempt is complete.
243 static void setKeepAlive(long socketId,
246 SetKeepAliveCallback callback);
248 // Sets or clears <code>TCP_NODELAY</code> for a TCP connection. Nagle's
249 // algorithm will be disabled when <code>TCP_NODELAY</code> is set.
250 // |socketId| : The socketId.
251 // |noDelay| : If true, disables Nagle's algorithm.
252 // |callback| : Called when the setNoDelay attempt is complete.
253 static void setNoDelay(long socketId,
255 SetNoDelayCallback callback);
257 // Retrieves the state of the given socket.
258 // |socketId| : The socketId.
259 // |callback| : Called when the state is available.
260 static void getInfo(long socketId,
261 GetInfoCallback callback);
263 // Retrieves information about local adapters on this system.
264 // |callback| : Called when local adapter information is available.
265 static void getNetworkList(GetNetworkCallback callback);
267 // Join the multicast group and start to receive packets from that group.
268 // The socket must be of UDP type and must be bound to a local port
269 // before calling this method.
270 // |socketId| : The socketId.
271 // |address| : The group address to join. Domain names are not supported.
272 // |callback| : Called when the join group operation is done with an
273 // integer parameter indicating the platform-independent error code.
274 static void joinGroup(long socketId,
276 JoinGroupCallback callback);
278 // Leave the multicast group previously joined using <code>joinGroup</code>.
279 // It's not necessary to leave the multicast group before destroying the
280 // socket or exiting. This is automatically called by the OS.
282 // Leaving the group will prevent the router from sending multicast
283 // datagrams to the local host, presuming no other process on the host is
284 // still joined to the group.
286 // |socketId| : The socketId.
287 // |address| : The group address to leave. Domain names are not supported.
288 // |callback| : Called when the leave group operation is done with an
289 // integer parameter indicating the platform-independent error code.
290 static void leaveGroup(long socketId, DOMString address,
291 LeaveGroupCallback callback);
293 // Set the time-to-live of multicast packets sent to the multicast group.
295 // Calling this method does not require multicast permissions.
297 // |socketId| : The socketId.
298 // |ttl| : The time-to-live value.
299 // |callback| : Called when the configuration operation is done.
300 static void setMulticastTimeToLive(
303 SetMulticastTimeToLiveCallback callback);
305 // Set whether multicast packets sent from the host to the multicast
306 // group will be looped back to the host.
308 // Note: the behavior of <code>setMulticastLoopbackMode</code> is slightly
309 // different between Windows and Unix-like systems. The inconsistency
310 // happens only when there is more than one application on the same host
311 // joined to the same multicast group while having different settings on
312 // multicast loopback mode. On Windows, the applications with loopback off
313 // will not RECEIVE the loopback packets; while on Unix-like systems, the
314 // applications with loopback off will not SEND the loopback packets to
315 // other applications on the same host. See MSDN: http://goo.gl/6vqbj
317 // Calling this method does not require multicast permissions.
319 // |socketId| : The socketId.
320 // |enabled| : Indicate whether to enable loopback mode.
321 // |callback| : Called when the configuration operation is done.
322 static void setMulticastLoopbackMode(
325 SetMulticastLoopbackModeCallback callback);
327 // Get the multicast group addresses the socket is currently joined to.
328 // |socketId| : The socketId.
329 // |callback| : Called with an array of strings of the result.
330 static void getJoinedGroups(long socketId,
331 GetJoinedGroupsCallback callback);