Struct ClientInviteDialog

Source

pub struct ClientInviteDialog { /* private fields */ }

Expand description

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

Creation - Dialog created when sending INVITE
Early State - Receives provisional responses (1xx)
Confirmed - Receives 2xx response and sends ACK
Active - Can send in-dialog requests (UPDATE, INFO, etc.)
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§

Source §

impl ClientInviteDialog

Source

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.

Source

pub fn state(&self) -> DialogState

Source

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.

Source

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.

Source

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?;

Source

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?;

Source

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?;

Source

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?;

Source

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?;

Source

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

Source

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.