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

Detailed Description

CoAP library optimized for minimal resource usage.

nanocoap provides a granular, low-level interface for writing CoAP messages via RIOT's sock networking API.

Server Operation

See the nanocoap_server example, which is built on the nanocoap_server() function. A server must define an array of coap_resource_t resources for which it responds. See the declarations of coap_resources and coap_resources_numof. The array contents must be ordered by the resource path, specifically the ASCII encoding of the path characters (digit and capital precede lower case). nanocoap provides the COAP_WELL_KNOWN_CORE_DEFAULT_HANDLER entry for /.well-known/core.

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.

Handler functions

For each resource, you must implement a coap_handler_t handler function. nanocoap provides functions to help implement the handler. If the handler is called via nanocoap_server(), the response buffer provided to the handler reuses the buffer for the request. So, your handler must read the request thoroughly before writing the response.

To read the request, use the coap_get_xxx() functions to read the header and options. Use the coap_opt_get_xxx() functions to read an option generically by data type. If the pkt payload_len attribute is a positive value, start to read it at the payload pointer attribute.

If a response does not require specific CoAP options, use coap_reply_simple(). If there is a payload, it writes a Content-Format option with the provided value.

For a response with additional CoAP options, start by calling coap_build_reply(). Then choose either the minimal API or the struct-based API to write the rest of the response. See the instructions in the section Write Options and Payload below.

Client Operation

Choose either the minimal API or the struct-based API to write a request. Follow the instructions in the section Write Options and Payload below.

To send the message and await the response, see nanocoap_request() as well as nanocoap_get(), which additionally copies the response payload to a user supplied buffer. Finally, read the response as described above in the server Handler functions section for reading a request.

Write Options and Payload

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 provides two APIs for writing CoAP options:

minimal API requires only a reference to the buffer for the message. However, 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.
struct-based API uses a coap_pkt_t struct to conveniently track each option as it is written and prepare for any payload. 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.

You must use one API exclusively for a given message. For either API, the caller must write options in order by option number (see "CoAP option numbers" in CoAP defines).

Minimal API

Before starting, ensure the CoAP header has been initialized with coap_build_hdr(). For a response, coap_build_reply() includes a call to coap_build_hdr(). Use the returned length to track the next position in the buffer to write and remaining length.

Next, use the coap_opt_put_xxx() and coap_put_xxx() functions to write each option. These functions require the position in the buffer to start writing, and return the number of bytes written.

Note: You must ensure the buffer has enough space remaining to write each option. The API does not verify the safety of writing an option.

If there is a payload, append a payload marker (0xFF). Then write the payload to within the maximum length remaining in the buffer.

Struct-based API

As with the minimal API, first ensure the CoAP header has been initialized with coap_build_hdr(). Then use coap_pkt_init() to initialize the coap_pkt_t struct.

Next, use the coap_opt_add_xxx() functions to write each option, like coap_opt_add_uint(). When all options have been added, call coap_opt_finish().

Note: You must ensure the buffer has enough space remaining to write each option. You can monitor coap_pkt_t.payload_len for remaining space, or watch for a -ENOSPC return value from the API.

Finally, write any message payload at the coap_pkt_t payload pointer attribute. The payload_len attribute provides the available length in the buffer. The option functions keep these values current as they are used.

Create a Block-wise Response (Block2)

Block-wise is a CoAP extension (RFC 7959) to divide a large payload across multiple physical packets. This section describes how to write a block-wise payload for a response, and is known as Block2. (Block1 is for a block-wise payload in a request.) See _riot_board_handler() in the nanocoap_server example for an example handler implementation.

Start with coap_block2_init() to read the client request and initialize a coap_slicer_t struct with the size and location for this slice of the overall payload. Then write the block2 option in the response with coap_opt_put_block2(). The option includes an indicator ("more") that a slice completes the overall payload transfer. You may not know the value for more at this point, but you must initialize the space in the packet for the option before writing the payload. The option is rewritten later.

