ruma_events/call/
candidates.rs

Help
1//! Types for the [`m.call.candidates`] event.
2//!
3//! [`m.call.candidates`]: https://spec.matrix.org/latest/client-server-api/#mcallcandidates
4
5use js_int::UInt;
6use ruma_common::{OwnedVoipId, VoipVersionId};
7use ruma_macros::EventContent;
8use serde::{Deserialize, Serialize};
9
10/// The content of an `m.call.candidates` event.
11///
12/// This event is sent by callers after sending an invite and by the callee after answering. Its
13/// purpose is to give the other party additional ICE candidates to try using to communicate.
14#[derive(Clone, Debug, Deserialize, Serialize, EventContent)]
15#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
16#[ruma_event(type = "m.call.candidates", kind = MessageLike)]
17pub struct CallCandidatesEventContent {
18    /// A unique identifier for the call.
19    pub call_id: OwnedVoipId,
20
21    /// **Required in VoIP version 1.** The unique ID for this session for the duration of the
22    /// call.
23    ///
24    /// Must be the same as the one sent by the previous invite or answer from
25    /// this session.
26    #[serde(skip_serializing_if = "Option::is_none")]
27    pub party_id: Option<OwnedVoipId>,
28
29    /// A list of candidates.
30    ///
31    /// In VoIP version 1, this list should end with a `Candidate` with an empty `candidate` field
32    /// when no more candidates will be sent.
33    pub candidates: Vec<Candidate>,
34
35    /// The version of the VoIP specification this messages adheres to.
36    pub version: VoipVersionId,
37}
38
39impl CallCandidatesEventContent {
40    /// Creates a new `CallCandidatesEventContent` with the given call id, candidate list and VoIP
41    /// version.
42    pub fn new(call_id: OwnedVoipId, candidates: Vec<Candidate>, version: VoipVersionId) -> Self {
43        Self { call_id, candidates, version, party_id: None }
44    }
45
46    /// Convenience method to create a VoIP version 0 `CallCandidatesEventContent` with all the
47    /// required fields.
48    pub fn version_0(call_id: OwnedVoipId, candidates: Vec<Candidate>) -> Self {
49        Self::new(call_id, candidates, VoipVersionId::V0)
50    }
51
52    /// Convenience method to create a VoIP version 1 `CallCandidatesEventContent` with all the
53    /// required fields.
54    pub fn version_1(
55        call_id: OwnedVoipId,
56        party_id: OwnedVoipId,
57        candidates: Vec<Candidate>,
58    ) -> Self {
59        Self { call_id, party_id: Some(party_id), candidates, version: VoipVersionId::V1 }
60    }
61}
62
63/// An ICE (Interactive Connectivity Establishment) candidate.
64#[derive(Clone, Debug, Deserialize, Serialize)]
65#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
66#[serde(rename_all = "camelCase")]
67pub struct Candidate {
68    /// The SDP "a" line of the candidate.
69    pub candidate: String,
70
71    /// The SDP media type this candidate is intended for.
72    ///
73    /// At least one of `sdp_mid` or `sdp_m_line_index` is required, unless
74    /// `candidate` is empty.
75    #[serde(skip_serializing_if = "Option::is_none")]
76    pub sdp_mid: Option<String>,
77
78    /// The index of the SDP "m" line this candidate is intended for.
79    ///
80    /// At least one of `sdp_mid` or `sdp_m_line_index` is required, unless
81    /// `candidate` is empty.
82    #[serde(skip_serializing_if = "Option::is_none")]
83    pub sdp_m_line_index: Option<UInt>,
84}
85
86impl Candidate {
87    /// Creates a new `Candidate` with the given "a" line.
88    pub fn new(candidate: String) -> Self {
89        Self { candidate, sdp_mid: None, sdp_m_line_index: None }
90    }
91
92    /// Creates a new `Candidate` with all the required fields in VoIP version 0.
93    pub fn version_0(candidate: String, sdp_mid: String, sdp_m_line_index: UInt) -> Self {
94        Self { candidate, sdp_mid: Some(sdp_mid), sdp_m_line_index: Some(sdp_m_line_index) }
95    }
96}
ruma_events/call/candidates.rs

ruma_events/call/
candidates.rs
