Expand description
SIP/SIPS, tel: and URN URI values, each component held in canonical form.
Parse text into these types with sip-uri.
These types were sip-uri’s own until 0.2; code written against them there migrates with sip-uri’s guide.
The serde feature serializes each value as its parts, and deserializes
them through the same canonizing constructor as From a parts struct.
A Host reads a hostname through Host::from_hostname. The shape is
under the same semver as the fields: a field added to a parts struct is a
minor release, missing fields take their defaults, unknown ones are
ignored, and a SIP URI read without scheme has none. That compatibility
needs a self-describing format such as JSON, YAML or CBOR: in a
positional one such as bincode or postcard, an added field changes the
encoding, so data stored that way does not survive a minor release.
use sip_uri_types::{Host, SipUri, TelUri};
let uri = SipUri::new(Host::Hostname("example.com".into()))
.with_user("+15551234567")
.with_param("user", Some("phone"));
assert_eq!(uri.to_string(), "sip:+15551234567@example.com;user=phone");
let tel = TelUri::new("+1555 123");
assert_eq!(tel.number(), Some("+1555%20123"));§Canonical form
Each component keeps its conformant characters literal, decodes escapes
of unreserved characters only, and holds every other byte as an uppercase
%XX, whichever path built the value. A tel: number, a fragment and a
URN component decode no escape at all. An escaped reserved character
stays escaped, so %2B1 and +1 are distinct users.
Builders and parts structs take URI text, not logical values: a well-formed
%XX in it is read as an escape, never re-encoded. with_user("%2B1")
holds %2B1. encoding has one encoder and one decoder per component
a builder takes as text, between logical bytes and that text.
Hostnames are lowercased as ASCII only, with no IDNA and no non-ASCII case
folding. An IPv6 address renders as std::net::Ipv6Addr displays it,
and an IPv6 zone ID is not representable.
§Equality
Eq and Hash compare the canonical form component by component. That
is identity, never RFC 3261 §19.1.4, RFC 3966 §4 or RFC 8141 §3
equivalence: param order, param and header name case, a tel: number’s
visual separators, a hostname’s trailing dot and a URN’s r-, q- and
f-components all count. RFC equivalence is sip-uri’s UriEquivalence.
UriHeaderEquivalence is the interface by which that comparison
matches two Headers sets, which a SIP header parser implements with
each field’s own rules; ordered_headers_equivalent is the default.
§Stability
The URI kinds with their own type are fixed: a URI with any other scheme
is Uri::Other. Uri and Scheme are therefore exhaustive.
The minimum supported Rust version is 1.70, 1.71 with the serde
feature. Raising it is a minor release.
Modules§
- encoding
- Logical bytes to the URI text a builder takes, and back.
Structs§
- Assigned
Name fmt::Displayadapter returned byUrnUri::assigned_name.- Bare
fmt::Displaywrapper that renders IPv6 without brackets.- Capacity
Error - A list’s text would exceed
u32::MAXbytes. - Headers
- Headers of a SIP URI, after
?. A header written without=has no value, and one writtenname=has an empty one. - Hostname
- DNS hostname in canonical form, so equal names compare and hash equal however they were written.
- Kind
Mismatch Error - A
Uriconverted into a variant’s type it does not hold. - Other
Uri - Text kept as sent except for its scheme, which is lowercased, and the
bytes
OtherUri::newescapes. - Pairs
- Iterator over the
(name, value)pairs of aParams,UserParamsorHeaders, in order. - Params
- Parameters of a SIP URI after the host, or of a tel: URI.
- SipUri
- SIP or SIPS URI per RFC 3261 §19.
- SipUri
Parts - The components of a
SipUri, each canonized on conversion. - TelUri
- tel: URI per RFC 3966.
- TelUri
Parts - The components of a
TelUri, each canonized on conversion. - UrnUri
- URN (Uniform Resource Name) per RFC 8141.
- UrnUri
Parts - The components of a
UrnUri, each canonized on conversion. - User
Host fmt::Displayadapter returned bySipUri::user_host.- User
Params - Parameters inside a SIP URI’s userinfo, after the user part.
Enums§
- Host
- Host component of a SIP URI.
- Other
UriError - Why
OtherUri::newrefused its parts. - Scheme
- SIP URI scheme.
- Uri
- A URI: SIP/SIPS, tel, URN, or an opaque URI with an unrecognized scheme.
Traits§
- UriHeader
Equivalence - The header-field matching rules sip-uri’s
UriEquivalence::equivalent_withapplies to two SIP URIs’ header sets.
Functions§
- ordered_
headers_ equivalent - URI headers equivalent by RFC 3261 §7.3.1 row order with exact values: rows with different names in any order, rows sharing a name, compared ASCII-case-insensitively, in order and with byte-equal canonical values.