Struct coap_message_implementations::inmemory_write::Message

pub struct Message<'a> { /* private fields */ }

A message writing into a preallocated buffer

Implementations

impl<'a> Message<'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).

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

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 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 finish(self) -> usize

Return the number of bytes that were populated inside tail

Trait Implementations

impl<'a> MinimalWritableMessage for Message<'a>

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 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<'a> MutableWritableMessage for Message<'a>

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<'a> ReadableMessage for Message<'a>

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