nanocoap.h File Reference

nanocoap API More...

Detailed Description

nanocoap API

Author

Kaspar Schleiser kaspa.nosp@m.r@sc.nosp@m.hleis.nosp@m.er.d.nosp@m.e

Ken Bannister kb2ma.nosp@m.@run.nosp@m.box.c.nosp@m.om

Hauke Petersen hauke.nosp@m..pet.nosp@m.ersen.nosp@m.@fu-.nosp@m.berli.nosp@m.n.de

Definition in file nanocoap.h.

#include <assert.h>
#include <errno.h>
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include <string.h>
#include <unistd.h>
#include "bitarithm.h"
#include "bitfield.h"
#include "byteorder.h"
#include "iolist.h"
#include "macros/utils.h"
#include "modules.h"
#include "net/coap.h"
#include "net/sock/udp.h"

Include dependency graph for nanocoap.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	coap_hdr_t
	Raw CoAP PDU header structure. More...
struct	coap_optpos_t
	CoAP option array entry. More...
struct	coap_pkt_t
	CoAP PDU parsing context structure. More...
struct	coap_resource_t
	Type for CoAP resource entry. More...
struct	coap_resource_subtree_t
	Type for CoAP resource subtrees. More...
struct	_coap_request_ctx
	CoAP resource request handler context. More...
struct	coap_block1_t
	Block1 helper struct. More...
struct	coap_block_slicer_t
	Blockwise transfer helper struct. More...

Macros
#define	COAP_FORMAT_NONE   (UINT16_MAX)
	nanoCoAP-specific value to indicate no format specified
#define	CONFIG_NANOCOAP_NOPTS_MAX   (16)
	Maximum number of Options in a message.
#define	CONFIG_NANOCOAP_URI_MAX   (64)
	Maximum length of a resource path string read from or written to a message.
#define	CONFIG_NANOCOAP_BLOCK_SIZE_EXP_MAX   (6)
	Maximum size for a blockwise transfer as a power of 2.
#define	CONFIG_NANOCOAP_BLOCKSIZE_DEFAULT   COAP_BLOCKSIZE_64
	CoAP block-wise-transfer size that should be used by default.
#define	CONFIG_NANOCOAP_QS_MAX   (64)
	Maximum length of a query string written to a message.
#define	CONFIG_NANOCOAP_BLOCK_HEADER_MAX   (80)
	Maximum length of a CoAP header for a blockwise message.
#define	NANOCOAP_RESOURCE(name)
	CoAP XFA resource entry.
#define	CONFIG_NANOCOAP_SERVER_WELL_KNOWN_CORE   !IS_USED(MODULE_GCOAP)
	Respond to /.well-known/core to list all resources on the server.
#define	COAP_WELL_KNOWN_CORE_DEFAULT_HANDLER
	Resource definition for the default .well-known/core handler.

Typedefs
typedef struct _coap_request_ctx	coap_request_ctx_t
	Forward declaration of internal CoAP resource request handler context.
typedef ssize_t(*	coap_handler_t) (coap_pkt_t *pkt, uint8_t *buf, size_t len, coap_request_ctx_t *context)
	Resource handler type.
typedef int(*	coap_blockwise_cb_t) (void *arg, size_t offset, uint8_t *buf, size_t len, int more)
	Coap blockwise request callback descriptor.
typedef int(*	coap_request_cb_t) (void *arg, coap_pkt_t *pkt)
	Coap request callback descriptor.
typedef uint16_t	coap_method_flags_t
	Method flag type.

Functions
void	coap_request_ctx_init (coap_request_ctx_t *ctx, sock_udp_ep_t *remote)
	Initialize CoAP request context.
const char *	coap_request_ctx_get_path (const coap_request_ctx_t *ctx)
	Get resource path associated with a CoAP request.
void *	coap_request_ctx_get_context (const coap_request_ctx_t *ctx)
	Get resource context associated with a CoAP request.