Next, use the coap_blockwise_put_xxx() functions to write the payload content. These functions use the coap_block_slicer_t to enable or disable actually writing the content, depending on the current position within the overall payload transfer.

Finally, use the convenience function coap_block2_build_reply(), which finalizes the packet and calls coap_block2_finish() internally to update the block2 option.

Modules
	Nanocoap compile configurations

Files
file	nanocoap.h
	nanocoap API

file	nanocoap_sock.h
	nanocoap high-level API

Data Structures
struct	coap_hdr_t
	Raw CoAP PDU header structure. More...

struct	coap_optpos_t
	CoAP option array entry. More...

struct	coap_pkt_t
	CoAP PDU parsing context structure. More...

struct	coap_resource_t
	Type for CoAP resource entry. More...

struct	coap_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	COAP_WELL_KNOWN_CORE_DEFAULT_HANDLER
	Resource definition for the default .well-known/core handler. More...

Typedefs
typedef ssize_t(*	coap_handler_t) (coap_pkt_t pkt, uint8_t buf, size_t len, void *context)
	Resource handler type.

Functions
int	coap_parse (coap_pkt_t pkt, uint8_t buf, size_t len)
	Parse a CoAP PDU. More...

ssize_t	coap_build_reply (coap_pkt_t pkt, unsigned code, uint8_t rbuf, unsigned rlen, unsigned payload_len)
	Build reply to CoAP request. More...

ssize_t	coap_reply_simple (coap_pkt_t pkt, unsigned code, uint8_t buf, size_t len, unsigned ct, const uint8_t *payload, uint8_t payload_len)
	Create CoAP reply (convenience function) More...

ssize_t	coap_handle_req (coap_pkt_t pkt, uint8_t resp_buf, unsigned resp_buf_len)
	Handle incoming CoAP request. More...

ssize_t	coap_build_hdr (coap_hdr_t hdr, unsigned type, uint8_t token, size_t token_len, unsigned code, uint16_t id)
	Builds a CoAP header. More...

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. More...

size_t	coap_put_option (uint8_t buf, uint16_t lastonum, uint16_t onum, const uint8_t odata, size_t olen)
	Insert a CoAP option into buffer. More...

size_t	coap_put_option_ct (uint8_t *buf, uint16_t lastonum, uint16_t content_type)
	Insert content type option into buffer. More...

size_t	coap_opt_put_string (uint8_t buf, uint16_t lastonum, uint16_t optnum, const char string, char separator)
	Encode the given string as multi-part option into buffer. More...

static size_t	coap_opt_put_uri_path (uint8_t buf, uint16_t lastonum, const char uri)
	Convenience function for inserting URI_PATH option into buffer. More...

static size_t	coap_opt_put_uri_query (uint8_t buf, uint16_t lastonum, const char uri)
	Convenience function for inserting URI_QUERY option into buffer. More...

static size_t	coap_opt_put_location_path (uint8_t buf, uint16_t lastonum, const char location)
	Convenience function for inserting LOCATION_PATH option into buffer. More...

static size_t	coap_opt_put_location_query (uint8_t buf, uint16_t lastonum, const char location)
	Convenience function for inserting LOCATION_QUERY option into buffer. More...

int	coap_get_blockopt (coap_pkt_t pkt, uint16_t option, uint32_t blknum, unsigned *szx)
	Generic block option getter. More...

int	coap_get_block1 (coap_pkt_t pkt, coap_block1_t block1)
	Block1 option getter. More...

int	coap_get_block2 (coap_pkt_t pkt, coap_block1_t block2)
	Block2 option getter. More...

size_t	coap_put_option_block1 (uint8_t *buf, uint16_t lastonum, unsigned blknum, unsigned szx, int more)
	Insert block1 option into buffer. More...

size_t	coap_put_block1_ok (uint8_t pkt_pos, coap_block1_t block1, uint16_t lastonum)
	Insert block1 option into buffer (from coap_block1_t) More...

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. More...

