Struct DialOptions 

pub struct DialOptions {
    pub from: String,
    pub media_address: IpAddr,
    pub media_bind_address: IpAddr,
    pub initial_direction: Direction,
    pub timeout: Option<Duration>,
    pub session_expires: Option<Duration>,
    pub service_route: Vec<String>,
    pub headers: Vec<Header>,
    pub media: MediaPolicy,
    pub credentials: Option<Credentials>,
    pub identity: Option<OutboundIdentityPolicy>,
}

How a call is placed.

Fields

from: String

Our own address of record.

media_address: IpAddr

Where this side receives media.

media_bind_address: IpAddr

The local interface on which the media socket is opened.

This defaults to Self::media_address when constructed with Self::new. Set it independently when the SDP address is a public mapping which is not locally bindable. ICE nomination still owns the eventual media path when ICE is enabled; ordinary RTP cannot override that result.

Beta API migration

Adding this public field deliberately breaks external DialOptions struct literals and exhaustive patterns. Add media_bind_address (normally equal to media_address) or move to Self::new and the builder methods. Constructor-based callers remain compatible.

initial_direction: Direction

Direction advertised by the initial SDP offer.

SendRecv is the ordinary endpoint default. A two-dialog owner uses this to map the source leg’s initial offer onto fresh SDP for its target leg without copying endpoint addresses, ports or key material.

timeout: Option<Duration>

How long to wait for an answer before giving up and cancelling.

None waits as long as the transaction layer does — 64·T1, or 32 seconds with the default constants. A bound here rather than around the call is what makes giving up correct: dropping the future partway through leaves the far end believing it is in a call, and only code inside the exchange can send the CANCEL that stops it.

session_expires: Option<Duration>

Ask for an RFC 4028 session timer of this length.

None is the default and means no timer is requested. That is not the same as no timer being run: a far end that asks for one gets it, because refusing to refresh a session the peer is timing would have it hang up on a call that is working.

service_route: Vec<String>

The pre-loaded route set to put on the INVITE, outermost proxy first (RFC 3608 §6.1).

Empty by default: the INVITE goes to target and no further. Set it from a registrar’s Service-Route — UserAgent::service_route().rendered() produces exactly this — when the registration says outbound requests must traverse proxies. Without it, a call placed through a registration reaches a proxy holding no state for it. This field serializes the Route headers; the application must resolve the outer hop and supply that transport destination as the Target passed to dial. The call layer does not resolve a Route URI or override the caller’s target.

headers: Vec<Header>

Application-supplied fields on the initial INVITE.

Values have already passed sipx_sip::Header::build’s line-injection checks. The call layer retains them in the options so authentication and session-timer retries send the same request metadata as the first attempt. Applications remain responsible for refusing stack-owned routing and dialog fields before constructing these values.

media: MediaPolicy

The media policy for this call.

The default is G.711, no ICE. In particular, enabling a crate feature never changes what goes on the wire without an application selecting it.

credentials: Option<Credentials>

Credentials to answer a 401 or 407 during this call attempt.

Owned by the application and retained only in the options it passes. Their Debug representation redacts the password, and the call path never logs an authorization value. dial and dial_once perform the bounded retry; dial_early surfaces Error::AuthenticationChallenge because its handle names the original INVITE.

identity: Option<OutboundIdentityPolicy>

Authentication service selected for this call’s initial INVITE attempts.

None is the wire-compatible default: no Date or Identity is added and no authority, credential, or time input is consulted. The policy owns those explicit caller inputs.

Implementations

impl DialOptions

pub fn new(from: impl Into<String>, media_address: IpAddr) -> Self

Options for a call from an address of record.

pub fn with_codecs(self, codecs: Codecs) -> Self

Offer these codecs, most preferred first.

Codecs::Opus puts Opus ahead of the G.711 pair in the offer; the far end’s answer decides what the call carries, and a peer without Opus still gets G.711.

pub const fn with_initial_direction(self, direction: Direction) -> Self

Advertise this direction in the initial offer.

pub fn with_keying(self, keying: Keying) -> Self

Key this call with the selected mechanism.

pub fn with_media_policy(self, media: MediaPolicy) -> Self

Use this complete media policy for the call.

pub const fn with_media_bind_address(self, address: IpAddr) -> Self

Bind RTP on this local address without changing the address advertised in SDP.

pub fn with_service_route(self, hops: Vec<String>) -> Self

Traverse these proxies on the way out, outermost first (RFC 3608).

The values are Route header values — <sip:proxy.example;lr> — which is what ServiceRoute::rendered returns. Order is normative: §6.1 requires a UA that exercises a service route to preserve the order the registrar listed. This only serializes headers: resolve the outer hop in the application and pass that address as the target to dial.

pub fn with_header(self, header: Header) -> Self

Add a validated application-owned field to every initial INVITE attempt.

pub fn with_credentials(self, credentials: Credentials) -> Self

Answer a digest challenge with these credentials (RFC 3261 §22).

pub fn with_identity(self, identity: OutboundIdentityPolicy) -> Self

Sign every initial INVITE attempt with this caller-owned authentication policy.

pub fn with_session_timer(self, interval: Duration) -> Self

Detect a far end that vanishes, by refreshing the session on this interval (RFC 4028).

Without this, a peer that loses power leaves the call up forever: there is no BYE, the socket never closes, and nothing else in SIP notices. The interval is raised to the RFC’s ninety-second floor if it is shorter, because a shorter one is an amplification vector rather than a configuration choice.

pub fn with_timeout(self, timeout: Duration) -> Self

Give up after this long.

Trait Implementations

impl Clone for DialOptions

fn clone(&self) -> DialOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for DialOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.