uint32_t	coap_request_ctx_get_tl_type (const coap_request_ctx_t *ctx)
	Get transport the packet was received over.
const sock_udp_ep_t *	coap_request_ctx_get_remote_udp (const coap_request_ctx_t *ctx)
	Get the remote endpoint from which the request was received.
const sock_udp_ep_t *	coap_request_ctx_get_local_udp (const coap_request_ctx_t *ctx)
	Get the local endpoint on which the request has been received.
static ssize_t	coap_get_proxy_uri (coap_pkt_t *pkt, char **target)
	Convenience function for getting the packet's Proxy-Uri option.
int	coap_match_path (const coap_resource_t *resource, const uint8_t *uri)
	Checks if a CoAP resource path matches a given URI.

nanoCoAP specific CoAP method flags used in coap_handlers array
#define	COAP_GET   (0x01)
#define	COAP_POST   (0x02)
#define	COAP_PUT   (0x04)
#define	COAP_DELETE   (0x08)
#define	COAP_FETCH   (0x10)
#define	COAP_PATCH   (0x20)
#define	COAP_IPATCH   (0x40)
#define	COAP_IGNORE   (0xFF)
	For situations where the method is not important.
#define	COAP_MATCH_SUBTREE   (0x8000)
	Path is considered as a prefix when matching.

coap_opt_finish() flag parameter values
Directs packet/buffer updates when user finishes adding options
#define	COAP_OPT_FINISH_NONE   (0x0000)
	no special handling required
#define	COAP_OPT_FINISH_PAYLOAD   (0x0001)
	expect a payload to follow

Functions – Options for Block
Read Block1 (POST/PUT request) or Block2 (GET response) options, and generally useful functions to write block options.
#define	coap_szx2size(szx)
	Helper to decode SZX value to size in bytes.
void	coap_block_object_init (coap_block1_t *block, size_t blknum, size_t blksize, int more)
	Initialize a block struct from content information.
bool	coap_block_finish (coap_block_slicer_t *slicer, uint16_t option)
	Finish a block request (block1 or block2)
static bool	coap_block1_finish (coap_block_slicer_t *slicer)
	Finish a block1 request.
static bool	coap_block2_finish (coap_block_slicer_t *slicer)
	Finish a block2 response.
void	coap_block2_init (coap_pkt_t *pkt, coap_block_slicer_t *slicer)
	Initialize a block2 slicer struct for writing the payload.
void	coap_block_slicer_init (coap_block_slicer_t *slicer, size_t blknum, size_t blksize)
	Initialize a block slicer struct from content information.
size_t	coap_blockwise_put_bytes (coap_block_slicer_t *slicer, uint8_t *bufpos, const void *c, size_t len)
	Add a byte array to a block2 reply.
size_t	coap_blockwise_put_char (coap_block_slicer_t *slicer, uint8_t *bufpos, char c)
	Add a single character to a block2 reply.
int	coap_get_block (coap_pkt_t *pkt, coap_block1_t *block, uint16_t option)
	Block option getter.
static int	coap_get_block1 (coap_pkt_t *pkt, coap_block1_t *block)
	Block1 option getter.
static int	coap_get_block2 (coap_pkt_t *pkt, coap_block1_t *block)
	Block2 option getter.
int	coap_get_blockopt (coap_pkt_t *pkt, uint16_t option, uint32_t *blknum, uint8_t *szx)
	Generic block option getter.
bool	coap_has_unprocessed_critical_options (const coap_pkt_t *pkt)
	Check whether any of the packet's options that are critical.
static unsigned	coap_size2szx (unsigned len)
	Helper to encode byte size into next equal or smaller SZX value.

Functions – Header Read/Write
Includes message ID, code, type, token, CoAP version
static uint8_t *	coap_hdr_data_ptr (const coap_hdr_t *hdr)
	Get the start of data after the header.
