lib/html/doc/interface/WebSocket.dartdoc

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

/// @domName WebSocket
/**
 * Use the WebSocket interface to connect to a WebSocket,
 * and to send and receive data on that WebSocket.
 *
 * To use a WebSocket in your web app, first create a WebSocket object,
 * passing the WebSocket URL as an argument to the constructor.
 *
 *     var webSocket = new WebSocket('ws://127.0.0.1:1337/ws');
 *
 * To send data on the WebSocket, use the [send] method.
 *
 *     if (webSocket != null && webSocket.readyState == WebSocket.OPEN) {
 *       webSocket.send(data);
 *     } else {
 *       print('WebSocket not connected, message $data not sent');
 *     }
 *
 * To receive data on the WebSocket, register a listener for message events.
 *
 *     webSocket.on.message.add((MessageEvent e) {
 *       receivedData(e.data);
 *     });
 *
 * The message event handler receives a [MessageEvent] object
 * as its sole argument.
 * You can also define open, close, and error handlers,
 * as specified by [WebSocketEvents].
 *
 * For more information, see the
 * [WebSockets](http://www.dartlang.org/docs/library-tour/#html-websockets)
 * section of the library tour and
 * [Introducing WebSockets](http://www.html5rocks.com/en/tutorials/websockets/basics/),
 * an HTML5Rocks.com tutorial.
 */
abstract class WebSocket implements EventTarget {

  factory WebSocket(String url) => _WebSocketFactoryProvider.createWebSocket(url);

  /**
   * @domName EventTarget.addEventListener, EventTarget.removeEventListener, EventTarget.dispatchEvent
   */
  WebSocketEvents get on;

  static const int CLOSED = 3;

  static const int CLOSING = 2;

  static const int CONNECTING = 0;

  static const int OPEN = 1;

  /** @domName WebSocket.URL */
  abstract String get URL;

  /** @domName WebSocket.binaryType */
  String binaryType;

  /** @domName WebSocket.bufferedAmount */
  abstract int get bufferedAmount;

  /** @domName WebSocket.extensions */
  abstract String get extensions;

  /** @domName WebSocket.protocol */
  abstract String get protocol;

  /** @domName WebSocket.readyState */
  abstract int get readyState;

  /** @domName WebSocket.url */
  abstract String get url;

  /** @domName WebSocket.addEventListener */
  void $dom_addEventListener(String type, EventListener listener, [bool useCapture]);

  /** @domName WebSocket.close */
  void close([int code, String reason]);

  /** @domName WebSocket.dispatchEvent */
  bool $dom_dispatchEvent(Event evt);

  /** @domName WebSocket.removeEventListener */
  void $dom_removeEventListener(String type, EventListener listener, [bool useCapture]);

  /** @domName WebSocket.send */
  void send(data);
}

abstract class WebSocketEvents implements Events {

  EventListenerList get close;

  EventListenerList get error;

  EventListenerList get message;

  EventListenerList get open;
}