From edbb5a9711570afa46e2ae9fca8cf8366f672715 Mon Sep 17 00:00:00 2001
From: Brian Quinlan <brian@sweetapp.com>
Date: Fri, 12 Jul 2024 18:13:36 -0700
Subject: [PATCH] Add WebSocket usage examples to cupertino_http (#1266)

---
 pkgs/cupertino_http/README.md                 | 32 +++++++++++++++++--
 .../lib/src/cupertino_web_socket.dart         | 22 +++++++++++++
 2 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/pkgs/cupertino_http/README.md b/pkgs/cupertino_http/README.md
index ef5c9fff8c..0e12a6ef08 100644
--- a/pkgs/cupertino_http/README.md
+++ b/pkgs/cupertino_http/README.md
@@ -46,6 +46,31 @@ void main() async {
 }
 ```
 
+[CupertinoWebSocket][] provides a [package:web_socket][] [WebSocket][]
+implementation.
+
+```dart
+import 'package:cupertino_http/cupertino_http.dart';
+import 'package:web_socket/web_socket.dart';
+
+void main() async {
+  final socket = await CupertinoWebSocket.connect(
+      Uri.parse('wss://ws.postman-echo.com/raw'));
+
+  socket.events.listen((e) async {
+    switch (e) {
+      case TextDataReceived(text: final text):
+        print('Received Text: $text');
+        await socket.close();
+      case BinaryDataReceived(data: final data):
+        print('Received Binary: $data');
+      case CloseReceived(code: final code, reason: final reason):
+        print('Connection to server closed: $code [$reason]');
+    }
+  });
+}
+```
+
 You can also use the [Foundation URL Loading System] API directly.
 
 ```dart
@@ -63,6 +88,9 @@ final task = session.dataTaskWithCompletionHandler(URLRequest.fromUrl(url),
 task.resume();
 ```
 
-[package:http Client]: https://pub.dev/documentation/http/latest/http/Client-class.html
-[Foundation URL Loading System]: https://developer.apple.com/documentation/foundation/url_loading_system
+[CupertinoWebSocket]: https://pub.dev/documentation/cupertino_http/latest/cupertino_http/CupertinoWebSocket-class.html
 [dart:io HttpClient]: https://api.dart.dev/stable/dart-io/HttpClient-class.html
+[Foundation URL Loading System]: https://developer.apple.com/documentation/foundation/url_loading_system
+[package:http Client]: https://pub.dev/documentation/http/latest/http/Client-class.html
+[package:web_socket]: https://pub.dev/packages/web_socket
+[WebSocket]: https://pub.dev/documentation/web_socket/latest/web_socket/WebSocket-class.html
diff --git a/pkgs/cupertino_http/lib/src/cupertino_web_socket.dart b/pkgs/cupertino_http/lib/src/cupertino_web_socket.dart
index 666c018835..b374dd9907 100644
--- a/pkgs/cupertino_http/lib/src/cupertino_web_socket.dart
+++ b/pkgs/cupertino_http/lib/src/cupertino_web_socket.dart
@@ -25,6 +25,28 @@ class ConnectionException extends WebSocketException {
 ///
 /// NOTE: the [WebSocket] interface is currently experimental and may change in
 /// the future.
+///
+/// ```dart
+/// import 'package:cupertino_http/cupertino_http.dart';
+/// import 'package:web_socket/web_socket.dart';
+///
+/// void main() async {
+///   final socket = await CupertinoWebSocket.connect(
+///       Uri.parse('wss://ws.postman-echo.com/raw'));
+///
+///   socket.events.listen((e) async {
+///     switch (e) {
+///       case TextDataReceived(text: final text):
+///         print('Received Text: $text');
+///         await socket.close();
+///       case BinaryDataReceived(data: final data):
+///         print('Received Binary: $data');
+///       case CloseReceived(code: final code, reason: final reason):
+///         print('Connection to server closed: $code [$reason]');
+///     }
+///   });
+/// }
+/// ```
 class CupertinoWebSocket implements WebSocket {
   /// Create a new WebSocket connection using the
   /// [NSURLSessionWebSocketTask API](https://developer.apple.com/documentation/foundation/nsurlsessionwebsockettask).