static size_t	coap_hdr_get_token_len (const coap_hdr_t *hdr)
	Get the token length of a CoAP over UDP (DTLS) packet.
static const void *	coap_hdr_get_token (const coap_hdr_t *hdr)
	Get the Token of a CoAP over UDP (DTLS) packet.
static uint8_t	coap_code (unsigned cls, unsigned detail)
	Encode given code class and code detail to raw code.
static unsigned	coap_get_code_class (const coap_pkt_t *pkt)
	Get a message's code class (3 most significant bits of code)
static unsigned	coap_get_code_detail (const coap_pkt_t *pkt)
	Get a message's code detail (5 least significant bits of code)
static unsigned	coap_get_code_decimal (const coap_pkt_t *pkt)
	Get a message's code in decimal format ((class * 100) + detail)
static unsigned	coap_get_code_raw (const coap_pkt_t *pkt)
	Get a message's raw code (class + detail)
static coap_method_t	coap_get_method (const coap_pkt_t *pkt)
	Get a request's method type.
static unsigned	coap_get_id (const coap_pkt_t *pkt)
	Get the message ID of the given CoAP packet.
static unsigned	coap_get_token_len (const coap_pkt_t *pkt)
	Get a message's token length [in byte].
static void *	coap_get_token (const coap_pkt_t *pkt)
	Get pointer to a message's token.
static unsigned	coap_get_total_len (const coap_pkt_t *pkt)
	Get the total length of a CoAP packet in the packet buffer.
static unsigned	coap_get_type (const coap_pkt_t *pkt)
	Get the message type.
static unsigned	coap_get_ver (const coap_pkt_t *pkt)
	Get the CoAP version number.
static uint8_t	coap_hdr_tkl_ext_len (const coap_hdr_t *hdr)
	Get the size of the extended Token length field (RFC 8974)
static unsigned	coap_get_total_hdr_len (const coap_pkt_t *pkt)
	Get the total header length (4-byte header + token length)
static unsigned	coap_get_response_hdr_len (const coap_pkt_t *pkt)
	Get the header length a response to the given packet will have.
static void	coap_hdr_set_code (coap_hdr_t *hdr, uint8_t code)
	Write the given raw message code to given CoAP header.
static void	coap_pkt_set_code (coap_pkt_t *pkt, uint8_t code)
	Write the given raw message code to given CoAP pkt.
static void	coap_hdr_set_type (coap_hdr_t *hdr, unsigned type)
	Set the message type for the given CoAP header.
static size_t	coap_hdr_len (const coap_hdr_t *hdr)
	Get the header length of a CoAP packet.

Functions – Options Read
Read options from a parsed packet. Packets accessed through coap_find_option or any of the coap_opt_get_* functions track their access in bit field created at parsing time to enable checking for critical options in coap_has_unprocessed_critical_options. These functions thus have a side effect, and code that calls them on critical options needs to ensure that failure to process the accessed option is propagated into failure to process the message. For example, a server helper that tries to read the If-None-Match option (which is critical) and finds it to be longer than it can process must not return as if no If-None-Match option was present, as it has already triggered the side effect of marking the option as processed.
uint8_t *	coap_find_option (coap_pkt_t *pkt, unsigned opt_num)
	Get pointer to an option field by type.
uint8_t *	coap_iterate_option (coap_pkt_t *pkt, unsigned opt_num, uint8_t **opt_pos, int *opt_len)
	Get pointer to an option field, can be called in a loop if there are multiple options with the same number.
unsigned	coap_get_content_type (coap_pkt_t *pkt)
	Get content type from packet.
unsigned	coap_get_accept (coap_pkt_t *pkt)
	Get the Accept option value from a packet if present.
int	coap_opt_get_uint (coap_pkt_t *pkt, uint16_t optnum, uint32_t *value)
	Get a uint32 option value.
