Trait coap_message::MinimalWritableMessage

pub trait MinimalWritableMessage {
    type Code: Code;
    type OptionNumber: OptionNumber;
    type AddOptionError: RenderableOnMinimal + Debug;
    type SetPayloadError: RenderableOnMinimal + Debug;
    type UnionError: RenderableOnMinimal + Debug + From<Self::AddOptionError> + From<Self::SetPayloadError> + From<<Self::Code as Code>::Error> + From<<Self::OptionNumber as OptionNumber>::Error>;

    // Required methods
    fn set_code(&mut self, code: Self::Code);
    fn add_option(
        &mut self,
        number: Self::OptionNumber,
        value: &[u8]
    ) -> Result<(), Self::AddOptionError>;
    fn set_payload(&mut self, data: &[u8]) -> Result<(), Self::SetPayloadError>;

    // Provided methods
    fn set_from_message<M>(&mut self, msg: &M) -> Result<(), Self::UnionError>
       where M: ReadableMessage + WithSortedOptions { ... }
    fn add_option_str(
        &mut self,
        number: Self::OptionNumber,
        value: &str
    ) -> Result<(), Self::AddOptionError> { ... }
    fn add_option_uint<U: Unsigned + ToBytes>(
        &mut self,
        number: Self::OptionNumber,
        value: U
    ) -> Result<(), Self::AddOptionError> { ... }
    fn convert_code_error(e: <Self::Code as Code>::Error) -> Self::UnionError { ... }
    fn convert_option_number_error(
        e: <Self::OptionNumber as OptionNumber>::Error
    ) -> Self::UnionError { ... }
    fn convert_add_option_error(e: Self::AddOptionError) -> Self::UnionError { ... }
    fn convert_set_payload_error(e: Self::SetPayloadError) -> Self::UnionError { ... }
}

A message that can be written to, creating a CoAP request or response.

This is the bare minimum a message type needs to provide to generic applications. It is up to the user to ensure this valid sequence of operations:

• Exactly one call to set_code
• Any number of calls to add_option, with monotonically increasing option numbers
• Zero or one call to set_payload

Steps that can reasonably fail at runtime are fallible – for example, a payload to be set may simply not fit within the message size. Adding options in the wrong sequence is also an expected source, eg. when code paths are triggered that were not tested in that combination.

Other errors violating the call sequence, such as failure to call set_code, or adding an option after the payload has been set, may be implemented in a panic. (When occurring in a fallible operation, the implementation may also choose to report an error instead).

Failed operations may be retried (eg. with shorter values); the failed attempt must not have an effect on the message.

Implementations may tolerate erroneous call sequences as long as they can produce messages that are likely to match the caller’s expectations – no need to keep track of usage errors just to produce correct errors. Users may wrap messages in dedicated checkers for more strictness.

Required Associated Types

type Code: Code

See Self::set_code()

type OptionNumber: OptionNumber

See Self::add_option()

type AddOptionError: RenderableOnMinimal + Debug

Error returned when an option can not be added (eg. for lack of space, or because an option of a higher number or even the payload was already set)

type SetPayloadError: RenderableOnMinimal + Debug

Error returned when setting the payload (eg. for lack of space, or when a message of that type does not take a payload)

type UnionError: RenderableOnMinimal + Debug + From<Self::AddOptionError> + From<Self::SetPayloadError> + From<<Self::Code as Code>::Error> + From<<Self::OptionNumber as OptionNumber>::Error>

Error type into which either of the other errors, as well as the errors for conversion of the Code and OptionNumber, can be .into()ed.

For many implementations it can make sense to use a single error type for all of those, in which case the From bounds are trivially fulfilled.

Required Methods

fn set_code(&mut self, code: Self::Code)

Set the CoAP code of the message (in a request, that is the request method)

fn add_option( &mut self, number: Self::OptionNumber, value: &[u8] ) -> Result<(), Self::AddOptionError>

Add an option to the message

Calls to this method need to happen in ascending numeric sequence.

The option number is pre-encoded in the Self::OptionNumber type. The value is provided in its serialized form. Under the aspect of option value formats, this adds opaque options (but may just as well be used for adding options in another format when they are pre-encoded).

fn set_payload(&mut self, data: &[u8]) -> Result<(), Self::SetPayloadError>

Set the payload to the message

This must be called only once.

Provided Methods

fn set_from_message<M>(&mut self, msg: &M) -> Result<(), Self::UnionError>

where M: ReadableMessage + WithSortedOptions,

Copy code, options and payload in from a readable message

fn add_option_str( &mut self, number: Self::OptionNumber, value: &str ) -> Result<(), Self::AddOptionError>

Shortcut for add_option(self, number, value.as_bytes()).

Implementations with type checked options can provide more efficient implementations (ie. ones that don’t need to UTF-8-check when they feed the resulting bytes back into a string field), but must still accept string options via the generic add_option() method.

fn add_option_uint<U: Unsigned + ToBytes>( &mut self, number: Self::OptionNumber, value: U ) -> Result<(), Self::AddOptionError>

Shortcut for add_option on a buffer containing the uint encoded value

Implementations with type checked options can provide more efficient implementations (ie. ones that don’t need to decode the uint when reading it into a uint field), but must still accept integer options via the generic add_option() method.

fn convert_code_error(e: <Self::Code as Code>::Error) -> Self::UnionError

Auxiliary function for converting Self::Code::Error

This should really not be needed, but serves well in allowing coap-request-imlementations to convert errors found during writing into their RequestUnionError that can be returned.

fn convert_option_number_error( e: <Self::OptionNumber as OptionNumber>::Error ) -> Self::UnionError

Auxiliary function for converting Self::OptionNumber::Error

This should really not be needed, but serves well in allowing coap-request-imlementations to convert errors found during writing into their RequestUnionError that can be returned.

fn convert_add_option_error(e: Self::AddOptionError) -> Self::UnionError

Auxiliary function for converting Self::AddOptionError

This should really not be needed, but serves well in allowing coap-request-imlementations to convert errors found during writing into their RequestUnionError that can be returned.

fn convert_set_payload_error(e: Self::SetPayloadError) -> Self::UnionError

Auxiliary function for converting Self::SetPayloadError

This should really not be needed, but serves well in allowing coap-request-imlementations to convert errors found during writing into their RequestUnionError that can be returned.

Object Safety

This trait is not object safe.

Implementors