Trait coap_message::MutableWritableMessage

source · [−]
pub trait MutableWritableMessage: MinimalWritableMessage {
    fn available_space(&self) -> usize;
    fn payload_mut(&mut self) -> &mut [u8];
    fn truncate(&mut self, len: usize);
    fn mutate_options<F>(&mut self, callback: F)
   where
        F: FnMut(Self::OptionNumber, &mut [u8]);

    fn payload_mut_with_len(&mut self, len: usize) -> &mut [u8] { ... }
}
Expand description

A message that allows later manipulation of a once set payload, and later truncation.

This is a bit of an unsorted bag that needs further cleanup (FIXME) – most of this is motivated by block-wise and write-in-place. Might need a bit of reshape, possibly something like a once-callable .write_payload(|d: &mut [u8]| { write_to(d); Ok(bytes_written)}). Does this need a hint of the length to allocate for implementations that don’t pre-allocate the message? Is 1024 a good enough value to not pass it?

The available_space is only needed where applications want to use up the last byte by not zero-padding the Block2 option to its szx=0 equivalent.

Can that be efficiently be replaced with something like this, and can it be optimized down to the hand-written counting-of-option-bytes that’s involved in the use of available_space?

ⓘ
let mut m = allocated_message;
for szx in 6..0 {
    snap = m.snapshot();
    m.add_option(BLOCK2, ...);
    m.add_option(..., ...);

    if let Ok(_) = m.write_payload(|p| {
        if (p.len() < 1 << (4 + szx)) {
            return Err(());
        }

        let written = write_block(...);

        Ok(written)
    }) {
        break;
    } else {
        m = m.revert_to(snap);
    }
} else {
    panic!("Allocated space doesn't even suffice for 16 byte payload");
}

Required Methods

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

👎Deprecated since 0.1.1:

Use payload_mut_with_len instead

Legacy method for mutable access to the payload

This is deprecated in favor of MutableWritableMessage::payload_mut_with_len which makes it possible to implement allocated-on-demand writable messages without pessimistically pre-allocating based on a handler’s estimate_length().

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.

Apply a callback to all options in sequence

This is a possibly inefficient but generic way achieve “allocate first, set when done” pattern typically found for options like ETag.

Provided Methods

Memory-map len bytes of the payload for writing

If a payload has been set previously, that payload will be available in the slice; in that case, the caller must make sure to not exceed its length.

If no payload has been set previously, and the requested length exceeds the available buffer space, the longest possible payload should be mapped.

It is a provided method for compatibility with older implementations; new ones should (and ones without preallocated memory need to) implement this instead.

Implementors