Updating trunk VERSION from 2139.0 to 2140.0
[chromium-blink-merge.git] / extensions / common / api / sockets_udp.idl
blob8ce5a233835886c3a5a78f49e11f4fc71558baea
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.udp</code> API to send and receive data over the
6 // network using UDP connections. This API supersedes the UDP functionality
7 // previously found in the "socket" API.
8 namespace sockets.udp {
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 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;
23 // An application-defined string associated with the socket.
24 DOMString? name;
26 // The size of the buffer used to receive data. If the buffer is too small
27 // to receive the UDP packet, data is lost. The default value is 4096.
28 long? bufferSize;
31 // Result of <code>create</code> call.
32 dictionary CreateInfo {
33 // The ID of the newly created socket. Note that socket IDs created from
34 // this API are not compatible with socket IDs created from other APIs, such
35 // as the deprecated <code>$(ref:socket)</code> API.
36 long socketId;
39 // Callback from the <code>create</code> method.
40 // |createInfo| : The result of the socket creation.
41 callback CreateCallback = void (CreateInfo createInfo);
43 // Callback from the <code>bind</code> method.
44 // |result| : The result code returned from the underlying network call.
45 // A negative value indicates an error.
46 callback BindCallback = void (long result);
48 // Result of the <code>send</code> method.
49 dictionary SendInfo {
50 // The result code returned from the underlying network call.
51 // A negative value indicates an error.
52 long resultCode;
54 // The number of bytes sent (if result == 0)
55 long? bytesSent;
58 // Callback from the <code>send</code> method.
59 // |sendInfo| : Result of the <code>send</code> method.
60 callback SendCallback = void (SendInfo sendInfo);
62 // Callback from the <code>close</code> method.
63 callback CloseCallback = void ();
65 // Callback from the <code>update</code> method.
66 callback UpdateCallback = void ();
68 // Callback from the <code>setPaused</code> method.
69 callback SetPausedCallback = void ();
71 // Result of the <code>getInfo</code> method.
72 dictionary SocketInfo {
73 // The socket identifier.
74 long socketId;
76 // Flag indicating whether the socket is left open when the application is
77 // suspended (see <code>SocketProperties.persistent</code>).
78 boolean persistent;
80 // Application-defined string associated with the socket.
81 DOMString? name;
83 // The size of the buffer used to receive data. If no buffer size has been
84 // specified explictly, the value is not provided.
85 long? bufferSize;
87 // Flag indicating whether the socket is blocked from firing onReceive
88 // events.
89 boolean paused;
91 // If the underlying socket is bound, contains its local
92 // IPv4/6 address.
93 DOMString? localAddress;
95 // If the underlying socket is bound, contains its local port.
96 long? localPort;
99 // Callback from the <code>getInfo</code> method.
100 // |socketInfo| : Object containing the socket information.
101 callback GetInfoCallback = void (SocketInfo socketInfo);
103 // Callback from the <code>getSockets</code> method.
104 // |socketInfos| : Array of object containing socket information.
105 callback GetSocketsCallback = void (SocketInfo[] socketInfos);
107 // Callback from the <code>joinGroup</code> method.
108 // |result| : The result code returned from the underlying network call.
109 // A negative value indicates an error.
110 callback JoinGroupCallback = void (long result);
112 // Callback from the <code>leaveGroup</code> method.
113 // |result| : The result code returned from the underlying network call.
114 // A negative value indicates an error.
115 callback LeaveGroupCallback = void (long result);
117 // Callback from the <code>setMulticastTimeToLive</code> method.
118 // |result| : The result code returned from the underlying network call.
119 // A negative value indicates an error.
120 callback SetMulticastTimeToLiveCallback = void (long result);
122 // Callback from the <code>setMulticastLoopbackMode</code> method.
123 // |result| : The result code returned from the underlying network call.
124 // A negative value indicates an error.
125 callback SetMulticastLoopbackModeCallback = void (long result);
127 // Callback from the <code>getJoinedGroupsCallback</code> method.
128 // |groups| : Array of groups the socket joined.
129 callback GetJoinedGroupsCallback = void (DOMString[] groups);
131 // Data from an <code>onReceive</code> event.
132 dictionary ReceiveInfo {
133 // The socket ID.
134 long socketId;
136 // The UDP packet content (truncated to the current buffer size).
137 ArrayBuffer data;
139 // The address of the host the packet comes from.
140 DOMString remoteAddress;
142 // The port of the host the packet comes from.
143 long remotePort;
146 // Data from an <code>onReceiveError</code> event.
147 dictionary ReceiveErrorInfo {
148 // The socket ID.
149 long socketId;
151 // The result code returned from the underlying recvfrom() call.
152 long resultCode;
155 interface Functions {
156 // Creates a UDP socket with the given properties.
157 // |properties| : The socket properties (optional).
158 // |callback| : Called when the socket has been created.
159 static void create(optional SocketProperties properties,
160 CreateCallback callback);
162 // Updates the socket properties.
163 // |socketId| : The socket ID.
164 // |properties| : The properties to update.
165 // |callback| : Called when the properties are updated.
166 static void update(long socketId,
167 SocketProperties properties,
168 optional UpdateCallback callback);
170 // Pauses or unpauses a socket. A paused socket is blocked from firing
171 // <code>onReceive</code> events.
172 // |connectionId| : The socket ID.
173 // |paused| : Flag to indicate whether to pause or unpause.
174 // |callback| : Called when the socket has been successfully paused or
175 // unpaused.
176 static void setPaused(long socketId,
177 boolean paused,
178 optional SetPausedCallback callback);
180 // Binds the local address and port for the socket. For a client socket, it
181 // is recommended to use port 0 to let the platform pick a free port.
183 // Once the <code>bind</code> operation completes successfully,
184 // <code>onReceive</code> events are raised when UDP packets arrive on the
185 // address/port specified -- unless the socket is paused.
187 // |socketId| : The socket ID.
188 // |address| : The address of the local machine. DNS name, IPv4 and IPv6
189 // formats are supported. Use "0.0.0.0" to accept packets from all local
190 // available network interfaces.
191 // |port| : The port of the local machine. Use "0" to bind to a free port.
192 // |callback| : Called when the <code>bind</code> operation completes.
193 static void bind(long socketId,
194 DOMString address,
195 long port,
196 BindCallback callback);
198 // Sends data on the given socket to the given address and port. The socket
199 // must be bound to a local port before calling this method.
200 // |socketId| : The socket ID.
201 // |data| : The data to send.
202 // |address| : The address of the remote machine.
203 // |port| : The port of the remote machine.
204 // |callback| : Called when the <code>send</code> operation completes.
205 static void send(long socketId,
206 ArrayBuffer data,
207 DOMString address,
208 long port,
209 SendCallback callback);
211 // Closes the socket and releases the address/port the socket is bound to.
212 // Each socket created should be closed after use. The socket id is no
213 // longer valid as soon at the function is called. However, the socket is
214 // guaranteed to be closed only when the callback is invoked.
215 // |socketId| : The socket ID.
216 // |callback| : Called when the <code>close</code> operation completes.
217 static void close(long socketId,
218 optional CloseCallback callback);
220 // Retrieves the state of the given socket.
221 // |socketId| : The socket ID.
222 // |callback| : Called when the socket state is available.
223 static void getInfo(long socketId,
224 GetInfoCallback callback);
226 // Retrieves the list of currently opened sockets owned by the application.
227 // |callback| : Called when the list of sockets is available.
228 static void getSockets(GetSocketsCallback callback);
230 // Joins the multicast group and starts to receive packets from that group.
231 // The socket must be bound to a local port before calling this method.
232 // |socketId| : The socket ID.
233 // |address| : The group address to join. Domain names are not supported.
234 // |callback| : Called when the <code>joinGroup</code> operation completes.
235 static void joinGroup(long socketId,
236 DOMString address,
237 JoinGroupCallback callback);
239 // Leaves the multicast group previously joined using
240 // <code>joinGroup</code>. This is only necessary to call if you plan to
241 // keep using the socketafterwards, since it will be done automatically by
242 // the OS when the socket is closed.
244 // Leaving the group will prevent the router from sending multicast
245 // datagrams to the local host, presuming no other process on the host is
246 // still joined to the group.
248 // |socketId| : The socket ID.
249 // |address| : The group address to leave. Domain names are not supported.
250 // |callback| : Called when the <code>leaveGroup</code> operation completes.
251 static void leaveGroup(long socketId,
252 DOMString address,
253 LeaveGroupCallback callback);
255 // Sets the time-to-live of multicast packets sent to the multicast group.
257 // Calling this method does not require multicast permissions.
259 // |socketId| : The socket ID.
260 // |ttl| : The time-to-live value.
261 // |callback| : Called when the configuration operation completes.
262 static void setMulticastTimeToLive(
263 long socketId,
264 long ttl,
265 SetMulticastTimeToLiveCallback callback);
267 // Sets whether multicast packets sent from the host to the multicast group
268 // will be looped back to the host.
270 // Note: the behavior of <code>setMulticastLoopbackMode</code> is slightly
271 // different between Windows and Unix-like systems. The inconsistency
272 // happens only when there is more than one application on the same host
273 // joined to the same multicast group while having different settings on
274 // multicast loopback mode. On Windows, the applications with loopback off
275 // will not RECEIVE the loopback packets; while on Unix-like systems, the
276 // applications with loopback off will not SEND the loopback packets to
277 // other applications on the same host. See MSDN: http://goo.gl/6vqbj
279 // Calling this method does not require multicast permissions.
281 // |socketId| : The socket ID.
282 // |enabled| : Indicate whether to enable loopback mode.
283 // |callback| : Called when the configuration operation completes.
284 static void setMulticastLoopbackMode(
285 long socketId,
286 boolean enabled,
287 SetMulticastLoopbackModeCallback callback);
289 // Gets the multicast group addresses the socket is currently joined to.
290 // |socketId| : The socket ID.
291 // |callback| : Called with an array of strings of the result.
292 static void getJoinedGroups(long socketId,
293 GetJoinedGroupsCallback callback);
296 interface Events {
297 // Event raised when a UDP packet has been received for the given socket.
298 // |info| : The event data.
299 static void onReceive(ReceiveInfo info);
301 // Event raised when a network error occured while the runtime was waiting
302 // for data on the socket address and port. Once this event is raised, the
303 // socket is paused and no more <code>onReceive</code> events will be raised
304 // for this socket until the socket is resumed.
305 // |info| : The event data.
306 static void onReceiveError(ReceiveErrorInfo info);