Dart RawSocketEvent
last modified October 18, 2026
The RawSocketEvent class in Dart represents events that occur on
a raw socket connection. It's used with RawSocket for low-level
network communication.
RawSocketEvent provides event types for read, write, readClosed, and closed
states. It's part of Dart's dart:io library for non-web applications.
Basic Definition
RawSocketEvent is an enum-like class that defines socket events.
These events are triggered during socket operations and must be handled.
The events are read for incoming data, write for
output readiness, readClosed when the remote side stops sending,
and closed when the socket is closed. Errors are reported through
the stream's error handler, not as event values.
Basic Socket Event Handling
This example shows basic event handling with RawSocketEvent.
import 'dart:io';
void main() async {
var socket = await RawSocket.connect('example.com', 80);
socket.listen((event) {
switch (event) {
case RawSocketEvent.read:
var data = socket.read();
if (data != null) {
print('Data available to read');
}
break;
case RawSocketEvent.write:
print('Ready to send data');
socket.write('GET / HTTP/1.1\r\nHost: example.com\r\n'
'Connection: close\r\n\r\n'.codeUnits);
socket.writeEventsEnabled = false;
break;
case RawSocketEvent.readClosed:
print('Reading closed');
socket.close();
break;
case RawSocketEvent.closed:
print('Connection closed');
break;
}
});
}
We connect to a server and listen for socket events. The listen callback receives RawSocketEvent values indicating socket state changes.
$ dart main.dart Ready to send data Data available to read Reading closed Connection closed
Reading Data on READ Event
This example demonstrates reading data when READ events occur.
import 'dart:io';
import 'dart:convert';
void main() async {
var socket = await RawSocket.connect('example.com', 80);
var request = 'GET / HTTP/1.1\r\nHost: example.com\r\n'
'Connection: close\r\n\r\n';
socket.write(request.codeUnits);
socket.listen((event) {
if (event == RawSocketEvent.read) {
var data = socket.read();
if (data != null) {
print(utf8.decode(data));
}
} else if (event == RawSocketEvent.readClosed) {
socket.close();
} else if (event == RawSocketEvent.closed) {
socket.close();
}
});
}
We send an HTTP request and read the response when READ events occur. The socket.read() method returns available data as a byte list.
$ dart main.dart HTTP/1.1 200 OK Content-Type: text/html; charset=UTF-8 ...
Handling Write Events
This example shows how to handle WRITE events for efficient data sending.
import 'dart:io';
void main() async {
var socket = await RawSocket.connect('localhost', 8080);
var messages = ['Hello', 'World', 'From', 'Dart'];
var index = 0;
socket.listen((event) {
if (event == RawSocketEvent.write && index < messages.length) {
socket.write(messages[index++].codeUnits);
print('Sent: ${messages[index-1]}');
}
if (index == messages.length) {
socket.shutdown(SocketDirection.send);
}
});
socket.writeEventsEnabled = true;
}
We send messages only when the socket is ready to write. WRITE events indicate when the socket can accept more data without blocking.
$ dart main.dart Sent: Hello Sent: World Sent: From Sent: Dart
Handling Socket Errors
This example demonstrates handling connection and stream errors on a socket.
import 'dart:io';
void main() async {
try {
var socket = await RawSocket.connect('invalid.host', 80);
socket.listen((event) {
if (event == RawSocketEvent.read) {
var data = socket.read();
if (data != null) {
print('Data received');
}
} else if (event == RawSocketEvent.readClosed) {
print('Connection closed');
socket.close();
} else if (event == RawSocketEvent.closed) {
socket.close();
}
}, onError: (error) {
print('Error occurred on socket: $error');
socket.close();
});
} on SocketException catch (e) {
print('Connection failed: ${e.message}');
}
}
We handle both connection errors and runtime socket errors. Connection errors
are thrown by connect, while runtime errors are delivered to the
stream's onError handler.
$ dart main.dart Connection failed: Failed host lookup: 'invalid.host'
Complete Socket Client
This example shows a complete socket client with all event types.
import 'dart:io';
import 'dart:convert';
void main() async {
try {
var socket = await RawSocket.connect('example.com', 80);
var request = 'GET / HTTP/1.1\r\nHost: example.com\r\n'
'Connection: close\r\n\r\n';
socket.listen((event) {
switch (event) {
case RawSocketEvent.read:
var data = socket.read();
if (data != null) {
var text = utf8.decode(data, allowMalformed: true);
print(text.split('\r\n').first);
}
break;
case RawSocketEvent.write:
socket.write(request.codeUnits);
socket.writeEventsEnabled = false;
break;
case RawSocketEvent.readClosed:
print('Read closed by server');
socket.close();
break;
case RawSocketEvent.closed:
print('Connection closed by server');
socket.close();
break;
}
}, onError: (error) {
print('Socket error: $error');
socket.close();
});
} on SocketException catch (e) {
print('Connection error: ${e.message}');
}
}
This complete example handles all socket events: initial writing, reading response data, and proper cleanup on closure or errors.
$ dart main.dart HTTP/1.1 200 OK Read closed by server Connection closed by server
Best Practices
- Enable events: Set writeEventsEnabled only when needed
- Error handling: Always handle stream errors and closure events
- Resource cleanup: Close sockets when done
- Buffer management: Read all available data on READ events
- Throttling: Control write rates using WRITE events
Source
Dart RawSocketEvent Documentation
This tutorial covered Dart's RawSocketEvent class with practical examples showing event handling, data transfer, and error management for socket programming.
Author
List all Dart tutorials.