Struct toad_msg::builder::MessageBuilder

pub struct MessageBuilder<PayloadBytes, Options> { /* private fields */ }

Builder for Messages

Implementations

impl<C, O> MessageBuilder<C, O>where O: OptionMap, C: Array<Item = u8>,

pub fn new(ty: Type, code: Code) -> Self

Create a new builder

pub fn ty(self, ty: Type) -> Self

Sets message Type

pub fn code(self, code: Code) -> Self

Sets message Code

pub fn payload(self, p: C) -> Self

Sets message Payload

pub fn id(self, id: Id) -> Self

Sets message Id

pub fn token(self, token: Token) -> Self

Sets message Token

pub fn host<S>(self, host: S) -> Selfwhere S: AsRef<str>,

Update the value for the Uri-Host option, discarding any existing values.

pub fn block1(self, size: u16, num: u32, more: bool) -> Self

[opt::known::no_repeat::BLOCK1]

pub fn block2(self, size: u16, num: u32, more: bool) -> Self

[opt::known::no_repeat::BLOCK2]

pub fn port(self, port: u16) -> Self

Update the value for the Uri-Port option, discarding any existing values.

pub fn path<S>(self, path: S) -> Selfwhere S: AsRef<str>,

Update the value for the Uri-Path option, discarding any existing values.

pub fn content_format(self, format: ContentFormat) -> Self

Update the value for the Content-Format option, discarding any existing values.

Content-Format

generated from RFC7252 section 5.10.3

The Content-Format Option indicates the representation format of the message payload. The representation format is given as a numeric Content-Format identifier that is defined in the “CoAP Content- Formats” registry (Section 12.3). In the absence of the option, no default value is assumed, i.e., the representation format of any representation message payload is indeterminate (Section 5.5).

pub fn observe(self, a: Action) -> Self

Set the value for the Observe option, discarding any existing values.

pub fn accept(self, format: ContentFormat) -> Self

Update the value for the Accept option, discarding any existing values.

pub fn size1(self, size_bytes: u64) -> Self

Update the value for the Size1 option, discarding any existing values.

Size1 Option

generated from RFC7252 section 5.10.9

The Size1 option provides size information about the resource representation in a request. The option value is an integer number of bytes. Its main use is with block-wise transfers [BLOCK]. In the present specification, it is used in 4.13 responses (Section 5.9.2.9) to indicate the maximum size of request entity that the server is able and willing to handle.

pub fn size2(self, size_bytes: u64) -> Self

Update the value for the Size2 option, discarding any existing values.

pub fn if_exists(self) -> Self

Discard all values for If-Match, and replace them with an empty value.

This signals that our request should only be processed if we’re trying to update a resource that exists (e.g. this ensures PUT only updates and will never insert)

If-Match

generated from RFC7252 section 5.10.8.1

The If-Match Option MAY be used to make a request conditional on the current existence or value of an ETag for one or more representations of the target resource. If-Match is generally useful for resource update requests, such as PUT requests, as a means for protecting against accidental overwrites when multiple clients are acting in parallel on the same resource (i.e., the “lost update” problem).

The value of an If-Match option is either an ETag or the empty string. An If-Match option with an ETag matches a representation with that exact ETag. An If-Match option with an empty value matches any existing representation (i.e., it places the precondition on the existence of any current representation for the target resource).

The If-Match Option can occur multiple times. If any of the options match, then the condition is fulfilled.

If there is one or more If-Match Options, but none of the options match, then the condition is not fulfilled.

pub fn if_not_exists(self) -> Self

Enable the If-None-Match flag

This signals that our request should only be processed if we’re trying to insert a resource that does not exist (e.g. this ensures PUT only inserts and will never update)

If-None-Match

generated from RFC7252 section 5.10.8.2

The If-None-Match Option MAY be used to make a request conditional on the nonexistence of the target resource. If-None-Match is useful for resource creation requests, such as PUT requests, as a means for protecting against accidental overwrites when multiple clients are acting in parallel on the same resource. The If-None-Match Option carries no value.

If the target resource does exist, then the condition is not fulfilled.

(It is not very useful to combine If-Match and If-None-Match options in one request, because the condition will then never be fulfilled.)

pub fn max_age(self, max_age_seconds: u32) -> Self

Update the value for the Max-Age option, discarding any existing values.

