Struct GenericMessage 

pub struct GenericMessage<EM: EncodedMessage> { /* private fields */ }

A message writing into a preallocated buffer

Implementations

impl<'a> GenericMessage<SliceMessage<'a>>

A CoAP messag that resides in contiguous mutable memory

Exceeding the guarantees of MutableWritableMessage, this does allow some out-of-sequence invocations: Even after payload has been written to, options can be added, memmove’ing (right-rotating) the written payload, possibly truncating it out of the buffer. This is needed to accommodate libOSCORE’s requirements (because while libOSCORE can also do without a memmove-ing message, that’d require its use through WritableMessage to adhere to in-OSCORE write sequence conventions, making the whole situation no easier on the coap-message abstraction). Data will only be moved if an option is added after content has been set, so this comes at no runtime cost for those who do not need it. (It may be later turned into a feature. Then, the memmove code would be removed; carrying the latest option number in the WriteState should come at no extra cost due to the struct’s content and alignment).

When viewed through the coap_message::ReadableMessage trait, this will behave as if writing had stopped (but still allows writes after reading); in particular, the payload will be shown as empty. (This may be obvious from most points of view, but when coming from a [coap_message::WritableMessage] point of view where payloads can only ever be truncated and not made longer, this clarification is relevant).

The type is covariant over its lifetime. This also means that we can never add any methods where we move references into Self, but we don’t do this: The lifetime 'a only serves to describe the memory backing it; data is moved in there, not stored by reference.

FIXME: The covaraint property is not available through … how would it even be made available?

pub fn new(code: &'a mut u8, tail: &'a mut [u8]) -> Self

pub fn new_from_existing(code: &'a mut u8, tail: &'a mut [u8]) -> Self

Create a MutableWritableMessage on a buffer that already contains a serialized message

While this is generally not useful (a parsed message has its paylod already set, and if there’s no payload, there’s no space to add options or any payload), it allows mutable access to the option bytes and the payload. This is primarily useful in situations when data is processed in place, eg. decrypted (in OSCORE), or CBOR is shifted around to get contiguous slices out of indefinite length strings.

This uses the same strategy for errors as crate::inmemory::Message: Validation happens incrementally.

pub fn downcast_from<M: MinimalWritableMessage>( generic: &'a mut M, ) -> Option<&'a mut Self>

Available on crate feature downcast only.

impl<T: EncodedMessage> GenericMessage<T>

pub fn new_from_empty_encoded(encoded: T) -> Self

impl<EM: EncodedMessage> GenericMessage<EM>

pub fn reset(&mut self)

Discard anything that has been written in the message, and allow any operation that would be allowed after calling Self::new().

This is a short-cut to messages that can be snapshotted and rewound, and a band-aid until that is available in traits.

pub fn finish(self) -> usize

Return the number of bytes that were populated inside tail

Trait Implementations

impl<EM: EncodedMessage> Debug for GenericMessage<EM>

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

Formats the value using the given formatter.

impl<EM: EncodedMessage> Format for GenericMessage<EM>

Available on crate feature defmt only.

fn format(&self, f: Formatter<'_>)

Writes the defmt representation of self to fmt.

impl<EM: EncodedMessage> MinimalWritableMessage for GenericMessage<EM>

type Code = u8

See Self::set_code()

type OptionNumber = u16

See Self::add_option()

type UnionError = WriteError

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.

type AddOptionError = WriteError

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

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

fn set_code(&mut self, code: u8)

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

fn add_option(&mut self, number: u16, data: &[u8]) -> Result<(), WriteError>

Add an option to the message

fn set_payload(&mut self, payload: &[u8]) -> Result<(), WriteError>

Set the payload to the message

fn with_static_type_annotation( &mut self, ) -> Option<RefMutWithStaticType<'_, Self>>

Type ID of Self or a ’static version of Self

fn promote_to_mutable_writable_message(&mut self) -> Option<&mut Self>

Tries to obtain a MutableWritableMessage from self.

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

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

where U: Unsigned + ToBytes,

Shortcut for add_option on a buffer containing the uint encoded value

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

Auxiliary function for converting Self::Code::Error

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

Auxiliary function for converting Self::OptionNumber::Error

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

Auxiliary function for converting Self::AddOptionError

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

Auxiliary function for converting Self::SetPayloadError

impl<EM: EncodedMessage> MutableWritableMessage for GenericMessage<EM>

fn available_space(&self) -> usize

Number of bytes available for additional options, payload marker and payload

fn payload_mut_with_len(&mut self, len: usize) -> Result<&mut [u8], WriteError>

Memory-map len bytes of the payload for writing

fn truncate(&mut self, len: usize) -> Result<(), WriteError>

Truncate an already-set payload to the given length; that payload must have been written to before using MinimalWritableMessage::set_payload, or with a suitable MutableWritableMessage::payload_mut_with_len call.

fn mutate_options<F>(&mut self, f: F)

where F: FnMut(u16, &mut [u8]),

Apply a callback to all options in sequence

impl<EM: EncodedMessage> ReadableMessage for GenericMessage<EM>

type Code = u8

See Self::code()

type MessageOption<'b> = MessageOption<'b> where Self: 'b

Type of an individual option, indiciating its option number and value

type OptionsIter<'b> = OptionsIter<'b> where Self: 'b

See Self::options()

fn code(&self) -> u8

Get the code (request method or response code) of the message

fn payload(&self) -> &[u8]

Get the payload set in the message

fn options(&self) -> <Self as ReadableMessage>::OptionsIter<'_>

Produce all options in arbitrary order as an iterator

fn with_static_type_annotation(&self) -> Option<RefWithStaticType<'_, Self>>

Type ID of Self or a ’static version of Self

impl<EM: EncodedMessage> WithSortedOptions for GenericMessage<EM>