Struct toad::req::builder::ReqBuilder

source ·

pub struct ReqBuilder<P>where
    P: PlatformTypes,
    OptValue<P>: Clone + Eq + Debug,
    SetError<P>: Clone + Debug + Eq,{ /* private fields */ }

Expand description

Build a request

note: this is highly experimental and will likely move and change roles. Do not use.

use toad::req::ReqBuilder;
use toad::std::{dtls, PlatformTypes as Std};
use toad::ContentFormat;

let payload = r#"""{
             "name": "Jameson",
             "say": "Hello"
           }"""#;

let request = ReqBuilder::<Std<dtls::Y>>::get("say_stuff").accept(ContentFormat::Json)
                                                          .content_format(ContentFormat::Json)
                                                          .payload(payload)
                                                          .build()
                                                          .unwrap();

let rep = send(&request);
assert_eq!(rep.payload_string().unwrap(), "Hello, Jameson!");

Implementations§

source §

impl ReqBuilderwhere P: PlatformTypes, OptValue: Clone + Eq + Debug, SetError: Clone + Debug + Eq,

source

pub fn get(path: impl AsRef<str>) -> Self

Creates a GET request

source

pub fn put(path: impl AsRef<str>) -> Self

Creates a PUT request

source

pub fn post(path: impl AsRef<str>) -> Self

Creates a POST request

source

pub fn delete(path: impl AsRef<str>) -> Self

Creates a DELETE request

source

pub fn option<V: ToCoapValue>(self, number: OptNumber, value: V) -> Self

Set the value of a non-repeatable option.

If the option has already been set, this will yield Err(Error::OptionNotRepeatable).

source

pub fn add_option<V: ToCoapValue>(self, number: OptNumber, value: V) -> Self

source

pub fn payload<V: ToCoapValue>(self, value: V) -> Self

Set the payload of the request

source

pub fn build(self) -> Result<Req, Error>

Unwrap the builder into the built request

source

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

Uri-Host, Uri-Port, Uri-Path, and Uri-Query

generated from RFC7252 section 5.10.1

The Uri-Host, Uri-Port, Uri-Path, and Uri-Query Options are used to specify the target resource of a request to a CoAP origin server. The options encode the different components of the request URI in a way that no percent-encoding is visible in the option values and that the full URI can be reconstructed at any involved endpoint. The syntax of CoAP URIs is defined in Section 6.

The steps for parsing URIs into options is defined in Section 6.4. These steps result in zero or more Uri-Host, Uri-Port, Uri-Path, and Uri-Query Options being included in a request, where each option holds the following values:

o the Uri-Host Option specifies the Internet host of the resource being requested,

o the Uri-Port Option specifies the transport-layer port number of the resource,

o each Uri-Path Option specifies one segment of the absolute path to the resource, and

o each Uri-Query Option specifies one argument parameterizing the resource.

Note: Fragments ([RFC3986], Section 3.5) are not part of the request URI and thus will not be transmitted in a CoAP request.

The default value of the Uri-Host Option is the IP literal representing the destination IP address of the request message. Likewise, the default value of the Uri-Port Option is the destination UDP port. The default values for the Uri-Host and Uri-Port Options are sufficient for requests to most servers. Explicit Uri-Host and Uri-Port Options are typically used when an endpoint hosts multiple virtual servers.

The Uri-Path and Uri-Query Option can contain any character sequence. No percent-encoding is performed. The value of a Uri-Path Option MUST NOT be “.” or “..” (as the request URI must be resolved before parsing it into options).

The steps for constructing the request URI from the options are defined in Section 6.5. Note that an implementation does not necessarily have to construct the URI; it can simply look up the target resource by examining the individual options.

Examples can be found in Appendix B.

source

pub fn size1(self, value: u32) -> Self

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.

source

pub fn if_match(self, value: ArrayVec<[u8; 8]>) -> Self

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.

source

pub fn if_none_match<S: AsRef<str>>(self) -> Self

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.)

source

pub fn proxy_uri<S: AsRef<str>>(self, value: S) -> Self

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.

source

pub fn proxy_scheme<S: AsRef<str>>(self, value: S) -> Self

See docs for Self.proxy_uri()

source

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

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.)

source

pub fn location_query<S: AsRef<str>>(self, value: S) -> Self

See docs for Self.location_path()

source

pub fn location_path<S: AsRef<str>>(self, value: S) -> Self

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.

source

pub fn etag(self, value: ArrayVec<[u8; 8]>) -> Self

ETag

generated from RFC7252 section 5.10.6

An entity-tag is intended for use as a resource-local identifier for differentiating between representations of the same resource that vary over time. It is generated by the server providing the resource, which may generate it in any number of ways including a version, checksum, hash, or time. An endpoint receiving an entity- tag MUST treat it as opaque and make no assumptions about its content or structure. (Endpoints that generate an entity-tag are encouraged to use the most compact representation possible, in particular in regards to clients and intermediaries that may want to store multiple ETag values.)

ETag as a Request Option

generated from RFC7252 section 5.10.6.2

In a GET request, an endpoint that has one or more representations previously obtained from the resource, and has obtained ETag response options with these, can specify an instance of the ETag Option for one or more of these stored responses.

A server can issue a 2.03 Valid response (Section 5.9.1.3) in place of a 2.05 Content response if one of the ETags given is the entity- tag for the current representation, i.e., is valid; the 2.03 Valid response then echoes this specific ETag in a response option.

In effect, a client can determine if any of the stored representations is current (see Section 5.6.2) without needing to transfer them again.

The ETag Option MAY occur zero, one, or multiple times in a request.

ETag as a Response Option

generated from RFC7252 section 5.10.6.1

The ETag Option in a response provides the current value (i.e., after the request was processed) of the entity-tag for the “tagged representation”. If no Location-* options are present, the tagged representation is the selected representation (Section 5.5.3) of the target resource. If one or more Location-* options are present and thus a location URI is indicated (Section 5.10.7), the tagged representation is the representation that would be retrieved by a GET request to the location URI.

An ETag response option can be included with any response for which there is a tagged representation (e.g., it would not be meaningful in a 4.04 or 4.00 response). The ETag Option MUST NOT occur more than once in a response.

There is no default value for the ETag Option; if it is not present in a response, the server makes no statement about the entity-tag for the tagged representation.

source

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

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).

source

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

Accept

generated from RFC7252 section 5.10.4

The CoAP Accept option can be used to indicate which Content-Format is acceptable to the client. The representation format is given as a numeric Content-Format identifier that is defined in the “CoAP Content-Formats” registry (Section 12.3). If no Accept option is given, the client does not express a preference (thus no default value is assumed). The client prefers the representation returned by the server to be in the Content-Format indicated. The server returns the preferred Content-Format if available. If the preferred Content- Format cannot be returned, then a 4.06 “Not Acceptable” MUST be sent as a response, unless another error code takes precedence for this response.