CoAP library optimized for minimal resource usage. More...

Detailed Description

CoAP library optimized for minimal resource usage.

nanocoap is a toolbox for reading and writing CoAP messages. It provides functions for core header attributes like message type and code. It also provides high and low level interfaces to CoAP options, including Block.

nanocoap includes the core structs to store message information. It also provides helper functions for use before sending and after receiving a message, such as coap_parse_udp() to read an incoming message.

Application APIs

This page provides reference documentation for the contents of nanocoap. To use nanocoap in an application, see the functional APIs that are built with it. nanocoap sock is for a targeted client or server with lesser resource requirements, and gcoap provides a more featureful messaging hub.

Option APIs

For both server responses and client requests, CoAP uses an Option mechanism to encode message metadata that is not required for each message. For example, the resource URI path is required only for a request, and is encoded as the Uri-Path option.

nanocoap sock uses the simpler Buffer API, described in the section Options Write Buffer API. gcoap uses the more convenient Packet API, described in the section Options Write Packet API.

For either API, the caller must write options in order by option number (see "CoAP option numbers" in CoAP defines).

Server path matching

By default the URI-path of an incoming request should match exactly one of the registered resources. But also, a resource can be configured to match just a prefix of the URI-path of the request by adding the COAP_MATCH_SUBTREE option to coap_resource_t::methods.

For example, if a resource is configured with a path /resource01 and the COAP_MATCH_SUBTREE option is used it would match any of /resource01/, /resource01/sub/path, /resource01alt.

If the behavior of matching /resource01alt is not wanted and only subtrees are wanted to match, the path should be /resource01/.

If in addition just /resource01 is wanted to match, together with any subtrees of /resource01/, then a first resource with the path /resource01 and exact matching should be register, and then a second one with the path /resource01/ and subtree matching.

Topics
	CoAP file server
	Library for serving files from the VFS to CoAP clients.

	nanoCoAP compile configurations

	nanoCoAP-Cache implementation
	A cache implementation for nanocoap response messages.

Files
file	nanocoap.h
	nanocoap API

Data Structures
struct	coap_udp_hdr_t
	Raw CoAP over UDP 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_builder_t
	Structure to hold the state for building a CoAP message. 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_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 coap_udp_hdr_t	coap_hdr_t
	Alias for coap_udp_hdr_t for backward compatibility.

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 char uri)
	Checks if a CoAP resource path matches a given URI.

Functions – Header Read/Write
Includes message ID, code, type, token, CoAP version
static uint8_t *	coap_hdr_data_ptr (const coap_udp_hdr_t *hdr)
	Get the start of data after the header.

static size_t	coap_hdr_get_token_len (const coap_udp_hdr_t *hdr)
	Get the token length of a CoAP over UDP (DTLS) packet.

static const void *	coap_hdr_get_token (const coap_udp_hdr_t *hdr)
	Get the Token of a CoAP over UDP (DTLS) packet.

static coap_udp_hdr_t *	coap_get_udp_hdr (coap_pkt_t *pkt)
	Get the CoAP header of a CoAP over UDP packet.

static const coap_udp_hdr_t *	coap_get_udp_hdr_const (const coap_pkt_t *pkt)
	Same as coap_get_udp_hdr but for `const` memory.

static uint8_t	coap_code (unsigned cls, unsigned detail)
	Encode given code class and code detail to raw code.

static unsigned	coap_get_code_raw (const coap_pkt_t *pkt)
	Get a message's raw code (class + detail)

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 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 void	coap_set_id (coap_pkt_t *pkt, uint16_t id)
	Set 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_udp_hdr_t *hdr)
	Get the size of the extended Token length field (RFC 8974)

static uint8_t	coap_pkt_tkl_ext_len (const coap_pkt_t *pkt)
	Get the size of the extended Token length field (RFC 8974)

bool	coap_is_hdr_in_bounds (const coap_pkt_t *pkt, size_t len)
	Validate that the header of `pkt` is no longer than `len` bytes.

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_udp_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_udp_hdr_t *hdr, unsigned type)
	Set the message type for the given CoAP header.

static size_t	coap_hdr_len (const coap_udp_hdr_t *hdr)
	Get the header length of a CoAP packet.

static void	coap_pkt_set_type (coap_pkt_t *pkt, unsigned type)
	Set the message type for the given CoAP packet.

static void	coap_pkt_set_tkl (coap_pkt_t *pkt, uint8_t tkl)
	Set the message token length for the given 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, char 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, char 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, char 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, char 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 for Block
Read Block1 (POST/PUT request) or Block2 (GET response) options, and generally useful functions to write block options.
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)
	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.

int	coap_blockwise_put_bytes (coap_builder_t state, coap_block_slicer_t slicer, const void *c, size_t len)
	Add a byte array to a block2 reply when building the response using a coap_builder_t structure to assemble the message.

int	coap_blockwise_put_bytes_pkt (coap_pkt_t pdu, coap_block_slicer_t slicer, const void *c, size_t len)
	Add a byte array to a block2 reply when building the response using a coap_pkt_t structure to assemble the message,.

int	coap_blockwise_put_char (coap_builder_t state, coap_block_slicer_t slicer, char c)
	Add a single character to a block2 reply when building the response using a coap_builder_t structure to assemble the message.

int	coap_blockwise_put_char_pkt (coap_pkt_t pdu, coap_block_slicer_t slicer, char c)
	Add a single character to a block2 reply when building the response using a coap_pkt_t structure to assemble the message.

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.

#define	coap_szx2size(szx)
	Helper to decode SZX value to size in 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.
int	coap_builder_init (coap_builder_t state, void buf, size_t buf_len, size_t header_len)
	Initialize `state` for building a message.

static bool	coap_builder_has_overflown (const coap_builder_t *state)
	Check if building the message failed due to insufficient buffer space.

static ssize_t	coap_builder_msg_size (const coap_builder_t *state)
	Get the size of the CoAP message in `state`.

static size_t	coap_builder_buf_size (const coap_builder_t *state)
	Get the size of the buffer in `state`.

static size_t	coap_builder_buf_remaining (const coap_builder_t *state)
	Get the remaining free buffer space in `state`.

WARN_UNUSED_RESULT int	coap_builder_init_reply (coap_builder_t state, void buf, size_t buf_len, coap_pkt_t *req, uint8_t code)
	Initialize `state` for building a response and add the response header with matching token and suitable message ID to it.

int	coap_builder_add_payload (coap_builder_t state, const void pld, size_t pld_len)
	Add a payload marker and payload with bounds checking.

void *	coap_builder_allocate_payload (coap_builder_t *state, size_t pld_len)
	Write the payload marker into the current position of `state` and allocate `pld_len` bytes of payload after it.

static int	coap_builder_add_payload_marker (coap_builder_t *state)
	Add a payload marker with bounds checking.

int	coap_opt_put_block (coap_builder_t state, coap_block_slicer_t slicer, uint16_t option)
	Insert block option into buffer.

static int	coap_opt_put_block1 (coap_builder_t state, coap_block_slicer_t slicer)
	Insert block1 option into buffer.

static int	coap_opt_put_block2 (coap_builder_t state, coap_block_slicer_t slicer)
	Insert block2 option into buffer.

int	coap_opt_put_uint (coap_builder_t *state, uint16_t onum, uint32_t value)
	Encode the given uint option into buffer.

static int	coap_opt_put_block1_control (coap_builder_t state, coap_block1_t block)
	Insert block1 option into buffer in control usage.

static int	coap_opt_put_block2_control (coap_builder_t state, coap_block1_t block)
	Insert block2 option into buffer in control usage.

static int	coap_opt_put_observe (coap_builder_t *state, uint32_t obs)
	Insert an CoAP Observe Option into the buffer.

int	coap_opt_put_string_with_len (coap_builder_t state, uint16_t optnum, const char string, size_t len, char separator)
	Encode the given string as multi-part option into buffer.

static int	coap_opt_put_string (coap_builder_t state, uint16_t optnum, const char string, char separator)
	Encode the given string as multi-part option into buffer.

static int	coap_opt_put_location_path (coap_builder_t state, const char location)
	Convenience function for inserting LOCATION_PATH option into buffer.

static int	coap_opt_put_location_query (coap_builder_t state, const char location)
	Convenience function for inserting LOCATION_QUERY option into buffer.

static int	coap_opt_put_uri_path (coap_builder_t state, const char uri)
	Convenience function for inserting URI_PATH option into buffer.

static int	coap_opt_put_uri_query (coap_builder_t state, const char uri_query)
	Convenience function for inserting URI_QUERY option into buffer.

int	coap_opt_put_uri_pathquery (coap_builder_t state, const char uri)
	Convenience function for inserting URI_PATH and URI_QUERY into buffer This function will automatically split path and query parameters.

static int	coap_opt_put_proxy_uri (coap_builder_t state, const char uri)
	Convenience function for inserting PROXY_URI option into buffer.

int	coap_put_block1_ok (coap_builder_t state, coap_block1_t block1)
	Insert block1 option into buffer (from coap_block1_t)

int	coap_opt_put (coap_builder_t state, uint16_t onum, const void odata, size_t olen)
	Insert a CoAP option into buffer.

static int	coap_opt_put_block1_raw (coap_builder_t *state, unsigned blknum, unsigned szx, int more)
	Insert block1 option into buffer.

static int	coap_opt_put_ct (coap_builder_t *state, uint16_t content_type)
	Insert content type option into buffer.

Functions – Messaging
Functions to support sending and receiving messages.
ssize_t	coap_build_udp_hdr (void buf, size_t buf_len, uint8_t type, const void token, size_t token_len, uint8_t code, uint16_t id)
	Build a CoAP over UDP header.

