Struct SvcParamsBuilder

pub struct SvcParamsBuilder<Octs> { /* private fields */ }

A builder for a service parameter sequence.

This type wraps an octets builder and allows appending parameter values. You can create a new empty builder using the empty function or copy an existing value through from_params.

You can add additional values using the push method. There are also dedicated methods for all known value types. The builder will make sure that each parameter key can only appear once. Thus, pushing values may fail if a value is already present.

The builder also takes care of sorting the values into their correct order. So you can push them in any order.

It only sorts the items when producing a frozen value via the freeze method.

Implementations

impl<Octs: OctetsBuilder + AsRef<[u8]> + AsMut<[u8]>> SvcParamsBuilder<Octs>

pub fn mandatory( &mut self, keys: impl AsRef<[SvcParamKey]>, ) -> Result<(), PushValueError>

Adds a ‘mandatory’ value with the given keys.

Returns an error if there already is a ‘mandatory’ value, keys contains more values than fit into a service binding parameter value, or the underlying octets builder runs out of space.

impl<Octs: OctetsBuilder + AsRef<[u8]> + AsMut<[u8]>> SvcParamsBuilder<Octs>

pub fn alpn(&mut self, protocols: &[&[u8]]) -> Result<(), PushAlpnError>

Adds an ALPN value to the parameters.

The ALPN protocol names to be included in the value must be provided as a slice of those names in order to be able to calculate the length of the value up front.

Returns an error if there already is an ALPN value, or if protocols contains more values than fit into a service binding parameter value, or the underlying octets builder runs out of space.

impl<Octs: OctetsBuilder + AsRef<[u8]> + AsMut<[u8]>> SvcParamsBuilder<Octs>

pub fn no_default_alpn(&mut self) -> Result<(), PushError>

Adds the NoDefaultAlpn value.

impl<Octs: OctetsBuilder + AsRef<[u8]> + AsMut<[u8]>> SvcParamsBuilder<Octs>

pub fn port(&mut self, port: u16) -> Result<(), PushError>

Adds a port value with the given port number.

impl<Octs: OctetsBuilder + AsRef<[u8]> + AsMut<[u8]>> SvcParamsBuilder<Octs>

pub fn ech<Source: AsRef<[u8]> + ?Sized>( &mut self, ech: &Source, ) -> Result<(), PushValueError>

Adds a port value with the given port number.

impl<Octs: OctetsBuilder + AsRef<[u8]> + AsMut<[u8]>> SvcParamsBuilder<Octs>

pub fn ipv4hint( &mut self, addrs: impl AsRef<[Ipv4Addr]>, ) -> Result<(), PushValueError>

Adds an ‘ipv4hint’ value with the given addresses.

Returns an error if there already is an ‘ipv4hint’ value, addrs contains more values than fit into a service binding parameter value, or the underlying octets builder runs out of space.

impl<Octs: OctetsBuilder + AsRef<[u8]> + AsMut<[u8]>> SvcParamsBuilder<Octs>

pub fn ipv6hint( &mut self, addrs: impl AsRef<[Ipv6Addr]>, ) -> Result<(), PushValueError>

Adds an ‘ipv6hint’ value with the given addresses.

Returns an error if there already is an ‘ipv6hint’ value, addrs contains more values than fit into a service binding parameter value, or the underlying octets builder runs out of space.

impl<Octs: OctetsBuilder + AsRef<[u8]> + AsMut<[u8]>> SvcParamsBuilder<Octs>

pub fn dohpath(&mut self, template: &str) -> Result<(), PushValueError>

Adds a ‘dohpath’ value with the URI template.

Returns an error if there already is a ‘dohpath’ value, template is too long to fit in a service binding parameter value, or the underlying octets builder runs out of space.

impl<Octs> SvcParamsBuilder<Octs>

pub fn empty() -> Self

where Octs: EmptyBuilder,

Creates an empty parameter builder.

pub fn from_params<Src: Octets + ?Sized>( params: &SvcParams<Src>, ) -> Result<Self, ShortBuf>

where Octs: AsRef<[u8]> + OctetsBuilder + EmptyBuilder,

Creates a parameter builder from an existing parameter sequence.

The function creates a new empty builder and copies over the content of params. It can fail if the octets builder is not capable of providing enough space to hold the content of params.

pub fn push<Value: ComposeSvcParamValue + ?Sized>( &mut self, value: &Value, ) -> Result<(), PushError>

where Octs: OctetsBuilder + AsRef<[u8]> + AsMut<[u8]>,

Adds a new value to the builder.

The method will return an error if a value with this key is already present or if there isn’t enough space left in the builder’s buffer.

pub fn freeze<Target>( &self, ) -> Result<SvcParams<Target>, <<Target as FromBuilder>::Builder as OctetsBuilder>::AppendError>

where Octs: AsRef<[u8]>, Target: FromBuilder, <Target as FromBuilder>::Builder: OctetsBuilder + EmptyBuilder,

Freezes the builder to a parameter sequence.

Because the values may need to be resorted, this method actually produces a new octets sequence. This is why it doesn’t consume the builder and may fail if the target octet’s builder can’t provide enough space.

Trait Implementations

impl<Octs: Clone> Clone for SvcParamsBuilder<Octs>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Octs: Debug> Debug for SvcParamsBuilder<Octs>

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

Formats the value using the given formatter.