Events: Break out and non-exhaust context body structs (#54)

This PR makes many of the types under `EventContext` separate `#[non_exhaustive]` structs. This makes it more feasible to add further information to connection and packet events as required in future. On this note, driver (re)connection events now include the SSRC supplied by Discord and the domain name which was connected to.

In addition, this fixes global timed events to return a list of all live tracks, and extensively details/documents events at a high level.

This was tested using `cargo make ready`.

src/events/context/data/connect.rs

@@ -0,0 +1,21 @@
+/// Voice connection details gathered at setup/reinstantiation.
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+#[non_exhaustive]
+pub struct ConnectData<'a> {
+    /// The domain name of Discord's voice/TURN server.
+    ///
+    /// With the introduction of Discord's automatic voice server selection,
+    /// this is no longer guaranteed to match a server's settings. This field
+    /// may be useful if you need/wish to move your voice connection to a node/shard
+    /// closer to Discord.
+    pub server: &'a str,
+    /// The [RTP SSRC] *("Synchronisation source")* assigned by the voice server
+    /// for the duration of this call.
+    ///
+    /// All packets sent will use this SSRC, which is not related to the sender's User
+    /// ID. These are usually allocated sequentially by Discord, following on from
+    /// a random starting SSRC.
+    ///
+    /// [RTP SSRC]: https://tools.ietf.org/html/rfc3550#section-3
+    pub ssrc: u32,
+}

src/events/context/data/mod.rs

@@ -0,0 +1,11 @@
+//! Types containing the main body of an [`EventContext`].
+//!
+//! [`EventContext`]: super::EventContext
+mod connect;
+mod rtcp;
+mod speaking;
+mod voice;
+
+use discortp::{rtcp::Rtcp, rtp::Rtp};
+
+pub use self::{connect::*, rtcp::*, speaking::*, voice::*};

src/events/context/data/rtcp.rs

@@ -0,0 +1,15 @@
+use super::*;
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[non_exhaustive]
+/// Telemetry/statistics packet, received from another stream (detailed in `packet`).
+/// `payload_offset` contains the true payload location within the raw packet's `payload()`,
+/// to allow manual decoding of `Rtcp` packet bodies.
+pub struct RtcpData<'a> {
+    /// Raw RTCP packet data.
+    pub packet: &'a Rtcp,
+    /// Byte index into the packet body (after headers) for where the payload begins.
+    pub payload_offset: usize,
+    /// Number of bytes at the end of the packet to discard.
+    pub payload_end_pad: usize,
+}

src/events/context/data/speaking.rs

@@ -0,0 +1,14 @@
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+#[non_exhaustive]
+/// Speaking state transition, describing whether a given source has started/stopped
+/// transmitting. This fires in response to a silent burst, or the first packet
+/// breaking such a burst.
+pub struct SpeakingUpdateData {
+    /// Whether this user is currently speaking.
+    pub speaking: bool,
+    /// Synchronisation Source of the user who has begun speaking.
+    ///
+    /// This must be combined with another event class to map this back to
+    /// its original UserId.
+    pub ssrc: u32,
+}

src/events/context/data/voice.rs

@@ -0,0 +1,20 @@
+use super::*;
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+#[non_exhaustive]
+/// Opus audio packet, received from another stream (detailed in `packet`).
+/// `payload_offset` contains the true payload location within the raw packet's `payload()`,
+/// if extensions or raw packet data are required.
+/// If `audio.len() == 0`, then this packet arrived out-of-order.
+pub struct VoiceData<'a> {
+    /// Decoded audio from this packet.
+    pub audio: &'a Option<Vec<i16>>,
+    /// Raw RTP packet data.
+    ///
+    /// Includes the SSRC (i.e., sender) of this packet.
+    pub packet: &'a Rtp,
+    /// Byte index into the packet body (after headers) for where the payload begins.
+    pub payload_offset: usize,
+    /// Number of bytes at the end of the packet to discard.
+    pub payload_end_pad: usize,
+}