Struct Dialing 

pub struct Dialing { /* private fields */ }

An invitation this side has placed, which the far end has not yet answered.

The calling side’s counterpart of Ringing, and the reason it is a separate entry point is that dial cannot be both. dial waits for the final response inside itself, which is what almost every application wants and is why its signature is unchanged; but an application that wants to do anything while the far end rings has to hold the early dialog, and before this there was no moment at which it could.

What it holds is what the eventual Call will need: the INVITE’s still-open response stream, the media port bound before the offer named it, and — once a provisional creates one — the dialog itself. Self::answered hands all three over rather than rebuilding them, which matters most for the dialog: its sequence space already carries the PRACK and any UPDATE sent while ringing, and a dialog built afresh from the 2xx would restart that space at the INVITE’s own number, putting the first BYE behind a request the far end has already seen (RFC 3261 §12.2.1.1).

Nothing happens on its own. A Dialing dropped without Self::answered or Self::cancel leaves the far end ringing, exactly as a Call dropped without Call::hang_up leaves the far end in a call. The discipline is the application’s: making it implicit would mean withdrawing an invitation from a destructor that cannot await the CANCEL it sends, nor the 200 that may cross it.

Implementations

impl Dialing

pub fn dialog(&self) -> Option<&Dialog>

The early dialog, once a provisional has established one (RFC 3261 §12.1.1).

Exposed read-only because C-2 will want to know which dialog a provisional’s media belongs to — with forking, one invitation can produce several — without this handle having to guess in advance what it will be asked.

pub fn has_early_session(&self) -> bool

Whether the far end has answered this invitation’s offer, in a reliable provisional.

The precondition for Self::update, and worth reading as the question RFC 3311 §5.1 actually asks: not “is there a dialog” but “is there an offer/answer exchange still open”. A 180 with no body establishes the first and does nothing about the second.

pub fn media(&self) -> Option<&MediaSession>

The running early-media session, once a reliable provisional answered the INVITE offer.

None for a bodiless provisional and before an answer arrives. When this is Some, the same session is moved into the Call returned by Self::answered.

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

This attempt’s event stream, continuing on the confirmed call.

Handed out once. A reliable provisional that starts media queues CallEvent::EarlyMediaStarted before this method can return it; the same receiver later observes CallEvent::Answered without being replaced at confirmation.

pub async fn wait_for_early_media(&mut self) -> Result<bool>

Drive this invitation until early media starts or a final response arrives.

dial_early returns on the first early dialog, which may be a bodiless 180; a later reliable 183 can still answer the offer. This method keeps the handle in the application’s ownership while reading through those later provisionals. true means Self::media is now available and CallEvent::EarlyMediaStarted has been emitted. false means the invitation reached a final response first; Self::answered then hands back the already-completed call (or its final error).

Errors

The same provisional, final-refusal, timeout, cancellation, and transaction errors as Self::answered. false reports a successful final response with no early-media phase; the already-completed call is retained for Self::answered.

pub fn peer_allows_update(&self) -> bool

Whether the far end has said it accepts UPDATE (RFC 3311 §4).

Advisory, not enforced: §4 says a UAS “SHOULD” list it, and refusing to send on a peer that merely omitted the header would fail calls that would have worked. Worth checking before Self::update if a 405 would be more expensive than not trying.

pub async fn update(&mut self, direction: Direction) -> Result<()>

Renegotiate the early session from this side (RFC 3311 §5.1).

One implementation of §5.1, shared with Ringing::update: the RFC makes UPDATE something either end may send, so there is one body of rules and two callers rather than a copy per role.

Errors

Error::NoEarlySession if the far end has not answered our offer yet (Self::has_early_session); Error::NoDialog if no provisional established one; and Error::Rejected if the far end refuses, including the 491 of an offer that crossed one of ours.

pub async fn on_update(&mut self, incoming: &Incoming) -> Result<bool>

Answer an UPDATE that arrived in this early dialog (RFC 3311 §5.2).

Returns whether it was one for this dialog, so an application with one inbox can offer everything it receives and act on what is left. The refusals are the same three the answering side gives, because they are the same code.

Errors

Fails only if the response could not be built or sent. A refusal is a successful call: §5.2’s 488 and 500 are responses this stack sends deliberately, not errors here.

pub async fn answered(self) -> Result<Call>

Wait for the invitation to be answered, and take the call it becomes.

Consuming, because everything it needs moves into the Call. Provisionals that arrive while waiting are handled exactly as they were before it returned — PRACKed, and read for the answer that makes the session renegotiable — so an application that calls this immediately is in the same position as one that had called dial.

Errors

Error::Rejected if the far end declined, Error::IntervalTooBrief for a 422 (see dial_early on why it is not retried), Error::Cancelled if the deadline passed — the invitation is withdrawn first — and Error::NoResponse if the transaction ended without a final response.

And, from a provisional rather than from the answer: Error::Sdp or Error::NoCommonCodec if a reliable provisional answers our offer with a description that cannot be used (RFC 3262 §5). That one withdraws the invitation with a CANCEL (RFC 3261 §9.1) rather than waiting for a 2xx to fail on, because a far end that answered no offer of ours may never send one.

pub async fn answered_until<F>(self, cancelled: F) -> Result<Call>

where F: Future<Output = ()> + Send,

Wait for confirmation until cancelled resolves.

Cancellation withdraws the owned invitation before returning, including ACK-then-BYE cleanup for a successful final response already in flight. This closes the ownership gap between dial_early_until returning an early handle and the final answer arriving.

Errors

The same errors as Self::answered. Local cancellation returns Error::Cancelled after cleanup completes.

pub async fn cancel(self)

Give up on the invitation, and make sure the far end stops ringing (RFC 3261 §9.1, §15).

The counterpart of Self::answered, and the reason both consume the handle. A 200 that crosses the CANCEL is acknowledged and then hung up, which §15 requires and a CANCEL cannot do on its own.

pub async fn cancel_with_reason(self, reason: ReasonValue)

Cancel this invitation with an explicit protocol cause.

A SIP 200 reason represents the RFC 3326 §3.1 case where another coupled or forked leg completed the call; other valid SIP and Q.850 causes are retained unchanged.

Trait Implementations

impl Debug for Dialing

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

Formats the value using the given formatter.