Trait coap_message::MinimalWritableMessage

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

    // 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 { ... }
    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> { ... }
}

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

This is the bare minimum a message needs to provide to be populated as a request or response by a generic program; it is up to the program to ensure the 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, when uncommon code paths are triggered together.

Other errors in the 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 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.

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)

type Code: Code

type OptionNumber: OptionNumber

Required Methods

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

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.

This works on option values as they are encoded in messages. 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>

Provided Methods

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

where M: ReadableMessage,

Copy code, options and payload in from a readable message

Implementations can override this for cases where it can be done more efficiently than iterating over the options and appending them.

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.

While the trait under U is hidden (pending the use of a more generic one num-types based one), own implementations are not possible.

Object Safety

This trait is not object safe.

Implementors