ssize_t	coap_opt_add_opaque (coap_pkt_t pkt, uint16_t optnum, const uint8_t val, size_t val_len)
	Encode the given buffer as an opaque data option into pkt. More...

ssize_t	coap_opt_add_uint (coap_pkt_t *pkt, uint16_t optnum, uint32_t value)
	Encode the given uint option into pkt. More...

static ssize_t	coap_opt_add_format (coap_pkt_t *pkt, uint16_t format)
	Append a Content-Format option to the pkt buffer. More...

ssize_t	coap_opt_finish (coap_pkt_t *pkt, uint16_t flags)
	Finalizes options as required and prepares for payload. More...

size_t	coap_opt_put_block2 (uint8_t buf, uint16_t lastonum, coap_block_slicer_t slicer, bool more)
	Insert block2 option into buffer. More...

unsigned	coap_get_content_type (coap_pkt_t *pkt)
	Get content type from packet. More...

ssize_t	coap_opt_get_string (const coap_pkt_t pkt, uint16_t optnum, uint8_t target, size_t max_len, char separator)
	Read a full option as null terminated string into the target buffer. More...

static ssize_t	coap_get_uri_path (const coap_pkt_t pkt, uint8_t target)
	Convenience function for getting the packet's URI_PATH. More...

static ssize_t	coap_get_uri_query (const coap_pkt_t pkt, uint8_t target)
	Convenience function for getting the packet's URI_QUERY option. More...

static ssize_t	coap_get_location_path (const coap_pkt_t pkt, uint8_t target, size_t max_len)
	Convenience function for getting the packet's LOCATION_PATH option. More...

static ssize_t	coap_get_location_query (const coap_pkt_t pkt, uint8_t target, size_t max_len)
	Convenience function for getting the packet's LOCATION_QUERY option. More...

void	coap_block2_init (coap_pkt_t pkt, coap_block_slicer_t slicer)
	Initialize a block2 slicer struct for writing the payload. More...

void	coap_block2_finish (coap_block_slicer_t *slicer)
	Finish a block2 response. More...

ssize_t	coap_block2_build_reply (coap_pkt_t pkt, unsigned code, uint8_t rbuf, unsigned rlen, unsigned payload_len, coap_block_slicer_t *slicer)
	Build reply to CoAP block2 request. More...

size_t	coap_blockwise_put_char (coap_block_slicer_t slicer, uint8_t bufpos, char c)
	Add a single character to a block2 reply. More...

size_t	coap_blockwise_put_bytes (coap_block_slicer_t slicer, uint8_t bufpos, const uint8_t *c, size_t len)
	Add a byte array to a block2 reply. More...

static unsigned	coap_szx2size (unsigned szx)
	Helper to decode SZX value to size in bytes. More...

static unsigned	coap_get_ver (coap_pkt_t *pkt)
	Get the CoAP version number. More...

static unsigned	coap_get_type (coap_pkt_t *pkt)
	Get the message type. More...

static unsigned	coap_get_token_len (coap_pkt_t *pkt)
	Get a message's token length [in byte]. More...

static unsigned	coap_get_code_class (coap_pkt_t *pkt)
	Get a message's code class (3 most significant bits of code) More...

static unsigned	coap_get_code_detail (coap_pkt_t *pkt)
	Get a message's code detail (5 least significant bits of code) More...

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

static unsigned	coap_get_code (coap_pkt_t *pkt)
	Get a message's code in decimal format ((class * 100) + detail) More...

static unsigned	coap_get_id (coap_pkt_t *pkt)
	Get the message ID of the given CoAP packet. More...

static uint8_t *	coap_hdr_data_ptr (coap_hdr_t *hdr)
	Get the start of data after the header. More...

static unsigned	coap_get_total_hdr_len (coap_pkt_t *pkt)
	Get the total header length (4-byte header + token length) More...

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

static void	coap_hdr_set_code (coap_hdr_t *hdr, uint8_t code)
	Write the given raw message code to given CoAP header. More...

