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 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 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.

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

Send a BYE request to terminate the dialog

Sends a BYE request to gracefully terminate an established dialog. This should only be called for confirmed dialogs. If the dialog is not confirmed, this method returns immediately without error.

Returns

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

Examples

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

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 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: 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.