Struct ClientInviteDialog 

pub struct ClientInviteDialog { /* private fields */ }

Client-side INVITE Dialog (UAC)

ClientInviteDialog represents a client-side INVITE dialog in SIP. This is used when the local user agent acts as a User Agent Client (UAC) and initiates an INVITE transaction to establish a session with a remote party.

Key Features

• Session Initiation - Initiates INVITE transactions to establish calls
• In-dialog Requests - Sends UPDATE, INFO, OPTIONS within established dialogs
• Session Termination - Handles BYE and CANCEL for ending sessions
• Re-INVITE Support - Supports session modification via re-INVITE
• Authentication - Handles 401/407 authentication challenges
• State Management - Tracks dialog state transitions

Dialog Lifecycle

1. Creation - Dialog created when sending INVITE
2. Early State - Receives provisional responses (1xx)
3. Confirmed - Receives 2xx response and sends ACK
4. Active - Can send in-dialog requests (UPDATE, INFO, etc.)
5. Termination - Sends BYE or CANCEL to end session

Examples

Basic Call Flow

// After dialog is established:

// Send an UPDATE request
let response = dialog.update(None, Some(new_sdp_body)).await?;

// Send INFO request
let response = dialog.info(None, Some(info_body)).await?;

// End the call
dialog.bye().await?;

Session Modification

// Modify session with re-INVITE
let headers = vec![
    rsip::Header::ContentType("application/sdp".into())
];
let response = dialog.reinvite(Some(headers), Some(new_sdp)).await?;

if let Some(resp) = response {
    if resp.status_code == rsip::StatusCode::OK {
        println!("Session modified successfully");
    }
}

Thread Safety

ClientInviteDialog is thread-safe and can be cloned and shared across tasks. All operations are atomic and properly synchronized.

Implementations

impl ClientInviteDialog

pub fn id(&self) -> DialogId

Get the dialog identifier

Returns the unique DialogId that identifies this dialog instance. The DialogId consists of Call-ID, from-tag, and to-tag.

pub fn state(&self) -> DialogState

pub fn from_inner(inner: Arc<DialogInner>) -> Self

pub fn snapshot(&self) -> DialogSnapshot

pub fn cancel_token(&self) -> &CancellationToken

Get the cancellation token for this dialog

Returns a reference to the CancellationToken that can be used to cancel ongoing operations for this dialog.

pub async fn bye(&self) -> Result<()>

Send a BYE request to terminate the dialog.

Thin wrapper over bye_with_headers(None).

// End an established call
dialog.bye().await?;

pub async fn bye_with_headers(&self, headers: Option<Vec<Header>>) -> Result<()>

Send a BYE request with custom headers to terminate the dialog.

This is the low-level variant used to add SIP headers (e.g. Reason) to the outgoing BYE request.

The dialog must be in Confirmed state for BYE to be sent; otherwise this method is a no-op.

Parameters

• headers - Optional extra SIP headers to include in the BYE request.

Returns

• Ok(()) - BYE was sent successfully or dialog is not confirmed.
• Err(Error) - Failed to build/send BYE request.

pub async fn bye_with_reason(&self, reason: String) -> Result<()>

Send a BYE request with a SIP Reason header.

Convenience wrapper over bye_with_headers() that adds: Reason: <reason>.

Typical values:

• SIP;cause=804;text="MEDIA_TIMEOUT"
• Q.850;cause=16;text="Normal call clearing"

Parameters

• reason - Value of the Reason header (without the Reason: name).

pub async fn hangup(&self) -> Result<()>

Hang up the call

If the dialog is confirmed, send a BYE request to terminate the call. If the dialog is not confirmed, send a CANCEL request to cancel the call.

Thin wrapper over hangup_with_headers(None).

pub async fn hangup_with_headers( &self, headers: Option<Vec<Header>>, ) -> Result<()>

Hang up the call with custom headers.

If the dialog is still in early phase and can be canceled, this sends CANCEL. Headers are not attached to the CANCEL request by default.

If the dialog is confirmed, this sends BYE and attaches the provided headers.

Parameters

• headers - Optional extra SIP headers to include when BYE is used.

pub async fn hangup_with_reason(&self, reason: String) -> Result<()>

Hang up the call and attach a SIP Reason header when BYE is used.

Convenience wrapper over hangup_with_headers() that adds: Reason: <reason>.

Parameters

• reason - Value of the Reason header used for BYE.

pub async fn cancel(&self) -> Result<()>

Send a CANCEL request to cancel an ongoing INVITE

Sends a CANCEL request to cancel an INVITE transaction that has not yet been answered with a final response. This is used to abort call setup before the call is established.

Returns

• Ok(()) - CANCEL was sent successfully
• Err(Error) - Failed to send CANCEL request

Examples

// Cancel an outgoing call before it's answered
dialog.cancel().await?;

