pub struct DialogLayer {
pub endpoint: EndpointInnerRef,
pub inner: DialogLayerInnerRef,
}Expand description
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
- Creation - Dialog created from incoming INVITE or outgoing request
- Early State - Dialog exists but not yet confirmed
- Confirmed - Dialog established with 2xx response and ACK
- Active - Dialog can exchange in-dialog requests
- Terminated - Dialog ended with BYE or error
- 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: DialogLayerInnerRefImplementations§
Source§impl DialogLayer
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<InviteDialog>
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 is_empty(&self) -> bool
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>
Sourcepub fn get_client_dialog_by_call_id(&self, call_id: &str) -> Vec<InviteDialog>
pub fn get_client_dialog_by_call_id(&self, call_id: &str) -> Vec<InviteDialog>
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 InviteDialog
instances whose DialogId.call_id equals the provided call_id.
The returned vector may be empty if no matching client dialogs are found.
Sourcepub fn restore_from_snapshot(
&self,
snapshot: DialogSnapshot,
state_sender: DialogStateSender,
) -> Result<bool>
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>
Source§impl DialogLayer
impl DialogLayer
Sourcepub fn make_invite_request(&self, opt: &InviteOption) -> Result<Request>
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 requestErr(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);Sourcepub async fn do_invite(
&self,
opt: InviteOption,
state_sender: DialogStateSender,
) -> Result<(InviteDialog, Option<Response>)>
pub async fn do_invite( &self, opt: InviteOption, state_sender: DialogStateSender, ) -> Result<(InviteDialog, 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 parametersstate_sender- Channel for receiving dialog state updates
§Returns
Ok((InviteDialog, Option<Response>))- Created dialog and final responseErr(Error)- Failed to send INVITE or process responses
§Call Flow
- Creates INVITE request from options
- Creates client dialog and transaction
- Sends INVITE request
- Processes responses (1xx, 2xx, 3xx-6xx)
- Handles authentication challenges if needed
- 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 {
rsipstack::sip::StatusCode::OK => {
println!("Call answered!");
// Process SDP answer in resp.body
},
rsipstack::sip::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
§Important: Cleanup Required
When a 2xx response is received, the confirmed dialog is registered in
the internal dialog registry. The caller is responsible for removing it
after the dialog terminates by calling DialogLayer::remove_dialog
with the dialog’s DialogId.
The recommended pattern is to listen for
DialogState::Terminated
on the state_sender channel and call remove_dialog when received.
See the “Monitoring Dialog State” example above.
Failure to call remove_dialog will cause the dialog to remain in the
registry indefinitely, resulting in a memory leak.
§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.
Sourcepub fn do_invite_async(
self: &Arc<Self>,
opt: InviteOption,
state_sender: DialogStateSender,
) -> Result<(InviteDialog, JoinHandle<InviteAsyncResult>)>
pub fn do_invite_async( self: &Arc<Self>, opt: InviteOption, state_sender: DialogStateSender, ) -> Result<(InviteDialog, JoinHandle<InviteAsyncResult>)>
Asynchronously executes an INVITE transaction in the background.
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.
§Important: Cleanup Required
On a successful (2xx) response the confirmed dialog is registered in
the internal dialog registry. The caller must remove it after the
dialog terminates by calling DialogLayer::remove_dialog with the
confirmed dialog’s DialogId.
Listen for
DialogState::Terminated
on the state_sender channel and call remove_dialog when received.
Failure to do so will keep the dialog in the registry and cause a
memory leak.
pub fn create_client_invite_dialog( &self, opt: InviteOption, state_sender: DialogStateSender, ) -> Result<(InviteDialog, Transaction)>
Auto Trait Implementations§
impl !RefUnwindSafe for DialogLayer
impl !UnwindSafe for DialogLayer
impl Freeze for DialogLayer
impl Send for DialogLayer
impl Sync for DialogLayer
impl Unpin for DialogLayer
impl UnsafeUnpin for DialogLayer
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more