Max-Age

generated from RFC7252 section 5.10.5

The Max-Age Option indicates the maximum time a response may be cached before it is considered not fresh (see Section 5.6.1).

The option value is an integer number of seconds between 0 and 2**32-1 inclusive (about 136.1 years). A default value of 60 seconds is assumed in the absence of the option in a response.

The value is intended to be current at the time of transmission. Servers that provide resources with strict tolerances on the value of Max-Age SHOULD update the value before each retransmission. (See also Section 5.7.1.)

pub fn proxy_uri<S>(self, uri: S) -> Selfwhere S: AsRef<str>,

Update the value for the Proxy-Uri option, discarding any existing values.

Proxy-Uri and Proxy-Scheme

generated from RFC7252 section 5.10.2

The Proxy-Uri Option is used to make a request to a forward-proxy (see Section 5.7). The forward-proxy is requested to forward the request or service it from a valid cache and return the response.

The option value is an absolute-URI ([RFC3986], Section 4.3).

Note that the forward-proxy MAY forward the request on to another proxy or directly to the server specified by the absolute-URI. In order to avoid request loops, a proxy MUST be able to recognize all of its server names, including any aliases, local variations, and the numeric IP addresses.

An endpoint receiving a request with a Proxy-Uri Option that is unable or unwilling to act as a forward-proxy for the request MUST cause the return of a 5.05 (Proxying Not Supported) response.

The Proxy-Uri Option MUST take precedence over any of the Uri-Host, Uri-Port, Uri-Path or Uri-Query options (each of which MUST NOT be included in a request containing the Proxy-Uri Option).

As a special case to simplify many proxy clients, the absolute-URI can be constructed from the Uri-* options. When a Proxy-Scheme Option is present, the absolute-URI is constructed as follows: a CoAP URI is constructed from the Uri-* options as defined in Section 6.5. In the resulting URI, the initial scheme up to, but not including, the following colon is then replaced by the content of the Proxy- Scheme Option. Note that this case is only applicable if the components of the desired URI other than the scheme component actually can be expressed using Uri-* options; for example, to represent a URI with a userinfo component in the authority, only Proxy-Uri can be used.

pub fn add_query<S>(self, query: S) -> Selfwhere S: AsRef<str>,

Insert a new value for the Uri-Query option, alongside any existing values.

pub fn add_if_match<B>(self, tag: B) -> Selfwhere B: AsRef<[u8]>,

Insert a new value for the If-Match option, alongside any existing values.

If-Match

generated from RFC7252 section 5.10.8.1

The If-Match Option MAY be used to make a request conditional on the current existence or value of an ETag for one or more representations of the target resource. If-Match is generally useful for resource update requests, such as PUT requests, as a means for protecting against accidental overwrites when multiple clients are acting in parallel on the same resource (i.e., the “lost update” problem).

The value of an If-Match option is either an ETag or the empty string. An If-Match option with an ETag matches a representation with that exact ETag. An If-Match option with an empty value matches any existing representation (i.e., it places the precondition on the existence of any current representation for the target resource).

The If-Match Option can occur multiple times. If any of the options match, then the condition is fulfilled.

If there is one or more If-Match Options, but none of the options match, then the condition is not fulfilled.

pub fn add_location_path<S>(self, path: S) -> Selfwhere S: AsRef<str>,

Insert a new value for the Location-Path option, alongside any existing values.

Location-Path and Location-Query

generated from RFC7252 section 5.10.7

The Location-Path and Location-Query Options together indicate a relative URI that consists either of an absolute path, a query string, or both. A combination of these options is included in a 2.01 (Created) response to indicate the location of the resource created as the result of a POST request (see Section 5.8.2). The location is resolved relative to the request URI.

If a response with one or more Location-Path and/or Location-Query Options passes through a cache that interprets these options and the implied URI identifies one or more currently stored responses, those entries MUST be marked as not fresh.

Each Location-Path Option specifies one segment of the absolute path to the resource, and each Location-Query Option specifies one argument parameterizing the resource. The Location-Path and Location-Query Option can contain any character sequence. No percent-encoding is performed. The value of a Location-Path Option MUST NOT be “.” or “..”.

