1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

#![no_std]
#![feature(generic_associated_types)]
//! 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.
//!
//! [CoAP]: http://coap.technology/
//!
//! 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, and [in coap-lite] on how
//! these handlers can be integrated with an actual CoAP library.
//!
//! [examples available in coap-handler]: https://gitlab.com/chrysn/coap-handler/-/blob/master/src/implementations.rs
//! [in coap-lite]: https://github.com/martindisch/coap-lite/blob/master/examples/server_coaphandler.rs
//!
//! For further examples of the coap-message ecosystem, look at the
//! [embedded-nal-minimal-coapserver] (which builds on [embedded-nal], the network abstraction
//! layer) and the [coap-message-utils] that provide comon tools for writing similar
//! implementations of the coap-message traits.
//!
//! [embedded-nal-minimal-coapserver]: https://gitlab.com/chrysn/embedded-nal-minimal-coapserver
//! [embedded-nal]: https://crates.io/crates/embedded-nal
//! [coap-message-utils]: https://crates.io/crates/coap-message-utils
//!
//! 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.
//!
//! [estimate-length]: https://docs.rs/coap-handler/0.0.1/coap_handler/trait.Handler.html#tymethod.estimate_length

mod message;
mod numbers;

pub use message::{
    MessageOption, MinimalWritableMessage, MutableWritableMessage, ReadableMessage,
    SeekWritableMessage, WithSortedOptions,
};

pub use numbers::{Code, FromOtherOption, OptionNumber};

#[cfg(feature = "typenum_test")]
mod typenum_test;

#[cfg(feature = "alloc")]
pub mod heapmessage;

pub mod numtraits;