Struct MessageMut 

pub struct MessageMut<EM: MessageBufferMut> { /* private fields */ }

A CoAP message 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, as long as it does not truncate it. 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::MutableWritableMessage 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 anyway: The lifetime 'a only serves to describe the memory backing it; data is moved in there, not stored by reference. This property is accessible through downcasting.

Invariants

The message in the EM is always a well-formed CoAP message. This is upheld by construction or checked at creation time (when existing messages are consumed). As the underlying MessageBufferMut can be implemented without unsafe, this crate can only panic (but not invoke undefined behavior) when that is violated.

Implementations

impl<'a> MessageMut<SliceBufferMut<'a>>

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

Constructor of a message buffer around exclusive memory.

This is a short-cut for creating a SliceBufferMut and passing it to Self::new_empty().

pub fn new_from_encoded_slice( code: &'a mut u8, tail: &'a mut [u8], ) -> Result<Self, ParsingError>

Creates a MutableWritableMessage on a buffer that already contains a serialized message.

While this is generally not useful (as the message has been completed and there is no room for anything more), 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.

If the message has been parsed as a Message around a mutable back-end before, it is preferable to use its .into_mutable() method, as that can avoid the full parsing that is needed to uphold this type’s guarantees.

Errors

… are returned if the input slice does not contain a well-formed message.

impl<T: MessageBufferMut> MessageMut<T>

pub fn new_empty(encoded: T) -> Self

Constructor of a message buffer around any MessageBufferMut.

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

Available on crate feature downcast only.

Returns a full Self from input that is expected (but not known at type level) to be one.

impl<EM: MessageBufferMut> MessageMut<EM>

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

Inserts an option.

This behaves similarly to add_option(), but without the limitation of needing to uphold option ordering manually.

This comes at the cost of iterating over all options and re-encoding one.

Errors

This function returns a WriteError if there isn’t sufficient space left for the insertion.

pub fn retain_options<P>(&mut self, predicate: P)

where P: Fn(u16, &[u8]) -> bool,

Retains all options the predicate applies to, the rest will be removed.

pub fn reset(&mut self)

Discards anything that has been written in the message, and allows any operation that would be allowed after calling Self::new_empty().

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 untruncate(&mut self, added_len: usize) -> Result<(), WriteError>

Expands the bounds of the payload by added_len.

Similar to payload_mut_with_len(), but it has no restriction on length (beyond the length of the underlying buffer).

Errors

… are raised if there is insufficient space for extending the payload.

pub fn finish(self) -> (usize, EM)

Returns the number of bytes that were populated inside tail, along with the encoded data.

For EMs that are just referenced (i.e., slices), the 2nd output can often just be discarded, but it is essential for owned ones.

Trait Implementations

impl<EM: Clone + MessageBufferMut> Clone for MessageMut<EM>

fn clone(&self) -> MessageMut<EM>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<EM: MessageBufferMut> Debug for MessageMut<EM>

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

Formats the value using the given formatter.

impl<EM: MessageBufferMut> Format for MessageMut<EM>

Available on crate feature defmt only.

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

Writes the defmt representation of self to fmt.

impl<EM: MessageBufferMut> MinimalWritableMessage for MessageMut<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: MessageBufferMut> MutableWritableMessage for MessageMut<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: MessageBufferMut> ReadableMessage for MessageMut<EM>

type Code = u8

See Self::code()

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

Type of an individual option, indicating 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: MessageBufferMut> WithSortedOptions for MessageMut<EM>