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.socket</code> API to send and receive data over the 6// network using TCP and UDP connections. <b>Note:</b> Starting with Chrome 33, 7// this API is deprecated in favor of the $(ref:sockets.udp), $(ref:sockets.tcp) and 8// $(ref:sockets.tcpServer) APIs. 9namespace socket { 10 enum SocketType { 11 tcp, 12 udp 13 }; 14 15 // The socket options. 16 dictionary CreateOptions { 17 }; 18 19 dictionary CreateInfo { 20 // The id of the newly created socket. 21 long socketId; 22 }; 23 24 callback CreateCallback = void (CreateInfo createInfo); 25 26 callback ConnectCallback = void (long result); 27 28 callback BindCallback = void (long result); 29 30 callback ListenCallback = void (long result); 31 32 callback SecureCallback = void (long result); 33 34 dictionary AcceptInfo { 35 long resultCode; 36 // The id of the accepted socket. 37 long? socketId; 38 }; 39 40 callback AcceptCallback = void (AcceptInfo acceptInfo); 41 42 dictionary ReadInfo { 43 // The resultCode returned from the underlying read() call. 44 long resultCode; 45 46 ArrayBuffer data; 47 }; 48 49 callback ReadCallback = void (ReadInfo readInfo); 50 51 dictionary WriteInfo { 52 // The number of bytes sent, or a negative error code. 53 long bytesWritten; 54 }; 55 56 callback WriteCallback = void (WriteInfo writeInfo); 57 58 dictionary RecvFromInfo { 59 // The resultCode returned from the underlying recvfrom() call. 60 long resultCode; 61 62 ArrayBuffer data; 63 64 // The address of the remote machine. 65 DOMString address; 66 67 long port; 68 }; 69 70 dictionary SocketInfo { 71 // The type of the passed socket. This will be <code>tcp</code> or 72 // <code>udp</code>. 73 SocketType socketType; 74 75 // Whether or not the underlying socket is connected. 76 // 77 // For <code>tcp</code> sockets, this will remain true even if the remote 78 // peer has disconnected. Reading or writing to the socket may then result 79 // in an error, hinting that this socket should be disconnected via 80 // <code>disconnect()</code>. 81 // 82 // For <code>udp</code> sockets, this just represents whether a default 83 // remote address has been specified for reading and writing packets. 84 boolean connected; 85 86 // If the underlying socket is connected, contains the IPv4/6 address of 87 // the peer. 88 DOMString? peerAddress; 89 90 // If the underlying socket is connected, contains the port of the 91 // connected peer. 92 long? peerPort; 93 94 // If the underlying socket is bound or connected, contains its local 95 // IPv4/6 address. 96 DOMString? localAddress; 97 98 // If the underlying socket is bound or connected, contains its local port. 99 long? localPort; 100 }; 101 102 dictionary NetworkInterface { 103 // The underlying name of the adapter. On *nix, this will typically be 104 // "eth0", "lo", etc. 105 DOMString name; 106 107 // The available IPv4/6 address. 108 DOMString address; 109 110 // The prefix length 111 long prefixLength; 112 }; 113 114 dictionary TLSVersionConstraints { 115 // The minimum and maximum acceptable versions of TLS. These will 116 // be <code>ssl3</code>, <code>tls1</code>, <code>tls1.1</code>, 117 // or <code>tls1.2</code>. 118 DOMString? min; 119 DOMString? max; 120 }; 121 122 dictionary SecureOptions { 123 TLSVersionConstraints? tlsVersion; 124 }; 125 126 callback RecvFromCallback = void (RecvFromInfo recvFromInfo); 127 128 callback SendToCallback = void (WriteInfo writeInfo); 129 130 callback SetKeepAliveCallback = void (boolean result); 131 132 callback SetNoDelayCallback = void (boolean result); 133 134 callback GetInfoCallback = void (SocketInfo result); 135 136 callback GetNetworkCallback = void (NetworkInterface[] result); 137 138 callback JoinGroupCallback = void (long result); 139 140 callback LeaveGroupCallback = void (long result); 141 142 callback SetMulticastTimeToLiveCallback = void (long result); 143 144 callback SetMulticastLoopbackModeCallback = void (long result); 145 146 callback GetJoinedGroupsCallback = void (DOMString[] groups); 147 148 interface Functions { 149 // Creates a socket of the specified type that will connect to the specified 150 // remote machine. 151 // |type| : The type of socket to create. Must be <code>tcp</code> or 152 // <code>udp</code>. 153 // |options| : The socket options. 154 // |callback| : Called when the socket has been created. 155 static void create(SocketType type, 156 optional CreateOptions options, 157 CreateCallback callback); 158 159 // Destroys the socket. Each socket created should be destroyed after use. 160 // |socketId| : The socketId. 161 static void destroy(long socketId); 162 163 // Connects the socket to the remote machine (for a <code>tcp</code> 164 // socket). For a <code>udp</code> socket, this sets the default address 165 // which packets are sent to and read from for <code>read()</code> 166 // and <code>write()</code> calls. 167 // |socketId| : The socketId. 168 // |hostname| : The hostname or IP address of the remote machine. 169 // |port| : The port of the remote machine. 170 // |callback| : Called when the connection attempt is complete. 171 static void connect(long socketId, 172 DOMString hostname, 173 long port, 174 ConnectCallback callback); 175 176 // Binds the local address for socket. Currently, it does not support 177 // TCP socket. 178 // |socketId| : The socketId. 179 // |address| : The address of the local machine. 180 // |port| : The port of the local machine. 181 // |callback| : Called when the bind attempt is complete. 182 static void bind(long socketId, 183 DOMString address, 184 long port, 185 BindCallback callback); 186 187 // Disconnects the socket. For UDP sockets, <code>disconnect</code> is a 188 // non-operation but is safe to call. 189 // |socketId| : The socketId. 190 static void disconnect(long socketId); 191 192 // Reads data from the given connected socket. 193 // |socketId| : The socketId. 194 // |bufferSize| : The read buffer size. 195 // |callback| : Delivers data that was available to be read without 196 // blocking. 197 static void read(long socketId, 198 optional long bufferSize, 199 ReadCallback callback); 200 201 // Writes data on the given connected socket. 202 // |socketId| : The socketId. 203 // |data| : The data to write. 204 // |callback| : Called when the write operation completes without blocking 205 // or an error occurs. 206 static void write(long socketId, 207 ArrayBuffer data, 208 WriteCallback callback); 209 210 // Receives data from the given UDP socket. 211 // |socketId| : The socketId. 212 // |bufferSize| : The receive buffer size. 213 // |callback| : Returns result of the recvFrom operation. 214 static void recvFrom(long socketId, 215 optional long bufferSize, 216 RecvFromCallback callback); 217 218 // Sends data on the given UDP socket to the given address and port. 219 // |socketId| : The socketId. 220 // |data| : The data to write. 221 // |address| : The address of the remote machine. 222 // |port| : The port of the remote machine. 223 // |callback| : Called when the send operation completes without blocking 224 // or an error occurs. 225 static void sendTo(long socketId, 226 ArrayBuffer data, 227 DOMString address, 228 long port, 229 SendToCallback callback); 230 231 // This method applies to TCP sockets only. 232 // Listens for connections on the specified port and address. This 233 // effectively makes this a server socket, and client socket 234 // functions (connect, read, write) can no longer be used on this socket. 235 // |socketId| : The socketId. 236 // |address| : The address of the local machine. 237 // |port| : The port of the local machine. 238 // |backlog| : Length of the socket's listen queue. 239 // |callback| : Called when listen operation completes. 240 static void listen(long socketId, 241 DOMString address, 242 long port, 243 optional long backlog, 244 ListenCallback callback); 245 246 // This method applies to TCP sockets only. 247 // Registers a callback function to be called when a connection is 248 // accepted on this listening server socket. Listen must be called first. 249 // If there is already an active accept callback, this callback will be 250 // invoked immediately with an error as the resultCode. 251 // |socketId| : The socketId. 252 // |callback| : The callback is invoked when a new socket is accepted. 253 static void accept(long socketId, 254 AcceptCallback callback); 255 256 // Enables or disables the keep-alive functionality for a TCP connection. 257 // |socketId| : The socketId. 258 // |enable| : If true, enable keep-alive functionality. 259 // |delay| : Set the delay seconds between the last data packet received 260 // and the first keepalive probe. Default is 0. 261 // |callback| : Called when the setKeepAlive attempt is complete. 262 static void setKeepAlive(long socketId, 263 boolean enable, 264 optional long delay, 265 SetKeepAliveCallback callback); 266 267 // Sets or clears <code>TCP_NODELAY</code> for a TCP connection. Nagle's 268 // algorithm will be disabled when <code>TCP_NODELAY</code> is set. 269 // |socketId| : The socketId. 270 // |noDelay| : If true, disables Nagle's algorithm. 271 // |callback| : Called when the setNoDelay attempt is complete. 272 static void setNoDelay(long socketId, 273 boolean noDelay, 274 SetNoDelayCallback callback); 275 276 // Retrieves the state of the given socket. 277 // |socketId| : The socketId. 278 // |callback| : Called when the state is available. 279 static void getInfo(long socketId, 280 GetInfoCallback callback); 281 282 // Retrieves information about local adapters on this system. 283 // |callback| : Called when local adapter information is available. 284 static void getNetworkList(GetNetworkCallback callback); 285 286 // Join the multicast group and start to receive packets from that group. 287 // The socket must be of UDP type and must be bound to a local port 288 // before calling this method. 289 // |socketId| : The socketId. 290 // |address| : The group address to join. Domain names are not supported. 291 // |callback| : Called when the join group operation is done with an 292 // integer parameter indicating the platform-independent error code. 293 static void joinGroup(long socketId, 294 DOMString address, 295 JoinGroupCallback callback); 296 297 // Leave the multicast group previously joined using <code>joinGroup</code>. 298 // It's not necessary to leave the multicast group before destroying the 299 // socket or exiting. This is automatically called by the OS. 300 // 301 // Leaving the group will prevent the router from sending multicast 302 // datagrams to the local host, presuming no other process on the host is 303 // still joined to the group. 304 // 305 // |socketId| : The socketId. 306 // |address| : The group address to leave. Domain names are not supported. 307 // |callback| : Called when the leave group operation is done with an 308 // integer parameter indicating the platform-independent error code. 309 static void leaveGroup(long socketId, DOMString address, 310 LeaveGroupCallback callback); 311 312 // Set the time-to-live of multicast packets sent to the multicast group. 313 // 314 // Calling this method does not require multicast permissions. 315 // 316 // |socketId| : The socketId. 317 // |ttl| : The time-to-live value. 318 // |callback| : Called when the configuration operation is done. 319 static void setMulticastTimeToLive( 320 long socketId, 321 long ttl, 322 SetMulticastTimeToLiveCallback callback); 323 324 // Set whether multicast packets sent from the host to the multicast 325 // group will be looped back to the host. 326 // 327 // Note: the behavior of <code>setMulticastLoopbackMode</code> is slightly 328 // different between Windows and Unix-like systems. The inconsistency 329 // happens only when there is more than one application on the same host 330 // joined to the same multicast group while having different settings on 331 // multicast loopback mode. On Windows, the applications with loopback off 332 // will not RECEIVE the loopback packets; while on Unix-like systems, the 333 // applications with loopback off will not SEND the loopback packets to 334 // other applications on the same host. See MSDN: http://goo.gl/6vqbj 335 // 336 // Calling this method does not require multicast permissions. 337 // 338 // |socketId| : The socketId. 339 // |enabled| : Indicate whether to enable loopback mode. 340 // |callback| : Called when the configuration operation is done. 341 static void setMulticastLoopbackMode( 342 long socketId, 343 boolean enabled, 344 SetMulticastLoopbackModeCallback callback); 345 346 // Get the multicast group addresses the socket is currently joined to. 347 // |socketId| : The socketId. 348 // |callback| : Called with an array of strings of the result. 349 static void getJoinedGroups(long socketId, 350 GetJoinedGroupsCallback callback); 351 352 // Start a TLS client connection over a connected TCP client socket. 353 // |socketId| : The connected socket to use. 354 // |options| : Constraints and parameters for the TLS connection. 355 // |callback| : Called when the TLS connection attempt is complete. 356 static void secure(long socketId, 357 optional SecureOptions options, 358 SecureCallback callback); 359 }; 360 361}; 362