Adds socket.getInfo to the socket API

chrome/common/extensions/api/experimental_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 experimental.socket {
   enum SocketType {
     tcp,
     udp
@@ skipping 38 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>.

[miket_OOO, 2012/07/30 16:53:10]

We should say something here about what "connected" means in the UDP case.
(Unfortunately, the documentation for our connect API itself is a little too
concise to be helpful.) It doesn't actually connect or cause anything to go out
over the wire. It just associates a destination address with the socket. So a
"connected" UDP socket never gets disconnected, either.

[thorogood, 2012/07/31 01:21:09]

I've added a section for UDP, as well as updating the documentation for
connect().

+    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.

[miket_OOO, 2012/07/30 16:53:10]

Remove extra slash.

[thorogood, 2012/07/31 01:21:09]

Done.

+    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);
@@ skipping 78 matching lines @@
                              optional long delay,
                              SetKeepAliveCallback callback);
 
     // Enable/disable Nagle algorithm.
     // |socketId| : The socketId.
     // |noDelay| : If true, disable Nagle algorithm.
     // |callback| : Called when the setNoDelay attempt is complete.
     static void setNoDelay(long socketId,
                            boolean noDelay,
                            SetNoDelayCallback callback);
+
+    // Retrieve the state of the given socket.

[miket_OOO, 2012/07/30 16:53:10]

"Retrieves" to match the voice of earlier docs. (Would you please update
setNoDelay and setKeepAlive, which are using the wrong voice, too?)

[thorogood, 2012/07/31 01:21:09]

Done. I've also updated the setNoDelay comment just a touch, since I feel it was
difficult to grok.

+    // |socketId| : The socketId.
+    // |callback| : Called when the state is available.
+    static void getInfo(long socketId,
+                        GetInfoCallback callback);
   };
 
 };