Struct Invitation 

pub struct Invitation { /* private fields */ }

An incoming call: the INVITE, and the inbox of the call it may become.

The inbox exists before the application has decided anything, and that is the point. The ACK to our own 2xx can arrive before answer has returned, so a route installed only once a Call existed would have nowhere to put it.

Dropping this without answering releases the route: the next request for that dialog is answered as an unknown one rather than queued for a call that will never exist.

It is also what a CANCEL for this INVITE ends (RFC 3261 §9.2). The dispatcher answers the CANCEL itself — is_cancelled and events are how an application finds out, and answer is how it is stopped from accepting an invitation the caller has already withdrawn.

Implementations

impl Invitation

pub fn request(&self) -> &Incoming

The INVITE, to answer, ring or refuse.

pub fn is_cancelled(&self) -> bool

Whether the caller withdrew this invitation before it was answered (RFC 3261 §9.2).

True from the moment the dispatcher has answered a matching CANCEL, which is also the moment it sent the 487 that ended the INVITE transaction. There is nothing left to accept: Self::answer refuses with Error::InvitationCancelled from here on.

This is the poll. Self::events is the push, and an application that is ringing wants that one — it has to be told to stop, not remember to ask.

pub fn events(&mut self) -> Option<CallEvents>

This invitation’s event stream, handed out exactly once.

Returns None on every call after the first, the same contract Call::events has and for the same reason: there is one consumer by construction rather than a value a second reader could be cloned from.

Exactly one event is ever emitted on it — CallEvent::Ended(EndCause::RemoteCancel), when the caller gives up. An invitation that is answered produces no event here: it becomes a Call, which has a stream of its own that starts with Answered.

pub async fn answer( &self, endpoint: &Handle, media_address: IpAddr, ) -> Result<Call>

Answer this invitation, unless the caller has already withdrawn it.

crate::answer with two things the free function cannot know, both of which come from the invitation owning the INVITE’s server transaction:

• It fails with Error::InvitationCancelled once a CANCEL has ended the transaction, rather than putting a 200 on a transaction that already carried a 487.
• It records that a final response has gone out, which is what makes a CANCEL arriving afterwards the no-op RFC 3261 §9.2 requires instead of a teardown.

The To tag is the invitation’s own, so the 200 accepting it and the 200 answering a late CANCEL agree on one, which is §9.2’s SHOULD.

Prefer this to crate::answer on anything a Dispatcher surfaced. The free function still works and still answers correctly — it simply cannot tell the dispatcher what it did, so a CANCEL that arrives around it is judged on the transaction’s last known state.

Answers from the default codec set, Codecs::G711. Self::answer_with takes a selection.

pub async fn answer_with( &self, endpoint: &Handle, media_address: IpAddr, codecs: Codecs, ) -> Result<Call>

Self::answer, from a chosen codec set rather than the default one (M-30).

The dispatcher’s counterpart of crate::answer_with. This exists rather than being left to the free function because this is the path the docs above tell an application to prefer: a selection reachable only through crate::answer_with would be a selection every dispatched call has to give up cancellation bookkeeping to make.

pub async fn answer_with_policy( &self, endpoint: &Handle, media_address: IpAddr, policy: MediaPolicy, ) -> Result<Call>

Self::answer, using one coherent codec and ICE policy.

pub async fn answer_with_policy_at( &self, endpoint: &Handle, media_address: MediaAddress, policy: MediaPolicy, ) -> Result<Call>

Self::answer_with_policy with independent advertised and bound media addresses.

pub async fn trying(&self, endpoint: &Handle) -> Result<()>

Send the optional 100 Trying used by a signalling workload.

A 100 creates neither an early dialog nor a final-response claim, so a matching CANCEL may still end this invitation afterwards. It deliberately carries no To tag (RFC 3261 §8.2.6.2).

pub async fn answer_signalling( self, endpoint: &Handle, contact: impl Into<Bytes>, ) -> Result<SignallingCall>

Accept an SDP-free INVITE as a signalling-only confirmed dialog.

No media socket or task is created. The returned SignallingCall owns the reserved per-dialog inbox, retransmits this 2xx until a valid ACK, validates BYE, and can originate a bounded BYE of its own. contact is the local dialog target advertised in the final response.

pub async fn answer_signalling_with_tag( self, endpoint: &Handle, contact: impl Into<Bytes>, tag: impl Into<String>, ) -> Result<SignallingCall>

Self::answer_signalling with an application-selected, validated dialog tag.

This exists for deterministic protocol fixtures. The tag is claimed atomically with the invitation, so a crossing CANCEL either wins with the old pending tag or loses and uses this same tag in its own response; the two transactions cannot disagree.

pub async fn refuse( &self, endpoint: &Handle, status: u16, reason: impl Into<Bytes>, ) -> Result<()>

Refuse this pending invitation with a final response.

The dispatcher’s cancellation state is claimed before the response leaves, so a crossing CANCEL receives its own 200 but cannot also replace this final response with 487.

pub fn into_parts(self) -> (Incoming, Receiver<Incoming>)

Split into the INVITE and the inbox, ready for answer and serve.

What is given up is the cancellation state: Self::is_cancelled and Self::answer go with it. The dispatcher keeps answering CANCELs for this transaction either way — the table owns that, not this handle — so what is lost is the application’s view of it, which is why this is the call to make after answering rather than instead of it.

Trait Implementations

impl Debug for Invitation

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.