Struct Error

pub struct Error { /* private fields */ }

A build-time-flexible renderable error type

This is used wherever this crate produces errors, and also recommended for outside handlers – the idea being that the more code parts share a type, the more compact code can be emitted.

Depending on what gets configured, it may just be a single u8 error code, or it may contain more details such as the number of the option that could not be processed, or any other Standard Problem Details (RFC9290).

The most typical use for this is to be used as a coap_handler::Handler::ExtractRequestError. It can also be used as a coap_handler::Handler::BuildResponseError, to express late errors, but then it needs to coexist with the errors raised from writing to the response message. For that coexistence, the Self::from_unionerror conversion is provided.

Implementations

impl Error

pub fn bad_option(unprocessed_option: u16) -> Self

Create an error response for an unprocessed option

The response is rendered with a single unprocessed-coap-option problem detail if that feature is enabled.

If the unprocessed option has a special error code (e.g. Accept => 4.06 Not Acceptable or Content Format => 4.15 Unsupported Content-Format), that code is emitted instead of the default 4.02 Bad Option, and the unprocessed-coap-option problem details is not emitted. In particular, Uri-Path is turned into a 4.04 Not Found, because it indicates that some resource did not expect any URI components after the last expected component.

Note that the CoAP option number is given as a u16, as is common around the CoAP crates (even though 0 is a reseved value). It is an error to pass in the value 0; the implementation may treat this as a reason for a panic, or silently ignore the error and not render the problem detail.

pub fn bad_request_with_rbep(byte: usize) -> Self

Create a 4.00 Bad Request error with a Request Body Error Position indicating at which position in the request’s body the error occurred

If the crate is compiled without the error_request_body_error_position feature, the position information will be ignored. The value may also be ignored if it exceeds an internal limit of how large values can be expressed.

pub fn from_unionerror(_err: impl Debug + RenderableOnMinimal) -> Self

Convert any writable message’s UnionError into an Error.

This discards the error’s details and just builds an Internal Server Error.

The reason why this exists as a method is ergonomics: It allows handler implementations to have a BuildResponse that returns crafted Error instances, and still escalate errors from writing through .map_err(Error::from_unionerror).

Downsides

Using this might lose some debug information if the errors of the writable message turn out to be more than Internal Server Error messages. Currently, such uses are not known; if they come up, this method will likely be deprecated in favor of something that extracts errors better. (One option for that point is to use an enum of Error and whatever the other thing is; right now, this would only lead to duplication in generated machine code).

Constraints

Note that this signature does not constrain the type of _err a lot – there is no hard criterium to recognize whether a type is a conversion or write error pertaining to the current response message, or just an arbitrary error. By convention, this is only applied to items that can be converted into the UnionError; upholding that convention helps spotting if ever there needs to be a replacement for this.

pub fn bad_request() -> Self

Create an otherwise empty 4.00 Bad Request error

pub fn unauthorized() -> Self

Create an otherwise empty 4.01 Unauthorized error

pub fn forbidden() -> Self

Create an otherwise empty 4.03 Forbidden error

pub fn not_found() -> Self

Create an otherwise empty 4.04 Not Found error

pub fn method_not_allowed() -> Self

Create an otherwise empty 4.05 Method Not Allowed error

pub fn not_acceptable() -> Self

Create an otherwise empty 4.06 Not Acceptable error

Note that this error can also be created by calling [Self::bad_option(o)] when o is an Accept option (so there is no need for special casing by the application, but it may be convenient to use this function when it is decided late that the requested format was parsed turned out to be unsuitable).

pub fn unsupported_content_format() -> Self

Create an otherwise empty 4.15 Unsupported Content Format error

Note that this error can also be created by calling [Self::bad_option(o)] when o is a Content-Format option (so there is no need for special casing by the application, but it may be convenient to use this function when it is decided late that a content format that was parsed turned out to be unsuitable).

pub fn internal_server_error() -> Self

Create an otherwise empty 5.00 Internal Server Error error

pub fn service_unavailable() -> Self

Create an otherwise empty 5.03 Service Unavailable error

pub fn with_title(self, title: &'static str) -> Self

Set a title on the error

The title will be used as a diagnostic payload if no other diagnostic components are on a message, or it will be set as the title detail. This function is available unconditionally, but the title property is only stored if the error_title feature is enabled, or on debug builds to be shown in the Debug representation.

On CoAP message implementations where [MinimalWritableMessage::promote_to_mutable_writable_message] returns None, the title may not be shown in more complex results for lack of buffer space; where it returns Some, it can use the full available message and is thus usually shown (unless the full error response is too large for the message, in which case no payload is emitted).

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl RenderableOnMinimal for Error

type Error<IE: RenderableOnMinimal + Debug> = IE

Error to return when even the error rendering is unsuccessful (a “double error”).

fn render<M: MinimalWritableMessage>( self, message: &mut M, ) -> Result<(), Self::Error<M::UnionError>>

Express the error in a CoAP response message

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 12 bytes