Adds socket.getInfo to the socket API

chrome/common/extensions/api/socket.idl

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // File-level comment to appease parser. Eventually this will not be necessary.
 
 namespace socket {
   enum SocketType {
     tcp,
     udp
@@ skipping 35 matching lines @@
     long resultCode;
 
     ArrayBuffer data;
 
     // The address of the remote machine.
     DOMString address;
 
     long port;
   };
 
+  dictionary SocketInfo {
+    // The type of the passed socket. This will be <code>tcp</code> or
+    // <code>udp</code>.
+    SocketType socketType;
+
+    // Whether or not the underlying socket is connected.
+    //
+    // For <code>tcp</code> sockets, this will remain true even if the remote
+    // peer has disconnected. Reading or writing to the socket may then result
+    // in an error, hinting that this socket should be disconnected via
+    // <code>disconnect()</code>.
+    //
+    // For <code>udp</code> sockets, this just represents whether a default
+    // remote address has been specified for reading and writing packets.
+    boolean connected;
+
+    // If the underlying socket is connected, contains the IPv4/6 address of
+    // the peer.
+    DOMString? peerAddress;
+
+    // If the underlying socket is connected, contains the port of the
+    // connected peer.
+    long? peerPort;
+
+    // If the underlying socket is bound or connected, contains its local
+    // IPv4/6 address.
+    DOMString? localAddress;
+
+    // If the underlying socket is bound or connected, contains its local port.
+    long? localPort;
+  };
+
   callback RecvFromCallback = void (RecvFromInfo recvFromInfo);
 
   callback SendToCallback = void (WriteInfo writeInfo);
 
   callback SetKeepAliveCallback = void (boolean result);
 
   callback SetNoDelayCallback = void (boolean result);
 
+  callback GetInfoCallback = void (SocketInfo result);
+
   interface Functions {
     // Creates a socket of the specified type that will connect to the specified
     // remote machine.
     // |type| : The type of socket to create. Must be <code>tcp</code> or
     // <code>udp</code>.
     // |options| : The socket options.
     // |callback| : Called when the socket has been created.
     static void create(SocketType type,
                        optional CreateOptions options,
                        CreateCallback callback);
 
     // Destroys the socket. Each socket created should be destroyed after use.
     // |socketId| : The socketId.
     static void destroy(long socketId);
 
-    // Connects the socket to the remote machine.
+    // Connects the socket to the remote machine (for a <code>tcp</code>
+    // socket). For a <code>udp</code> socket, this sets the default address
+    // which packets are sent to and read from for <code>read()</code>
+    // and <code>write()</code> calls.
     // |socketId| : The socketId.
     // |hostname| : The hostname or IP address of the remote machine.
     // |port| : The port of the remote machine.
     // |callback| : Called when the connection attempt is complete.
     static void connect(long socketId,
                         DOMString hostname,
                         long port,
                         ConnectCallback callback);
 
     // Binds the local address for socket. Currently, it does not support
@@ skipping 44 matching lines @@
     // |address| : The address of the remote machine.
     // |port| : The port of the remote machine.
     // |callback| : Called when the send operation completes without blocking
     // or an error occurs.
     static void sendTo(long socketId,
                        ArrayBuffer data,
                        DOMString address,
                        long port,
                        SendToCallback callback);
 
-    // Enable/disable keep-alive functionality for a TCP connection.
+    // Enables or disables the keep-alive functionality for a TCP connection.
     // |socketId| : The socketId.
     // |enable| : If true, enable keep-alive functionality.
     // |delay| : Set the delay seconds between the last data packet received
     // and the first keepalive probe. Default is 0.
     // |callback| : Called when the setKeepAlive attempt is complete.
     static void setKeepAlive(long socketId,
                              boolean enable,
                              optional long delay,
                              SetKeepAliveCallback callback);
 
-    // Enable/disable Nagle algorithm.
+    // Sets or clears <code>TCP_NODELAY</code> for a TCP connection. Nagle's
+    // algorithm will be disabled when <code>TCP_NODELAY</code> is set.
     // |socketId| : The socketId.
-    // |noDelay| : If true, disable Nagle algorithm.
+    // |noDelay| : If true, disables Nagle's algorithm.
     // |callback| : Called when the setNoDelay attempt is complete.
     static void setNoDelay(long socketId,
                            boolean noDelay,
                            SetNoDelayCallback callback);
+
+    // Retrieves the state of the given socket.
+    // |socketId| : The socketId.
+    // |callback| : Called when the state is available.
+    static void getInfo(long socketId,

[Peng, 2012/08/03 14:13:36]

I am not sure if new added function should be experimental first. Please confirm
it with mike.

[thorogood, 2012/08/05 02:22:57]

Since the whole API is now out of experimental, I'm fairly sure it is safe to
add this. I'll wait for another LGTM from Mike, or from someone else locally in
Sydney.

[miket_OOO, 2012/08/06 21:47:53]

Yes, that's fine; it's additive and backward-compatible. It's of course less
mature than the other APIs in this family, but I don't think it's worth
inventing a new doc-only designation of "not experimental but not guaranteed
stable yet, either." My answer might change if a many apps were already using
the socket API.

+                        GetInfoCallback callback);
   };
 
 };