ssize_t	coap_opt_get_string (coap_pkt_t *pkt, uint16_t optnum, uint8_t *target, size_t max_len, char separator)
	Read a full option as null terminated string into the target buffer.
static ssize_t	coap_get_location_path (coap_pkt_t *pkt, uint8_t *target, size_t max_len)
	Convenience function for getting the packet's LOCATION_PATH option.
static ssize_t	coap_get_location_query (coap_pkt_t *pkt, uint8_t *target, size_t max_len)
	Convenience function for getting the packet's LOCATION_QUERY option.
static ssize_t	coap_get_uri_path (coap_pkt_t *pkt, uint8_t *target)
	Convenience function for getting the packet's URI_PATH.
static ssize_t	coap_get_uri_query_string (coap_pkt_t *pkt, char *target, size_t max_len)
	Convenience function for getting the packet's URI_QUERY option.
bool	coap_find_uri_query (coap_pkt_t *pkt, const char *key, const char **value, size_t *len)
	Find a URI query option of the packet.
int	coap_iterate_uri_query (coap_pkt_t *pkt, void **ctx, char *key, size_t key_len_max, char *value, size_t value_len_max)
	Iterate over a packet's URI Query options.
ssize_t	coap_opt_get_next (const coap_pkt_t *pkt, coap_optpos_t *opt, uint8_t **value, bool init_opt)
	Iterate over a packet's options.
ssize_t	coap_opt_get_opaque (coap_pkt_t *pkt, unsigned opt_num, uint8_t **value)
	Retrieve the value for an option as an opaque array of bytes.

Functions – Options Write Packet API
Use a coap_pkt_t struct to manage writing Options to the PDU. The caller must monitor space remaining in the buffer; however, the API will not write past the end of the buffer, and returns -ENOSPC when it is full.
ssize_t	coap_opt_add_block (coap_pkt_t *pkt, coap_block_slicer_t *slicer, bool more, uint16_t option)
	Add block option in descriptive use from a slicer object.
static ssize_t	coap_opt_add_block1 (coap_pkt_t *pkt, coap_block_slicer_t *slicer, bool more)
	Add block1 option in descriptive use from a slicer object.
static ssize_t	coap_opt_add_block2 (coap_pkt_t *pkt, coap_block_slicer_t *slicer, bool more)
	Add block2 option in descriptive use from a slicer object.
ssize_t	coap_opt_add_uint (coap_pkt_t *pkt, uint16_t optnum, uint32_t value)
	Encode the given uint option into pkt.
static ssize_t	coap_opt_add_block1_control (coap_pkt_t *pkt, coap_block1_t *block)
	Encode the given block1 option in control use.
static ssize_t	coap_opt_add_block2_control (coap_pkt_t *pkt, coap_block1_t *block)
	Encode the given block2 option in control use.
static ssize_t	coap_opt_add_accept (coap_pkt_t *pkt, uint16_t format)
	Append an Accept option to the pkt buffer.
static ssize_t	coap_opt_add_format (coap_pkt_t *pkt, uint16_t format)
	Append a Content-Format option to the pkt buffer.
ssize_t	coap_opt_add_opaque (coap_pkt_t *pkt, uint16_t optnum, const void *val, size_t val_len)
	Encode the given buffer as an opaque data option into pkt.
ssize_t	coap_opt_add_uri_query2 (coap_pkt_t *pkt, const char *key, size_t key_len, const char *val, size_t val_len)
	Adds a single Uri-Query option in the form 'key=value' into pkt.
static ssize_t	coap_opt_add_uri_query (coap_pkt_t *pkt, const char *key, const char *val)
	Adds a single Uri-Query option in the form 'key=value' into pkt.
ssize_t	coap_opt_add_proxy_uri (coap_pkt_t *pkt, const char *uri)
	Adds a single Proxy-URI option into pkt.
ssize_t	coap_opt_add_chars (coap_pkt_t *pkt, uint16_t optnum, const char *chars, size_t chars_len, char separator)
	Encode the given array of characters as option(s) into pkt.
