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. //! //! 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. //! //! [examples available in coap-handler]: https://gitlab.com/chrysn/coap-handler/-/blob/master/src/implementations.rs //! [coap-message-demos]: https://gitlab.com/chrysn/coap-message-demos //! //! 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. //! //! [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;