pub async fn reinvite( &self, headers: Option<Vec<Header>>, body: Option<Vec<u8>>, ) -> Result<Option<Response>>

Send a re-INVITE request to modify the session

Sends a re-INVITE request within an established dialog to modify the session parameters (e.g., change media, add/remove streams). This can only be called for confirmed dialogs.

Parameters

• headers - Optional additional headers to include
• body - Optional message body (typically new SDP)

Returns

• Ok(Some(Response)) - Response to the re-INVITE
• Ok(None) - Dialog not confirmed, no request sent
• Err(Error) - Failed to send re-INVITE

Examples

let new_sdp = b"v=0\r\no=- 123 456 IN IP4 192.168.1.1\r\n...";
let response = dialog.reinvite(None, Some(new_sdp.to_vec())).await?;

pub async fn update( &self, headers: Option<Vec<Header>>, body: Option<Vec<u8>>, ) -> Result<Option<Response>>

Send an UPDATE request to modify session parameters

Sends an UPDATE request within an established dialog to modify session parameters without the complexity of a re-INVITE. This is typically used for smaller session modifications.

Parameters

• headers - Optional additional headers to include
• body - Optional message body (typically SDP)

Returns

• Ok(Some(Response)) - Response to the UPDATE
• Ok(None) - Dialog not confirmed, no request sent
• Err(Error) - Failed to send UPDATE

Examples

let response = dialog.update(None, Some(sdp_body)).await?;

pub async fn info( &self, headers: Option<Vec<Header>>, body: Option<Vec<u8>>, ) -> Result<Option<Response>>

Send an INFO request for mid-dialog information

Sends an INFO request within an established dialog to exchange application-level information. This is commonly used for DTMF tones, but can carry any application-specific data.

Parameters

• headers - Optional additional headers to include
• body - Optional message body (application-specific data)

Returns

• Ok(Some(Response)) - Response to the INFO
• Ok(None) - Dialog not confirmed, no request sent
• Err(Error) - Failed to send INFO

Examples

// Send DTMF tone
let dtmf_body = b"Signal=1\r\nDuration=100\r\n";
let headers = vec![
    rsip::Header::ContentType("application/dtmf-relay".into())
];
let response = dialog.info(Some(headers), Some(dtmf_body.to_vec())).await?;

pub async fn options( &self, headers: Option<Vec<Header>>, body: Option<Vec<u8>>, ) -> Result<Option<Response>>

pub async fn request( &self, method: Method, headers: Option<Vec<Header>>, body: Option<Vec<u8>>, ) -> Result<Option<Response>>

Send a generic in-dialog request

This method allows sending any SIP request within the dialog. It automatically handles CSeq increment, Call-ID, From/To tags, and Route set.

pub async fn notify( &self, headers: Option<Vec<Header>>, body: Option<Vec<u8>>, ) -> Result<Option<Response>>

Send a NOTIFY request

pub async fn refer( &self, refer_to: Uri, headers: Option<Vec<Header>>, body: Option<Vec<u8>>, ) -> Result<Option<Response>>

Send a REFER request

Sends a REFER request to transfer the call to another destination.

Parameters

• refer_to - The URI to refer to (Refer-To header value)
• headers - Optional additional headers
• body - Optional message body

pub async fn notify_refer( &self, status: StatusCode, sub_state: &str, ) -> Result<Option<Response>>

Send a REFER progress notification (RFC 3515)

This is used by the REFER recipient to notify the sender about the progress of the referred action.

Parameters

• status - The status of the referred action (e.g., 100 Trying, 200 OK)
• sub_state - The subscription state (e.g., “active”, “terminated;reason=noresource”)

pub fn as_subscription(&self) -> ClientSubscriptionDialog

Convert this INVITE dialog to a subscription dialog

This is useful for handling implicit subscriptions created by REFER.

pub async fn message( &self, headers: Option<Vec<Header>>, body: Option<Vec<u8>>, ) -> Result<Option<Response>>

Send a MESSAGE request

Sends an instant message within the dialog.

pub async fn handle(&mut self, tx: &mut Transaction) -> Result<()>

Handle incoming transaction for this dialog

Processes incoming SIP requests that are routed to this dialog. This method handles sequence number validation and dispatches to appropriate handlers based on the request method.

Parameters

• tx - The incoming transaction to handle

Returns

• Ok(()) - Request handled successfully
• Err(Error) - Failed to handle request

Supported Methods

• BYE - Terminates the dialog
• INFO - Handles information exchange
• OPTIONS - Handles capability queries
• UPDATE - Handles session updates
• INVITE - Handles re-INVITE (when confirmed)

pub async fn process_invite( &self, tx: &mut Transaction, ) -> Result<(DialogId, Option<Response>)>

Trait Implementations

impl Clone for ClientInviteDialog

fn clone(&self) -> ClientInviteDialog

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.