https://github.com/dart-lang/web_socket_channel
StreamChannel wrappers for WebSockets.
https://github.com/dart-lang/web_socket_channel
Last synced: 3 months ago
JSON representation
StreamChannel wrappers for WebSockets.
- Host: GitHub
- URL: https://github.com/dart-lang/web_socket_channel
- Owner: dart-lang
- License: bsd-3-clause
- Created: 2016-02-24T19:00:45.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-12-12T10:09:47.000Z (6 months ago)
- Last Synced: 2025-01-15T06:41:48.914Z (5 months ago)
- Language: Dart
- Homepage: https://pub.dev/packages/web_socket_channel
- Size: 236 KB
- Stars: 431
- Watchers: 47
- Forks: 111
- Open Issues: 124
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
> [!IMPORTANT]
> This repo has moved to https://github.com/dart-lang/http/tree/master/pkgs/web_socket_channel
[](https://github.com/dart-lang/web_socket_channel/actions/workflows/test-package.yml)
[](https://pub.dev/packages/web_socket_channel)
[](https://pub.dev/packages/web_socket_channel/publisher)
`package:web_socket_channel` provides cross-platform
[`StreamChannel`][stream_channel] wrappers for WebSocket connections.
## Docs and Usage
It provides a cross-platform
[`WebSocketChannel`][WebSocketChannel] API, a cross-platform implementation of
that API that communicates over an underlying [`StreamChannel`][stream_channel],
[an implementation][IOWebSocketChannel] that wraps `dart:io`'s `WebSocket`
class, and [a similar implementation][HtmlWebSocketChannel] that wraps
`dart:html`'s.
[stream_channel]: https://pub.dev/packages/stream_channel
[WebSocketChannel]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel-class.html
[IOWebSocketChannel]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel.io/IOWebSocketChannel-class.html
[HtmlWebSocketChannel]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel.html/HtmlWebSocketChannel-class.html
It also provides constants for the WebSocket protocol's pre-defined status codes
in the [`status.dart` library][status]. It's strongly recommended that users
import this library with the prefix `status`.
[status]: https://pub.dev/documentation/web_socket_channel/latest/status/status-library.html
```dart
import 'package:web_socket_channel/web_socket_channel.dart';
import 'package:web_socket_channel/status.dart' as status;
main() async {
final wsUrl = Uri.parse('ws://example.com');
final channel = WebSocketChannel.connect(wsUrl);
await channel.ready;
channel.stream.listen((message) {
channel.sink.add('received!');
channel.sink.close(status.goingAway);
});
}
```
## `WebSocketChannel`
The [`WebSocketChannel`][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`][protocol] getter that returns the negotiated protocol for the
socket, as well as [`closeCode`][closeCode] and [`closeReason`][closeReason]
getters that provide information about why the socket closed.
[protocol]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel/protocol.html
[closeCode]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel/closeCode.html
[closeReason]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel/closeReason.html
The channel's [`sink` property][sink] is also special. It returns a
[`WebSocketSink`][WebSocketSink], which is just like a `StreamSink` except that
its [`close()`][sink.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.
[sink]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel/sink.html
[WebSocketSink]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketSink-class.html
[sink.close]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketSink/close.html
`WebSocketChannel` also works as a cross-platform implementation of the
WebSocket protocol. The [`WebSocketChannel.connect` constructor][connect]
connects to a listening server using the appropriate implementation for the
platform.
[connect]: https://pub.dev/documentation/web_socket_channel/latest/web_socket_channel/WebSocketChannel/WebSocketChannel.connect.html