// 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.
 */
interface WebSocket extends EventTarget default _WebSocketFactoryProvider {

  WebSocket(String url);

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

  static final int CLOSED = 3;

  static final int CLOSING = 2;

  static final int CONNECTING = 0;

  static final int OPEN = 1;

  /** @domName WebSocket.URL */
  final String URL;

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

  /** @domName WebSocket.bufferedAmount */
  final int bufferedAmount;

  /** @domName WebSocket.extensions */
  final String extensions;

  /** @domName WebSocket.protocol */
  final String protocol;

  /** @domName WebSocket.readyState */
  final int readyState;

  /** @domName WebSocket.url */
  final String 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 */
  bool send(String data);
}

interface WebSocketEvents extends Events {

  EventListenerList get close();

  EventListenerList get error();

  EventListenerList get message();

  EventListenerList get open();
}