The steps for constructing the location URI from the options are analogous to Section 6.5, except that the first five steps are skipped and the result is a relative URI-reference, which is then interpreted relative to the request URI. Note that the relative URI- reference constructed this way always includes an absolute path (e.g., leaving out Location-Path but supplying Location-Query means the path component in the URI is “/”).

The options that are used to compute the relative URI-reference are collectively called Location-* options. Beyond Location-Path and Location-Query, more Location-* options may be defined in the future and have been reserved option numbers 128, 132, 136, and 140. If any of these reserved option numbers occurs in addition to Location-Path and/or Location-Query and are not supported, then a 4.02 (Bad Option) error MUST be returned.

pub fn add_location_query<S>(self, query: S) -> Selfwhere S: AsRef<str>,

Insert a new value for the Location-Query option, alongside any existing values.

Location-Path and Location-Query

generated from RFC7252 section 5.10.7

The Location-Path and Location-Query Options together indicate a relative URI that consists either of an absolute path, a query string, or both. A combination of these options is included in a 2.01 (Created) response to indicate the location of the resource created as the result of a POST request (see Section 5.8.2). The location is resolved relative to the request URI.

If a response with one or more Location-Path and/or Location-Query Options passes through a cache that interprets these options and the implied URI identifies one or more currently stored responses, those entries MUST be marked as not fresh.

Each Location-Path Option specifies one segment of the absolute path to the resource, and each Location-Query Option specifies one argument parameterizing the resource. The Location-Path and Location-Query Option can contain any character sequence. No percent-encoding is performed. The value of a Location-Path Option MUST NOT be “.” or “..”.

The steps for constructing the location URI from the options are analogous to Section 6.5, except that the first five steps are skipped and the result is a relative URI-reference, which is then interpreted relative to the request URI. Note that the relative URI- reference constructed this way always includes an absolute path (e.g., leaving out Location-Path but supplying Location-Query means the path component in the URI is “/”).

The options that are used to compute the relative URI-reference are collectively called Location-* options. Beyond Location-Path and Location-Query, more Location-* options may be defined in the future and have been reserved option numbers 128, 132, 136, and 140. If any of these reserved option numbers occurs in addition to Location-Path and/or Location-Query and are not supported, then a 4.02 (Bad Option) error MUST be returned.

pub fn add_etag<B>(self, tag: B) -> Selfwhere B: AsRef<[u8]>,

Insert a new value for the ETag option, alongside any existing values.

Location-Path and Location-Query

generated from RFC7252 section 5.10.7

The Location-Path and Location-Query Options together indicate a relative URI that consists either of an absolute path, a query string, or both. A combination of these options is included in a 2.01 (Created) response to indicate the location of the resource created as the result of a POST request (see Section 5.8.2). The location is resolved relative to the request URI.

If a response with one or more Location-Path and/or Location-Query Options passes through a cache that interprets these options and the implied URI identifies one or more currently stored responses, those entries MUST be marked as not fresh.

Each Location-Path Option specifies one segment of the absolute path to the resource, and each Location-Query Option specifies one argument parameterizing the resource. The Location-Path and Location-Query Option can contain any character sequence. No percent-encoding is performed. The value of a Location-Path Option MUST NOT be “.” or “..”.

The steps for constructing the location URI from the options are analogous to Section 6.5, except that the first five steps are skipped and the result is a relative URI-reference, which is then interpreted relative to the request URI. Note that the relative URI- reference constructed this way always includes an absolute path (e.g., leaving out Location-Path but supplying Location-Query means the path component in the URI is “/”).

The options that are used to compute the relative URI-reference are collectively called Location-* options. Beyond Location-Path and Location-Query, more Location-* options may be defined in the future and have been reserved option numbers 128, 132, 136, and 140. If any of these reserved option numbers occurs in addition to Location-Path and/or Location-Query and are not supported, then a 4.02 (Bad Option) error MUST be returned.

impl<C, O> MessageBuilder<C, O>where O: OptionMap, C: Array<Item = u8>,

pub fn build(self) -> Message<C, O>

Consume the builder, returning the built message

Trait Implementations

impl<PayloadBytes: Clone, Options: Clone> Clone for MessageBuilder<PayloadBytes, Options>

fn clone(&self) -> MessageBuilder<PayloadBytes, Options>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<PayloadBytes: Debug, Options: Debug> Debug for MessageBuilder<PayloadBytes, Options>

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

Formats the value using the given formatter.