Struct SvcParams

pub struct SvcParams<Octs: ?Sized> { /* private fields */ }

A sequence of service binding parameters.

These parameters provide information helpful when trying to connect to an endpoint offering a service. They consist of a sequence of parameter values. Each value has a type and some data specific to that type. The type is provided through a u16 key with values assigned via an IANA registry. The key and registry are available through SvcParamKey. Each key is only allowed to appear at most once in the parameter sequence. Values need to be ordered by their key’s integer value.

A value of the SvcParams type contains a sequence of values in their wire-format encoded form. It guarantees that this content is correctly encoded. It does not guarantee that the content of the individual parameter value is correct. It also does not guarantee any size limit to the octets sequence.

You can create a value of this type through parsing or manually via from_octets or from_slice. You can also build a new value from scratch via the SvcParamsBuilder. The from_values function provides a shortcut that crates the builder, passes it to a closure, and returns the finished parameter sequence.

Access to the values of the parameter sequence happens through a mechanism similar to record data: Various types exist that implement either a specific value type or a group of types. These types need to implement the SvcParamValue and ParseSvcParamValue traits to be used to access values. They can be used as a type parameter to the iter method to acquire an iterator over all the values that they understand. Since every concrete value can only be present once, the first method can be used together with a value type implementing that concrete value to get the value if present. As a convenience, methods exist for every currently defined value type which return a value of that type if present.

The type UnknownSvcParam can be used to represent any value type with the value as a octets sequence. The AllValues enum provides typed access to all known value types.

Wire Format

The wire format of a parameter sequence consists of a sequence of values. Each value is encoded as a 16 bit parameter key – represented by SvcParamKey in this crate –, followed by an unsigned 16 bit length value, followed by this many octets. Since the sequence is the last element in the record data, it is limited by the length of the record data only.

Implementations

impl<Octs: Octets + ?Sized> SvcParams<Octs>

pub fn mandatory(&self) -> Option<Mandatory<Octs::Range<'_>>>

Returns the content of the ‘mandatory’ value if present.

impl<Octs: Octets + ?Sized> SvcParams<Octs>

pub fn alpn(&self) -> Option<Alpn<Octs::Range<'_>>>

Returns the content of the ‘mandatory’ value if present.

impl<Octs: Octets + ?Sized> SvcParams<Octs>

pub fn no_default_alpn(&self) -> bool

Returns whether the NoDefaultAlpn value is present.

impl<Octs: Octets + ?Sized> SvcParams<Octs>

pub fn port(&self) -> Option<Port>

Returns the content of the port value if present.

impl<Octs: Octets + ?Sized> SvcParams<Octs>

pub fn ech(&self) -> Option<Ech<Octs::Range<'_>>>

Returns the content of the ECH value if present.

impl<Octs: Octets + ?Sized> SvcParams<Octs>

pub fn ipv4hint(&self) -> Option<Ipv4Hint<Octs::Range<'_>>>

Returns the content of the ‘ipv4hint’ value if present.

impl<Octs: Octets + ?Sized> SvcParams<Octs>

pub fn ipv6hint(&self) -> Option<Ipv6Hint<Octs::Range<'_>>>

Returns the content of the ‘ipv6hint’ value if present.

impl<Octs: Octets + ?Sized> SvcParams<Octs>

pub fn dohpath(&self) -> Option<DohPath<Octs::Range<'_>>>

Returns the content of the ‘dohpath’ value if present.

impl<Octs> SvcParams<Octs>

pub fn from_octets(octets: Octs) -> Result<Self, SvcParamsError>

where Octs: AsRef<[u8]>,

Creates a parameter sequence from an octets sequence.

The method checks that octets contains a parameter sequence that is correctly encoded in wire format. It does not check that the individual values are correctly encoded. It also does not check for any length limit.

pub unsafe fn from_octets_unchecked(octets: Octs) -> Self

Creates a new value from an octets sequence without checking.

Safety

The caller has to ensure that octets contains a properly formatted parameter sequence.

impl SvcParams<[u8]>

pub fn from_slice(slice: &[u8]) -> Result<&Self, SvcParamsError>

Creates a parameter sequence from an octets slice.

The method checks that slice contains a parameter sequence that is correctly encoded in wire format. It does not check that the individual values are correctly encoded. It also does not check for any length limit.

pub unsafe fn from_slice_unchecked(slice: &[u8]) -> &Self

Creates a new value from a slice without checking.

Safety

The caller has to ensure that slice contains a properly formatted parameter sequence.

impl<Octs> SvcParams<Octs>

pub fn from_values<F>(op: F) -> Result<Self, PushError>

where Octs: FromBuilder, <Octs as FromBuilder>::Builder: AsRef<[u8]> + OctetsBuilder + EmptyBuilder, F: FnOnce(&mut SvcParamsBuilder<<Octs as FromBuilder>::Builder>) -> Result<(), PushError>,

