Implemented W3C complient web socket client interface

runtime/bin/websocket.dart

 // Copyright (c) 2012, 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.
 
 /**
  * The web socket protocol is implemented by a HTTP server handler
  * which can be instantiated like this:
  *
  *     WebSocketHandler wsHandler = new WebSocketHandler();
  *
@@ skipping 123 matching lines @@
   send(message);
 
   /**
    * Close the web socket connection. The default value for [status]
    * and [reason] are [:null:].
    */
   close([int status, String reason]);
 }
 
 
+/**
+ * Event delivered when there is data on a web socket connection.
+ */
+interface WebSocketDataEvent default _WebSocketDataEvent {
+  /**
+   * The type of [message] is either [:String:] or [:List<int>:]
+   * depending on whether it is a text or binary message. If the
+   * message is empty [message] will be [:null:]
+   */
+  get data();
+}
+
+
+/**
+ * Event delivered when a web socket connection is closed.
+ */
+interface WebSocketCloseEvent default _WebSocketCloseEvent {
+  bool get wasClean();

[Mads Ager (google), 2012/05/07 13:01:35]

Document the getters?

[Søren Gjesse, 2012/05/07 13:59:20]

Done.

+  int get code();
+  String get reason();
+}
+
+
+/**
+ * Alternative web socket client interface. This interface is compliant
+ * with the W3C browser API for web sockets specified in
+ * http://dev.w3.org/html5/websockets/.
+ */
+interface WebSocket default _WebSocket {
+  /**
+   * Possible states of the connection.
+   */
+  static final int CONNECTING = 0;
+  static final int OPEN = 1;
+  static final int CLOSING = 2;
+  static final int CLOSED = 3;
+
+  /**
+   * Create a new web socket connection. The URL supplied in [url]
+   * must use the scheme [:ws:]. The [protocols] argument is either a
+   * [:String:] or [:List<String>:] specifying the subprotocols the

[Mads Ager (google), 2012/05/07 13:01:35]

Should we just make this List<String> to simplify the interface or do you find
['one_protocol'] too annoying to write?

[Søren Gjesse, 2012/05/07 13:59:20]

The constructor defined in http://dev.w3.org/html5/websockets/ is

[Constructor(DOMString url, optional (DOMString or DOMString[]) protocols)]
interface WebSocket : EventTarget {
  ...
}

so to match that we need to support both.

+   * client is willing to speak.
+   */
+  WebSocket(String url, [protocols]);
+
+  /**
+   * Returns the current state of the connection.
+   */
+  int get readyState();
+
+  /**
+   * Returns the number of bytes currently buffered for transmission.
+   */
+  int get bufferedAmount();
+
+  /**
+   * Sets the callback to be called when a web socket connection has
+   * been established.
+   */
+  void set onopen(Function callback);
+
+  /**
+   * Sets the callback to be called when the web socket connection
+   * encountered an error.
+   */
+  void set onerror(Function callback);
+
+  /**
+   * Sets the callback to be called when the web socket connection is
+   * closed.
+   */
+  void set onclose(void callback(WebSocketCloseEvent event));
+
+  /**
+   * The extensions property is initially the empty string. After the
+   * web socket connection is established this string reflects the
+   * extensions used by the server.
+   */
+  String get extensions();
+
+  /**
+   * The protocol property is initially the empty string. After the
+   * web socket connection is established the value is the subprotocol
+   * selected by the server. If no subprotocol is negotiated the
+   * value will remain [:null:].
+   */
+  String get protocol();
+
+  /**
+   * Closes the web socket connection.
+   */
+  void close(int code, String reason);
+
+  /**
+   * Sets the callback to be called when a message have been
+   * received.
+   */
+  void set onmessage(void callback(WebSocketDataEvent event));
+
+  /**
+   * Sends data on the web socket connection. The data in [data] must
+   * be either a [:String:] or [:List<int>:] holding bytes.
+   */
+  void send(data);
+}
+
+
 class WebSocketException implements Exception {
   const WebSocketException([String this.message = ""]);
   String toString() => "WebSocketException: $message";
   final String message;
 }