Add UDP support to dart:io

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,
  * IP version 4 (IPv4) and IP version 6 (IPv6) are supported.
@@ skipping 300 matching lines @@
 class SocketOption {
   /**
    * Enable or disable no-delay on the socket. If TCP_NODELAY is enabled, the
    * socket will not buffer data internally, but instead write each data chunk
    * as an invidual TCP packet.
    *
    * TCP_NODELAY is disabled by default.
    */
   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;
 }
 
 /**
  * Events for the [RawSocket].
  */
 class RawSocketEvent {
   static const RawSocketEvent READ = const RawSocketEvent._(0);
   static const RawSocketEvent WRITE = const RawSocketEvent._(1);
@@ skipping 163 matching lines @@
    */
   InternetAddress get address;
 
   /**
    * Returns the remote [InternetAddress] connected to by this socket.
    */
   InternetAddress get remoteAddress;
 }
 
 
+/**
+ * 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;
   final InternetAddress address;
   final int port;
 
   const SocketException(String this.message,
                         {OSError this.osError,
                          InternetAddress this.address,
                          int this.port});
@@ skipping 11 matching lines @@
     }
     if (address != null) {
       sb.write(", address = ${address.host}");
     }
     if (port != null) {
       sb.write(", port = $port");
     }
     return sb.toString();
   }
 }