| // 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. |
| |
| /** |
| * Web socket status codes used when closing a web socket connection. |
| */ |
| abstract class WebSocketStatus { |
| static const int NORMAL_CLOSURE = 1000; |
| static const int GOING_AWAY = 1001; |
| static const int PROTOCOL_ERROR = 1002; |
| static const int UNSUPPORTED_DATA = 1003; |
| static const int RESERVED_1004 = 1004; |
| static const int NO_STATUS_RECEIVED = 1005; |
| static const int ABNORMAL_CLOSURE = 1006; |
| static const int INVALID_FRAME_PAYLOAD_DATA = 1007; |
| static const int POLICY_VIOLATION = 1008; |
| static const int MESSAGE_TOO_BIG = 1009; |
| static const int MISSING_MANDATORY_EXTENSION = 1010; |
| static const int INTERNAL_SERVER_ERROR = 1011; |
| static const int RESERVED_1015 = 1015; |
| } |
| |
| /** |
| * The web socket protocol is implemented by a HTTP server handler |
| * which can be instantiated like this: |
| * |
| * WebSocketHandler wsHandler = new WebSocketHandler(); |
| * |
| * and then its onRequest method can be assigned to the HTTP server, e.g. |
| * |
| * server.defaultHandler = wsHandler.onRequest; |
| * |
| * or |
| * |
| * server.addRequestHandler((req) => req.path == "/ws", |
| * wsHandler.onRequest); |
| * |
| * This handler strives to implement web sockets as specified by RFC6455. |
| */ |
| abstract class WebSocketHandler { |
| factory WebSocketHandler() => new _WebSocketHandler(); |
| |
| /** |
| * Request handler to be registered with the HTTP server. |
| */ |
| void onRequest(HttpRequest request, HttpResponse response); |
| |
| /** |
| * Sets the callback to be called when a new web socket connection |
| * has been established. |
| */ |
| void set onOpen(callback(WebSocketConnection connection)); |
| } |
| |
| |
| /** |
| * Server web socket connection. |
| */ |
| abstract class WebSocketConnection { |
| /** |
| * Sets the callback to be called when a message have been |
| * received. The type on [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:]. |
| */ |
| void set onMessage(void callback(message)); |
| |
| /** |
| * Sets the callback to be called when the web socket connection is |
| * closed. [status] indicate the reason for closing. For network |
| * errors the value of [status] will be |
| * WebSocketStatus.ABNORMAL_CLOSURE]. In this callbach it is |
| * possible to call [close] if [close] has not already been called. |
| * If [close] has still not been called after the close callback |
| * returns the received close status will automatically be echoed |
| * back to the other end to finish the close handshake. |
| */ |
| void set onClosed(void callback(int status, String reason)); |
| |
| /** |
| * Sends a message. The [message] must be a [:String:] a |
| * [:List<int>:] or [:null:]. |
| */ |
| send(Object message); |
| |
| /** |
| * Close the web socket connection. The default value for [status] |
| * and [reason] are [:null:]. |
| */ |
| close([int status, String reason]); |
| |
| /** |
| * WebSocketConnection is hashable. |
| */ |
| int get hashCode; |
| } |
| |
| |
| /** |
| * Client web socket connection. |
| */ |
| abstract class WebSocketClientConnection { |
| /** |
| * Creates a new web socket client connection based on a HTTP client |
| * connection. The HTTP client connection must be freshly opened. |
| */ |
| factory WebSocketClientConnection(HttpClientConnection conn, |
| [List<String> protocols]) { |
| return new _WebSocketClientConnection(conn, protocols); |
| } |
| |
| /** |
| * Sets the callback to be called when the request object for the |
| * opening handshake request is ready. This callback can be used if |
| * one need to add additional headers to the opening handshake |
| * request. |
| */ |
| void set onRequest(void callback(HttpClientRequest request)); |
| |
| /** |
| * Sets the callback to be called when a web socket connection has |
| * been established. |
| */ |
| void set onOpen(void callback()); |
| |
| /** |
| * Sets the callback to be called when a message have been |
| * received. 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:]. |
| */ |
| void set onMessage(void callback(message)); |
| |
| /** |
| * Sets the callback to be called when the web socket connection is |
| * closed. [status] indicate the reason for closing. For network |
| * errors the value of [status] will be |
| * WebSocketStatus.ABNORMAL_CLOSURE]. |
| */ |
| void set onClosed(void callback(int status, String reason)); |
| |
| /** |
| * Sets the callback to be called when the response object for the |
| * opening handshake did not cause a web socket connection |
| * upgrade. This will be called in case the response status code is |
| * not 101 (Switching Protocols). If this callback is not set the |
| * [:onError:] callback will be called if the server did not upgrade |
| * the connection. |
| */ |
| void set onNoUpgrade(void callback(HttpClientResponse response)); |
| |
| /** |
| * Sends a message. The [message] must be a [:String:] or a |
| * [:List<int>:]. To send an empty message use either an empty |
| * [:String:] or an empty [:List<int>:]. [:null:] cannot be used. |
| */ |
| send(message); |
| |
| /** |
| * Close the web socket connection. The default value for [status] |
| * and [reason] are [:null:]. |
| */ |
| close([int status, String reason]); |
| |
| /** |
| * WebSocketClientConnection is hashable. |
| */ |
| int get hashCode; |
| } |
| |
| |
| /** |
| * Base class for the events generated by the W3C complient browser |
| * API for web sockets. |
| */ |
| abstract class Event { } |
| |
| /** |
| * Event delivered when there is data on a web socket connection. |
| */ |
| abstract class MessageEvent extends Event { |
| /** |
| * 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. |
| */ |
| abstract class CloseEvent extends Event { |
| /** |
| * Returns whether the connection was closed cleanly or not. |
| */ |
| bool get wasClean; |
| |
| /** |
| * Returns the web socket connection close code provided by the |
| * server. |
| */ |
| int get code; |
| |
| /** |
| * Returns the web socket connection close reason provided by the |
| * server. |
| */ |
| 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/. |
| */ |
| abstract class WebSocket { |
| /** |
| * Possible states of the connection. |
| */ |
| static const int CONNECTING = 0; |
| static const int OPEN = 1; |
| static const int CLOSING = 2; |
| static const 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 |
| * client is willing to speak. |
| */ |
| factory WebSocket(String url, [protocols]) => new _WebSocket(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(void callback()); |
| |
| /** |
| * Sets the callback to be called when the web socket connection |
| * encountered an error. |
| */ |
| void set onerror(void callback(e)); |
| |
| /** |
| * Sets the callback to be called when the web socket connection is |
| * closed. |
| */ |
| void set onclose(void callback(CloseEvent 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(MessageEvent 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; |
| } |