static void	coap_hdr_set_type (coap_hdr_t *hdr, unsigned type)
	Set the message type for the given CoAP header. More...

static unsigned	coap_method2flag (unsigned code)
	Convert message code (request method) into a corresponding bit field. More...

int	coap_match_path (const coap_resource_t resource, uint8_t uri)
	Checks if a CoAP resource path matches a given URI. More...

static bool	coap_has_observe (coap_pkt_t *pkt)
	Identifies a packet containing an observe option. More...

static void	coap_clear_observe (coap_pkt_t *pkt)
	Clears the observe option value from a packet. More...

static uint32_t	coap_get_observe (coap_pkt_t *pkt)
	Get the value of the observe option from the given packet. More...

ssize_t	coap_well_known_core_default_handler (coap_pkt_t pkt, uint8_t buf, size_t len, void *context)
	Reference to the default .well-known/core handler defined by the application.

Variables
const coap_resource_t	coap_resources []
	Global CoAP resource list.

const unsigned	coap_resources_numof
	Number of entries in global CoAP resource list.

Nanocoap specific CoAP method flags used in coap_handlers array
#define	COAP_GET (0x1)

#define	COAP_POST (0x2)

#define	COAP_PUT (0x4)

#define	COAP_DELETE (0x8)

#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_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 1186 of file nanocoap.h.

Function Documentation

◆ coap_block2_build_reply()

ssize_t coap_block2_build_reply	(	coap_pkt_t *	pkt,
		unsigned	code,
		uint8_t *	rbuf,
		unsigned	rlen,
		unsigned	payload_len,
		coap_block_slicer_t *	slicer
	)

Build reply to CoAP block2 request.

This function can be used to create a reply to a CoAP block2 request packet. In addition to coap_build_reply, this function checks the block2 option and returns an error message to the client if necessary.

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]	payload_len	length of payload
[in]	slicer	slicer to use

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

◆ coap_block2_finish()

void coap_block2_finish ( coap_block_slicer_t * slicer )

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 overwrites bytes in the packet, it doesn't add new bytes to the packet.

Parameters

[in,out] slicer Preallocated slicer struct to use

◆ 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_blockwise_put_bytes()

size_t coap_blockwise_put_bytes	(	coap_block_slicer_t *	slicer,
		uint8_t *	bufpos,
		const uint8_t *	c,
		size_t	len
	)

Add a byte array to a block2 reply.

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]	slicer	slicer to use
[in]	bufpos	pointer to the current payload buffer position
[in]	c	byte array to copy
[in]	len	length of the byte array

Returns: Number of bytes writen to bufpos

◆ coap_blockwise_put_char()

size_t coap_blockwise_put_char	(	coap_block_slicer_t *	slicer,
		uint8_t *	bufpos,
		char	c
	)

Add a single character to a block2 reply.

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]	slicer	slicer to use
[in]	bufpos	pointer to the current payload buffer position
[in]	c	character to write

Returns: Number of bytes writen to bufpos

◆ coap_build_hdr()

ssize_t coap_build_hdr	(	coap_hdr_t *	hdr,
		unsigned	type,
		uint8_t *	token,
		size_t	token_len,
		unsigned	code,
		uint16_t	id
	)

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

Returns: length of resulting header

◆ coap_build_reply()

ssize_t coap_build_reply	(	coap_pkt_t *	pkt,
		unsigned	code,
		uint8_t *	rbuf,
		unsigned	rlen,
		unsigned	payload_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 payload_len will ensure the payload fits into the buffer along with the header. For this validation, payload_len must include any 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]	payload_len	length of payload

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

◆ 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 1157 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 1076 of file nanocoap.h.

◆ coap_get_block1()

int coap_get_block1	(	coap_pkt_t *	pkt,
		coap_block1_t *	block1
	)

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]	block1	ptr to preallocated coap_block1_t structure

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

◆ coap_get_block2()

