Add new InternetAddress class with a static lookup function (including IPv6 results).

sdk/lib/io/socket.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
+
+/**
+ * [InternetAddressType] is the type an [InternetAddress]. Currently, IPv4 and
+ * IPv6 are supported.
+ */
+class InternetAddressType {
+  static const InternetAddressType IPv4 = const InternetAddressType._(0);
+  static const InternetAddressType IPv6 = const InternetAddressType._(1);
+  static const InternetAddressType ANY = const InternetAddressType._(-1);
+
+  final int _value;
+
+  const InternetAddressType._(int this._value);
+
+  factory InternetAddressType._from(int value) {
+    if (value == 0) return IPv4;
+    if (value == 1) return IPv6;
+    throw new ArgumentError("Invalid type: $value");
+  }
+
+  /**
+   * Get the name of the type, e.g. "IPv4" or "IPv6".
+   */
+  String get name {
+    switch (_value) {
+      case -1: return "ANY";
+      case 0: return "IPv4";
+      case 1: return "IPv6";
+      default: throw new ArgumentError("Invalid InternetAddress");
+    }
+  }
+
+  String toString() => "InternetAddressType($name)";
+}
+
+
+/**
+ * The [InternetAddress] is an object reflecting either a remote or a local
+ * address, for wich a socket can be connected to or bound on.
+ *
+ */
+abstract class InternetAddress {
+  /**
+   * The [type] of the [InternetAddress] specified what IP procotol.
+   */
+  InternetAddressType type;
+
+  /**
+   * The resolved address of the host.
+   */
+  String get address;
+
+  /**
+   * The host used to lookup the address.
+   */
+  String get host;
+
+  /**
+   * Lookup a host, returning a Future of a list of [InternetAddress]s. If
+   * [type] is [InternetAddressType.ANY], it will lookup both IPv4 and IPv6
+   * addresses. The order of the list depends on the local machine and the DNS
+   * lookup performed, and can as such change over time.
+   */
+  external static Future<List<InternetAddress>> lookup(
+      String host, {InternetAddressType type: InternetAddressType.ANY});
+}
+
 /**
  * The RawServerSocket is a server socket, providing a stream of low-level
  * [RawSocket]s.
  *
  * See [RawSocket] for more info.
  */
 abstract class RawServerSocket implements Stream<RawSocket> {
   /**
    * Returns a future for a [:RawServerSocket:]. When the future
    * completes the server socket is bound to the given [address] and
    * [port] and has started listening on it.
    *
    * The default value for [address] is 127.0.0.1, which will allow
    * only incoming connections from the local host. To allow for
    * incoming connection from the network use either the value 0.0.0.0
    * to bind to all interfaces or the IP address of a specific
    * interface.
    *
    * If [port] has the value [:0:] (the default) an ephemeral port will
    * be chosen by the system. The actual port used can be retrieved
    * using the [:port:] getter.
    *
    * The optional argument [backlog] can be used to specify the listen
    * backlog for the underlying OS listen setup. If [backlog] has the
    * value of [:0:] (the default) a reasonable value will be chosen by
    * the system.
    */
   external static Future<RawServerSocket> bind([String address = "127.0.0.1",
-                                               int port = 0,
-                                               int backlog = 0]);
+                                                int port = 0,
+                                                int backlog = 0]);
 
   /**
    * Returns the port used by this socket.
    */
   int get port;
 
   /**
    * Closes the socket.
    */
   void close();
@@ skipping 90 matching lines @@
 
 /**
  * The [RawSocket] is a low-level interface to a socket, exposing the raw
  * events signaled by the system. It's a [Stream] of [RawSocketEvent]s.
  */
 abstract class RawSocket implements Stream<RawSocketEvent> {
   /**
    * Creates a new socket connection to the host and port and returns a [Future]
    * that will complete with either a [RawSocket] once connected or an error
    * if the host-lookup or connection failed.
+   *
+   * [host] can either be a [String] or an [InternetAddress]. If [host] is a
+   * [String], [connect] will perform a [InternetAddress.lookup] and use
+   * the first value in the list.
    */
-  external static Future<RawSocket> connect(String host, int port);
+  external static Future<RawSocket> connect(host, int port);
 
   /**
    * Returns the number of received and non-read bytes in the socket that
    * can be read.
    */
   int available();
 
   /**
    * Read up to [len] bytes from the socket. This function is
    * non-blocking and will only return data if data is available. The
@@ skipping 15 matching lines @@
    * Returns the port used by this socket.
    */
   int get port;
 
   /**
    * Returns the remote port connected to by this socket.
    */
   int get remotePort;
 
   /**
-   * Returns the host used to connect this socket.
+   * Returns the [InternetAddress] used to connect this socket.
    */
-  String get host;
+  InternetAddress get address;
 
   /**
    * Returns the remote host connected to by this socket.
    */
   String get remoteHost;
 
   /**
    * Closes the socket. Calling [close] will never throw an exception
    * and calling it several times is supported. Calling [close] can result in
    * a [RawSocketEvent.READ_CLOSED] event.
@@ skipping 34 matching lines @@
 /**
  * A high-level class for communicating over a TCP socket. The [Socket] exposes
  * both a [Stream] and a [IOSink] interface, making it ideal for
  * using together with other [Stream]s.
  */
 abstract class Socket implements Stream<List<int>>, IOSink {
   /**
    * Creats a new socket connection to the host and port and returns a [Future]
    * that will complete with either a [Socket] once connected or an error
    * if the host-lookup or connection failed.
+   *
+   * [host] can either be a [String] or an [InternetAddress]. If [host] is a
+   * [String], [connect] will perform a [InternetAddress.lookup] and use
+   * the first value in the list.
    */
-  external static Future<Socket> connect(String host, int port);
+  external static Future<Socket> connect(host, int port);
 
   /**
    * Destroy the socket in both directions. Calling [destroy] will make the
    * send a close event on the stream and will no longer react on data being
    * piped to it.
    *
    * Call [close](inherited from [IOSink]) to only close the [Socket]
    * for sending data.
    */
   void destroy();
@@ skipping 10 matching lines @@
    * Returns the port used by this socket.
    */
   int get port;
 
   /**
    * Returns the remote port connected to by this socket.
    */
   int get remotePort;
 
   /**
-   * Returns the host used to connect this socket.
+   * Returns the [InternetAddress] used to connect this socket.
    */
-  String get host;
+  InternetAddress get address;
 
   /**
    * Returns the remote host connected to by this socket.
    */
   String get remoteHost;
 }
 
 
 class SocketIOException implements Exception {
   const SocketIOException([String this.message = "",
                            OSError this.osError = null]);
   String toString() {
     StringBuffer sb = new StringBuffer();
     sb.write("SocketIOException");
     if (!message.isEmpty) {
       sb.write(": $message");
       if (osError != null) {
         sb.write(" ($osError)");
       }
     } else if (osError != null) {
       sb.write(": $osError");
     }
     return sb.toString();
   }
   final String message;
   final OSError osError;
 }