Struct SessionDescription

Source

pub struct SessionDescription {
    pub kind: SdpType,
    pub sdp: String,
}

Expand description

A session description (offer/answer).

Fields§

§kind: SdpType§sdp: String

Implementations§

Source §

impl SessionDescription

Source

pub fn ice_ufrags(&self) -> Vec<&str>

The ice-ufrag values this description carries, in document order.

One per m-section. Bundled sections repeat the same value; a non-BUNDLE description has a distinct ufrag per transport.

Source

pub fn with_ice_credentials(&self, ufrag: &str, pwd: &str) -> Result<Self>

Return a copy with every ice-ufrag and ice-pwd replaced.

§Why this exists

libwebrtc generates ICE credentials itself and exposes no setter — the SetIceParameters entry point lives on IceTransportInternal, below the public API, and calling it out of band would desync the transport from the description that was signalled. An application that needs to choose its ufrag — routing through an edge relay that demultiplexes on it, for instance — has to do it here instead.

It works because the local description is the source of truth: JsepTransport::SetLocalJsepTransportDescription reads IceParameters straight out of the description’s transport description, and the only guard libwebrtc applies to a local description checks that credentials are present, not that it generated them. tests/ice_credentials.rs verifies this by observation rather than by reading: a loopback whose offerer has substituted credentials connects, which it could not if the transport had kept its own.

§Ordering

Call this on the description returned by create_offer/create_answer and before PeerConnection::set_local_description. Setting the local description is what creates the transport and starts gathering, so substituting afterwards has nothing to act on.

let answer = pc.create_answer()?;
let answer = answer.with_ice_credentials("MyRelayIssuedUfrag00", "aPasswordOfAtLeast22Chars")?;
pc.set_local_description(&answer)?;

§Renegotiation

Changing ice-ufrag/ice-pwd between generations is an ICE restart (RFC 8445 §9): the transport discards its checklist and revalidates. So on a renegotiation that is not meant to restart ICE, re-apply the same values the session already uses. Substituting a fresh pair out of habit — rotating a routing token, say — restarts connectivity checks and can interrupt media.

A renegotiation-time description also differs from a first one in carrying the candidates gathered so far. Those are left untouched, which is correct for this build: it emits a=candidate lines without the optional trailing ufrag token, so no candidate-level value can fall out of step with the substituted media-level one. tests/ice_credentials.rs pins that, since it is an upstream behaviour rather than a guarantee.

§Errors

If either value is outside RFC 8445’s length range or contains a character outside ice-char (ALPHA / DIGIT / "+" / "/"). Rejecting here rather than at set_local_description keeps the failure attributable: libwebrtc reports the same problem as a generic invalid-parameters error much later.

Note that RFC 8839 §5.4 asks a sender to keep the ufrag to 32 characters even though a receiver must accept 256. That is not enforced here, because the range libwebrtc itself accepts is the one that governs interoperation, but staying inside 32 is the safer choice.

Source

pub fn declares_frame_metadata(&self) -> bool

Whether this description declares frame-metadata support.

True when it carries a session-level a=x-reactor-frame-metadata:<version> whose version this build understands (FRAME_METADATA_VERSION). A peer speaking a different trailer format therefore reads as unsupported rather than as a partial match.

Read off the SDP string, not from libwebrtc: it drops a= lines it does not recognise when parsing, so the parsed description never carries this.

This is what PeerConnection::set_remote_description arms the connection’s FrameMetadataGate from.

Source

pub fn declares_dc_chunking(&self) -> bool

Return a copy declaring frame-metadata support, as a session-level attribute.

create_offer already applies this to every offer, and create_answer mirrors the offer — so a caller using this crate’s signalling path never needs it. It is public for callers that assemble or rewrite descriptions themselves.

Idempotent: a description that already declares the capability comes back unchanged, as does one with no lines at all.

§Why a bespoke attribute

The declaration says only “this peer understands the trailer”. An a=extmap would have been the recognisable spelling, but it means “I will send this RTP header extension”, which is not true — no header extension is ever emitted — and it would drag in a shared id namespace that the peer validates (RFC 8843 requires one id to mean one URI across a BUNDLE group), so a collision would surface as the far side’s set_remote_description failing. An unregistered x- attribute claims nothing false and has no id to collide.

The cost is that libwebrtc discards it while parsing, so it is only ever readable from the SDP string. Nothing here depends on the parsed form.

§Placement

Inserted immediately before the first m= line, which is the end of the session section: RFC 8866 §5 puts session-level attributes after t=/z=/k= and before the first media description, and everything preceding the first m= is by definition session level. Whether this description declares data-channel chunking at a version this build speaks (a=x-reactor-dc-chunking:1 …). Read off the SDP string, like declares_frame_metadata.

Source

pub fn with_dc_chunking(&self, params: &DcChunkingParams) -> Self

Return a copy declaring data-channel chunking with params, at session level. Idempotent. PeerConnection::create_offer and create_answer already apply it when the connection takes part, so callers using this crate’s signalling never need it.

Source