Struct Config 

pub struct Config {

    pub aor: String,
    pub contact: String,
    pub registrar: Uri,
    pub target: Target,
    pub credentials: Option<Credentials>,
    pub expires: Duration,
    pub user_agent: String,
    pub headers: Vec<Header>,
    pub instance: Option<InstanceId>,
    pub reg_id: Option<RegId>,
    pub gruu: Option<Kind>,
    pub push: Option<Device>,
    pub keepalive_timeout: Duration,
}

How a user agent is configured.

Fields

aor: String

The address of record, as it appears in To and From.

contact: String

Where to reach this agent.

registrar: Uri

The registrar’s URI.

target: Target

Where to send registrations.

credentials: Option<Credentials>

Credentials, if the registrar wants them.

expires: Duration

The lease to ask for.

user_agent: String

What to put in User-Agent.

headers: Vec<Header>

Validated application-owned fields preserved on every REGISTER attempt and refresh.

instance: Option<InstanceId>

The device identity this agent registers under (RFC 5626 §4.1, RFC 5627 §4.1).

One field for both mechanisms, because both name the instance with the same +sip.instance media feature tag and a registrar that correlates them must see one value. Set it with Config::with_outbound or Config::with_gruu; whichever is called last decides, and either way there is only ever one identity to present.

None registers the ordinary way: a Contact naming an address and nothing naming the device behind it, so every restart looks to the registrar like a new phone.

reg_id: Option<RegId>

Which Outbound flow this registration is, when Outbound is in use (RFC 5626 §4.2).

None registers the ordinary way: a binding that is only as durable as the NAT mapping behind it.

gruu: Option<Kind>

Which GRUU this agent uses, when it is asking for one (RFC 5627 §4.4).

None does not ask. See gruu::Kind for why the choice is the application’s.

push: Option<Device>

How a push notification service can wake this device (RFC 8599 §4.1.2).

None registers without push, which is every client that holds a connection of its own. Set it with Config::with_push; the values come from the application’s push service, behind crate::push::PushService.

keepalive_timeout: Duration

How long a keep-alive may go unanswered before the flow is failed (RFC 5626 §4.4).

Defaults to §4.4.1’s ten seconds. It is configurable because the RFC gives two rules and only one of them is a duration: §4.4.1 fixes ten seconds for the CRLF pong, while §4.4.2 bounds the STUN case by 7 retransmissions of an RTO estimate instead. Ten seconds is the conservative reading of both, and a deployment that knows its round-trip times — or a test that does not want to wait — is entitled to a shorter one.

Implementations

impl Config

pub fn new( aor: impl Into<String>, contact: impl Into<String>, registrar: Uri, target: Target, ) -> Self

A configuration for an address of record.

pub fn with_keepalive_timeout(self, within: Duration) -> Self

Fail a flow whose keep-alive is unanswered for this long (RFC 5626 §4.4).

pub fn with_outbound(self, flow: Flow) -> Self

Register this contact as one Outbound flow (RFC 5626).

The Contact gains reg-id and +sip.instance, and the REGISTER offers the outbound option tag. Whether the registrar actually did an outbound registration is a separate question, answered by UserAgent::flow_accepted after the fact — §6 has the registrar say so in Require, and a UA that assumes it would keep a flow alive that nothing routes down.

pub fn with_gruu(self, instance: InstanceId, kind: Kind) -> Self

Ask the registrar for a GRUU, and say which of the two to use (RFC 5627 §4.1, §4.4).

The REGISTER gains the gruu option tag and presents instance; the GRUUs that come back are readable through UserAgent::gruus and are what UserAgent::dialog_contact then publishes.

instance is the same identity Outbound registers with, and it is stored in the same field: a UA using both mechanisms presents one instance ID, because a registrar correlating them would otherwise see one device claiming to be two. Whether the registrar actually issues a GRUU is its business — §4.2 requires a UA to cope with one, both or neither, and getting neither is not an error.

See gruu::Kind for why Kind::Public is the default and why asking for Kind::Temporary never quietly yields the public one.

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

Add credentials.

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

Add a validated application-owned field to every REGISTER request.

pub fn with_push(self, device: Device) -> Self

Be reachable through this push notification service (RFC 8599 §4.1.2).

The Contact URI gains pn-provider, pn-param and pn-prid — inside the angle brackets, where a registrar’s URI parser looks; §8.7 registers them as URI parameters and a ; outside the brackets starts a different grammar entirely.

Registering is only half the mechanism. When the push arrives, call UserAgent::woken — §4.1.3’s binding-refresh REGISTER — before expecting the request the push was sent for, because until the refresh there is no flow for it to arrive on. And after any registration, ask UserAgent::push_support whether the registrar named this service: a 200 from a registrar that supports a different one is a binding nothing will ever wake.

Trait Implementations

impl Clone for Config

fn clone(&self) -> Config

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Config

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

Formats the value using the given formatter.