Crate coap_message

CoAP mesage abstraction

This crate defines interfaces for readable and writable CoAP messages, which are used in the Internet of Things to transfer state in representations (REST). With these interfaces, it allows CoAP servers and clients to be written independently of the actual CoAP library that is used to serialize and deserialize the messages to the protocol.

The defined traits only cover the properties of CoAP at the request/response exchange level, not of the transport specific details. In particular, they do not expose tokens, message IDs or message types: Those are not even present in some transports, and in general there is no need for libraries to expose them. In the same vein, no methods are described to allocate messages: For constrained devices, that may not even be possible, and with CoAP libraries that support multiple configured transports, the type of message allocated may easily depend on the intended use. They do not cover remote addresses either, as these too are transport specific.

The crate also provides some trivial implementations of the types: Code for u8, OptionNumber for u16, as well as the heapmessage::HeapMessage for easy message manipulation and ownership on alloc systems.

Usage

Until standalone examples are available, there are examples available in coap-handler that illustrate in varying quality how to read from and write to messages.

The A larger chunk of examples and demos is available at coap-message-demos, which illustrates both how to build coap-message based handlers (albeit mainly using the existing implementations of coap-handler), and how to use them in practice with different implementations of CoAP.

If you are on the implementing side of the message traits, you may want to have a look at coap-message-utils, which contains useful building blocks.

Error handling

The readable message types are designed with minimal fallability -- for example, iterating over the options can not raise a "premature end of message" style error, and the payload is always "present" (albeit possibly empty). This encodes the concept that having a message type implies validity of the message.

Libraries that insist on minimizing the cycles spent parsing (as typical in embedded situations) can opt to express the formatting error as a critical, not-safe-to-forward option (eg. the private-use number 65535). As consumers of a message that has not been checked in advance must check all options before acting on the message anyway, this ensures that the error does not go unnoticed.

For the writable message types, no errors are implemented either, necessarily resulting in panics when things go awry. The expectation is that applications communicate their allocation needs to the stack before populating the message, for example using the estimate-length function of coap-handler. As for codes and options not supported by a library, these types of errors are caught by the Code and OptionNumber fallible conversions.

Modules

heapmessage	This module provides HeapMessage, an implementation of all the message traits backed by heap memory.
numtraits

Traits

Code	A message code A CoAP code
FromOtherOption	Experimental trait for conversion between option representation, with the goal to later avoid the conversion step via u16 and specialize for T->T conversions.
MessageOption	Iteration item for option values
MinimalWritableMessage	A message that needs to have its code, any options in ascending order and its payload set in that very sequence.
MutableWritableMessage	A message that allows later manipulation of a once set payload, and later truncation.
OptionNumber	A CoAP option number
ReadableMessage	A CoAP message whose code, options and payload can be read
SeekWritableMessage	Marker trait that indicates that the sequence of calling set_code, add_option and set_payload is not fixed. The sequence of calls only has meaning in that later set_code and set_payload calls override earlier ones, and that add_option on the same option number are stored in their sequence.
WithSortedOptions	Marker trait that indicates that ReadableMessage::options are produced in ascending sequence.