pub struct Uri { /* private fields */ }Expand description
A URI.
§Equality
Uri deliberately does not implement PartialEq as RFC 3261 equivalence. That
relation is not transitive — the RFC says so in §19.1.4, and gives the example that
sip:carol@chicago.com is equivalent to both sip:carol@chicago.com;security=on and
sip:carol@chicago.com;security=off, which are not equivalent to each other. A
non-transitive PartialEq breaks HashMap, sorting, and every reader’s assumptions.
So: Uri::equivalent implements the RFC relation and is what protocol logic must use.
Implementations§
Source§impl Uri
impl Uri
Sourcepub fn parse(raw: Bytes) -> Result<Self, UriError>
pub fn parse(raw: Bytes) -> Result<Self, UriError>
Parse a URI.
The input must be the URI alone: any enclosing <> and surrounding whitespace belong
to the header grammar and must be stripped by the caller.
Sourcepub fn user(&self) -> Option<&[u8]>
pub fn user(&self) -> Option<&[u8]>
The user part, still percent-encoded, or None for a URI with no userinfo or a
scheme sipx does not model.
Sourcepub fn password(&self) -> Option<&[u8]>
pub fn password(&self) -> Option<&[u8]>
The password, still percent-encoded.
Present in the grammar and therefore parsed; RFC 3261 §19.1.1 advises against using it, and sipx never puts one in a URI it builds.
Sourcepub fn decoded_user(&self) -> Option<Vec<u8>>
pub fn decoded_user(&self) -> Option<Vec<u8>>
The user part with its percent escapes decoded.
Yields bytes, not a string, and that is not an oversight: RFC 4475 §3.1.1.4 has a
registration whose user part is null-%00-null, and sip:%C3%A9@host decodes to
non-ASCII. Either would have to panic or be lossily replaced to become a str.
Returns None if there is no user part or an escape is malformed.
Sourcepub fn replace_user(&mut self, user: impl Into<Bytes>) -> Result<bool, UriError>
pub fn replace_user(&mut self, user: impl Into<Bytes>) -> Result<bool, UriError>
Replace an existing, already percent-encoded user part of a SIP or SIPS URI.
Returns Ok(false) without touching the URI when its scheme is not SIP or SIPS or it has
no user part. For a parsed URI, a valid replacement changes only the retained user span:
scheme spelling, password, host spelling, delimiters, port, parameters and URI headers stay
byte-identical. The old verbatim form is invalidated rather than replayed stale. A URI whose
verbatim form was already discarded serializes canonically from its structured parts.
§Errors
UriError::PercentEscape reports a malformed % HEX HEX sequence. UriError::User
reports an empty value or a byte outside RFC 3261 §25.1’s user production. Either error
leaves the URI unchanged.
Sourcepub fn replace_tel_subscriber(
&mut self,
subscriber: impl Into<Bytes>,
) -> Result<bool, UriError>
pub fn replace_tel_subscriber( &mut self, subscriber: impl Into<Bytes>, ) -> Result<bool, UriError>
Replace the telephone-subscriber of a parsed RFC 3966 tel: URI.
Returns Ok(false) without touching the URI for every other scheme. A successful
replacement splices only the parser-retained subscriber span, so mixed-case scheme
spelling and the complete optional parameter tail stay byte-identical. This validates
the global/local subscriber production but deliberately does not interpret parameters
such as phone-context.
§Errors
UriError::TelephoneSubscriber reports an empty value or one outside RFC 3966’s
global-number-digits and local-number-digits productions. The error is atomic.
Sourcepub fn port(&self) -> Option<u16>
pub fn port(&self) -> Option<u16>
The port, if the URI states one.
A URI without a port is not the same as one naming the default port; see
Uri::equivalent.
Sourcepub fn opaque(&self) -> Option<&[u8]>
pub fn opaque(&self) -> Option<&[u8]>
Everything after the scheme, for a scheme sipx does not model.
Sourcepub fn tel_parts(&self) -> Option<TelUriParts<'_>>
pub fn tel_parts(&self) -> Option<TelUriParts<'_>>
Split an RFC 3966 tel: URI into exact subscriber and parameter-tail spans.
Returns None for every other scheme. This is a syntax view only: it preserves visual
separators, parameter spelling and order and performs no normalization or validation.
Sourcepub fn selected_transport(&self) -> Result<UriTransport, UriTransportError>
pub fn selected_transport(&self) -> Result<UriTransport, UriTransportError>
Select the effective transport without resolving the URI’s host.
Sourcepub fn push_param(&mut self, param: Param)
pub fn push_param(&mut self, param: Param)
Add a URI parameter.
Appended, not replaced: RFC 3261 §19.1.1 forbids a repeated uri-parameter, so a caller
re-setting one of its own parameters wants Uri::remove_param first — see Params.
Sourcepub fn push_header(&mut self, header: Param) -> bool
pub fn push_header(&mut self, header: Param) -> bool
Add a URI header component and report whether this URI can carry one.
SIP and SIPS URIs have a ?name=value component. Opaque schemes, including tel, do
not; returning false lets History-Info follow RFC 7044 §10.2 without pretending a
reason was embedded in a URI whose grammar has nowhere to put it.
Sourcepub fn remove_header(&mut self, name: &str) -> bool
pub fn remove_header(&mut self, name: &str) -> bool
Remove every URI header component with this name.
Sourcepub fn remove_param(&mut self, name: &str) -> bool
pub fn remove_param(&mut self, name: &str) -> bool
Remove a URI parameter, and say whether one was there.
Names match the way §19.1.4 compares them, so %74ransport is transport.
Sourcepub fn has_headers(&self) -> bool
pub fn has_headers(&self) -> bool
Whether this URI carries any header components.
A Request-URI must not (RFC 3261 §19.1.1); validation uses this.
Sourcepub fn write_to(&self, out: &mut Vec<u8>)
pub fn write_to(&self, out: &mut Vec<u8>)
Serialize.
A parsed, unmodified URI is written back exactly as it arrived.
Sourcepub fn equivalent(&self, other: &Self) -> bool
pub fn equivalent(&self, other: &Self) -> bool
Whether two URIs are equivalent under RFC 3261 §19.1.4.
Note that this relation is not transitive; see the type-level documentation.