Struct DialogLayer 

pub struct DialogLayer {
    pub endpoint: EndpointInnerRef,
    pub inner: DialogLayerInnerRef,
}

SIP Dialog Layer

DialogLayer provides high-level dialog management functionality for SIP applications. It handles dialog creation, lookup, and lifecycle management while coordinating with the transaction layer.

Key Responsibilities

• Creating and managing SIP dialogs
• Dialog identification and routing
• Dialog state tracking and cleanup
• Integration with transaction layer
• Sequence number management

Usage Patterns

Server-side Dialog Creation

use rsipstack::dialog::dialog_layer::DialogLayer;
use rsipstack::transaction::endpoint::EndpointInner;
use std::sync::Arc;

// Create dialog layer
let dialog_layer = DialogLayer::new(endpoint.clone());

// Handle incoming INVITE transaction
let server_dialog = dialog_layer.get_or_create_server_invite(
    &transaction,
    state_sender,
    credential,
    contact_uri
)?;

// Accept the call
server_dialog.accept(None, None)?;

Dialog Lookup and Routing

// Find existing dialog for incoming request
if let Some(mut dialog) = dialog_layer.match_dialog(&transaction) {
    // Route to existing dialog
    dialog.handle(&mut transaction).await?;
} else {
    // Create new dialog or reject
}

Dialog Cleanup

// Remove completed dialog
dialog_layer.remove_dialog(&dialog_id);

Dialog Lifecycle

1. Creation - Dialog created from incoming INVITE or outgoing request
2. Early State - Dialog exists but not yet confirmed
3. Confirmed - Dialog established with 2xx response and ACK
4. Active - Dialog can exchange in-dialog requests
5. Terminated - Dialog ended with BYE or error
6. Cleanup - Dialog removed from layer

Thread Safety

DialogLayer is thread-safe and can be shared across multiple tasks:

• Dialog lookup operations are concurrent
• Dialog creation is serialized when needed
• Automatic cleanup prevents memory leaks

Fields

endpoint: EndpointInnerRef

inner: DialogLayerInnerRef

Implementations

impl DialogLayer

pub fn new(endpoint: EndpointInnerRef) -> Self

pub fn get_or_create_server_invite( &self, tx: &Transaction, state_sender: DialogStateSender, credential: Option<Credential>, local_contact: Option<Uri>, ) -> Result<ServerInviteDialog>

pub fn get_or_create_server_subscription( &self, tx: &Transaction, state_sender: DialogStateSender, credential: Option<Credential>, local_contact: Option<Uri>, ) -> Result<ServerSubscriptionDialog>

pub fn get_or_create_server_publication( &self, tx: &Transaction, state_sender: DialogStateSender, credential: Option<Credential>, local_contact: Option<Uri>, ) -> Result<ServerPublicationDialog>

pub fn get_or_create_client_publication( &self, call_id: String, from_tag: String, to_tag: String, initial_request: Request, state_sender: DialogStateSender, credential: Option<Credential>, local_contact: Option<Uri>, ) -> Result<ClientPublicationDialog>

pub fn get_or_create_client_subscription( &self, call_id: String, from_tag: String, to_tag: String, initial_request: Request, state_sender: DialogStateSender, credential: Option<Credential>, local_contact: Option<Uri>, ) -> Result<ClientSubscriptionDialog>

pub fn increment_last_seq(&self) -> u32

pub fn len(&self) -> usize

pub fn all_dialog_ids(&self) -> Vec<String>

pub fn get_dialog(&self, id: &DialogId) -> Option<Dialog>

pub fn get_dialog_with(&self, id: &String) -> Option<Dialog>

pub fn get_client_dialog_by_call_id( &self, call_id: &str, ) -> Vec<ClientInviteDialog>

Returns all client-side INVITE dialogs (UAC) that share the given Call-ID.

In a forking scenario, multiple client dialogs can exist for the same Call-ID (same local From-tag, different remote To-tags). This helper scans the internal dialog registry and returns all ClientInviteDialog instances whose DialogId.call_id equals the provided call_id.

The returned vector may be empty if no matching client dialogs are found.

pub fn restore_from_snapshot( &self, snapshot: DialogSnapshot, state_sender: DialogStateSender, ) -> Result<bool>

Restore a dialog from persisted snapshot.

