rtc 0.21.0-alpha.2

Sans-I/O WebRTC implementation in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

//! Data channel event types.
//!
//! Events related to RTCDataChannel lifecycle and buffering state changes.

use crate::data_channel::RTCDataChannelId;

/// Events that can be emitted by an RTCDataChannel.
///
/// These events track the lifecycle and buffer state of data channels.
/// Applications should poll these events from `RTCPeerConnectionEvent::OnDataChannel`
/// to manage data channel connections and implement flow control.
///
/// # Lifecycle Events
///
/// Data channels go through the following lifecycle:
/// 1. `OnOpen` - Channel is ready for data transmission
/// 2. `OnClosing` - Channel is starting to close
/// 3. `OnClose` - Channel is fully closed
/// 4. `OnError` - An error occurred
///
/// # Buffer Events
///
/// - `OnBufferedAmountLow` - Buffer dropped below low-water mark (safe to send more)
/// - `OnBufferedAmountHigh` - Buffer exceeded high-water mark (should pause sending)
///
/// # Examples
///
/// ## Handling data channel events in event loop
///
/// ```
/// use rtc::peer_connection::event::{RTCPeerConnectionEvent, RTCDataChannelEvent};
///
/// # fn example(event: RTCPeerConnectionEvent) {
/// match event {
///     RTCPeerConnectionEvent::OnDataChannel(dc_event) => {
///         match dc_event {
///             RTCDataChannelEvent::OnOpen(channel_id) => {
///                 println!("Data channel opened: {:?}", channel_id);
///             }
///             RTCDataChannelEvent::OnClose(channel_id) => {
///                 println!("Data channel closed: {:?}", channel_id);
///             }
///             RTCDataChannelEvent::OnError(channel_id) => {
///                 eprintln!("Data channel error: {:?}", channel_id);
///             }
///             _ => {}
///         }
///     }
///     _ => {}
/// }
/// # }
/// ```
///
/// ## Implementing flow control with buffer events
///
/// ```
/// use rtc::peer_connection::event::{RTCPeerConnectionEvent, RTCDataChannelEvent};
///
/// # fn example(event: RTCPeerConnectionEvent, paused: &mut bool) {
/// match event {
///     RTCPeerConnectionEvent::OnDataChannel(dc_event) => {
///         match dc_event {
///             RTCDataChannelEvent::OnBufferedAmountLow(channel_id) => {
///                 println!("Buffer low - resume sending");
///                 *paused = false;
///             }
///             RTCDataChannelEvent::OnBufferedAmountHigh(channel_id) => {
///                 println!("Buffer high - pause sending");
///                 *paused = true;
///             }
///             _ => {}
///         }
///     }
///     _ => {}
/// }
/// # }
/// ```
///
/// # See Also
///
/// - [W3C RTCDataChannel](https://www.w3.org/TR/webrtc/#rtcdatachannel)
#[allow(clippy::enum_variant_names)]
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum RTCDataChannelEvent {
    /// Data channel has opened and is ready to send/receive data.
    ///
    /// This event is fired when the data channel transitions to the "open" state.
    /// Data can now be sent through the channel.
    OnOpen(RTCDataChannelId),

    /// An error occurred on the data channel.
    ///
    /// This event is fired when an error is encountered. The channel may still
    /// be usable depending on the error type.
    OnError(RTCDataChannelId),

    /// Data channel is closing.
    ///
    /// This event is fired when the channel begins the closing process.
    /// The channel is transitioning to the "closing" state.
    OnClosing(RTCDataChannelId),

    /// Data channel has closed.
    ///
    /// This event is fired when the channel is fully closed and no longer usable.
    /// No more data can be sent or received.
    OnClose(RTCDataChannelId),

    /// Buffered amount dropped below the low-water mark.
    ///
    /// This event is fired when the amount of buffered outgoing data drops
    /// below the threshold set by `set_buffered_amount_low_threshold()`.
    /// This indicates it's safe to send more data without causing excessive buffering.
    ///
    /// Use this event to implement flow control and prevent memory exhaustion.
    OnBufferedAmountLow(RTCDataChannelId),

    /// Buffered amount exceeded the high-water mark (implementation-specific).
    ///
    /// This is a non-standard event that can be used to detect when too much
    /// data is being buffered. Applications should pause sending when this fires.
    OnBufferedAmountHigh(RTCDataChannelId),
}

impl Default for RTCDataChannelEvent {
    fn default() -> Self {
        Self::OnOpen(Default::default())
    }
}