Struct kwap_msg::Message

pub struct Message<PayloadC: Array<Item = u8>, OptC: Array<Item = u8> + 'static, Opts: Array<Item = Opt<OptC>>> {
    pub id: Id,
    pub ty: Type,
    pub ver: Version,
    pub token: Token,
    pub code: Code,
    pub opts: Opts,
    pub payload: Payload<PayloadC>,
}

Message struct

Low-level representation of a message that has been parsed from the raw binary format.

Note that Message is generic over 3 Arrays:

• PayloadC: the byte buffer used to store the message’s Payload
• OptC: byte buffer used to store Option values (OptValue)
• Opts: collection of Options in the message

Messages support both serializing to bytes and from bytes, by using the provided TryFromBytes and TryIntoBytes traits.

RFC7252 - CoAP Messaging Model

## Messaging Model [_generated from RFC7252 section 2.1_](https://datatracker.ietf.org/doc/html/rfc7252#section-2.1)

The CoAP messaging model is based on the exchange of messages over UDP between endpoints.

CoAP uses a short fixed-length binary header (4 bytes) that may be followed by compact binary options and a payload. This message format is shared by requests and responses. The CoAP message format is specified in Section 3. Each message contains a Message ID used to detect duplicates and for optional reliability. (The Message ID is compact; its 16-bit size enables up to about 250 messages per second from one endpoint to another with default protocol parameters.)

Reliability is provided by marking a message as Confirmable (CON). A Confirmable message is retransmitted using a default timeout and exponential back-off between retransmissions, until the recipient sends an Acknowledgement message (ACK) with the same Message ID (in this example, 0x7d34) from the corresponding endpoint; see Figure 2. When a recipient is not at all able to process a Confirmable message (i.e., not even able to provide a suitable error response), it replies with a Reset message (RST) instead of an Acknowledgement (ACK).

                     Client              Server
                        |                  |
                        |   CON [0x7d34]   |
                        +----------------->|
                        |                  |
                        |   ACK [0x7d34]   |
                        |<-----------------+
                        |                  |

Figure 2: Reliable Message Transmission

A message that does not require reliable transmission (for example, each single measurement out of a stream of sensor data) can be sent as a Non-confirmable message (NON). These are not acknowledged, but still have a Message ID for duplicate detection (in this example, 0x01a0); see Figure 3. When a recipient is not able to process a Non-confirmable message, it may reply with a Reset message (RST).

                     Client              Server
                        |                  |
                        |   NON [0x01a0]   |
                        +----------------->|
                        |                  |

              Figure 3: Unreliable Message Transmission

See Section 4 for details of CoAP messages.

As CoAP runs over UDP, it also supports the use of multicast IP destination addresses, enabling multicast CoAP requests. Section 8 discusses the proper use of CoAP messages with multicast addresses and precautions for avoiding response congestion.

Several security modes are defined for CoAP in Section 9 ranging from no security to certificate-based security. This document specifies a binding to DTLS for securing the protocol; the use of IPsec with CoAP is discussed in [IPsec-CoAP].

RFC7252 - CoAP Message Binary Format

## Message Format [_generated from RFC7252 section 3_](https://datatracker.ietf.org/doc/html/rfc7252#section-3)

CoAP is based on the exchange of compact messages that, by default, are transported over UDP (i.e., each CoAP message occupies the data section of one UDP datagram). CoAP may also be used over Datagram Transport Layer Security (DTLS) (see Section 9.1). It could also be used over other transports such as SMS, TCP, or SCTP, the specification of which is out of this document’s scope. (UDP-lite [RFC3828] and UDP zero checksum [RFC6936] are not supported by CoAP.)

CoAP messages are encoded in a simple binary format. The message format starts with a fixed-size 4-byte header. This is followed by a variable-length Token value, which can be between 0 and 8 bytes long.

