Expand description
Low-level representation of CoAP messages.
The most notable item in kwap_msg
is Message
;
a CoAP message very close to the actual byte layout.
Allocation
CoAP messages have some attributes whose size is dynamic:
- The message payload (in http terms: the request/response body)
- the number of options (in http terms: headers)
- the value of an option (in http terms: header value)
Message
does not require an allocator and has no opinions about what kind of collection
it uses internally to store these values.
It solves this problem by being generic over the collections it needs and uses an Array
trait
to capture its idea of what makes a collection useful.
This means that you may use a provided implementation (for Vec
or tinyvec::ArrayVec
)
or provide your own collection (see the custom collections example)
//! Note: both of these type aliases are exported by `kwap_msg` for convenience.
use tinyvec::ArrayVec;
use kwap_msg::{Message, Opt};
// Message Payload byte buffer
// |
// | Option Value byte buffer
// | |
// | | Array of options in the message
// vvvvvvv vvvvvvv vvvvvvvvvvvvvvvvv
type VecMessage = Message<Vec<u8>, Vec<u8>, Vec<Opt<Vec<u8>>>>;
// Used like: `ArrayVecMessage<1024, 256, 16>`; a message that can store a payload up to 1024 bytes, and up to 16 options each with up to a 256 byte value.
type ArrayVecMessage<
const PAYLOAD_SIZE: usize,
const OPT_SIZE: usize,
const NUM_OPTS: usize,
> = Message<
ArrayVec<[u8; PAYLOAD_SIZE]>,
ArrayVec<[u8; OPT_SIZE]>,
ArrayVec<[Opt<ArrayVec<[u8; OPT_SIZE]>>; NUM_OPTS]>,
>;
It may look a little ugly, but a core goal of kwap
is to be platform- and alloc-agnostic.
Performance
This crate uses criterion
to measure performance of the heaped & heapless implementations in this crate as well as coap_lite::Packet
.
In general, kwap_msg::VecMessage
performs identically to coap_lite (+/- 5%), and both are much faster than kwap_msg::ArrayVecMessage
.
Benchmarks:
Serializing to bytes
Click to expand chart
Deserializing from bytes
Click to expand chart
Structs
CoAP Code Registries
Iterator yielded by EnumerateOptNumbers
, wrapping an Iterator
over Opt
s.
Message ID
Message
struct
Options
The “Option Delta” is the difference between this Option’s Number and the previous Option’s number.
Option Numbers
Option Value Formats
Payloads and Representations
Token
Version of the CoAP protocol that the message adheres to.
Enums
Whether a code is for a request, response, or empty message
Errors encounterable while parsing a message from bytes
Errors encounterable while parsing an option from bytes
Critical/Elective
Indicates if this message is of type Confirmable (0), Non-confirmable (1), Acknowledgement (2), or Reset (3).
Proxy Unsafe or Safe-to-Forward and NoCacheKey
Proxy Unsafe or Safe-to-Forward and NoCacheKey
Traits
Creates an iterator which gives the current opt’s number as well as the option.
Trait for converting a sequence of bytes into some data structure
Trait allowing fallible conversion into bytes
Type Definitions
Message that uses static fixed-capacity stack-allocating byte buffers
Message that uses Vec byte buffers