Restores only CONFIRMED snapshots. Non-confirmed snapshots are ignored (warn inside try_restore_from_snapshot).

Returns:

• Ok(true) => restored and inserted
• Ok(false) => skipped (already exists or not confirmed)

pub fn remove_dialog(&self, id: &DialogId)

pub fn match_dialog(&self, tx: &Transaction) -> Option<Dialog>

pub fn new_dialog_state_channel( &self, ) -> (DialogStateSender, DialogStateReceiver)

pub fn build_local_contact( &self, username: Option<String>, params: Option<Vec<Param>>, ) -> Result<Uri>

impl DialogLayer

pub fn make_invite_request(&self, opt: &InviteOption) -> Result<Request>

Create an INVITE request from options

Constructs a properly formatted SIP INVITE request based on the provided options. This method handles all the required headers and parameters according to RFC 3261.

Parameters

• opt - INVITE options containing all necessary parameters

Returns

• Ok(Request) - Properly formatted INVITE request
• Err(Error) - Failed to create request

Generated Headers

The method automatically generates:

• Via header with branch parameter
• From header with tag parameter
• To header (without tag for initial request)
• Contact header
• Content-Type header
• CSeq header with incremented sequence number
• Call-ID header

Examples

let request = dialog_layer.make_invite_request(&invite_option)?;
println!("Created INVITE to: {}", request.uri);

pub async fn do_invite( &self, opt: InviteOption, state_sender: DialogStateSender, ) -> Result<(ClientInviteDialog, Option<Response>)>

Send an INVITE request and create a client dialog

This is the main method for initiating outbound calls. It creates an INVITE request, sends it, and manages the resulting dialog. The method handles the complete INVITE transaction including authentication challenges and response processing.

Parameters

• opt - INVITE options containing all call parameters
• state_sender - Channel for receiving dialog state updates

Returns

• Ok((ClientInviteDialog, Option<Response>)) - Created dialog and final response
• Err(Error) - Failed to send INVITE or process responses

Call Flow

1. Creates INVITE request from options
2. Creates client dialog and transaction
3. Sends INVITE request
4. Processes responses (1xx, 2xx, 3xx-6xx)
5. Handles authentication challenges if needed
6. Returns established dialog and final response

Examples

Basic Call Setup

let (dialog, response) = dialog_layer.do_invite(invite_option, state_sender).await?;

if let Some(resp) = response {
    match resp.status_code {
        rsip::StatusCode::OK => {
            println!("Call answered!");
            // Process SDP answer in resp.body
        },
        rsip::StatusCode::BusyHere => {
            println!("Called party is busy");
        },
        _ => {
            println!("Call failed: {}", resp.status_code);
        }
    }
}

Monitoring Dialog State

let (state_tx, mut state_rx) = tokio::sync::mpsc::unbounded_channel();
let (dialog, response) = dialog_layer.do_invite(invite_option, state_tx).await?;

// Monitor dialog state changes
tokio::spawn(async move {
    while let Some(state) = state_rx.recv().await {
        match state {
            DialogState::Early(_, resp) => {
                println!("Ringing: {}", resp.status_code);
            },
            DialogState::Confirmed(_,_) => {
                println!("Call established");
            },
            DialogState::Terminated(_, code) => {
                println!("Call ended: {:?}", code);
                break;
            },
            _ => {}
        }
    }
});

Error Handling

The method can fail for various reasons:

• Network connectivity issues
• Authentication failures
• Invalid SIP URIs or headers
• Transaction timeouts
• Protocol violations

Authentication

If credentials are provided in the options, the method will automatically handle 401/407 authentication challenges by resending the request with proper authentication headers.

pub fn do_invite_async( self: &Arc<Self>, opt: InviteOption, state_sender: DialogStateSender, ) -> Result<(ClientInviteDialog, JoinHandle<InviteAsyncResult>)>

Registers the dialog under an early dialog ID while the INVITE is in progress. Once completed, the early entry is removed and, on 2xx response, the dialog is re-registered under the confirmed dialog ID. Returns a JoinHandle resolving to the final dialog ID and response.

pub fn create_client_invite_dialog( &self, opt: InviteOption, state_sender: DialogStateSender, ) -> Result<(ClientInviteDialog, Transaction)>