Clone this repo:
  1. 24382b6 Use `drain` to reach end of stream in tests (#75) by Nate Bosch · 12 days ago master 1.0.15
  2. 82692f9 Forward protocols parameter to WebSocket (#74) by choong · 12 days ago
  3. 5f5ca1a Fix pedantic dependency, update links in readme by Kevin Moore · 6 weeks ago 1.0.14
  4. 2342e4e Update to handle Socket implements Stream<Uint8List> (#65) by Todd Volkert · 6 weeks ago
  5. 7b5a488 Declare a return value of `Uint8List` in `BytesBuilder` methods (#58) by Todd Volkert · 3 months ago 1.0.13

The web_socket_channel package provides StreamChannel wrappers for WebSocket connections. It provides a cross-platform WebSocketChannel API, a cross-platform implementation of that API that communicates over an underlying StreamChannel, an implementation that wraps dart:io‘s WebSocket class, and a similar implementation that wrap’s dart:html's.

It also provides constants for the WebSocket protocol‘s pre-defined status codes in the status.dart library. It’s strongly recommended that users import this library should be imported with the prefix status.

import 'package:web_socket_channel/io.dart';
import 'package:web_socket_channel/status.dart' as status;

main() async {
  var channel = IOWebSocketChannel.connect("ws://localhost:1234");

  channel.stream.listen((message) {
    channel.sink.add("received!");
    channel.sink.close(status.goingAway);
  });
}

WebSocketChannel

The WebSocketChannel class's most important role is as the interface for WebSocket stream channels across all implementations and all platforms. In addition to the base StreamChannel interface, it adds a protocol getter that returns the negotiated protocol for the socket, as well as closeCode and closeReason getters that provide information about why the socket closed.

The channel‘s sink property is also special. It returns a WebSocketSink, which is just like a StreamSink except that its close() method supports optional closeCode and closeReason parameters. These parameters allow the caller to signal to the other socket exactly why they’re closing the connection.

WebSocketChannel also works as a cross-platform implementation of the WebSocket protocol. Because it can't initiate or handle HTTP requests in a cross-platform way, the WebSocketChannel() constructor takes an underlying StreamChannel over which it communicates using the WebSocket protocol. It also provides the static signKey() method to make it easier to implement the initial WebSocket handshake. These are used in the shelf_web_socket package to support WebSockets in a cross-platform way.

IOWebSocketChannel

The IOWebSocketChannel class wraps dart:io's WebSocket class. Because it imports dart:io, it has its own library, package:web_socket_channel/io.dart. This allows the main WebSocketChannel class to be available on all platforms.

An IOWebSocketChannel can be created by passing a dart:io WebSocket to its constructor. It's more common to want to connect directly to a ws:// or wss:// URL, in which case IOWebSocketChannel.connect() should be used.

import 'package:web_socket_channel/io.dart';

main() async {
  var channel = IOWebSocketChannel.connect("ws://localhost:8181");
  channel.sink.add("connected!");
  channel.stream.listen((message) {
    // ...
  });
}

HtmlWebSocketChannel

The HtmlWebSocketChannel class wraps dart:html's WebSocket class. Because it imports dart:html, it has its own library, package:web_socket_channel/html.dart. This allows the main WebSocketChannel class to be available on all platforms.

An HtmlWebSocketChannel can be created by passing a dart:html WebSocket to its constructor. It's more common to want to connect directly to a ws:// or wss:// URL, in which case HtmlWebSocketChannel.connect() should be used.

import 'package:web_socket_channel/html.dart';

main() async {
  var channel = HtmlWebSocketChannel.connect("ws://localhost:8181");
  channel.sink.add("connected!");
  channel.stream.listen((message) {
    // ...
  });
}