Creates a parameter sequence by constructing it from values.

The method expects a closure that receives an SvcParamsBuilder which it should push all the required values to. Once it returns, this builder is frozen into an SvcParams value and returned.

impl<Octs: AsRef<[u8]>> SvcParams<Octs>

pub fn parse<'a, Src: Octets<Range<'a> = Octs> + ?Sized + 'a>( parser: &mut Parser<'a, Src>, ) -> Result<Self, ParseError>

Parses a parameter sequence from its wire format.

impl<Octs: ?Sized> SvcParams<Octs>

pub fn as_octets(&self) -> &Octs

Returns a reference to the underlying octets sequence.

impl<Octs: AsRef<[u8]> + ?Sized> SvcParams<Octs>

pub fn as_slice(&self) -> &[u8]

Returns a slice of the underlying octets sequence.

pub fn for_slice(&self) -> &SvcParams<[u8]>

Returns a parameter sequence atop a slice of this value’s octets.

pub fn len(&self) -> usize

Returns the length of the parameter sequence in octets.

pub fn is_empty(&self) -> bool

Returns whether the parameters sequences is empty.

pub fn first<'s, Value>(&'s self) -> Option<Value>

where Octs: Octets, Value: ParseSvcParamValue<'s, Octs>,

Returns the first value of type Value.

This method is intended to be used with value types implementing a specific type. Since only one instance is allowed to be present, this method also returns None if the first value fails parsing, assuming that the value is unusable and should be ignored.

This may not be the correct behaviour in all cases. Please use self.iter::<Value>().next() to get an optional parsing result.

pub fn iter<Value>(&self) -> ValueIter<'_, Octs, Value>

Returns an iterator over all values accepted by Value.

pub fn iter_all(&self) -> ValueIter<'_, Octs, AllValues<Octs>>

where Octs: Sized,

Returns an iterator over all values.

pub fn iter_raw(&self) -> impl Iterator<Item = UnknownSvcParam<Octs::Range<'_>>>

where Octs: Octets + Sized,

Returns an iterator over all values in their raw form.

pub fn compose<Target: OctetsBuilder + ?Sized>( &self, target: &mut Target, ) -> Result<(), Target::AppendError>

Composes the wire-format of the parameter sequence.

Trait Implementations

impl<Octs, OtherOcts> CanonicalOrd<SvcParams<OtherOcts>> for SvcParams<Octs>

where Octs: AsRef<[u8]> + ?Sized, OtherOcts: AsRef<[u8]> + ?Sized,

fn canonical_cmp(&self, other: &SvcParams<OtherOcts>) -> Ordering

Returns the canonical ordering between self and other.

fn canonical_lt(&self, other: &Rhs) -> bool

Returns whether self is canonically less than other.

fn canonical_le(&self, other: &Rhs) -> bool

Returns whether self is canonically less than or equal to other.

fn canonical_gt(&self, other: &Rhs) -> bool

Returns whether self is canonically greater than other.

fn canonical_ge(&self, other: &Rhs) -> bool

Returns whether self is canonically greater than or equal to other.

impl<Octs: Clone + ?Sized> Clone for SvcParams<Octs>

fn clone(&self) -> SvcParams<Octs>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Octs: Octets + ?Sized> Debug for SvcParams<Octs>

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

Formats the value using the given formatter.

impl<Octs: Default + ?Sized> Default for SvcParams<Octs>

fn default() -> SvcParams<Octs>

Returns the “default value” for a type.

impl<Octs: Octets + ?Sized> Display for SvcParams<Octs>

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

Formats the value using the given formatter.

impl<Octs: AsRef<[u8]> + ?Sized> Hash for SvcParams<Octs>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

impl<SrcOcts, Octs> OctetsFrom<SvcParams<SrcOcts>> for SvcParams<Octs>

where Octs: OctetsFrom<SrcOcts>,

type Error = <Octs as OctetsFrom<SrcOcts>>::Error

fn try_octets_from(src: SvcParams<SrcOcts>) -> Result<Self, Self::Error>

Performs the conversion.

impl<Octs: AsRef<[u8]> + ?Sized> Ord for SvcParams<Octs>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

impl<Octs, OtherOcts> PartialEq<SvcParams<OtherOcts>> for SvcParams<Octs>

where Octs: AsRef<[u8]> + ?Sized, OtherOcts: AsRef<[u8]> + ?Sized,

fn eq(&self, other: &SvcParams<OtherOcts>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Octs, OtherOcts> PartialOrd<SvcParams<OtherOcts>> for SvcParams<Octs>

where Octs: AsRef<[u8]> + ?Sized, OtherOcts: AsRef<[u8]> + ?Sized,

fn partial_cmp(&self, other: &SvcParams<OtherOcts>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<Octs: AsRef<[u8]> + ?Sized> Eq for SvcParams<Octs>