From 942e897bf542944e46eb7eb8b7f1264667f72e74 Mon Sep 17 00:00:00 2001
From: Brian Quinlan <bquinlan@google.com>
Date: Mon, 30 Oct 2023 16:53:17 +0000
Subject: [PATCH] [doc/io] Add a RawSocketEvent example.

Bug: https://github.com/dart-lang/sdk/issues/33721
Change-Id: I4e8f35cec8d3e689469a63826d118cfa2fe42218
CoreLibraryReviewExempt: Documentation-only change
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/277701
Reviewed-by: Alexander Aprelev <aam@google.com>
Commit-Queue: Brian Quinlan <bquinlan@google.com>
---
 sdk/lib/io/socket.dart | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/sdk/lib/io/socket.dart b/sdk/lib/io/socket.dart
index bf784855452..710db83312a 100644
--- a/sdk/lib/io/socket.dart
+++ b/sdk/lib/io/socket.dart
@@ -464,11 +464,42 @@ final class RawSocketOption {
   external static int _getOptionValue(int key);
 }
 
-/// Events for the [RawSocket].
+/// Events for the [RawDatagramSocket], [RawSecureSocket], and [RawSocket].
 ///
-/// These event objects are used by the [Stream] behavior of [RawSocket]
+/// These event objects are used by the [Stream] behavior of the sockets
 /// (for example [RawSocket.listen], [RawSocket.forEach])
 /// when the socket's state change.
+///
+/// ```dart
+/// import 'dart:convert';
+/// import 'dart:io';
+///
+/// void main() async {
+///   final socket = await RawSocket.connect("example.com", 80);
+///
+///   socket.listen((event) {
+///     switch (event) {
+///       case RawSocketEvent.read:
+///         final data = socket.read();
+///         if (data != null) {
+///           print(ascii.decode(data));
+///         }
+///         break;
+///       case RawSocketEvent.write:
+///         socket.write(ascii.encode('GET /\r\nHost: example.com\r\n\r\n'));
+///         socket.writeEventsEnabled = false;
+///         break;
+///       case RawSocketEvent.readClosed:
+///         socket.close();
+///         break;
+///       case RawSocketEvent.closed:
+///         break;
+///       default:
+///         throw "Unexpected event $event";
+///     }
+///   });
+/// }
+/// ```
 class RawSocketEvent {
   /// An event indicates the socket is ready to be read.
   static const RawSocketEvent read = const RawSocketEvent._(0);