OLD | NEW |
(Empty) | |
| 1 The `web_socket_channel` package provides [`StreamChannel`][stream_channel] |
| 2 wrappers for WebSocket connections. It provides a cross-platform |
| 3 [`WebSocketChannel`][WebSocketChannel] API, a cross-platform implementation of |
| 4 that API that communicates over an underlying [`StreamChannel`][stream_channel], |
| 5 and [an implementation][IOWebSocketChannel] that wraps `dart:io`'s `WebSocket` |
| 6 class. |
| 7 |
| 8 [stream_channel]: https://pub.dartlang.org/packages/stream_channel |
| 9 [WebSocketChannel]: https://www.dartdocs.org/documentation/web_socket_channel/la
test/web_socket_channel/WebSocketChannel-class.html |
| 10 [IOWebSocketChannel]: https://www.dartdocs.org/documentation/web_socket_channel/
latest/io/IOWebSocketChannel-class.html |
| 11 |
| 12 ## `WebSocketChannel` |
| 13 |
| 14 The [`WebSocketChannel`][WebSocketChannel] class's most important role is as the |
| 15 interface for WebSocket stream channels across all implementations and all |
| 16 platforms. In addition to the base `StreamChannel` interface, it adds a |
| 17 [`protocol`][protocol] getter that returns the negotiated protocol for the |
| 18 socket; a [`pingInterval`][pingInterval] property that allows you to control the |
| 19 socket's keep-alive behavior; and [`closeCode`][closeCode] and |
| 20 [`closeReason`][closeReason] getters that provide information about why the |
| 21 socket closed. |
| 22 |
| 23 [protocol]: https://www.dartdocs.org/documentation/web_socket_channel/latest/web
_socket_channel/WebSocketChannel/protocol.html |
| 24 [pingInterval]: https://www.dartdocs.org/documentation/web_socket_channel/latest
/web_socket_channel/WebSocketChannel/pingInterval.html |
| 25 [closeCode]: https://www.dartdocs.org/documentation/web_socket_channel/latest/we
b_socket_channel/WebSocketChannel/closeCode.html |
| 26 [closeReason]: https://www.dartdocs.org/documentation/web_socket_channel/latest/
web_socket_channel/WebSocketChannel/closeReason.html |
| 27 |
| 28 The channel's [`sink` property][sink] is also special. It returns a |
| 29 [`WebSocketSink`][WebSocketSink], which is just like a `StreamSink` except that |
| 30 its [`close()`][sink.close] method supports optional `closeCode` and |
| 31 `closeReason` parameters. These parameters allow the caller to signal to the |
| 32 other socket exactly why they're closing the connection. |
| 33 |
| 34 [sink]: https://www.dartdocs.org/documentation/web_socket_channel/latest/web_soc
ket_channel/WebSocketChannel/sink.html |
| 35 [WebSocketSink]: https://www.dartdocs.org/documentation/web_socket_channel/lates
t/web_socket_channel/WebSocketSink-class.html |
| 36 [sink.close]: https://www.dartdocs.org/documentation/web_socket_channel/latest/w
eb_socket_channel/WebSocketSink/close.html |
| 37 |
| 38 `WebSocketChannel` also works as a cross-platform implementation of the |
| 39 WebSocket protocol. Because it can't initiate or handle HTTP requests in a |
| 40 cross-platform way, the [`new WebSocketChannel()` constructor][new] takes an |
| 41 underlying [`StreamChannel`][stream_channel] over which it communicates using |
| 42 the WebSocket protocol. It also provides the static [`signKey()`][signKey] |
| 43 method to make it easier to implement the [initial WebSocket handshake][]. These |
| 44 are used in the [`shelf_web_socket`][shelf_web_socket] package to support |
| 45 WebSockets in a cross-platform way. |
| 46 |
| 47 [new]: https://www.dartdocs.org/documentation/web_socket_channel/latest/web_sock
et_channel/WebSocketChannel/WebSocketChannel.html |
| 48 [signKey]: https://www.dartdocs.org/documentation/web_socket_channel/latest/web_
socket_channel/WebSocketChannel/signKey.html |
| 49 [initial WebSocket handshake]: https://tools.ietf.org/html/rfc6455#section-4.2.2 |
| 50 [shelf_web_socket]: https://pub.dartlang.org/packages/shelf_web_socket |
| 51 |
| 52 ## `IOWebSocketChannel` |
| 53 |
| 54 The [`IOWebSocketChannel`][IOWebSocketChannel] class wraps |
| 55 [`dart:io`'s `WebSocket` class][io.WebSocket]. Because it imports `dart:io`, it |
| 56 has its own library, `package:web_socket_channel/io.dart`. This allows the main |
| 57 `WebSocketChannel` class to be available on all platforms. |
| 58 |
| 59 [io.WebSocket]: https://api.dartlang.org/latest/dart-io/WebSocket-class.html |
| 60 |
| 61 An `IOWebSocketChannel` can be created by passing a `dart:io` WebSocket to |
| 62 [its constructor][new IOWebSocketChannel]. It's more common to want to connect |
| 63 directly to a `ws://` or `wss://` URL, in which case |
| 64 [`new IOWebSocketChannel.connect()`][IOWebSocketChannel.connect] should be used. |
| 65 |
| 66 [new IOWebSocketChannel]: https://www.dartdocs.org/documentation/web_socket_chan
nel/latest/io/IOWebSocketChannel/IOWebSocketChannel.html |
| 67 [IOWebSocketChannel.connect]: https://www.dartdocs.org/documentation/web_socket_
channel/latest/io/IOWebSocketChannel/IOWebSocketChannel.connect.html |
| 68 |
| 69 ```dart |
| 70 import 'package:web_socket_channel/io.dart'; |
| 71 |
| 72 main() async { |
| 73 var channel = new IOWebSocketChannel.connect("ws://localhost:8181"); |
| 74 channel.sink.add("connected!"); |
| 75 channel.sink.listen((message) { |
| 76 // ... |
| 77 }); |
| 78 } |
| 79 ``` |
OLD | NEW |