Adds socket.getInfo to the socket API

chrome/common/extensions/api/socket.idl

Index: chrome/common/extensions/api/socket.idl
diff --git a/chrome/common/extensions/api/socket.idl b/chrome/common/extensions/api/socket.idl
index 0dd858aa2c420ee4e19a5cde9ec6fcc8a5c1d445..95bf7cbbf464dd5bd5481aba96014bbf12a89ef0 100644
--- a/chrome/common/extensions/api/socket.idl
+++ b/chrome/common/extensions/api/socket.idl
@@ -53,6 +53,38 @@ namespace socket {
     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);
@@ -61,6 +93,8 @@ namespace socket {
 
   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.
@@ -76,7 +110,10 @@ namespace socket {
     // |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.
@@ -141,7 +178,7 @@ namespace socket {
                        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
@@ -152,13 +189,20 @@ namespace socket {
                              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);
   };
 
 };