int coap_get_block2	(	coap_pkt_t *	pkt,
		coap_block1_t *	block2
	)

Block2 option getter.

Parameters

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

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

◆ coap_get_blockopt()

int coap_get_blockopt	(	coap_pkt_t *	pkt,
		uint16_t	option,
		uint32_t *	blknum,
		unsigned *	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()

static unsigned coap_get_code ( 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 1027 of file nanocoap.h.

◆ coap_get_code_class()

static unsigned coap_get_code_class ( 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 991 of file nanocoap.h.

◆ coap_get_code_detail()

static unsigned coap_get_code_detail ( 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 1003 of file nanocoap.h.

◆ coap_get_code_raw()

static unsigned coap_get_code_raw ( 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 1015 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 ( coap_pkt_t * pkt )

inlinestatic

Get the message ID of the given CoAP packet.

Parameters

[in] pkt CoAP packet

Returns: message ID

Definition at line 1039 of file nanocoap.h.

◆ coap_get_location_path()

static ssize_t coap_get_location_path	(	const coap_pkt_t *	pkt,
		uint8_t *	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 827 of file nanocoap.h.

◆ coap_get_location_query()

static ssize_t coap_get_location_query	(	const coap_pkt_t *	pkt,
		uint8_t *	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 849 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 1169 of file nanocoap.h.

◆ coap_get_token_len()

static unsigned coap_get_token_len ( coap_pkt_t * pkt )

inlinestatic

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

Parameters

[in] pkt CoAP packet

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

Definition at line 979 of file nanocoap.h.

◆ coap_get_total_hdr_len()

static unsigned coap_get_total_hdr_len ( 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 1063 of file nanocoap.h.

◆ coap_get_type()

static unsigned coap_get_type ( 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 967 of file nanocoap.h.

◆ coap_get_uri_path()

static ssize_t coap_get_uri_path	(	const coap_pkt_t *	pkt,
		uint8_t *	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 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 NANOCOAP_URI_MAX; nr of bytes written to target (including '\0')

Definition at line 786 of file nanocoap.h.

◆ coap_get_uri_query()

static ssize_t coap_get_uri_query	(	const coap_pkt_t *	pkt,
		uint8_t *	target
	)

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.

Caller must ensure target can hold at least 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 NANOCOAP_URI_MAX; nr of bytes written to target (including '\0')

Definition at line 806 of file nanocoap.h.

◆ coap_get_ver()

static unsigned coap_get_ver ( coap_pkt_t * pkt )

inlinestatic

Get the CoAP version number.

Parameters

[in] pkt CoAP packet

Returns: CoAP version number

Definition at line 952 of file nanocoap.h.

◆ coap_handle_req()

ssize_t coap_handle_req	(	coap_pkt_t *	pkt,
		uint8_t *	resp_buf,
		unsigned	resp_buf_len
	)

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

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 1147 of file nanocoap.h.

◆ coap_hdr_data_ptr()

static uint8_t* coap_hdr_data_ptr ( coap_hdr_t * hdr )

inlinestatic

Get the start of data after the header.

Parameters

[in] hdr Header of CoAP packet in contiguous memory

Returns: pointer to first byte after the header

Definition at line 1051 of file nanocoap.h.

◆ coap_hdr_set_code()

static void coap_hdr_set_code	(	coap_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

Definition at line 1087 of file nanocoap.h.

◆ coap_hdr_set_type()

static void coap_hdr_set_type	(	coap_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]

Definition at line 1100 of file nanocoap.h.

◆ coap_match_path()

int coap_match_path	(	const coap_resource_t *	resource,
		uint8_t *	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 unsigned 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 1116 of file nanocoap.h.

◆ 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 706 of file nanocoap.h.

◆ coap_opt_add_opaque()

ssize_t coap_opt_add_opaque	(	coap_pkt_t *	pkt,
		uint16_t	optnum,
		const uint8_t *	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_string()

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.

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

◆ 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_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_string()

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

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

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_put_block2()

size_t coap_opt_put_block2	(	uint8_t *	buf,
		uint16_t	lastonum,
		coap_block_slicer_t *	slicer,
		bool	more
	)

Insert block2 option into buffer.

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

Parameters

[out]	buf	buffer to write to
[in]	lastonum	number of previous option (for delta calculation), must be < 23
[in]	slicer	coap blockwise slicer helper struct
[in]	more	more flag (1 or 0)

Returns: amount of bytes written to buf

◆ coap_opt_put_location_path()

static size_t coap_opt_put_location_path	(	uint8_t *	buf,
		uint16_t	lastonum,
		const char *	location
	)

inlinestatic

Convenience function for inserting LOCATION_PATH option into buffer.

Parameters

[out]	buf	buffer to write to
[in]	lastonum	number of previous option (for delta calculation), or 0 if first option
[in]	location	ptr to string holding the location

Returns: amount of bytes written to buf

Definition at line 538 of file nanocoap.h.

◆ coap_opt_put_location_query()

static size_t coap_opt_put_location_query	(	uint8_t *	buf,
		uint16_t	lastonum,
		const char *	location
	)

inlinestatic

Convenience function for inserting LOCATION_QUERY option into buffer.

Parameters

[out]	buf	buffer to write to
[in]	lastonum	number of previous option (for delta calculation), or 0 if first option
[in]	location	ptr to string holding the location

Returns: amount of bytes written to buf

Definition at line 556 of file nanocoap.h.

◆ coap_opt_put_string()

size_t coap_opt_put_string	(	uint8_t *	buf,
		uint16_t	lastonum,
		uint16_t	optnum,
		const char *	string,
		char	separator
	)

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

Parameters

[out]	buf	buffer to write to
[in]	lastonum	number of previous option (for delta calculation), or 0 if first option
[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 buf

◆ coap_opt_put_uri_path()

static size_t coap_opt_put_uri_path	(	uint8_t *	buf,
		uint16_t	lastonum,
		const char *	uri
	)

inlinestatic

Convenience function for inserting URI_PATH option into buffer.

Parameters

[out]	buf	buffer to write to
[in]	lastonum	number of previous option (for delta calculation), or 0 if first option
[in]	uri	ptr to source URI

Returns: amount of bytes written to buf

Definition at line 506 of file nanocoap.h.

◆ coap_opt_put_uri_query()

static size_t coap_opt_put_uri_query	(	uint8_t *	buf,
		uint16_t	lastonum,
		const char *	uri
	)

inlinestatic

Convenience function for inserting URI_QUERY option into buffer.

Parameters

[out]	buf	buffer to write to
[in]	lastonum	number of previous option (for delta calculation), or 0 if first option
[in]	uri	ptr to source URI

Returns: amount of bytes written to buf

Definition at line 522 of file nanocoap.h.

◆ coap_parse()

int coap_parse	(	coap_pkt_t *	pkt,
		uint8_t *	buf,
		size_t	len
	)

Parse a CoAP PDU.

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: 0 on success; <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_put_block1_ok()

size_t coap_put_block1_ok	(	uint8_t *	pkt_pos,
		coap_block1_t *	block1,
		uint16_t	lastonum
	)

Insert block1 option into buffer (from coap_block1_t)

This function is wrapper around coap_put_option_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]	pkt_pos	buffer to write to
[in]	block1	ptr to block1 struct (created by coap_get_block1())
[in]	lastonum	last option number (must be < 27)

Returns: amount of bytes written to pkt_pos

◆ coap_put_option()

size_t coap_put_option	(	uint8_t *	buf,
		uint16_t	lastonum,
		uint16_t	onum,
		const uint8_t *	odata,
		size_t	olen
	)

Insert a CoAP option into buffer.

This function writes a CoAP option with nr. onum to buf. It handles calculating the option delta (from lastonum), encoding the length from olen and copying the option data from odata.

Parameters

[out]	buf	buffer to write to
[in]	lastonum	number of previous option (for delta calculation), or 0 for first option
[in]	onum	number of option
[in]	odata	ptr to raw option data (or NULL)
[in]	olen	length of `odata` (if any)

Returns: amount of bytes written to buf

◆ coap_put_option_block1()

size_t coap_put_option_block1	(	uint8_t *	buf,
		uint16_t	lastonum,
		unsigned	blknum,
		unsigned	szx,
		int	more
	)

Insert block1 option into buffer.

Parameters

[out]	buf	buffer to write to
[in]	lastonum	number of previous option (for delta calculation), must be < 27
[in]	blknum	block number
[in]	szx	SXZ value
[in]	more	more flag (1 or 0)

Returns: amount of bytes written to buf

◆ coap_put_option_ct()

size_t coap_put_option_ct	(	uint8_t *	buf,
		uint16_t	lastonum,
		uint16_t	content_type
	)

Insert content type option into buffer.

Parameters

[out]	buf	buffer to write to
[in]	lastonum	number of previous option (for delta calculation), or 0 if first option
[in]	content_type	content type to set

Returns: amount of bytes written to buf

◆ coap_reply_simple()

ssize_t coap_reply_simple	(	coap_pkt_t *	pkt,
		unsigned	code,
		uint8_t *	buf,
		size_t	len,
		unsigned	ct,
		const uint8_t *	payload,
		uint8_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
[in]	payload	ptr to payload
[in]	payload_len	length of payload

Returns: size of reply packet on success; <0 on error; -ENOSPC if buf too small

◆ coap_szx2size()

static unsigned coap_szx2size ( unsigned szx )

inlinestatic

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 940 of file nanocoap.h.

Detailed Description

Server Operation

Path matching

Handler functions

Client Operation

Write Options and Payload

Minimal API

Struct-based API

Create a Block-wise Response (Block2)

Modules

Files

Data Structures

Macros

Typedefs

Functions

Variables

Nanocoap specific CoAP method flags used in coap_handlers array

coap_opt_finish() flag parameter values

Macro Definition Documentation

◆ COAP_WELL_KNOWN_CORE_DEFAULT_HANDLER

Function Documentation

◆ coap_block2_build_reply()

◆ coap_block2_finish()

◆ coap_block2_init()

◆ coap_blockwise_put_bytes()

◆ coap_blockwise_put_char()

◆ coap_build_hdr()

◆ coap_build_reply()

◆ coap_clear_observe()

◆ coap_code()

◆ coap_get_block1()

◆ coap_get_block2()

◆ coap_get_blockopt()

◆ coap_get_code()

◆ coap_get_code_class()

◆ coap_get_code_detail()

◆ coap_get_code_raw()

◆ coap_get_content_type()

◆ coap_get_id()

◆ coap_get_location_path()

◆ coap_get_location_query()

◆ coap_get_observe()

◆ coap_get_token_len()

◆ coap_get_total_hdr_len()

◆ coap_get_type()

◆ coap_get_uri_path()

◆ coap_get_uri_query()

◆ coap_get_ver()

◆ coap_handle_req()

◆ coap_has_observe()

◆ coap_hdr_data_ptr()

◆ coap_hdr_set_code()

◆ coap_hdr_set_type()

◆ coap_match_path()

◆ coap_method2flag()

◆ coap_opt_add_format()

◆ coap_opt_add_opaque()

◆ coap_opt_add_string()

◆ coap_opt_add_uint()

◆ coap_opt_finish()

◆ coap_opt_get_string()

◆ coap_opt_put_block2()

◆ coap_opt_put_location_path()

◆ coap_opt_put_location_query()

◆ coap_opt_put_string()

◆ coap_opt_put_uri_path()

◆ coap_opt_put_uri_query()

◆ coap_parse()

◆ coap_pkt_init()

◆ coap_put_block1_ok()

◆ coap_put_option()

◆ coap_put_option_block1()

◆ coap_put_option_ct()

◆ coap_reply_simple()

◆ coap_szx2size()