static ssize_t	coap_build_hdr (coap_udp_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 (const coap_pkt_t pkt, coap_udp_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.

ssize_t	coap_parse_udp (coap_pkt_t pkt, uint8_t buf, size_t len)
	Parse a CoAP PDU in UDP / DTLS format.

static ssize_t	coap_parse (coap_pkt_t pkt, uint8_t buf, size_t len)
	Alias for coap_parse_udp.

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, uint8_t 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.

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

Macro Definition Documentation

◆ COAP_DELETE

#define COAP_DELETE (0x08)

Definition at line 111 of file nanocoap.h.

◆ COAP_FETCH

#define COAP_FETCH (0x10)

Definition at line 112 of file nanocoap.h.

◆ COAP_FORMAT_NONE

#define COAP_FORMAT_NONE (UINT16_MAX)

nanoCoAP-specific value to indicate no format specified

Definition at line 124 of file nanocoap.h.

◆ COAP_GET

#define COAP_GET (0x01)

Definition at line 108 of file nanocoap.h.

◆ COAP_IGNORE

#define COAP_IGNORE (0xFF)

For situations where the method is not important.

Definition at line 115 of file nanocoap.h.

◆ COAP_IPATCH

#define COAP_IPATCH (0x40)

Definition at line 114 of file nanocoap.h.

◆ COAP_MATCH_SUBTREE

#define COAP_MATCH_SUBTREE (0x8000)

Path is considered as a prefix when matching.

Definition at line 117 of file nanocoap.h.

◆ COAP_OPT_FINISH_NONE

#define COAP_OPT_FINISH_NONE (0x0000)

no special handling required

Definition at line 181 of file nanocoap.h.

◆ COAP_OPT_FINISH_PAYLOAD

#define COAP_OPT_FINISH_PAYLOAD (0x0001)

expect a payload to follow

Definition at line 183 of file nanocoap.h.

◆ COAP_PATCH

#define COAP_PATCH (0x20)

Definition at line 113 of file nanocoap.h.

◆ COAP_POST

#define COAP_POST (0x02)

Definition at line 109 of file nanocoap.h.

◆ COAP_PUT

#define COAP_PUT (0x04)

Definition at line 110 of file nanocoap.h.

◆ coap_szx2size

#define coap_szx2size ( szx )

Value:

(1U << ((szx) + 4))

Helper to decode SZX value to size in bytes.

Parameters

[in] szx SZX value to decode

Returns: SZX value decoded to bytes

Definition at line 1523 of file nanocoap.h.

◆ COAP_WELL_KNOWN_CORE_DEFAULT_HANDLER

#define COAP_WELL_KNOWN_CORE_DEFAULT_HANDLER

Value:

    { \
        .path = "/.well-known/core", \
        .methods = COAP_GET, \
        .handler = coap_well_known_core_default_handler \
    }

Resource definition for the default .well-known/core handler.

Definition at line 2976 of file nanocoap.h.

◆ CONFIG_NANOCOAP_BLOCK_HEADER_MAX

#define CONFIG_NANOCOAP_BLOCK_HEADER_MAX (80)

Maximum length of a CoAP header for a blockwise message.

      Value obtained experimentally when using SUIT

Definition at line 171 of file nanocoap.h.

◆ CONFIG_NANOCOAP_SERVER_WELL_KNOWN_CORE

#define CONFIG_NANOCOAP_SERVER_WELL_KNOWN_CORE !IS_USED(MODULE_GCOAP)

Respond to /.well-known/core to list all resources on the server.

Definition at line 2911 of file nanocoap.h.

◆ NANOCOAP_RESOURCE

#define NANOCOAP_RESOURCE ( name )

Value:

XFA_CONST(coap_resource_t, coap_resources_xfa, 0) CONCAT(coap_resource_, name) =

CONCAT

#define CONCAT(a, b)

Concatenate the tokens a and b.

Definition utils.h:25

coap_resource_t

Type for CoAP resource entry.

Definition nanocoap.h:327

XFA_CONST

#define XFA_CONST(type, xfa_name, prio)

Define variable in read-only cross-file array.

Definition xfa.h:156

CoAP XFA resource entry.

Parameters

name	internal name of the resource entry, must be unique

Definition at line 488 of file nanocoap.h.

Typedef Documentation

◆ coap_blockwise_cb_t

typedef int(* coap_blockwise_cb_t) (void *arg, size_t offset, uint8_t *buf, size_t len, int more)

Coap blockwise request callback descriptor.

Parameters

[in]	arg	Pointer to be passed as arguments to the callback
[in]	offset	Offset of received data
[in]	buf	Pointer to the received data
[in]	len	Length of the received data
[in]	more	-1 for no option, 0 for last block, 1 for more blocks

Returns: >=0 on success; <0 on error

Definition at line 303 of file nanocoap.h.

◆ coap_handler_t

typedef ssize_t(* coap_handler_t) (coap_pkt_t *pkt, uint8_t *buf, size_t len, coap_request_ctx_t *context)

Resource handler type.

Functions that implement this must be prepared to be called multiple times for the same request, as the server implementations do not perform message deduplication. That optimization is described in the CoAP specification.

This should be trivial for requests of the GET, PUT, DELETE, FETCH and iPATCH methods, as they are defined as idempotent methods in CoAP.

For POST, PATCH and other non-idempotent methods, this is an additional requirement introduced by the contract of this type.

Parameters

[in]	pkt	The request packet
[out]	buf	Buffer for the response
[in]	len	Size of the response buffer
[in]	context	Request context

Returns: Number of response bytes written on success Negative error on failure

Definition at line 288 of file nanocoap.h.

◆ coap_hdr_t

typedef coap_udp_hdr_t coap_hdr_t

Alias for coap_udp_hdr_t for backward compatibility.

Deprecated: Avoid using low level types in your application, but rather use the zero overhead wrappers and work on coap_pkt_t instead.

Definition at line 201 of file nanocoap.h.

◆ coap_method_flags_t

typedef uint16_t coap_method_flags_t

Method flag type.

Must be large enough to contain all CoAP method flags

Definition at line 322 of file nanocoap.h.

◆ coap_request_cb_t

typedef int(* coap_request_cb_t) (void *arg, coap_pkt_t *pkt)

Coap request callback descriptor.

Parameters

[in]	arg	Pointer to be passed as arguments to the callback
[in]	pkt	The received CoAP response. Buffers point to network stack internal memory.

Returns: >=0 on success; <0 on error

Definition at line 315 of file nanocoap.h.

◆ coap_request_ctx_t

typedef struct _coap_request_ctx coap_request_ctx_t

Forward declaration of internal CoAP resource request handler context.

Definition at line 264 of file nanocoap.h.

Function Documentation

◆ coap_block1_finish()

static bool coap_block1_finish ( coap_block_slicer_t * slicer )

inlinestatic

Finish a block1 request.

This function finalizes the block1 response header

Checks whether the more bit should be set in the block1 option and sets/clears it if required. Doesn't return the number of bytes, as this function overwrites bytes in the packet rather than adding new.

Parameters

[in,out] slicer Preallocated slicer struct to use

Return values

true	if the `more` bit is set in the block option
false	if the `more` bit is not set the block option

Definition at line 1304 of file nanocoap.h.

◆ coap_block2_finish()

static bool coap_block2_finish ( coap_block_slicer_t * slicer )

inlinestatic

Finish a block2 response.

This function finalizes the block2 response header

Checks whether the more bit should be set in the block2 option and sets/clears it if required. Doesn't return the number of bytes, as this function overwrites bytes in the packet rather than adding new.

Parameters

[in,out] slicer Preallocated slicer struct to use

Return values

true	if the `more` bit is set in the block option
false	if the `more` bit is not set the block option

Definition at line 1323 of file nanocoap.h.

◆ coap_block2_init()

void coap_block2_init	(	coap_pkt_t *	pkt,
		coap_block_slicer_t *	slicer )

Initialize a block2 slicer struct for writing the payload.

This function determines the size of the response payload based on the size requested by the client in pkt.

Parameters

[in]	pkt	packet to work on
[out]	slicer	Preallocated slicer struct to fill

◆ coap_block_finish()

bool coap_block_finish ( coap_block_slicer_t * slicer )

Finish a block request (block1 or block2)

This function finalizes the block response header

Checks whether the more bit should be set in the block option and sets/clears it if required. Doesn't return the number of bytes, as this function overwrites bytes in the packet rather than adding new.

Parameters

[in,out] slicer Preallocated slicer struct to use

Return values

true	if the `more` bit is set in the block option
false	if the `more` bit is not set the block option

◆ coap_block_object_init()

void coap_block_object_init	(	coap_block1_t *	block,
		size_t	blknum,
		size_t	blksize,
		int	more )

Initialize a block struct from content information.

Parameters

[out]	block	block struct to initialize
[in]	blknum	offset from the beginning of content, in terms of `blksize` byte blocks
[in]	blksize	size of each block; must be a power of 2 between 16 and 2 raised to CONFIG_NANOCOAP_BLOCK_SIZE_EXP_MAX
[in]	more	more blocks? use 1 if yes; 0 if no or unknown

◆ coap_block_slicer_init()

void coap_block_slicer_init	(	coap_block_slicer_t *	slicer,
		size_t	blknum,
		size_t	blksize )

Initialize a block slicer struct from content information.

Parameters

[out]	slicer	slicer struct to initialize
[in]	blknum	offset from the beginning of content, in terms of `blksize` byte blocks
[in]	blksize	size of each block; must be a power of 2 between 16 and 2 raised to CONFIG_NANOCOAP_BLOCK_SIZE_EXP_MAX

◆ coap_blockwise_put_bytes()

int coap_blockwise_put_bytes	(	coap_builder_t *	state,
		coap_block_slicer_t *	slicer,
		const void *	c,
		size_t	len )

Add a byte array to a block2 reply when building the response using a coap_builder_t structure to assemble the message.

This function is used to add an array of bytes to a CoAP block2 reply. It checks which parts of the string should be added to the reply and ignores parts that are outside the current block2 request.

Parameters

[in,out]	state	message builder state to use
[in,out]	slicer	slicer to use
[in]	c	byte array to copy
[in]	len	length of the byte array

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

◆ coap_blockwise_put_bytes_pkt()

int coap_blockwise_put_bytes_pkt	(	coap_pkt_t *	pdu,
		coap_block_slicer_t *	slicer,
		const void *	c,
		size_t	len )

Add a byte array to a block2 reply when building the response using a coap_pkt_t structure to assemble the message,.

This function is used to add an array of bytes to a CoAP block2 reply. it checks which parts of the string should be added to the reply and ignores parts that are outside the current block2 request.

Parameters

[in,out]	pdu	pkt to assemble the message in
[in,out]	slicer	slicer to use
[in]	c	byte array to copy
[in]	len	length of the byte array

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

◆ coap_blockwise_put_char()

int coap_blockwise_put_char	(	coap_builder_t *	state,
		coap_block_slicer_t *	slicer,
		char	c )

Add a single character to a block2 reply when building the response using a coap_builder_t structure to assemble the message.

This function is used to add single characters to a CoAP block2 reply. It checks whether the character should be added to the buffer and ignores it when the character is outside the current block2 request.

Parameters

[in,out]	state	message builder state to use
[in]	slicer	slicer to use
[in]	c	character to write

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

◆ coap_blockwise_put_char_pkt()

int coap_blockwise_put_char_pkt	(	coap_pkt_t *	pdu,
		coap_block_slicer_t *	slicer,
		char	c )

Add a single character to a block2 reply when building the response using a coap_pkt_t structure to assemble the message.

This function is used to add single characters to a CoAP block2 reply. It checks whether the character should be added to the buffer and ignores it when the character is outside the current block2 request.

Parameters

[in,out]	pdu	coap_pkt_t to build the response in
[in]	slicer	slicer to use
[in]	c	character to write

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

◆ coap_build_empty_ack()

ssize_t coap_build_empty_ack	(	const coap_pkt_t *	pkt,
		coap_udp_hdr_t *	ack )

Build empty reply to CoAP request.

This function can be used to create an empty ACK so that a later, separate response can be sent independently.

If the request was non-confirmable, this will generate nothing.

Parameters

[in]	pkt	packet to reply to
[out]	ack	buffer to write reply to

Returns: size of reply packet on success; -ENOSPC if rbuf too small

◆ coap_build_hdr()

static ssize_t coap_build_hdr	(	coap_udp_hdr_t *	hdr,
		unsigned	type,
		const void *	token,
		size_t	token_len,
		unsigned	code,
		uint16_t	id )

inlinestatic

Builds a CoAP header.

Caller must ensure hdr can hold the header and the full token!

Parameters

[out]	hdr	hdr to fill
[in]	type	CoAP packet type (e.g., COAP_TYPE_CON, ...)
[in]	token	token
[in]	token_len	length of `token`
[in]	code	CoAP code (e.g., COAP_CODE_204, ...)
[in]	id	CoAP request id

Precondition: token is either not overlapping with the memory buffer hdr points to, or is already at the right offset (e.g. when building the response inside the buffer the contained the request).

Returns: length of resulting header

Deprecated: Use coap_build_udp_hdr instead

Definition at line 2576 of file nanocoap.h.

◆ coap_build_reply()

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.

This function can be used to create a reply to any CoAP request packet. It will create the reply packet header based on parameters from the request (e.g., id, token).

Passing a non-zero max_data_len will ensure the remaining data fits into the buffer along with the header. For this validation, max_data_len must include any CoAP Options, the payload marker, as well as the payload proper.

Parameters

[in]	pkt	packet to reply to
[in]	code	reply code (e.g., COAP_CODE_204)
[out]	rbuf	buffer to write reply to
[in]	rlen	size of `rbuf`
[in]	max_data_len	Length of additional CoAP options, the payload marker and payload

Warning: CoAP request handlers must check the return value for being negative. If it is, they must stop further processing of the request and pass on the return value unmodified.

Returns: max_data_len + size of the header written in bytes

Return values

-ECANCELED	No-Response Option present and matching
-ENOSPC	`rbuf` too small
<0	other error

Usage:

static ssize_t _foo_handler(coap_pkt_t *pkt, uint8_t *buf, size_t len,
                            coap_request_ctx_t *context)
{
    static const char *payload = "Hello World";
    const payload_len = strlen(payload);
    // Worst case estimation of the data to add:
    size_t max_data_len = COAP_OPT_FOO_MAX_LEN + COAP_OPT_BAR_MAX_LEN
                        + COAP_PAYLOAD_MARKER_SIZE + payload_len;
    ssize_t hdr_len = coap_build_reply(pkt, COAP_CODE_CONTENT, buf, len, max_data_len);
 
    if (hdr_len < 0) {
        return hdr_len; // pass through error
    }
 
    // This step is needed due to an API design flaw
    hdr_len -= max_data_len;
 
    uint8_t *pos = buf + hdr_len;
    uint16_t lastonum = 0;
    pos += coap_opt_put_uint(buf, lastonum, COAP_OPT_FOO, 42);
    lastonum = COAP_OPT_FOO;
    pos += coap_opt_put_uint(buf, lastonum, COAP_OPT_BAR, 1337);
    *pos++ = COAP_PAYLOAD_MARKER;
    memcpy(pos, payload, payload_len);
    pos += payload_len;
    return (uintptr_t)pos - (uintptr_t)buf;
}

Deprecated: Use coap_builder_init_reply instead.

◆ coap_build_reply_header()

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)

This function generates the reply CoAP header and sets the payload pointer inside the response buffer to point to the start of the payload, so that it can be written directly after the header.

Parameters

[in]	pkt	packet to reply to
[in]	code	reply code (e.g., COAP_CODE_204)
[out]	buf	buffer to write reply to
[in]	len	size of `buf`
[in]	ct	content type of payload or COAP_FORMAT_NONE
[out]	payload	Will be set to the start of the payload inside `buf`. May be set to NULL if no payload response is wanted (no-reply option)
[out]	payload_len_max	max length of payload left in `buf`

Returns: size of reply header on success

Return values

-ECANCELED	reply should be sent due to no-reply option (pass this error through, server will handle this)
-ENOSPC	`buf` too small
<0	other error

◆ coap_build_udp_hdr()

ssize_t coap_build_udp_hdr	(	void *	buf,
		size_t	buf_len,
		uint8_t	type,
		const void *	token,
		size_t	token_len,
		uint8_t	code,
		uint16_t	id )

Build a CoAP over UDP header.

Parameters

[out]	buf	Destination buffer to write to
[in]	buf_len	Length of `buf` in bytes
[in]	type	CoAP packet type (e.g., COAP_TYPE_CON, ...)
[in]	token	token
[in]	token_len	length of `token`
[in]	code	CoAP code (e.g., COAP_CODE_204, ...)
[in]	id	CoAP request id

Returns: length of resulting header

◆ coap_builder_add_payload()

int coap_builder_add_payload	(	coap_builder_t *	state,
		const void *	pld,
		size_t	pld_len )

Add a payload marker and payload with bounds checking.

Parameters

[in,out]	state	state to use to build the message
[in]	pld	payload to add (may be `NULL` if `pld_len` is 0)
[in]	pld_len	length of `pld` in bytes

Return values

0	Success
-EOVERFLOW	Buffer too small
<0	Other error

Precondition: state is not NULL; pld is not NULL, unless pld_len is 0.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.; This may be called more than once, as state tracks whether the payload marker has already been added or not.

◆ coap_builder_add_payload_marker()

static int coap_builder_add_payload_marker ( coap_builder_t * state )

inlinestatic

Add a payload marker with bounds checking.

Parameters

[in,out] state state to use to build the message

Return values

0	Success
-EOVERFLOW	Buffer too small
<0	Other error

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

Definition at line 2091 of file nanocoap.h.

◆ coap_builder_allocate_payload()

void * coap_builder_allocate_payload	(	coap_builder_t *	state,
		size_t	pld_len )

Write the payload marker into the current position of state and allocate pld_len bytes of payload after it.

Parameters

[in,out]	state	The message builder to add the payload to
[in]	pld_len	Size of the payload to add in bytes

Returns: Pointer to the allocated payload

Return values

NULL	Failure to allocate the payload

Postcondition: The caller MUST write exactly pld_len bytes of data into the return buffer (unless NULL is returned)

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.; This may be called more than once, as state tracks whether the payload marker has already been added or not. On the second call a pointer to the second allocated chunk is returned.; Callings with function with pld_len set to zero will cause it to write the payload marker if needed and return a valid (non-NULL) pointer. The caller MUST NOT write any data to that address, since no memory was allocated.

◆ coap_builder_buf_remaining()

static size_t coap_builder_buf_remaining ( const coap_builder_t * state )

inlinestatic

Get the remaining free buffer space in state.

Parameters

[in] state The builder state to get the remaining buffer space from

Returns: Number of bytes that can still be appennded to state

Definition at line 1992 of file nanocoap.h.

◆ coap_builder_buf_size()

static size_t coap_builder_buf_size ( const coap_builder_t * state )

inlinestatic

Get the size of the buffer in state.

Parameters

[in] state The builder state to get the buffer size from

Return values

>0	The size of the buffer in `state`
0	`state` has been marked as invalid, as appending options/payloads as requested would have resulted in a buffer overflow.

Definition at line 1980 of file nanocoap.h.

◆ coap_builder_has_overflown()

static bool coap_builder_has_overflown ( const coap_builder_t * state )

inlinestatic

Check if building the message failed due to insufficient buffer space.

Parameters

[in] state The builder state to check

Return values

true	the assembly of the message was aborted due to lack of buffer space (overflow was prevented)
false	everything fit into the buffer so far

Definition at line 1946 of file nanocoap.h.

◆ coap_builder_init()

int coap_builder_init	(	coap_builder_t *	state,
		void *	buf,
		size_t	buf_len,
		size_t	header_len )

Initialize state for building a message.

Parameters

[in,out]	state	State to initialize
[in]	buf	Buffer to write the options to
[in]	buf_len	Length of `buf` (in bytes)
[in]	header_len	Length of the CoAP header (including Token excluding Options, in bytes)

Return values

0	Success
-EOVERFLOW	Buffer too small
<0	Other error

Note: The CoAP packet header (up to and including the CoAP Token) is not written by this function, the caller needs to take care of this.

◆ coap_builder_init_reply()

WARN_UNUSED_RESULT int coap_builder_init_reply	(	coap_builder_t *	state,
		void *	buf,
		size_t	buf_len,
		coap_pkt_t *	req,
		uint8_t	code )

Initialize state for building a response and add the response header with matching token and suitable message ID to it.

Parameters

[in,out]	state	State to initialize
[in]	buf	Buffer to write the options to
[in]	buf_len	Length of `buf` (in bytes)
[in,out]	req	Request to reply to
[in]	code	The code (e.g. COAP_CODE_CONTENT) of the reply

Return values

0	Success
-EOVERFLOW	Buffer too small
<0	Other error

Precondition: state is not NULL; buf is not NULL

Note: This already initialized the CoAP response header up to and including the CoAP Token. The caller still needs to add CoAP Options, CoAP Payload Marker, and a payload as needed.

◆ coap_builder_msg_size()

static ssize_t coap_builder_msg_size ( const coap_builder_t * state )

inlinestatic

Get the size of the CoAP message in state.

Parameters

[in] state The builder state to get the message size from

Return values

-EOVERFLOW	the assembly of the message was aborted due to lack of buffer space (overflow was prevented)
>=0	Success, the size of the assembled message is returned

Definition at line 1961 of file nanocoap.h.

◆ coap_clear_observe()

static void coap_clear_observe ( coap_pkt_t * pkt )

inlinestatic

Clears the observe option value from a packet.

Parameters

[in] pkt CoAP packet

Definition at line 2954 of file nanocoap.h.

◆ coap_code()

static uint8_t coap_code	(	unsigned	cls,
		unsigned	detail )

inlinestatic

Encode given code class and code detail to raw code.

Parameters

[in]	cls	message code class
[in]	detail	message code detail

Returns: raw message code

Definition at line 541 of file nanocoap.h.

◆ coap_find_option()

uint8_t * coap_find_option	(	coap_pkt_t *	pkt,
		unsigned	opt_num )

Get pointer to an option field by type.

Parameters

[in]	pkt	packet to work on
[in]	opt_num	the option number to search for

Returns: pointer to the option data NULL if option number was not found

◆ coap_find_uri_query()

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.

This function searches for a query option of the form "?key=value" and would, when present, return the pointer to "value" when searching for "key".

Parameters

[in]	pkt	pkt to work on
[in]	key	key string to look for
[out]	value	found value if present, may be NULL
[out]	len	length of value if present, may be NULL if value is NULL

Returns: true if the key was found, false if not

◆ coap_get_accept()

unsigned coap_get_accept ( coap_pkt_t * pkt )

Get the Accept option value from a packet if present.

Parameters

[in] pkt packet to work on

Returns: the packet's Accept option value if included, COAP_FORMAT_NONE otherwise

◆ coap_get_block()

int coap_get_block	(	coap_pkt_t *	pkt,
		coap_block1_t *	block,
		uint16_t	option )

Block option getter.

This function gets a CoAP packet's block option and parses it into a helper structure.

If no block option is present in pkt, the values in block will be initialized with zero. That implies both block->offset and block->more are also valid in that case, as packet with offset==0 and more==0 means it contains all the payload for the corresponding request.

Parameters

[in]	pkt	pkt to work on
[out]	block	ptr to preallocated coap_block1_t structure
[in]	option	block1 or block2

Returns: 0 if block option not present; 1 if structure has been filled

◆ coap_get_block1()

static int coap_get_block1	(	coap_pkt_t *	pkt,
		coap_block1_t *	block )

inlinestatic

Block1 option getter.

This function gets a CoAP packet's block1 option and parses it into a helper structure.

If no block1 option is present in pkt, the values in block1 will be initialized with zero. That implies both block1->offset and block1->more are also valid in that case, as packet with offset==0 and more==0 means it contains all the payload for the corresponding request.

Parameters

[in]	pkt	pkt to work on
[out]	block	ptr to preallocated coap_block1_t structure

Returns: 0 if block1 option not present; 1 if structure has been filled

Definition at line 1464 of file nanocoap.h.

◆ coap_get_block2()

static int coap_get_block2	(	coap_pkt_t *	pkt,
		coap_block1_t *	block )

inlinestatic

Block2 option getter.

Parameters

[in]	pkt	pkt to work on
[out]	block	ptr to preallocated coap_block1_t structure

Returns: 0 if block2 option not present; 1 if structure has been filled

Definition at line 1478 of file nanocoap.h.

◆ coap_get_blockopt()

int coap_get_blockopt	(	coap_pkt_t *	pkt,
		uint16_t	option,
		uint32_t *	blknum,
		uint8_t *	szx )

Generic block option getter.

Parameters

[in]	pkt	pkt to work on
[in]	option	actual block option number to get
[out]	blknum	block number
[out]	szx	SZX value

Returns: -1 if option not found; 0 if more flag is not set; 1 if more flag is set

◆ coap_get_code_class()

static unsigned coap_get_code_class ( const coap_pkt_t * pkt )

inlinestatic

Get a message's code class (3 most significant bits of code)

Parameters

[in] pkt CoAP packet

Returns: message code class

Definition at line 565 of file nanocoap.h.

◆ coap_get_code_decimal()

static unsigned coap_get_code_decimal ( const coap_pkt_t * pkt )

inlinestatic

Get a message's code in decimal format ((class * 100) + detail)

Parameters

[in] pkt CoAP packet

Returns: message code in decimal format

Definition at line 589 of file nanocoap.h.

◆ coap_get_code_detail()

static unsigned coap_get_code_detail ( const coap_pkt_t * pkt )

inlinestatic

Get a message's code detail (5 least significant bits of code)

Parameters

[in] pkt CoAP packet

Returns: message code detail

Definition at line 577 of file nanocoap.h.

◆ coap_get_code_raw()

static unsigned coap_get_code_raw ( const coap_pkt_t * pkt )

inlinestatic

Get a message's raw code (class + detail)

Parameters

[in] pkt CoAP packet

Returns: raw message code

Definition at line 553 of file nanocoap.h.

◆ coap_get_content_type()

unsigned coap_get_content_type ( coap_pkt_t * pkt )

Get content type from packet.

Parameters

[in] pkt packet to work on

Returns: the packet's content type value if included, COAP_FORMAT_NONE otherwise

◆ coap_get_id()

static unsigned coap_get_id ( const coap_pkt_t * pkt )

inlinestatic

Get the message ID of the given CoAP packet.

Parameters

[in] pkt CoAP packet to get the ID of

Returns: message ID

Definition at line 613 of file nanocoap.h.

◆ coap_get_location_path()

static ssize_t coap_get_location_path	(	coap_pkt_t *	pkt,
		char *	target,
		size_t	max_len )

inlinestatic

Convenience function for getting the packet's LOCATION_PATH option.

This function decodes the pkt's LOCATION_PATH option into a '/'-separated and '\0'-terminated string.

Caller must ensure target can hold at least 2 bytes!

Parameters

[in]	pkt	pkt to work on
[out]	target	buffer for location path
[in]	max_len	size of `target` in bytes

Returns: -ENOSPC if URI option is larger than max_len; nr of bytes written to target (including '\0')

Definition at line 1075 of file nanocoap.h.

◆ coap_get_location_query()

static ssize_t coap_get_location_query	(	coap_pkt_t *	pkt,
		char *	target,
		size_t	max_len )

inlinestatic

Convenience function for getting the packet's LOCATION_QUERY option.

This function decodes the pkt's LOCATION_PATH option into a '&'-separated and '\0'-terminated string.

Caller must ensure target can hold at least 2 bytes!

Parameters

[in]	pkt	pkt to work on
[out]	target	buffer for location path
[in]	max_len	size of `target` in bytes

Returns: -ENOSPC if URI option is larger than max_len; nr of bytes written to target (including '\0')

Definition at line 1097 of file nanocoap.h.

◆ coap_get_method()

static coap_method_t coap_get_method ( const coap_pkt_t * pkt )

inlinestatic

Get a request's method type.

Parameters

[in] pkt CoAP request packet

Returns: request method type

Definition at line 601 of file nanocoap.h.

◆ coap_get_observe()

static uint32_t coap_get_observe ( coap_pkt_t * pkt )

inlinestatic

Get the value of the observe option from the given packet.

Parameters

[in] pkt CoAP packet

Returns: value of the observe option

Definition at line 2966 of file nanocoap.h.

◆ coap_get_proxy_uri()

static ssize_t coap_get_proxy_uri	(	coap_pkt_t *	pkt,
		char **	target )

inlinestatic

Convenience function for getting the packet's Proxy-Uri option.

Parameters

[in]	pkt	pkt to work on
[out]	target	pointer to the PROXY_URI in `pkt`

Precondition: ((pkt != NULL) && (target != NULL))

Returns: length of the Proxy-Uri option; -ENOENT if Proxy-Uri option not found; -EINVAL if Proxy-Uri option cannot be parsed

Definition at line 1249 of file nanocoap.h.

◆ coap_get_response_hdr_len()

static unsigned coap_get_response_hdr_len ( const coap_pkt_t * pkt )

inlinestatic

Get the header length a response to the given packet will have.

Parameters

[in] pkt CoAP packet to reply to

Returns: Length of the response header including token excluding CoAP options and any payload marker

Definition at line 799 of file nanocoap.h.

◆ coap_get_token()

static void * coap_get_token ( const coap_pkt_t * pkt )

inlinestatic

Get pointer to a message's token.

Parameters

[in] pkt CoAP packet

Returns: pointer to the token position

Definition at line 651 of file nanocoap.h.

◆ coap_get_token_len()

static unsigned coap_get_token_len ( const coap_pkt_t * pkt )

inlinestatic

Get a message's token length [in byte].

If the nanocoap_token_ext module is enabled, this will include the extended token length.

Parameters

[in] pkt CoAP packet

Returns: length of token in the given message (0-8 byte)

Definition at line 639 of file nanocoap.h.

◆ coap_get_total_hdr_len()

static unsigned coap_get_total_hdr_len ( const coap_pkt_t * pkt )

inlinestatic

Get the total header length (4-byte header + token length)

Parameters

[in] pkt CoAP packet

Returns: total header length

Definition at line 786 of file nanocoap.h.

◆ coap_get_total_len()

static unsigned coap_get_total_len ( const coap_pkt_t * pkt )

inlinestatic

Get the total length of a CoAP packet in the packet buffer.

Note: This does not include possible payload snips.

Parameters

[in] pkt CoAP packet

Returns: total CoAP length

Definition at line 665 of file nanocoap.h.

◆ coap_get_type()

static unsigned coap_get_type ( const coap_pkt_t * pkt )

inlinestatic

Get the message type.

Parameters

[in] pkt CoAP packet

Returns: COAP_TYPE_CON; COAP_TYPE_NON; COAP_TYPE_ACK; COAP_TYPE_RST

Definition at line 680 of file nanocoap.h.

◆ coap_get_udp_hdr()

static coap_udp_hdr_t * coap_get_udp_hdr ( coap_pkt_t * pkt )

inlinestatic

Get the CoAP header of a CoAP over UDP packet.

Parameters

[in] pkt The packet to get the header of

Returns: A pointer to the header in the packet

Return values

NULL	The packet is not using UDP as transport

Definition at line 518 of file nanocoap.h.

◆ coap_get_udp_hdr_const()

static const coap_udp_hdr_t * coap_get_udp_hdr_const ( const coap_pkt_t * pkt )

inlinestatic

Same as coap_get_udp_hdr but for const memory.

Definition at line 527 of file nanocoap.h.

◆ coap_get_uri_path()

static ssize_t coap_get_uri_path	(	coap_pkt_t *	pkt,
		char *	target )

inlinestatic

Convenience function for getting the packet's URI_PATH.

This function decodes the pkt's URI option into a "/"-separated and '\0'-terminated string.

Caller must ensure target can hold at least CONFIG_NANOCOAP_URI_MAX bytes!

Parameters

[in]	pkt	pkt to work on
[out]	target	buffer for target URI

Returns: -ENOSPC if URI option is larger than CONFIG_NANOCOAP_URI_MAX; nr of bytes written to target (including '\0')

Definition at line 1118 of file nanocoap.h.

◆ coap_get_uri_query_string()

static ssize_t coap_get_uri_query_string	(	coap_pkt_t *	pkt,
		char *	target,
		size_t	max_len )

inlinestatic

Convenience function for getting the packet's URI_QUERY option.

This function decodes the pkt's URI_QUERY option into a "&"-separated and '\0'-terminated string.

Parameters

[in]	pkt	pkt to work on
[out]	target	buffer for target URI
[in]	max_len	size of `target` in bytes

Returns: -ENOSPC if URI option is larger than max_len; nr of bytes written to target (including '\0')

Definition at line 1137 of file nanocoap.h.

◆ coap_get_ver()

static unsigned coap_get_ver ( const coap_pkt_t * pkt )

inlinestatic

Get the CoAP version number.

Parameters

[in] pkt CoAP packet

Returns: CoAP version number

Definition at line 692 of file nanocoap.h.

◆ coap_handle_req()

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.

This function will find the correct handler, call it and write the reply into resp_buf.

Parameters

[in]	pkt	pointer to (parsed) CoAP packet
[out]	resp_buf	buffer for response
[in]	resp_buf_len	size of response buffer
[in]	ctx	CoAP request context information

Returns: size of reply packet on success; <0 on error

◆ coap_has_observe()

static bool coap_has_observe ( coap_pkt_t * pkt )

inlinestatic

Identifies a packet containing an observe option.

Parameters

[in] pkt CoAP packet

Returns: true if observe value is set; false if not

Definition at line 2944 of file nanocoap.h.

◆ coap_has_unprocessed_critical_options()

bool coap_has_unprocessed_critical_options ( const coap_pkt_t * pkt )

Check whether any of the packet's options that are critical.

(i.e must be understood by the receiver, indicated by a 1 in the option number's least significant bit) were not accessed since the packet was parsed.

Call this in a server on requests after all their option processing has happened, and stop processing the request if it returns true, returning a 4.02 Bad Option response.

Call this in a client when receiving a response before acting on it; consider the response unprocessable if it returns true.

Parameters

[in] pkt pkt to work on

Returns: true if any of the options marked as critical at parse time have not been accessed.; false if there are no critical options, or all have been accessed.

◆ coap_hdr_data_ptr()

static uint8_t * coap_hdr_data_ptr ( const coap_udp_hdr_t * hdr )

inlinestatic

Get the start of data after the header.

Parameters

[in] hdr Header of CoAP packet in contiguous memory

Deprecated: Use coap_get_token() instead

Returns: pointer to first byte after the header

Definition at line 774 of file nanocoap.h.

◆ coap_hdr_get_token()

static const void * coap_hdr_get_token ( const coap_udp_hdr_t * hdr )

inlinestatic

Get the Token of a CoAP over UDP (DTLS) packet.

Parameters

[in] hdr CoAP over UDP header

Returns: The CoAP Token inside the packet that hdr belongs to

Warning: This API is super goofy. It assumes that the packet is valid and will read more than sizeof(*hdr) into the data hdr points to while crossing fingers hard.

Deprecated: This function was introduced to keep legacy code alive. Introducing new callers should be avoided. In the RX path an coap_pkt_t will be available, so that you can call coap_get_token instead. In the TX path the token was added by us, so we really should know.

Definition at line 902 of file nanocoap.h.

◆ coap_hdr_get_token_len()

static size_t coap_hdr_get_token_len ( const coap_udp_hdr_t * hdr )

inlinestatic

Get the token length of a CoAP over UDP (DTLS) packet.

Parameters

[in] hdr CoAP over UDP header

Returns: The size of the token in bytes

Warning: This API is super goofy. It assumes that the packet is valid and will read more than sizeof(*hdr) into the data hdr points to while crossing fingers hard.

Deprecated: This function was introduced to keep legacy code alive. Introducing new callers should be avoided. In the RX path an coap_pkt_t will be available, so that you can call coap_get_token instead. In the TX path the token was added by us, so we really should know.

Definition at line 862 of file nanocoap.h.

◆ coap_hdr_len()

static size_t coap_hdr_len ( const coap_udp_hdr_t * hdr )

inlinestatic

Get the header length of a CoAP packet.

Warning: This API is super goofy. It assumes that the packet is valid and will read more than sizeof(*hdr) into the data hdr points to while crossing fingers hard.

Deprecated: This function was introduced to keep legacy code alive. Introducing new callers should be avoided. In the RX path an coap_pkt_t will be available, so that you can call coap_get_total_hdr_len instead. In the TX path the header was created by us (e.g. using coap_build_hdr which returns the header size), so we really should know already.

Definition at line 923 of file nanocoap.h.

◆ coap_hdr_set_code()

static void coap_hdr_set_code	(	coap_udp_hdr_t *	hdr,
		uint8_t	code )

inlinestatic

Write the given raw message code to given CoAP header.

Parameters

[out]	hdr	CoAP header to write to
[in]	code	raw message code

Deprecated: Use coap_pkt_set_code instead

Definition at line 812 of file nanocoap.h.

◆ coap_hdr_set_type()

static void coap_hdr_set_type	(	coap_udp_hdr_t *	hdr,
		unsigned	type )

inlinestatic

Set the message type for the given CoAP header.

Precondition: (type := [0-3])

Parameters

[out]	hdr	CoAP header to write
[in]	type	message type as integer value [0-3]

Deprecated: Use coap_pkt_set_type instead

Definition at line 838 of file nanocoap.h.

◆ coap_hdr_tkl_ext_len()

static uint8_t coap_hdr_tkl_ext_len ( const coap_udp_hdr_t * hdr )

inlinestatic

Get the size of the extended Token length field (RFC 8974)

Deprecated: Use coap_pkt_tkl_ext_len instead.

Note: This requires the nanocoap_token_ext module to be enabled

Parameters

[in] hdr CoAP header

Returns: number of bytes used for extended token length

Definition at line 709 of file nanocoap.h.

◆ coap_is_hdr_in_bounds()

bool coap_is_hdr_in_bounds	(	const coap_pkt_t *	pkt,
		size_t	len )

Validate that the header of pkt is no longer than len bytes.

This function will read at most len bytes of pkt->buf. It is intended to do basic validation of untrusted data. It only checks that the variable length CoAP header fields (such as the CoAP token and the extended TKL field) are within bounds, but it does not validate the header contents. Specifically, CoAP Options may still have Option Headers that refer to memory past len bytes.

Parameters

[in]	pkt	The CoAP packet to validate. (`pkt->buf` must be valid)
[in]	len	Length of `pkt->buf` in bytes

Return values

true	All header fields up to the CoAP token are within bounds
false	The packet is not valid

Warning: This function does not look at CoAP Options. They may still be out of bounds.

◆ coap_iterate_option()

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.

Parameters

[in]	pkt	packet to work on
[in]	opt_num	the option number to search for
[out]	opt_pos	opaque, must be set to `NULL` on first call
[out]	opt_len	size of the current option data

Returns: pointer to the option data NULL if option number was not found

◆ coap_iterate_uri_query()

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.

This expects that the Uri-Query options follow the widespread format key=value or just key

Key and Value will be copied into the supplied buffers as a NULL-terminated string.

Parameters

[in]	pkt	packet to read from
[out]	ctx	opaque, must be set to `NULL` on first call
[out]	key	Output buffer for the key
[in]	key_len_max	Size of the key output buffer
[out]	value	Output buffer for the value
[in]	value_len_max	Size of the value output buffer

Returns: 2 if key and value were found; 1 if key was found; 0 if no key was found; -E2BIG if key or value does not fit the supplied space

◆ coap_match_path()

int coap_match_path	(	const coap_resource_t *	resource,
		const char *	uri )

Checks if a CoAP resource path matches a given URI.

Builds on strcmp() with rules specific to URI path matching

Note: This function is not intended for application use.

◆ coap_method2flag()

static coap_method_flags_t coap_method2flag ( unsigned code )

inlinestatic

Convert message code (request method) into a corresponding bit field.

Parameters

[in] code request code denoting the request method

Returns: bit field corresponding to the given request method

Definition at line 2735 of file nanocoap.h.

◆ coap_opt_add_accept()

static ssize_t coap_opt_add_accept	(	coap_pkt_t *	pkt,
		uint16_t	format )

inlinestatic

Append an Accept option to the pkt buffer.

Postcondition: pkt.payload advanced to first byte after option; pkt.payload_len reduced by option length

Parameters

[in,out]	pkt	pkt referencing target buffer
[in]	format	COAP_FORMAT_xxx to accept

Returns: number of bytes written to buffer; <0 on error; -ENOSPC if no available options or insufficient buffer space

Definition at line 1685 of file nanocoap.h.

◆ coap_opt_add_block()

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.

When calling this function to initialize a packet with a block option, the more flag must be set to prevent the creation of an option with a length too small to contain the size bit.

Postcondition: pkt.payload advanced to first byte after option; pkt.payload_len reduced by option length

Parameters

[in,out]	pkt	pkt referencing target buffer
[in]	slicer	coap blockwise slicer helper struct
[in]	more	more flag (1 or 0)
[in]	option	option number (block1 or block2)

Returns: number of bytes written to buffer; <0 on error; -ENOSPC if no available options or insufficient buffer space

◆ coap_opt_add_block1()

static ssize_t coap_opt_add_block1	(	coap_pkt_t *	pkt,
		coap_block_slicer_t *	slicer,
		bool	more )

inlinestatic

Add block1 option in descriptive use from a slicer object.

When calling this function to initialize a packet with a block option, the more flag must be set to prevent the creation of an option with a length too small to contain the size bit.

Postcondition: pkt.payload advanced to first byte after option; pkt.payload_len reduced by option length

Parameters

[in,out]	pkt	pkt referencing target buffer
[in]	slicer	coap blockwise slicer helper struct
[in]	more	more flag (1 or 0)

Returns: number of bytes written to buffer; <0 on error; -ENOSPC if no available options or insufficient buffer space

Definition at line 1590 of file nanocoap.h.

◆ coap_opt_add_block1_control()

static ssize_t coap_opt_add_block1_control	(	coap_pkt_t *	pkt,
		coap_block1_t *	block )

inlinestatic

Encode the given block1 option in control use.

Postcondition: pkt.payload advanced to first byte after option; pkt.payload_len reduced by option length

Parameters

[in,out]	pkt	pkt referencing target buffer
[in]	block	block to encode

Returns: number of bytes written to buffer; <0 on error; -ENOSPC if no available options or insufficient buffer space

Definition at line 1648 of file nanocoap.h.

◆ coap_opt_add_block2()

static ssize_t coap_opt_add_block2	(	coap_pkt_t *	pkt,
		coap_block_slicer_t *	slicer,
		bool	more )

inlinestatic

Add block2 option in descriptive use from a slicer object.

When calling this function to initialize a packet with a block option, the more flag must be set to prevent the creation of an option with a length too small to contain the size bit.

Postcondition: pkt.payload advanced to first byte after option; pkt.payload_len reduced by option length

Parameters

[in,out]	pkt	pkt referencing target buffer
[in]	slicer	coap blockwise slicer helper struct
[in]	more	more flag (1 or 0)

Returns: number of bytes written to buffer; <0 on error; -ENOSPC if no available options or insufficient buffer space

Definition at line 1614 of file nanocoap.h.

◆ coap_opt_add_block2_control()

static ssize_t coap_opt_add_block2_control	(	coap_pkt_t *	pkt,
		coap_block1_t *	block )

inlinestatic

Encode the given block2 option in control use.

Postcondition: pkt.payload advanced to first byte after option; pkt.payload_len reduced by option length

Parameters

[in,out]	pkt	pkt referencing target buffer
[in]	block	block to encode

Returns: number of bytes written to buffer; <0 on error; -ENOSPC if no available options or insufficient buffer space

Definition at line 1666 of file nanocoap.h.

◆ coap_opt_add_chars()

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.

Use separator to split array of characters into multiple options.

Postcondition: pkt.payload advanced to first byte after option(s); pkt.payload_len reduced by option(s) length

Parameters

[in,out]	pkt	pkt referencing target buffer
[in]	optnum	option number to use
[in]	chars	array of characters to encode as option
[in]	chars_len	length of `chars`
[in]	separator	character used in `string` to separate parts

Returns: number of bytes written to buffer; <0 on error; -ENOSPC if no available options or insufficient buffer space

◆ coap_opt_add_format()

static ssize_t coap_opt_add_format	(	coap_pkt_t *	pkt,
		uint16_t	format )

inlinestatic

Append a Content-Format option to the pkt buffer.

Postcondition: pkt.payload advanced to first byte after option; pkt.payload_len reduced by option length

Parameters

[in,out]	pkt	pkt referencing target buffer
[in]	format	COAP_FORMAT_xxx to use

Returns: number of bytes written to buffer; <0 on error; -ENOSPC if no available options or insufficient buffer space

Definition at line 1703 of file nanocoap.h.

◆ coap_opt_add_opaque()

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.

Postcondition: pkt.payload advanced to first byte after option(s); pkt.payload_len reduced by option(s) length

Parameters

[in,out]	pkt	pkt referencing target buffer
[in]	optnum	option number to use
[in]	val	pointer to the value to be set
[in]	val_len	length of val

Returns: number of bytes written to buffer; <0 on error; -ENOSPC if no available options

◆ coap_opt_add_proxy_uri()

ssize_t coap_opt_add_proxy_uri	(	coap_pkt_t *	pkt,
		const char *	uri )

Adds a single Proxy-URI option into pkt.

Note: uri must be a NULL-terminated absolute URI

Parameters

[in,out]	pkt	Packet being built
[in]	uri	absolute proxy URI

Precondition: ((pkt != NULL) && (uri != NULL))

Returns: number of bytes written to pkt buffer; <0 on error; -ENOSPC if no available options or pkt full

◆ coap_opt_add_string()

static ssize_t coap_opt_add_string	(	coap_pkt_t *	pkt,
		uint16_t	optnum,
		const char *	string,
		char	separator )

inlinestatic

Encode the given string as option(s) into pkt.

Use separator to split string into multiple options.

Postcondition: pkt.payload advanced to first byte after option(s); pkt.payload_len reduced by option(s) length

Parameters

[in,out]	pkt	pkt referencing target buffer
[in]	optnum	option number to use
[in]	string	string to encode as option
[in]	separator	character used in `string` to separate parts

Returns: number of bytes written to buffer; <0 on error; -ENOSPC if no available options or insufficient buffer space

Definition at line 1821 of file nanocoap.h.

◆ coap_opt_add_uint()

ssize_t coap_opt_add_uint	(	coap_pkt_t *	pkt,
		uint16_t	optnum,
		uint32_t	value )

Encode the given uint option into pkt.

Postcondition: pkt.payload advanced to first byte after option; pkt.payload_len reduced by option length

Parameters

[in,out]	pkt	pkt referencing target buffer
[in]	optnum	option number to use
[in]	value	uint to encode

Returns: number of bytes written to buffer; <0 on error; -ENOSPC if no available options or insufficient buffer space

◆ coap_opt_add_uri_path()

static ssize_t coap_opt_add_uri_path	(	coap_pkt_t *	pkt,
		const char *	path )

inlinestatic

Adds one or multiple Uri-Path options in the form '/path' into pkt.

Note: Use this only for null-terminated strings.

Parameters

[in,out]	pkt	Packet being built
[in]	path	`\0`-terminated resource (sub)path

Precondition: ((pkt != NULL) && (path != NULL))

Returns: number of bytes written to pkt buffer; <0 on error; -ENOSPC if no available options or pkt full

Definition at line 1841 of file nanocoap.h.

◆ coap_opt_add_uri_path_buffer()

static ssize_t coap_opt_add_uri_path_buffer	(	coap_pkt_t *	pkt,
		const char *	path,
		size_t	path_len )

inlinestatic

Adds one or multiple Uri-Path options in the form '/path' into pkt.

Note: Use this only for null-terminated strings.

Parameters

[in,out]	pkt	Packet being built
[in]	path	Resource (sub)path
[in]	path_len	Length of `path`

Precondition: ((pkt != NULL) && (path != NULL))

Returns: number of bytes written to pkt buffer; <0 on error; -ENOSPC if no available options or pkt full

Definition at line 1861 of file nanocoap.h.

◆ coap_opt_add_uri_query()

static ssize_t coap_opt_add_uri_query	(	coap_pkt_t *	pkt,
		const char *	key,
		const char *	val )

inlinestatic

Adds a single Uri-Query option in the form 'key=value' into pkt.

Note: Use this only for null-terminated string. See coap_opt_add_uri_query2() for non null-terminated string.

Parameters

[in,out]	pkt	Packet being built
[in]	key	Key to add to the query string
[in]	val	Value to assign to `key` (may be NULL)

Precondition: ((pkt != NULL) && (key != NULL))

Returns: number of bytes written to pkt buffer; <0 on error; -ENOSPC if no available options or pkt full

Definition at line 1761 of file nanocoap.h.

◆ coap_opt_add_uri_query2()

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.

Parameters

[in,out]	pkt	Packet being built
[in]	key	Key to add to the query string
[in]	key_len	Length of `key`
[in]	val	Value to assign to `key` (may be NULL)
[in]	val_len	Length of `val`. 0 if `val` is NULL

Precondition: ((pkt != NULL) && (key != NULL) && (key_len > 0) && ((val_len == 0) || ((val != NULL) && (val_len > 0))))

Returns: number of bytes written to pkt buffer; <0 on error; -ENOSPC if no available options or pkt full

◆ coap_opt_finish()

ssize_t coap_opt_finish	(	coap_pkt_t *	pkt,
		uint16_t	flags )

Finalizes options as required and prepares for payload.

Postcondition: pkt.payload advanced to first available byte after options; pkt.payload_len is maximum bytes available for payload

Parameters

[in,out]	pkt	pkt to update
[in]	flags	see COAP_OPT_FINISH... macros

Returns: total number of bytes written to buffer; -ENOSPC if no buffer space for payload marker

◆ coap_opt_get_next()

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.

To start iteration from the first option, set init_opt to true. To start iteration from a specific option, set init_opt to false, set opt->offset to the offset of the desired option from pkt->hdr, and opt->opt_num as required. See below for how opt->opt_num is modified.

With each invocation, this function returns the length of the option value and sets value to point to the start of the value. The value for opt->opt_num is increased by the delta in the option number value over the preceding option in the packet. So, opt->opt_num is accurate if iteration started with the first option. Otherwise, it is useful for identification of repeated options. Finally, opt->offset is set to the offset for any following option, to prepare for the next iteration.

The end of the options is indicated by a -ENOENT return value. In this case value and opt are unchanged from their input values.

Parameters

[in]	pkt	packet to read from
[in,out]	opt	option attributes; read on input if `init_opt` is false
[out]	value	start of the option value
[in]	init_opt	true to retrieve first option; false to retrieve option at opt->offset

Returns: length of option value; -ENOENT if option not found

◆ coap_opt_get_opaque()

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.

Retrieves the location and length of the option value of any type. Useful for an opaque option, which essentially is an array of bytes. If more than one option for a given option number, retrieves the first option. To retrieve subsequent options, see coap_opt_get_next().

Parameters

[in]	pkt	packet to read from
[in]	opt_num	option number to retrieve
[out]	value	start of the option value

Returns: length of option; 0 if the option exists but is empty; -ENOENT if option not found; -EINVAL if option cannot be parsed

◆ coap_opt_get_string()

ssize_t coap_opt_get_string	(	coap_pkt_t *	pkt,
		uint16_t	optnum,
		char *	target,
		size_t	max_len,
		char	separator )

Read a full option as null terminated string into the target buffer.

This function is for reading and concatenating string based, multi-part CoAP options like COAP_OPT_URI_PATH or COAP_OPT_LOCATION_PATH. It will write all parts of the given option into the target buffer, separating the parts using the given separator. The resulting string is \0 terminated.

Parameters

[in]	pkt	packet to read from
[in]	optnum	absolute option number
[out]	target	target buffer
[in]	max_len	size of `target`
[in]	separator	character used for separating the option parts

Returns: -ENOSPC if the complete option does not fit into target; nr of bytes written to target (including '\0')

◆ coap_opt_get_uint()

int coap_opt_get_uint	(	coap_pkt_t *	pkt,
		uint16_t	optnum,
		uint32_t *	value )

Get a uint32 option value.

Parameters

[in]	pkt	packet to read from
[in]	optnum	absolute option number
[out]	value	the parsed option value

Returns: 0 if the option was found and the value was parsed correctly; -ENOENT if the option was not found in pkt; -ENOSPC if option length is greater than 4 octets; -EBADMSG if option value is invalid

◆ coap_opt_put()

int coap_opt_put	(	coap_builder_t *	state,
		uint16_t	onum,
		const void *	odata,
		size_t	olen )

Insert a CoAP option into buffer.

This function writes a CoAP option with nr. onum to the buffer managed by state and also does proper delta-encoding based on the most recently added option as per state. Both the option header is added and the option data from odata is copied.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	onum	number of the option to add
[in]	odata	ptr to raw option data (or NULL)
[in]	olen	length of `odata` (if any)

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: onum is greater than or equal to the option number of the option most recently put into state.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

◆ coap_opt_put_block()

int coap_opt_put_block	(	coap_builder_t *	state,
		coap_block_slicer_t *	slicer,
		uint16_t	option )

Insert block option into buffer.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	slicer	coap blockwise slicer helper struct
[in]	option	option number (block1 or block2)

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than option

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

◆ coap_opt_put_block1()

static int coap_opt_put_block1	(	coap_builder_t *	state,
		coap_block_slicer_t *	slicer )

inlinestatic

Insert block1 option into buffer.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	slicer	coap blockwise slicer helper struct

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than 27.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

Definition at line 2133 of file nanocoap.h.

◆ coap_opt_put_block1_control()

static int coap_opt_put_block1_control	(	coap_builder_t *	state,
		coap_block1_t *	block )

inlinestatic

Insert block1 option into buffer in control usage.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	block	block option attribute struct

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than 27.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

Definition at line 2197 of file nanocoap.h.

◆ coap_opt_put_block1_raw()

static int coap_opt_put_block1_raw	(	coap_builder_t *	state,
		unsigned	blknum,
		unsigned	szx,
		int	more )

inlinestatic

Insert block1 option into buffer.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	blknum	block number
[in]	szx	SXZ value
[in]	more	more flag (1 or 0)

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than 27.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

Definition at line 2505 of file nanocoap.h.

◆ coap_opt_put_block2()

static int coap_opt_put_block2	(	coap_builder_t *	state,
		coap_block_slicer_t *	slicer )

inlinestatic

Insert block2 option into buffer.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	slicer	coap blockwise slicer helper struct

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than 23.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

Definition at line 2155 of file nanocoap.h.

◆ coap_opt_put_block2_control()

static int coap_opt_put_block2_control	(	coap_builder_t *	state,
		coap_block1_t *	block )

inlinestatic

Insert block2 option into buffer in control usage.

Forces value of block 'more' attribute to zero, per spec.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	block	block option attribute struct

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than 23.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

Definition at line 2222 of file nanocoap.h.

◆ coap_opt_put_ct()

static int coap_opt_put_ct	(	coap_builder_t *	state,
		uint16_t	content_type )

inlinestatic

Insert content type option into buffer.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	content_type	content type to set

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than 12.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

Definition at line 2528 of file nanocoap.h.

◆ coap_opt_put_location_path()

static int coap_opt_put_location_path	(	coap_builder_t *	state,
		const char *	location )

inlinestatic

Convenience function for inserting LOCATION_PATH option into buffer.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	location	ptr to string holding the location

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than 8.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

Definition at line 2316 of file nanocoap.h.

◆ coap_opt_put_location_query()

static int coap_opt_put_location_query	(	coap_builder_t *	state,
		const char *	location )

inlinestatic

Convenience function for inserting LOCATION_QUERY option into buffer.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	location	ptr to string holding the location

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than 20.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

Definition at line 2339 of file nanocoap.h.

◆ coap_opt_put_observe()

static int coap_opt_put_observe	(	coap_builder_t *	state,
		uint32_t	obs )

inlinestatic

Insert an CoAP Observe Option into the buffer.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	obs	observe number to write

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than 6.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

Definition at line 2246 of file nanocoap.h.

◆ coap_opt_put_proxy_uri()

static int coap_opt_put_proxy_uri	(	coap_builder_t *	state,
		const char *	uri )

inlinestatic

Convenience function for inserting PROXY_URI option into buffer.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	uri	ptr to source URI

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than 35.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

Definition at line 2430 of file nanocoap.h.

◆ coap_opt_put_string()

static int coap_opt_put_string	(	coap_builder_t *	state,
		uint16_t	optnum,
		const char *	string,
		char	separator )

inlinestatic

Encode the given string as multi-part option into buffer.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	optnum	option number to use
[in]	string	string to encode as option
[in]	separator	character used in `string` to separate parts

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than optnum.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

Definition at line 2293 of file nanocoap.h.

◆ coap_opt_put_string_with_len()

int coap_opt_put_string_with_len	(	coap_builder_t *	state,
		uint16_t	optnum,
		const char *	string,
		size_t	len,
		char	separator )

Encode the given string as multi-part option into buffer.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	optnum	option number to use
[in]	string	string to encode as option
[in]	len	length of the string
[in]	separator	character used in `string` to separate parts

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than optnum.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

◆ coap_opt_put_uint()

int coap_opt_put_uint	(	coap_builder_t *	state,
		uint16_t	onum,
		uint32_t	value )

Encode the given uint option into buffer.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	onum	number of option
[in]	value	value to encode

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than onum.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

◆ coap_opt_put_uri_path()

static int coap_opt_put_uri_path	(	coap_builder_t *	state,
		const char *	uri )

inlinestatic

Convenience function for inserting URI_PATH option into buffer.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	uri	ptr to source URI

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than 11.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

Definition at line 2362 of file nanocoap.h.

◆ coap_opt_put_uri_pathquery()

int coap_opt_put_uri_pathquery	(	coap_builder_t *	state,
		const char *	uri )

Convenience function for inserting URI_PATH and URI_QUERY into buffer This function will automatically split path and query parameters.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	uri	ptr into a source URI, to the first character after the authority component

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than 11.

This function may produce two different options (Uri-Path and Uri-Query). Users that need to insert Content-Format, Max-Age or the currently unassigned option 13 need to split their URI themselves and call the respective helper functions.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

◆ coap_opt_put_uri_query()

static int coap_opt_put_uri_query	(	coap_builder_t *	state,
		const char *	uri_query )

inlinestatic

Convenience function for inserting URI_QUERY option into buffer.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	uri_query	ptr to source URI-Query

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than 15.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

Definition at line 2383 of file nanocoap.h.

◆ coap_opt_remove()

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.

Parameters

[in]	pkt	Packet to remove option from.
[in]	optnum	Option number of the option to remove. If the option appears more than once, the first occurrence will be removed

Precondition: pkt != NULL; The packet was finished using coap_opt_finish() and any payload is in its final configuration.

Returns: The new size of the packet with option of number optnum removed. In turn this means if there is no such option in the packet, the original size of the packet will be removed.; -EINVAL if there was a parsing error for the existing options

◆ coap_parse()

static ssize_t coap_parse	(	coap_pkt_t *	pkt,
		uint8_t *	buf,
		size_t	len )

inlinestatic

Alias for coap_parse_udp.

Deprecated: Use coap_parse_udp instead

Definition at line 2762 of file nanocoap.h.

◆ coap_parse_udp()

ssize_t coap_parse_udp	(	coap_pkt_t *	pkt,
		uint8_t *	buf,
		size_t	len )

Parse a CoAP PDU in UDP / DTLS format.

This function parses a raw CoAP PDU from buf with size len and fills the structure pointed to by pkt. pkt must point to a preallocated coap_pkt_t structure.

Parameters

[out]	pkt	structure to parse into
[in]	buf	pointer to raw packet data
[in]	len	length of packet at `buf`

Returns: Number of bytes parsed (may not match len on stream transports)

Return values

<0 error

◆ coap_payload_advance_bytes()

static void coap_payload_advance_bytes	(	coap_pkt_t *	pkt,
		size_t	len )

inlinestatic

Advance the payload pointer.

Precondition: You added len bytes of data to pkt->payload.

You can add payload to a CoAP request by writing data directly to pkt->payload. This convenience function takes care of advancing the payload pointer afterwards.

Parameters

[out]	pkt	pkt to which payload was added
[in]	len	length of payload

Definition at line 2796 of file nanocoap.h.

◆ coap_payload_put_bytes()

ssize_t coap_payload_put_bytes	(	coap_pkt_t *	pkt,
		const void *	data,
		size_t	len )

Add payload data to the CoAP request.

Precondition: coap_opt_finish must have been called before with the COAP_OPT_FINISH_PAYLOAD option.

The function copies data into the payload buffer of pkt and advances the payload pointer.

This is just a convenience function, you can also directly write to pkt->payload if you have a function that outputs payload to a buffer. In this case you should instead call coap_payload_advance_bytes.

Parameters

[out]	pkt	pkt to add payload to
[in]	data	payload data
[in]	len	length of payload

Returns: number of payload bytes added on success; < 0 on error

◆ coap_payload_put_char()

ssize_t coap_payload_put_char	(	coap_pkt_t *	pkt,
		char	c )

Add a single character to the payload data of the CoAP request.

This function is used to add single characters to a CoAP payload data. It checks whether the character can be added to the buffer and ignores if the payload area is already exhausted.

Parameters

[out]	pkt	pkt to add payload to
[in]	c	character to write

Returns: number of payload bytes added on success (always one); < 0 on error

◆ coap_pkt_init()

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.

Precondition: buf CoAP header already initialized

Postcondition: pkt.flags all zeroed; pkt.payload points to first byte after header; pkt.payload_len set to maximum space available for options + payload

Parameters

[out]	pkt	pkt to initialize
[in]	buf	buffer to write for pkt, with CoAP header already initialized
[in]	len	length of buf
[in]	header_len	length of header in buf, including token

◆ coap_pkt_set_code()

static void coap_pkt_set_code	(	coap_pkt_t *	pkt,
		uint8_t	code )

inlinestatic

Write the given raw message code to given CoAP pkt.

Parameters

[out]	pkt	CoAP packet to write to
[in]	code	raw message code

Definition at line 823 of file nanocoap.h.

◆ coap_pkt_set_tkl()

static void coap_pkt_set_tkl	(	coap_pkt_t *	pkt,
		uint8_t	tkl )

inlinestatic

Set the message token length for the given CoAP packet.

Precondition: tkl <= 8

Parameters

[out]	pkt	CoAP packet to write to
[in]	tkl	Token length to write

Warning: This function is internal, no out of tree users please.

Definition at line 955 of file nanocoap.h.

◆ coap_pkt_set_type()

static void coap_pkt_set_type	(	coap_pkt_t *	pkt,
		unsigned	type )

inlinestatic

Set the message type for the given CoAP packet.

Precondition: (type := [0-3])

Parameters

[out]	pkt	CoAP packet to write to
[in]	type	message type as integer value [0-3]

Definition at line 936 of file nanocoap.h.

◆ coap_pkt_tkl_ext_len()

static uint8_t coap_pkt_tkl_ext_len ( const coap_pkt_t * pkt )

inlinestatic

Get the size of the extended Token length field (RFC 8974)

Note

This requires the nanocoap_token_ext module to be enabled

@param[in]   pkt     CoAP packet

Returns: number of bytes used for extended token length

Definition at line 738 of file nanocoap.h.

◆ coap_put_block1_ok()

int coap_put_block1_ok	(	coap_builder_t *	state,
		coap_block1_t *	block1 )

Insert block1 option into buffer (from coap_block1_t)

This function is wrapper around coap_opt_put_block1(), taking its arguments from a coap_block1_t struct.

It will write option Nr. 27 (COAP_OPT_BLOCK1).

It is safe to be called when block1 was generated for a non-blockwise request.

Parameters

[in,out]	state	the data structure used to handle the state
[in]	block1	ptr to block1 struct (created by coap_get_block1())

Return values

0	Success
-EOVERFLOW	Not enough space in buffer
<0	Other error

Precondition: The option most recently added to state must be smaller than 27.

Note: If at the end of the response handler coap_builder_msg_size is used, it is safe to ignore the return value: state is marked as overflown by setting state->size to 0 on overflow.

◆ coap_reply_simple()

ssize_t coap_reply_simple	(	coap_pkt_t *	pkt,
		uint8_t	code,
		uint8_t *	buf,
		size_t	len,
		uint16_t	ct,
		const void *	payload,
		size_t	payload_len )

Create CoAP reply (convenience function)

This is a simple wrapper that allows for building CoAP replies for simple use-cases.

The reply will be written to buf. If payload and payload_len are non-zero, the payload will be copied into the resulting reply packet.

Parameters

[in]	pkt	packet to reply to
[in]	code	reply code (e.g., COAP_CODE_204)
[out]	buf	buffer to write reply to
[in]	len	size of `buf`
[in]	ct	content type of payload or COAP_FORMAT_NONE
[in]	payload	ptr to payload
[in]	payload_len	length of payload

Returns: size of reply packet on success

Return values

-ECANCELED	reply should be sent due to no-reply option (pass this error through, server will handle this)
-ENOSPC	`buf` too small
<0	other error

◆ coap_request_ctx_get_context()

void * coap_request_ctx_get_context ( const coap_request_ctx_t * ctx )

Get resource context associated with a CoAP request.

Parameters

[in] ctx The request context

Returns: Resource context of the request

◆ coap_request_ctx_get_local_udp()

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.

Parameters

[in] ctx The request context

Returns: Local endpoint to which the request has been received; NULL The request was not received via UDP

◆ coap_request_ctx_get_path()

const char * coap_request_ctx_get_path ( const coap_request_ctx_t * ctx )

Get resource path associated with a CoAP request.

Parameters

[in] ctx The request context

Returns: Resource path of the request

◆ coap_request_ctx_get_remote_udp()

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.

Parameters

[in] ctx The request context

Returns: Remote endpoint from which the request originated; NULL The request was not received via UDP

◆ coap_request_ctx_get_tl_type()

uint32_t coap_request_ctx_get_tl_type ( const coap_request_ctx_t * ctx )

Get transport the packet was received over.

See also: gcoap_socket_type_t for values.

Parameters

[in] ctx The request context

Returns: Transport Layer type of the request

◆ coap_request_ctx_init()

void coap_request_ctx_init	(	coap_request_ctx_t *	ctx,
		sock_udp_ep_t *	remote )

Initialize CoAP request context.

Parameters

[in]	ctx	Pointer to the request context to initialize
[in]	remote	Remote endpoint that made the request

◆ coap_set_id()

static void coap_set_id	(	coap_pkt_t *	pkt,
		uint16_t	id )

inlinestatic

Set the message ID of the given CoAP packet.

Parameters

[out]	pkt	CoAP packet to write the ID to
[in]	id	Message ID to write (in host byte order)

Definition at line 624 of file nanocoap.h.

◆ coap_size2szx()

static unsigned coap_size2szx ( unsigned len )

inlinestatic

Helper to encode byte size into next equal or smaller SZX value.

Parameters

[in] len Size in bytes

Returns: closest SZX value that fits into a buffer of len

Definition at line 1532 of file nanocoap.h.

◆ coap_subtree_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.

This function can be used as a generic handler for resources with the COAP_MATCH_SUBTREE where a new coap_resource_t is to be parsed.

Note: The context must be of type coap_resource_subtree_t.

Parameters

[in]	pkt	pointer to (parsed) CoAP packet
[out]	resp_buf	buffer for response
[in]	resp_buf_len	size of response buffer
[in]	context	pointer to request context, must contain context to coap_resource_subtree_t instance

Returns: size of the reply packet on success; <0 on error

◆ coap_tree_handler()

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.

This function will try to find a matching handler in resources and call the handler.

Parameters

[in]	pkt	pointer to (parsed) CoAP packet
[out]	resp_buf	buffer for response
[in]	resp_buf_len	size of response buffer
[in]	ctx	CoAP request context information
[in]	resources	Array of coap endpoint resources
[in]	resources_numof	length of the coap endpoint resources

Returns: size of the reply packet on success; <0 on error

Detailed Description

Application APIs

Option APIs

Server path matching

Topics

Files

Data Structures

Macros

Typedefs

Functions

Functions – Header Read/Write

Functions – Options Read

Functions – Options for Block

Functions – Options Write Packet API

Functions – Options Write Buffer API

Functions – Messaging

Functions – gcoap specific

nanoCoAP specific CoAP method flags used in coap_handlers array

coap_opt_finish() flag parameter values

Macro Definition Documentation

◆ COAP_DELETE

◆ COAP_FETCH

◆ COAP_FORMAT_NONE

◆ COAP_GET

◆ COAP_IGNORE

◆ COAP_IPATCH

◆ COAP_MATCH_SUBTREE

◆ COAP_OPT_FINISH_NONE

◆ COAP_OPT_FINISH_PAYLOAD

◆ COAP_PATCH

◆ COAP_POST

◆ COAP_PUT

◆ coap_szx2size

◆ COAP_WELL_KNOWN_CORE_DEFAULT_HANDLER

◆ CONFIG_NANOCOAP_BLOCK_HEADER_MAX

◆ CONFIG_NANOCOAP_SERVER_WELL_KNOWN_CORE

◆ NANOCOAP_RESOURCE

Typedef Documentation

◆ coap_blockwise_cb_t

◆ coap_handler_t

◆ coap_hdr_t

◆ coap_method_flags_t

◆ coap_request_cb_t

◆ coap_request_ctx_t

Function Documentation

◆ coap_block1_finish()

◆ coap_block2_finish()

◆ coap_block2_init()

◆ coap_block_finish()

◆ coap_block_object_init()

◆ coap_block_slicer_init()

◆ coap_blockwise_put_bytes()

◆ coap_blockwise_put_bytes_pkt()

◆ coap_blockwise_put_char()

◆ coap_blockwise_put_char_pkt()

◆ coap_build_empty_ack()

◆ coap_build_hdr()

◆ coap_build_reply()

◆ coap_build_reply_header()

◆ coap_build_udp_hdr()

◆ coap_builder_add_payload()

◆ coap_builder_add_payload_marker()

◆ coap_builder_allocate_payload()

◆ coap_builder_buf_remaining()

◆ coap_builder_buf_size()

◆ coap_builder_has_overflown()

◆ coap_builder_init()

◆ coap_builder_init_reply()

◆ coap_builder_msg_size()

◆ coap_clear_observe()

◆ coap_code()

◆ coap_find_option()

◆ coap_find_uri_query()

◆ coap_get_accept()

◆ coap_get_block()

◆ coap_get_block1()

◆ coap_get_block2()

◆ coap_get_blockopt()

◆ coap_get_code_class()

◆ coap_get_code_decimal()