Add UDP support to dart:io

sdk/lib/io/socket.dart

Index: sdk/lib/io/socket.dart
diff --git a/sdk/lib/io/socket.dart b/sdk/lib/io/socket.dart
index f1ceec534b7453aa5aa5b767f98e236e951f0f7a..bbb36574cb3c42b1c673aa4c320809872df652c4 100644
--- a/sdk/lib/io/socket.dart
+++ b/sdk/lib/io/socket.dart
@@ -318,6 +318,10 @@ class SocketOption {
    */
   static const SocketOption TCP_NODELAY = const SocketOption._(0);
 
+  static const SocketOption _IP_MULTICAST_LOOP = const SocketOption._(1);

[Anders Johnsen, 2013/11/25 18:00:06]

Should we move private ones to start by, say 16?

[Søren Gjesse, 2013/11/28 13:58:52]

The numbers are not visible outside, so it does not really matter.

+  static const SocketOption _IP_MULTICAST_TTL = const SocketOption._(2);
+  static const SocketOption _IP_BROADCAST = const SocketOption._(3);
+
   const SocketOption._(this._value);
   final _value;
 }
@@ -501,6 +505,118 @@ abstract class Socket implements Stream<List<int>>, IOSink {
 }
 
 
+/**
+ * Datagram package. Data send to and received from datagram sockets
+ * contains the internet address and port of the destination or source
+ * togeter with the data.
+ */
+class Datagram {
+  List<int> data;
+  InternetAddess address;
+  int port;
+
+  Datagram(this.data, this.address, this.port);
+}
+
+
+/**
+ * The [RawDatagramSocket] is a low-level interface to an UDP socket,
+ * exposing the raw events signaled by the system. It's a [Stream] of
+ * [RawSocketEvent]s.
+ *
+ * Note that the event [RawSocketEvent.CLOSED] will never be received
+ * as there is no connection which can be closed by a remote peer.

[Anders Johnsen, 2013/11/25 18:00:06]

'[...] as an UDP socket cannot be closed by a remote peer.' ?

[Søren Gjesse, 2013/11/28 13:58:52]

Done.

+ */
+abstract class RawDatagramSocket extends Stream {

[Anders Johnsen, 2013/11/25 18:00:06]

Can the Stream type be Stream<RawSocketEvent> ?

[Søren Gjesse, 2013/11/28 13:58:52]

Done.

+  /**
+   * Creates a new raw datagram socket binding it to an address and
+   * port.
+   */
+  factory RawDatagramSocket(InternetAddress address, int port) =>

[Anders Johnsen, 2013/11/25 18:00:06]

I think this should be like a Socket and ServerSocket, returning a Future. If
not, then one could argue that ServerSocket.bind should be a factory as well?

[Søren Gjesse, 2013/11/28 13:58:52]

I will make it return a future, and change the type from InternetAddress to
dynamic to support both InternetAddress and hostname.

My initial thoughts was that for most UDP applications one would use a numeric
InternetAddress, and therefore a future would not be needed as no DNS lookup
could be involved.

Lets keep this consistent, we can then consider normal constructors for
RawServerSocket, RawSocket and this with InternetAddress. But that might just
cause confusion.

+      new _RawDatagramSocket(address, port);
+
+  /**
+   * Returns the port used by this socket.
+   */
+  int get port;
+
+  /**
+   * Returns the address used by this socket.
+   */
+  InternetAddress get address;
+
+  /**
+   * Close the datagram socket.
+   */
+  void close();

[Anders Johnsen, 2013/11/25 18:00:06]

Does directional-close work for UDP sockets? (I'm thinking about shutdown)

[Søren Gjesse, 2013/11/28 13:58:52]

No the shutdown is a TCP thing.

+
+  /**
+   * Send a datagram.
+   *
+   * Returns `true` if the datagram was send.
+   */
+  bool send(Datagram datagram);
+
+  /**
+   * Send a datagram.
+   *
+   * Returns `true` if the datagram was send.
+   */
+  bool sendTo(List<data> buffer, InternetAddress address, int port);

[Anders Johnsen, 2013/11/25 18:00:06]

Having both send and sendTo, with so little difference, seems a bit redundant.

[Søren Gjesse, 2013/11/28 13:58:52]

Removed one.

+
+  /**
+   * Receive a datagram. If there are no datagrams available `null` is
+   * returned.
+   */
+  Datagram receive();
+
+  /**
+   * Join a multicast group.
+   *
+   * If an error occur when trying to join the multicast group an
+   * exception is thrown.
+   */
+  void join(InternetAddress group, [NetworkInterface interface]);

[Anders Johnsen, 2013/11/25 18:00:06]

This is really cool, with the optional interface. Could the interface be a named
argument?

[Søren Gjesse, 2013/11/28 13:58:52]

Done.

+
+  /**
+   * Leave a multicast group.
+   *
+   * If an error occur when trying to join the multicase group an
+   * exception is thrown.
+   */
+  void leave(InternetAddress group, [NetworkInterface interface]);

[Anders Johnsen, 2013/11/25 18:00:06]

Ditto.

[Søren Gjesse, 2013/11/28 13:58:52]

Done.

+
+  /**
+   * Set or get, if the [RawDatagramSocket] should listen for
+   * [RawSocketEvent.READ] events. Default is [true].
+   */
+  bool readEventsEnabled;
+
+  /**
+   * Set or get, if the [RawDatagramSocket] should listen for
+   * [RawSocketEvent.WRITE] events. Default is [true].  This is a
+   * one-shot listener, and writeEventsEnabled must be set to true
+   * again to receive another write event.
+   */
+  bool writeEventsEnabled;

[Anders Johnsen, 2013/11/25 18:00:06]

Is it true by default? I thought it is only set to true, when one cannot send a
message.

[Søren Gjesse, 2013/11/28 13:58:52]

It starts out as true.

+
+  /**
+   * Set or get, whether multicast traffic is looped back to the host.

[Anders Johnsen, 2013/11/25 18:00:06]

This, and those below, needs a default value in documentation.

[Søren Gjesse, 2013/11/28 13:58:52]

Done.

+   */
+  bool multicastLoopback;
+
+  /**
+   * Set or get, the TTL (time to live) for multicast traffic.
+   */
+  int multicastTTL;
+
+  /**
+   * Set or get, whether broadcast is enabled for the local interface.
+   */
+  bool broadcastEnabled;
+}
+
+
 class SocketException implements IOException {
   final String message;
   final OSError osError;