Struct ServerInviteDialog 

pub struct ServerInviteDialog { /* private fields */ }

Server-side INVITE Dialog (UAS)

ServerInviteDialog represents a server-side INVITE dialog in SIP. This is used when the local user agent acts as a User Agent Server (UAS) and receives an INVITE transaction from a remote party to establish a session.

Key Features

• Session Acceptance - Accepts or rejects incoming INVITE requests
• In-dialog Requests - Handles UPDATE, INFO, OPTIONS within established dialogs
• Session Termination - Handles BYE for ending sessions
• Re-INVITE Support - Supports session modification via re-INVITE
• ACK Handling - Properly handles ACK for 2xx responses
• State Management - Tracks dialog state transitions

Dialog Lifecycle

1. Creation - Dialog created when receiving INVITE
2. Processing - Can send provisional responses (1xx)
3. Decision - Accept (2xx) or reject (3xx-6xx) the INVITE
4. Wait ACK - If accepted, wait for ACK from client
5. Confirmed - ACK received, dialog established
6. Active - Can handle in-dialog requests
7. Termination - Receives BYE or sends BYE to end session

Examples

Basic Call Handling

// After receiving INVITE:

// Accept the call
dialog.accept(None, Some(answer_sdp))?;

// Or reject the call
dialog.reject(None, None)?;

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

Session Modification

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

Thread Safety

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

Implementations

impl ServerInviteDialog

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 fn initial_request(&self) -> Request

Get the initial INVITE request

Returns a reference to the initial INVITE request that created this dialog. This can be used to access the original request headers, body, and other information.

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

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

Accept the incoming INVITE request

Sends a 200 OK response to accept the incoming INVITE request. This establishes the dialog and transitions it to the WaitAck state, waiting for the ACK from the client.

Parameters

• headers - Optional additional headers to include in the response
• body - Optional message body (typically SDP answer)

Returns

• Ok(()) - Response sent successfully
• Err(Error) - Failed to send response or transaction terminated

Examples

// Accept with SDP answer
let answer_sdp = b"v=0\r\no=- 123 456 IN IP4 192.168.1.1\r\n...";
let headers = vec![
    rsip::Header::ContentType("application/sdp".into())
];
dialog.accept(Some(headers), Some(answer_sdp.to_vec()))?;

pub fn accept_with_public_contact( &self, username: &str, public_address: Option<HostWithPort>, local_address: &SipAddr, headers: Option<Vec<Header>>, body: Option<Vec<u8>>, ) -> Result<()>

Accept the incoming INVITE request with NAT-aware Contact header

Sends a 200 OK response to accept the incoming INVITE request, automatically adding a Contact header with the provided public address for proper NAT traversal. This is the recommended method when working with NAT environments.

Parameters

• username - SIP username for the Contact header
• public_address - Optional public address discovered via registration
• local_address - Local SIP address as fallback
• headers - Optional additional headers to include
• body - Optional SDP answer body

Returns

• Ok(()) - Response sent successfully
• Err(Error) - Failed to send response or transaction terminated

Examples

let public_addr = Some(rsip::HostWithPort {
    host: IpAddr::V4(Ipv4Addr::new(203, 0, 113, 1)).into(),
    port: Some(5060.into()),
});
let answer_sdp = b"v=0\r\no=- 123 456 IN IP4 203.0.113.1\r\n...";
let headers = vec![
    rsip::Header::ContentType("application/sdp".into())
];

dialog.accept_with_public_contact(
    "alice",
    public_addr,
    &local_addr,
    Some(headers),
    Some(answer_sdp.to_vec())
)?;

pub fn reject( &self, code: Option<StatusCode>, reason: Option<String>, ) -> Result<()>

Reject the incoming INVITE request

Sends a reject response to reject the incoming INVITE request. Sends a 603 Decline by default, or a custom status code if provided. This terminates the dialog creation process.

Returns

• Ok(()) - Response sent successfully
• Err(Error) - Failed to send response or transaction terminated

Examples

// Reject the incoming call
dialog.reject(Some(rsip::StatusCode::BusyHere), Some("Busy here".into()))?;

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 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 request( &self, method: Method, headers: Option<Vec<Header>>, body: Option<Vec<u8>>, ) -> Result<Option<Response>>

Send a generic in-dialog request

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

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) -> ServerSubscriptionDialog

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

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 and dialog state.

Parameters

• tx - The incoming transaction to handle

Returns

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

Supported Methods

• ACK - Confirms 2xx response (transitions to Confirmed state)
• BYE - Terminates the dialog
• INFO - Handles information exchange
• OPTIONS - Handles capability queries
• UPDATE - Handles session updates
• INVITE - Handles initial INVITE or re-INVITE

Trait Implementations

impl Clone for ServerInviteDialog

fn clone(&self) -> ServerInviteDialog

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl TryFrom<&Dialog> for ServerInviteDialog

type Error = Error

The type returned in the event of a conversion error.

fn try_from(dlg: &Dialog) -> Result<Self>

Performs the conversion.