Struct coap_message_utils::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.

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

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