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