Skip to main content

Crate sip_uri_types

Crate sip_uri_types 

Source
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§

AssignedName
fmt::Display adapter returned by UrnUri::assigned_name.
Bare
fmt::Display wrapper that renders IPv6 without brackets.
CapacityError
A list’s text would exceed u32::MAX bytes.
Headers
Headers of a SIP URI, after ?. A header written without = has no value, and one written name= has an empty one.
Hostname
DNS hostname in canonical form, so equal names compare and hash equal however they were written.
KindMismatchError
A Uri converted into a variant’s type it does not hold.
OtherUri
Text kept as sent except for its scheme, which is lowercased, and the bytes OtherUri::new escapes.
Pairs
Iterator over the (name, value) pairs of a Params, UserParams or Headers, 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.
SipUriParts
The components of a SipUri, each canonized on conversion.
TelUri
tel: URI per RFC 3966.
TelUriParts
The components of a TelUri, each canonized on conversion.
UrnUri
URN (Uniform Resource Name) per RFC 8141.
UrnUriParts
The components of a UrnUri, each canonized on conversion.
UserHost
fmt::Display adapter returned by SipUri::user_host.
UserParams
Parameters inside a SIP URI’s userinfo, after the user part.

Enums§

Host
Host component of a SIP URI.
OtherUriError
Why OtherUri::new refused its parts.
Scheme
SIP URI scheme.
Uri
A URI: SIP/SIPS, tel, URN, or an opaque URI with an unrecognized scheme.

Traits§

UriHeaderEquivalence
The header-field matching rules sip-uri’s UriEquivalence::equivalent_with applies 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.