static ssize_t	coap_opt_add_string (coap_pkt_t *pkt, uint16_t optnum, const char *string, char separator)
	Encode the given string as option(s) into pkt.
static ssize_t	coap_opt_add_uri_path (coap_pkt_t *pkt, const char *path)
	Adds one or multiple Uri-Path options in the form '/path' into pkt.
static ssize_t	coap_opt_add_uri_path_buffer (coap_pkt_t *pkt, const char *path, size_t path_len)
	Adds one or multiple Uri-Path options in the form '/path' into pkt.
ssize_t	coap_opt_finish (coap_pkt_t *pkt, uint16_t flags)
	Finalizes options as required and prepares for payload.
ssize_t	coap_opt_remove (coap_pkt_t *pkt, uint16_t optnum)
	Removes an option previously added with function in the coap_opt_add_...() group.

Functions – Options Write Buffer API
Write PDU Options directly to the array of bytes for a message. The caller must provide the last option number written as well as the buffer position. The caller is primarily responsible for tracking and managing the space remaining in the buffer.
size_t	coap_opt_put_block (uint8_t *buf, uint16_t lastonum, coap_block_slicer_t *slicer, bool more, uint16_t option)
	Insert block option into buffer.
static size_t	coap_opt_put_block1 (uint8_t *buf, uint16_t lastonum, coap_block_slicer_t *slicer, bool more)
	Insert block1 option into buffer.
static size_t	coap_opt_put_block2 (uint8_t *buf, uint16_t lastonum, coap_block_slicer_t *slicer, bool more)
	Insert block2 option into buffer.
size_t	coap_opt_put_uint (uint8_t *buf, uint16_t lastonum, uint16_t onum, uint32_t value)
	Encode the given uint option into buffer.
static size_t	coap_opt_put_block1_control (uint8_t *buf, uint16_t lastonum, coap_block1_t *block)
	Insert block1 option into buffer in control usage.
static size_t	coap_opt_put_block2_control (uint8_t *buf, uint16_t lastonum, coap_block1_t *block)
	Insert block2 option into buffer in control usage.
static size_t	coap_opt_put_observe (uint8_t *buf, uint16_t lastonum, uint32_t obs)
	Insert an CoAP Observe Option into the buffer.
size_t	coap_opt_put_string_with_len (uint8_t *buf, uint16_t lastonum, uint16_t optnum, const char *string, size_t len, char separator)
	Encode the given string as multi-part option into buffer.
static size_t	coap_opt_put_string (uint8_t *buf, uint16_t lastonum, uint16_t optnum, const char *string, char separator)
	Encode the given string as multi-part option into buffer.
static size_t	coap_opt_put_location_path (uint8_t *buf, uint16_t lastonum, const char *location)
	Convenience function for inserting LOCATION_PATH option into buffer.
static size_t	coap_opt_put_location_query (uint8_t *buf, uint16_t lastonum, const char *location)
	Convenience function for inserting LOCATION_QUERY option into buffer.
static size_t	coap_opt_put_uri_path (uint8_t *buf, uint16_t lastonum, const char *uri)
	Convenience function for inserting URI_PATH option into buffer.
static size_t	coap_opt_put_uri_query (uint8_t *buf, uint16_t lastonum, const char *uri)
	Convenience function for inserting URI_QUERY option into buffer.
size_t	coap_opt_put_uri_pathquery (uint8_t *buf, uint16_t *lastonum, const char *uri)
	Convenience function for inserting URI_PATH and URI_QUERY into buffer This function will automatically split path and query parameters.
static size_t	coap_opt_put_proxy_uri (uint8_t *buf, uint16_t lastonum, const char *uri)
	Convenience function for inserting PROXY_URI option into buffer.
