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.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.
8namespace 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;
22
23    // An application-defined string associated with the socket.
24    DOMString? name;
25
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;
29  };
30
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;
37  };
38
39  // Callback from the <code>create</code> method.
40  // |createInfo| : The result of the socket creation.
41  callback CreateCallback = void (CreateInfo createInfo);
42
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);
47
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;
53
54    // The number of bytes sent (if result == 0)
55    long? bytesSent;
56  };
57
58  // Callback from the <code>send</code> method.
59  // |sendInfo| : Result of the <code>send</code> method.
60  callback SendCallback = void (SendInfo sendInfo);
61
62  // Callback from the <code>close</code> method.
63  callback CloseCallback = void ();
64
65  // Callback from the <code>update</code> method.
66  callback UpdateCallback = void ();
67
68  // Callback from the <code>setPaused</code> method.
69  callback SetPausedCallback = void ();
70
71  // Result of the <code>getInfo</code> method.
72  dictionary SocketInfo {
73    // The socket identifier.
74    long socketId;
75
76    // Flag indicating whether the socket is left open when the application is
77    // suspended (see <code>SocketProperties.persistent</code>).
78    boolean persistent;
79
80    // Application-defined string associated with the socket.
81    DOMString? name;
82
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;
86
87    // Flag indicating whether the socket is blocked from firing onReceive
88    // events.
89    boolean paused;
90
91    // If the underlying socket is bound, contains its local
92    // IPv4/6 address.
93    DOMString? localAddress;
94
95    // If the underlying socket is bound, contains its local port.
96    long? localPort;
97  };
98
99  // Callback from the <code>getInfo</code> method.
100  // |socketInfo| : Object containing the socket information.
101  callback GetInfoCallback = void (SocketInfo socketInfo);
102
103  // Callback from the <code>getSockets</code> method.
104  // |socketInfos| : Array of object containing socket information.
105  callback GetSocketsCallback = void (SocketInfo[] socketInfos);
106
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);
111
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);
116
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);
121
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);
126
127  // Callback from the <code>getJoinedGroupsCallback</code> method.
128  // |groups| : Array of groups the socket joined.
129  callback GetJoinedGroupsCallback = void (DOMString[] groups);
130
131  // Data from an <code>onReceive</code> event.
132  dictionary ReceiveInfo {
133    // The socket ID.
134    long socketId;
135
136    // The UDP packet content (truncated to the current buffer size).
137    ArrayBuffer data;
138
139    // The address of the host the packet comes from.
140    DOMString remoteAddress;
141
142     // The port of the host the packet comes from.
143    long remotePort;
144  };
145
146  // Data from an <code>onReceiveError</code> event.
147  dictionary ReceiveErrorInfo {
148    // The socket ID.
149    long socketId;
150
151     // The result code returned from the underlying recvfrom() call.
152    long resultCode;
153  };
154
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);
161
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);
169
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);
179
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.
182    //
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.
186    //
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);
197
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);
210
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);
219
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);
225
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);
229
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);
238
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.
243    //
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.
247    //
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);
254
255    // Sets the time-to-live of multicast packets sent to the multicast group.
256    //
257    // Calling this method does not require multicast permissions.
258    //
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);
266
267    // Sets whether multicast packets sent from the host to the multicast group
268    // will be looped back to the host.
269    //
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
278    //
279    // Calling this method does not require multicast permissions.
280    //
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);
288
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);
294  };
295
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);
300
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);
307  };
308};
309