Following the Token value comes a sequence of zero or more CoAP Options in Type-Length-Value (TLV) format, optionally followed by a payload that takes up the rest of the datagram.

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Ver| T |  TKL  |      Code     |          Message ID           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   Token (if any, TKL bytes) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|   Options (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|1 1 1 1 1 1 1 1|    Payload (if any) ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                      Figure 7: Message Format

The fields in the header are defined as follows:

Version (Ver): 2-bit unsigned integer. Indicates the CoAP version number. Implementations of this specification MUST set this field to 1 (01 binary). Other values are reserved for future versions. Messages with unknown version numbers MUST be silently ignored.

Type (T): 2-bit unsigned integer. Indicates if this message is of type Confirmable (0), Non-confirmable (1), Acknowledgement (2), or Reset (3). The semantics of these message types are defined in Section 4.

Token Length (TKL): 4-bit unsigned integer. Indicates the length of the variable-length Token field (0-8 bytes). Lengths 9-15 are reserved, MUST NOT be sent, and MUST be processed as a message format error.

Code: 8-bit unsigned integer, split into a 3-bit class (most significant bits) and a 5-bit detail (least significant bits), documented as “c.dd” where “c” is a digit from 0 to 7 for the 3-bit subfield and “dd” are two digits from 00 to 31 for the 5-bit subfield. The class can indicate a request (0), a success response (2), a client error response (4), or a server error response (5). (All other class values are reserved.) As a special case, Code 0.00 indicates an Empty message. In case of a request, the Code field indicates the Request Method; in case of a response, a Response Code. Possible values are maintained in the CoAP Code Registries (Section 12.1). The semantics of requests and responses are defined in Section 5.

Message ID: 16-bit unsigned integer in network byte order. Used to detect message duplication and to match messages of type Acknowledgement/Reset to messages of type Confirmable/Non- confirmable. The rules for generating a Message ID and matching messages are defined in Section 4.

The header is followed by the Token value, which may be 0 to 8 bytes, as given by the Token Length field. The Token value is used to correlate requests and responses. The rules for generating a Token and correlating requests and responses are defined in Section 5.3.1.

Header and Token are followed by zero or more Options (Section 3.1). An Option can be followed by the end of the message, by another Option, or by the Payload Marker and the payload.

Following the header, token, and options, if any, comes the optional payload. If present and of non-zero length, it is prefixed by a fixed, one-byte Payload Marker (0xFF), which indicates the end of options and the start of the payload. The payload data extends from after the marker to the end of the UDP datagram, i.e., the Payload Length is calculated from the datagram size. The absence of the Payload Marker denotes a zero-length payload. The presence of a marker followed by a zero-length payload MUST be processed as a message format error.

Implementation Note: The byte value 0xFF may also occur within an option length or value, so simple byte-wise scanning for 0xFF is not a viable technique for finding the payload marker. The byte 0xFF has the meaning of a payload marker only where the beginning of another option could occur.

use kwap_msg::TryFromBytes;
use kwap_msg::*;
let packet: Vec<u8> = /* bytes! */

// `VecMessage` uses `Vec` as the backing structure for byte buffers
let msg = VecMessage::try_from_bytes(packet.clone()).unwrap();
let mut opts_expected = /* create expected options */

let expected = VecMessage {
  id: Id(1),
  ty: Type::Con,
  ver: Version(1),
  token: Token(tinyvec::array_vec!([u8; 8] => 254)),
  opts: opts_expected,
  code: Code {class: 2, detail: 5},
  payload: Payload(b"hello, world!".to_vec()),
};

assert_eq!(msg, expected);

Fields

id: Id

see Id for details

ty: Type

see Type for details

ver: Version

see Version for details

token: Token

see Token for details

code: Code

see Code for details

opts: Opts

see opt::Opt for details

payload: Payload<PayloadC>

see Payload

Trait Implementations

impl<PayloadC: Clone + Array<Item = u8>, OptC: Clone + Array<Item = u8> + 'static, Opts: Clone + Array<Item = Opt<OptC>>> Clone for Message<PayloadC, OptC, Opts>

fn clone(&self) -> Message<PayloadC, OptC, Opts>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<PayloadC: Debug + Array<Item = u8>, OptC: Debug + Array<Item = u8> + 'static, Opts: Debug + Array<Item = Opt<OptC>>> Debug for Message<PayloadC, OptC, Opts>

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

Formats the value using the given formatter.

impl<P: Array<Item = u8>, O: Array<Item = u8>, Os: Array<Item = Opt<O>>> GetSize for Message<P, O, Os>

fn get_size(&self) -> usize

Get the runtime size (in bytes) of a struct

fn max_size(&self) -> Option<usize>

Get the max size that this data structure can acommodate.

fn size_is_zero(&self) -> bool

Check if the runtime size is zero

fn is_full(&self) -> bool

Is there no room left in this collection?

impl<PayloadC: PartialEq + Array<Item = u8>, OptC: PartialEq + Array<Item = u8> + 'static, Opts: PartialEq + Array<Item = Opt<OptC>>> PartialEq<Message<PayloadC, OptC, Opts>> for Message<PayloadC, OptC, Opts>

fn eq(&self, other: &Message<PayloadC, OptC, Opts>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Message<PayloadC, OptC, Opts>) -> bool

This method tests for !=.

impl<PayloadC: PartialOrd + Array<Item = u8>, OptC: PartialOrd + Array<Item = u8> + 'static, Opts: PartialOrd + Array<Item = Opt<OptC>>> PartialOrd<Message<PayloadC, OptC, Opts>> for Message<PayloadC, OptC, Opts>

fn partial_cmp(&self, other: &Message<PayloadC, OptC, Opts>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, P: Array<Item = u8>, O: Array<Item = u8>, Os: Array<Item = Opt<O>>> TryFromBytes<&'a u8> for Message<P, O, Os>

type Error = MessageParseError

Error type yielded if conversion fails

fn try_from_bytes<I: IntoIterator<Item = &'a u8>>(
    bytes: I
) -> Result<Self, Self::Error>

Try to convert from some sequence of bytes T into Self

impl<P: Array<Item = u8>, O: Array<Item = u8>, Os: Array<Item = Opt<O>>> TryFromBytes<u8> for Message<P, O, Os>

type Error = MessageParseError

Error type yielded if conversion fails

fn try_from_bytes<I: IntoIterator<Item = u8>>(
    bytes: I
) -> Result<Self, Self::Error>

Try to convert from some sequence of bytes T into Self

impl<P: Array<Item = u8>, O: Array<Item = u8>, Os: Array<Item = Opt<O>>> TryIntoBytes for Message<P, O, Os>

type Error = MessageToBytesError

fn try_into_bytes<C: Array<Item = u8>>(self) -> Result<C, Self::Error>

Try to convert into a collection of bytes

impl<PayloadC: Array<Item = u8>, OptC: Array<Item = u8> + 'static, Opts: Array<Item = Opt<OptC>>> StructuralPartialEq for Message<PayloadC, OptC, Opts>