size_t	coap_put_block1_ok (uint8_t *pkt_pos, coap_block1_t *block1, uint16_t lastonum)
	Insert block1 option into buffer (from coap_block1_t)
size_t	coap_put_option (uint8_t *buf, uint16_t lastonum, uint16_t onum, const void *odata, size_t olen)
	Insert a CoAP option into buffer.
static size_t	coap_put_option_block1 (uint8_t *buf, uint16_t lastonum, unsigned blknum, unsigned szx, int more)
	Insert block1 option into buffer.
static size_t	coap_put_option_ct (uint8_t *buf, uint16_t lastonum, uint16_t content_type)
	Insert content type option into buffer.

Functions – Messaging
Functions to support sending and receiving messages.
ssize_t	coap_block2_build_reply (coap_pkt_t *pkt, unsigned code, uint8_t *rbuf, unsigned rlen, unsigned payload_len, coap_block_slicer_t *slicer)
	Build reply to CoAP block2 request.
ssize_t	coap_build_hdr (coap_hdr_t *hdr, unsigned type, const void *token, size_t token_len, unsigned code, uint16_t id)
	Builds a CoAP header.
ssize_t	coap_build_reply (coap_pkt_t *pkt, unsigned code, uint8_t *rbuf, unsigned rlen, unsigned max_data_len)
	Build reply to CoAP request.
ssize_t	coap_build_empty_ack (coap_pkt_t *pkt, coap_hdr_t *ack)
	Build empty reply to CoAP request.
ssize_t	coap_handle_req (coap_pkt_t *pkt, uint8_t *resp_buf, unsigned resp_buf_len, coap_request_ctx_t *ctx)
	Handle incoming CoAP request.
ssize_t	coap_tree_handler (coap_pkt_t *pkt, uint8_t *resp_buf, unsigned resp_buf_len, coap_request_ctx_t *ctx, const coap_resource_t *resources, size_t resources_numof)
	Pass a coap request to a matching handler.
ssize_t	coap_subtree_handler (coap_pkt_t *pkt, uint8_t *resp_buf, size_t resp_buf_len, coap_request_ctx_t *context)
	Generic coap subtree handler.
static coap_method_flags_t	coap_method2flag (unsigned code)
	Convert message code (request method) into a corresponding bit field.
int	coap_parse (coap_pkt_t *pkt, uint8_t *buf, size_t len)
	Parse a CoAP PDU.
void	coap_pkt_init (coap_pkt_t *pkt, uint8_t *buf, size_t len, size_t header_len)
	Initialize a packet struct, to build a message buffer.
static void	coap_payload_advance_bytes (coap_pkt_t *pkt, size_t len)
	Advance the payload pointer.
ssize_t	coap_payload_put_bytes (coap_pkt_t *pkt, const void *data, size_t len)
	Add payload data to the CoAP request.
ssize_t	coap_payload_put_char (coap_pkt_t *pkt, char c)
	Add a single character to the payload data of the CoAP request.
ssize_t	coap_build_reply_header (coap_pkt_t *pkt, unsigned code, void *buf, size_t len, uint16_t ct, void **payload, size_t *payload_len_max)
	Create CoAP reply header (convenience function)
ssize_t	coap_reply_simple (coap_pkt_t *pkt, unsigned code, uint8_t *buf, size_t len, uint16_t ct, const void *payload, size_t payload_len)
	Create CoAP reply (convenience function)
ssize_t	coap_well_known_core_default_handler (coap_pkt_t *pkt, uint8_t *buf, size_t len, coap_request_ctx_t *context)
	Reference to the default .well-known/core handler defined by the application.

Functions – gcoap specific
static bool	coap_has_observe (coap_pkt_t *pkt)
	Identifies a packet containing an observe option.
static void	coap_clear_observe (coap_pkt_t *pkt)
	Clears the observe option value from a packet.
static uint32_t	coap_get_observe (coap_pkt_t *pkt)
	Get the value of the observe option from the given packet.