Struct domain::rdata::svcb::SvcParams

source ·
pub struct SvcParams<Octs: ?Sized> { /* private fields */ }
Expand description

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§

source§

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

source

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

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

source§

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

source

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

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

source§

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

source

pub fn no_default_alpn(&self) -> bool

Returns whether the NoDefaultAlpn value is present.

source§

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

source

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

Returns the content of the port value if present.

source§

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

source

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

Returns the content of the ECH value if present.

source§

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

source

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

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

source§

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

source

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

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

source§

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

source

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

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

source§

impl<Octs> SvcParams<Octs>

source

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.

source

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.

source§

impl SvcParams<[u8]>

source

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.

source

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.

source§

impl<Octs> SvcParams<Octs>

source

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.

source§

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

source

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.

source§

impl<Octs: ?Sized> SvcParams<Octs>

source

pub fn as_octets(&self) -> &Octs

Returns a reference to the underlying octets sequence.

source§

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

source

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

Returns a slice of the underlying octets sequence.

source

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

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

source

pub fn len(&self) -> usize

Returns the length of the parameter sequence in octets.

source

pub fn is_empty(&self) -> bool

Returns whether the parameters sequences is empty.

source

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.

source

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

Returns an iterator over all values accepted by Value.

source

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

Returns an iterator over all values.

source

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.

source

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

Composes the wire-format of the parameter sequence.

Trait Implementations§

source§

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

source§

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

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

fn default() -> SvcParams<Octs>

Returns the “default value” for a type. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

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

Feeds this value into the given Hasher. Read more
source§

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

§

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

source§

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

Performs the conversion.
source§

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

source§

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

This method returns an Ordering between self and other. Read more
source§

impl<Octs, OtherOcts> PartialEq<SvcParams<OtherOcts>> for SvcParams<Octs>where Octs: AsRef<[u8]> + ?Sized, OtherOcts: AsRef<[u8]> + ?Sized,

source§

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

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl<Octs, OtherOcts> PartialOrd<SvcParams<OtherOcts>> for SvcParams<Octs>where Octs: AsRef<[u8]> + ?Sized, OtherOcts: AsRef<[u8]> + ?Sized,

source§

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

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · source§

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

This method tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

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

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · source§

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

This method tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

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

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more
source§

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

Auto Trait Implementations§

§

impl<Octs: ?Sized> RefUnwindSafe for SvcParams<Octs>where Octs: RefUnwindSafe,

§

impl<Octs: ?Sized> Send for SvcParams<Octs>where Octs: Send,

§

impl<Octs: ?Sized> Sync for SvcParams<Octs>where Octs: Sync,

§

impl<Octs: ?Sized> Unpin for SvcParams<Octs>where Octs: Unpin,

§

impl<Octs: ?Sized> UnwindSafe for SvcParams<Octs>where Octs: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<Source, Target> OctetsInto<Target> for Sourcewhere Target: OctetsFrom<Source>,

§

type Error = <Target as OctetsFrom<Source>>::Error

source§

fn try_octets_into( self ) -> Result<Target, <Source as OctetsInto<Target>>::Error>

Performs the conversion.
source§

fn octets_into(self) -> Targetwhere Self::Error: Into<Infallible>,

Performs an infallible conversion.
source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for Twhere T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

source§

fn vzip(self) -> V