Nanocoap small CoAP library

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

Modules

 Nanocoap compile configurations
 
 Nanocoap-Cache implementation
 A cache implementation for nanocoap response messages.
 

Files

file  nanocoap.h
 nanocoap 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_resource_subtree_t
 Type for CoAP resource subtrees. More...
 
struct  _coap_request_ctx
 CoAP resource request handler context. More...
 
struct  coap_block1_t
 Block1 helper struct. More...
 
struct  coap_block_slicer_t
 Blockwise transfer helper struct. More...
 

Macros

#define COAP_FORMAT_NONE   (UINT16_MAX)
 Nanocoap-specific value to indicate no format specified.
 
#define CONFIG_NANOCOAP_BLOCK_HEADER_MAX   (80)
 Maximum length of a CoAP header for a blockwise message. More...
 
#define COAP_WELL_KNOWN_CORE_DEFAULT_HANDLER
 Resource definition for the default .well-known/core handler. More...
 

Typedefs

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

Functions

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

Variables

const coap_resource_t coap_resources []
 Global CoAP resource list.
 
const unsigned coap_resources_numof
 Number of entries in global CoAP resource list.
 

Functions – Header Read/Write

Includes message ID, code, type, token, CoAP version

static uint8_t coap_code (unsigned cls, unsigned detail)
 Encode given code class and code detail to raw code. More...
 
static unsigned coap_get_code_class (const coap_pkt_t *pkt)
 Get a message's code class (3 most significant bits of code) More...
 
static unsigned coap_get_code_detail (const coap_pkt_t *pkt)
 Get a message's code detail (5 least significant bits of code) More...
 
static unsigned coap_get_code (const coap_pkt_t *pkt)
 Get a message's code in decimal format ((class * 100) + detail) More...
 
static unsigned coap_get_code_raw (const coap_pkt_t *pkt)
 Get a message's raw code (class + detail) More...
 
static unsigned coap_get_id (const coap_pkt_t *pkt)
 Get the message ID of the given CoAP packet. More...
 
static unsigned coap_get_token_len (const coap_pkt_t *pkt)
 Get a message's token length [in byte]. More...
 
static void * coap_get_token (const coap_pkt_t *pkt)
 Get pointer to a message's token. More...
 
static unsigned coap_get_total_hdr_len (const coap_pkt_t *pkt)
 Get the total header length (4-byte header + token length) More...
 
static unsigned coap_get_total_len (const coap_pkt_t *pkt)
 Get the total length of a CoAP packet in the packet buffer. More...
 
static unsigned coap_get_type (const coap_pkt_t *pkt)
 Get the message type. More...
 
static unsigned coap_get_ver (const coap_pkt_t *pkt)
 Get the CoAP version number. More...
 
static uint8_t * coap_hdr_data_ptr (const coap_hdr_t *hdr)
 Get the start of data after the header. 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...
 

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. More...
 
unsigned coap_get_content_type (coap_pkt_t *pkt)
 Get content type from packet. More...
 
unsigned coap_get_accept (coap_pkt_t *pkt)
 Get the Accept option value from a packet if present. More...
 
int coap_opt_get_uint (coap_pkt_t *pkt, uint16_t optnum, uint32_t *value)
 Get a uint32 option value. More...
 
ssize_t coap_opt_get_string (coap_pkt_t *pkt, uint16_t optnum, uint8_t *target, size_t max_len, char separator)
 Read a full option as null terminated string into the target buffer. More...
 
static ssize_t coap_get_location_path (coap_pkt_t *pkt, uint8_t *target, size_t max_len)
 Convenience function for getting the packet's LOCATION_PATH option. More...
 
static ssize_t coap_get_location_query (coap_pkt_t *pkt, uint8_t *target, size_t max_len)
 Convenience function for getting the packet's LOCATION_QUERY option. More...
 
static ssize_t coap_get_uri_path (coap_pkt_t *pkt, uint8_t *target)
 Convenience function for getting the packet's URI_PATH. More...
 
static ssize_t coap_get_uri_query (coap_pkt_t *pkt, uint8_t *target)
 Convenience function for getting the packet's URI_QUERY option. More...
 
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. More...
 
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. More...
 

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. More...
 
bool coap_block_finish (coap_block_slicer_t *slicer, uint16_t option)
 Finish a block request (block1 or block2) More...
 
static bool coap_block1_finish (coap_block_slicer_t *slicer)
 Finish a block1 request. More...
 
static bool coap_block2_finish (coap_block_slicer_t *slicer)
 Finish a block2 response. 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_block_slicer_init (coap_block_slicer_t *slicer, size_t blknum, size_t blksize)
 Initialize a block slicer struct from content information. More...
 
size_t coap_blockwise_put_bytes (coap_block_slicer_t *slicer, uint8_t *bufpos, const void *c, size_t len)
 Add a byte array to a block2 reply. 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...
 
int coap_get_block (coap_pkt_t *pkt, coap_block1_t *block, uint16_t option)
 Block option getter. More...
 
static int coap_get_block1 (coap_pkt_t *pkt, coap_block1_t *block)
 Block1 option getter. More...
 
static int coap_get_block2 (coap_pkt_t *pkt, coap_block1_t *block)
 Block2 option getter. More...
 
int coap_get_blockopt (coap_pkt_t *pkt, uint16_t option, uint32_t *blknum, uint8_t *szx)
 Generic block option getter. More...
 
bool coap_has_unprocessed_critical_options (const coap_pkt_t *pkt)
 Check whether any of the packet's options that are critical. More...
 
static unsigned coap_szx2size (unsigned szx)
 Helper to decode SZX value to size in bytes. More...
 
static unsigned coap_size2szx (unsigned len)
 Helper to encode byte size into next equal or smaller SZX value. More...
 

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. More...
 
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. More...
 
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. 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_block1_control (coap_pkt_t *pkt, coap_block1_t *block)
 Encode the given block1 option in control use. More...
 
static ssize_t coap_opt_add_block2_control (coap_pkt_t *pkt, coap_block1_t *block)
 Encode the given block2 option in control use. More...
 
static ssize_t coap_opt_add_accept (coap_pkt_t *pkt, uint16_t format)
 Append an Accept option to the pkt buffer. 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_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. More...
 
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. More...
 
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. More...
 
ssize_t coap_opt_add_proxy_uri (coap_pkt_t *pkt, const char *uri)
 Adds a single Proxy-URI option into pkt. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
ssize_t coap_opt_finish (coap_pkt_t *pkt, uint16_t flags)
 Finalizes options as required and prepares for payload. More...
 
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. More...
 

Functions – Options Write Buffer API

Write PDU Options directly to the array of bytes for a message.

The caller must provide the last option number written as well as the buffer position. The caller is primarily responsible for tracking and managing the space remaining in the buffer.

size_t coap_opt_put_block (uint8_t *buf, uint16_t lastonum, coap_block_slicer_t *slicer, bool more, uint16_t option)
 Insert block option into buffer. More...
 
static size_t coap_opt_put_block1 (uint8_t *buf, uint16_t lastonum, coap_block_slicer_t *slicer, bool more)
 Insert block1 option into buffer. More...
 
static size_t coap_opt_put_block2 (uint8_t *buf, uint16_t lastonum, coap_block_slicer_t *slicer, bool more)
 Insert block2 option into buffer. More...
 
size_t coap_opt_put_uint (uint8_t *buf, uint16_t lastonum, uint16_t onum, uint32_t value)
 Encode the given uint option into buffer. More...
 
static size_t coap_opt_put_block1_control (uint8_t *buf, uint16_t lastonum, coap_block1_t *block)
 Insert block1 option into buffer in control usage. More...
 
static size_t coap_opt_put_block2_control (uint8_t *buf, uint16_t lastonum, coap_block1_t *block)
 Insert block2 option into buffer in control usage. More...
 
size_t coap_opt_put_string_with_len (uint8_t *buf, uint16_t lastonum, uint16_t optnum, const char *string, size_t len, char separator)
 Encode the given string as multi-part option into buffer. More...
 
static size_t coap_opt_put_string (uint8_t *buf, uint16_t lastonum, uint16_t optnum, const char *string, char separator)
 Encode the given string as multi-part option into buffer. 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...
 
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...
 
size_t coap_opt_put_uri_pathquery (uint8_t *buf, uint16_t *lastonum, const char *uri)
 Convenience function for inserting URI_PATH and URI_QUERY into buffer This function will automatically split path and query parameters. More...
 
static size_t coap_opt_put_proxy_uri (uint8_t *buf, uint16_t lastonum, const char *uri)
 Convenience function for inserting PROXY_URI option into buffer. 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...
 
size_t coap_put_option (uint8_t *buf, uint16_t lastonum, uint16_t onum, const void *odata, size_t olen)
 Insert a CoAP option into buffer. More...
 
static size_t coap_put_option_block1 (uint8_t *buf, uint16_t lastonum, unsigned blknum, unsigned szx, int more)
 Insert block1 option into buffer. More...
 
static size_t coap_put_option_ct (uint8_t *buf, uint16_t lastonum, uint16_t content_type)
 Insert content type option into buffer. More...
 

Functions – Messaging

Functions to support sending and receiving messages.

ssize_t coap_block2_build_reply (coap_pkt_t *pkt, unsigned code, uint8_t *rbuf, unsigned rlen, unsigned payload_len, coap_block_slicer_t *slicer)
 Build reply to CoAP block2 request. 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...
 
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_handle_req (coap_pkt_t *pkt, uint8_t *resp_buf, unsigned resp_buf_len, coap_request_ctx_t *ctx)
 Handle incoming CoAP request. More...
 
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. More...
 
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. More...
 
static coap_method_flags_t coap_method2flag (unsigned code)
 Convert message code (request method) into a corresponding bit field. More...
 
int coap_parse (coap_pkt_t *pkt, uint8_t *buf, size_t len)
 Parse a CoAP PDU. 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...
 
static void coap_payload_advance_bytes (coap_pkt_t *pkt, size_t len)
 Advance the payload pointer. More...
 
ssize_t coap_payload_put_bytes (coap_pkt_t *pkt, const void *data, size_t len)
 Add payload data to the CoAP request. More...
 
ssize_t coap_payload_put_char (coap_pkt_t *pkt, char c)
 Add a single character to the payload data of the CoAP request. More...
 
ssize_t coap_reply_simple (coap_pkt_t *pkt, unsigned code, uint8_t *buf, size_t len, unsigned ct, const void *payload, size_t payload_len)
 Create CoAP reply (convenience function) More...
 
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. 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...
 

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_WELL_KNOWN_CORE_DEFAULT_HANDLER

#define COAP_WELL_KNOWN_CORE_DEFAULT_HANDLER
Value:
{ \
.path = "/.well-known/core", \
.methods = COAP_GET, \
}
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.

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

Definition at line 2116 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 177 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]argPointer to be passed as arguments to the callback
[in]offsetOffset of received data
[in]bufPointer to the received data
[in]lenLength 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 281 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]pktThe request packet
[out]bufBuffer for the response
[in]lenSize of the response buffer
[in]contextRequest context
Returns
Number of response bytes written on success Negative error on failure

Definition at line 266 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 300 of file nanocoap.h.

◆ coap_request_cb_t

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

Coap equest callback descriptor.

Parameters
[in]argPointer to be passed as arguments to the callback
[in]pktThe received CoAP response. Buffers point to network stack internal memory.
Returns
>=0 on success
<0 on error

Definition at line 293 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]slicerPreallocated slicer struct to use
Returns
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 897 of file nanocoap.h.

◆ 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]pktpacket to reply to
[in]codereply code (e.g., COAP_CODE_204)
[out]rbufbuffer to write reply to
[in]rlensize of rbuf
[in]payload_lenlength of payload
[in]slicerslicer to use
Returns
size of reply packet on success
<0 on error

◆ 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]slicerPreallocated slicer struct to use
Returns
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 916 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]pktpacket to work on
[out]slicerPreallocated slicer struct to fill

◆ coap_block_finish()

bool coap_block_finish ( coap_block_slicer_t slicer,
uint16_t  option 
)

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]slicerPreallocated slicer struct to use
[in]optionoption number (block1 or block2)
Returns
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]blockblock struct to initialize
[in]blknumoffset from the beginning of content, in terms of blksize byte blocks
[in]blksizesize of each block; must be a power of 2 between 16 and 2 raised to CONFIG_NANOCOAP_BLOCK_SIZE_EXP_MAX
[in]moremore 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]slicerslicer struct to initialize
[in]blknumoffset from the beginning of content, in terms of blksize byte blocks
[in]blksizesize 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()

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

Add a byte array to a block2 reply.

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]slicerslicer to use
[in]bufpospointer to the current payload buffer position
[in]cbyte array to copy
[in]lenlength of the byte array
Returns
Number of bytes written 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]slicerslicer to use
[in]bufpospointer to the current payload buffer position
[in]ccharacter to write
Returns
Number of bytes written 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]hdrhdr to fill
[in]typeCoAP packet type (e.g., COAP_TYPE_CON, ...)
[in]tokentoken
[in]token_lenlength of token
[in]codeCoAP code (e.g., COAP_CODE_204, ...)
[in]idCoAP 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]pktpacket to reply to
[in]codereply code (e.g., COAP_CODE_204)
[out]rbufbuffer to write reply to
[in]rlensize of rbuf
[in]payload_lenlength of payload
Returns
size of reply packet on success
         Note that this size can be severely shortened if due to a No-Response option there
         is only an empty ACK to be sent back. The caller may just continue populating the
         payload (the space was checked to suffice), but may also skip that needless step
         if the returned length is less than the requested payload length.
0 if no response should be sent due to a No-Response option in the request
<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]pktCoAP packet

Definition at line 2094 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]clsmessage code class
[in]detailmessage code detail
Returns
raw message code

Definition at line 429 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]pktpacket to work on
[in]opt_numthe option number to search for
Returns
pointer to the option data NULL if option number was not found

◆ coap_get_accept()

unsigned coap_get_accept ( coap_pkt_t pkt)

Get the Accept option value from a packet if present.

Parameters
[in]pktpacket 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]pktpkt to work on
[out]blockptr to preallocated coap_block1_t structure
[in]optionblock1 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]pktpkt to work on
[out]blockptr to preallocated coap_block1_t structure
Returns
0 if block1 option not present
1 if structure has been filled

Definition at line 1013 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]pktpkt to work on
[out]blockptr to preallocated coap_block1_t structure
Returns
0 if block2 option not present
1 if structure has been filled

Definition at line 1027 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]pktpkt to work on
[in]optionactual block option number to get
[out]blknumblock number
[out]szxSZX 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 ( const coap_pkt_t pkt)
inlinestatic

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

Parameters
[in]pktCoAP packet
Returns
message code in decimal format

Definition at line 465 of file nanocoap.h.

◆ 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]pktCoAP packet
Returns
message code class

Definition at line 441 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]pktCoAP packet
Returns
message code detail

Definition at line 453 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]pktCoAP packet
Returns
raw message code

Definition at line 477 of file nanocoap.h.

◆ coap_get_content_type()

unsigned coap_get_content_type ( coap_pkt_t pkt)

Get content type from packet.

Parameters
[in]pktpacket 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]pktCoAP packet
Returns
message ID

Definition at line 489 of file nanocoap.h.

◆ coap_get_location_path()

static ssize_t coap_get_location_path ( 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]pktpkt to work on
[out]targetbuffer for location path
[in]max_lensize 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 709 of file nanocoap.h.

◆ coap_get_location_query()

static ssize_t coap_get_location_query ( 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]pktpkt to work on
[out]targetbuffer for location path
[in]max_lensize 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 731 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]pktCoAP packet
Returns
value of the observe option

Definition at line 2106 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]pktpkt to work on
[out]targetpointer 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 841 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]pktCoAP packet
Returns
pointer to the token position

Definition at line 513 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].

Parameters
[in]pktCoAP packet
Returns
length of token in the given message (0-8 byte)

Definition at line 501 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]pktCoAP packet
Returns
total header length

Definition at line 525 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]pktCoAP packet
Returns
total CoAP length

Definition at line 539 of file nanocoap.h.

◆ coap_get_type()

static unsigned coap_get_type ( const coap_pkt_t pkt)
inlinestatic

Get the message type.

Parameters
[in]pktCoAP packet
Returns
COAP_TYPE_CON
COAP_TYPE_NON
COAP_TYPE_ACK
COAP_TYPE_RST

Definition at line 554 of file nanocoap.h.

◆ coap_get_uri_path()

static ssize_t coap_get_uri_path ( 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 CONFIG_NANOCOAP_URI_MAX bytes!

Parameters
[in]pktpkt to work on
[out]targetbuffer 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 752 of file nanocoap.h.

◆ coap_get_uri_query()

static ssize_t coap_get_uri_query ( 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 CONFIG_NANOCOAP_URI_MAX bytes!

Parameters
[in]pktpkt to work on
[out]targetbuffer 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 772 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]pktCoAP packet
Returns
CoAP version number

Definition at line 566 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]pktpointer to (parsed) CoAP packet
[out]resp_bufbuffer for response
[in]resp_buf_lensize of response buffer
[in]ctxCoAP 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]pktCoAP packet
Returns
true if observe value is set
false if not

Definition at line 2084 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]pktpkt 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_hdr_t hdr)
inlinestatic

Get the start of data after the header.

Parameters
[in]hdrHeader of CoAP packet in contiguous memory
Returns
pointer to first byte after the header

Definition at line 578 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]hdrCoAP header to write to
[in]coderaw message code

Definition at line 589 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]hdrCoAP header to write
[in]typemessage type as integer value [0-3]

Definition at line 602 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 coap_method_flags_t coap_method2flag ( unsigned  code)
inlinestatic

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

Parameters
[in]coderequest code denoting the request method
Returns
bit field corresponding to the given request method

Definition at line 1924 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]pktpkt referencing target buffer
[in]formatCOAP_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 1237 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]pktpkt referencing target buffer
[in]slicercoap blockwise slicer helper struct
[in]moremore flag (1 or 0)
[in]optionoption 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]pktpkt referencing target buffer
[in]slicercoap blockwise slicer helper struct
[in]moremore 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 1142 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]pktpkt referencing target buffer
[in]blockblock to encode
Returns
number of bytes written to buffer
<0 on error
-ENOSPC if no available options or insufficient buffer space

Definition at line 1200 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]pktpkt referencing target buffer
[in]slicercoap blockwise slicer helper struct
[in]moremore 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 1166 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]pktpkt referencing target buffer
[in]blockblock to encode
Returns
number of bytes written to buffer
<0 on error
-ENOSPC if no available options or insufficient buffer space

Definition at line 1218 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]pktpkt referencing target buffer
[in]optnumoption number to use
[in]charsarray of characters to encode as option
[in]chars_lenlength of chars
[in]separatorcharacter 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]pktpkt referencing target buffer
[in]formatCOAP_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 1255 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]pktpkt referencing target buffer
[in]optnumoption number to use
[in]valpointer to the value to be set
[in]val_lenlength 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]pktPacket being built
[in]uriabsolute 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]pktpkt referencing target buffer
[in]optnumoption number to use
[in]stringstring to encode as option
[in]separatorcharacter 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 1373 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]pktpkt referencing target buffer
[in]optnumoption number to use
[in]valueuint 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]pktPacket 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 1393 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]pktPacket being built
[in]pathResource (sub)path
[in]path_lenLength 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 1413 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]pktPacket being built
[in]keyKey to add to the query string
[in]valValue 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 1313 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]pktPacket being built
[in]keyKey to add to the query string
[in]key_lenLength of key
[in]valValue to assign to key (may be NULL)
[in]val_lenLength 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]pktpkt to update
[in]flagssee 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]pktpacket to read from
[in,out]optoption attributes; read on input if init_opt is false
[out]valuestart of the option value
[in]init_opttrue 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]pktpacket to read from
[in]opt_numoption number to retrieve
[out]valuestart 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,
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]pktpacket to read from
[in]optnumabsolute option number
[out]targettarget buffer
[in]max_lensize of target
[in]separatorcharacter 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]pktpacket to read from
[in]optnumabsolute option number
[out]valuethe 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_block()

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

Insert block option into buffer.

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.

Parameters
[out]bufbuffer to write to
[in]lastonumnumber of previous option, must be < option
[in]slicercoap blockwise slicer helper struct
[in]moremore flag (1 or 0)
[in]optionoption number (block1 or block2)
Returns
amount of bytes written to buf

◆ coap_opt_put_block1()

static size_t coap_opt_put_block1 ( uint8_t *  buf,
uint16_t  lastonum,
coap_block_slicer_t slicer,
bool  more 
)
inlinestatic

Insert block1 option into buffer.

When calling this function to initialize a packet with a block1 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]bufbuffer to write to
[in]lastonumnumber of previous option (for delta calculation), must be < 27
[in]slicercoap blockwise slicer helper struct
[in]moremore flag (1 or 0)
Returns
amount of bytes written to buf

Definition at line 1497 of file nanocoap.h.

◆ coap_opt_put_block1_control()

static size_t coap_opt_put_block1_control ( uint8_t *  buf,
uint16_t  lastonum,
coap_block1_t block 
)
inlinestatic

Insert block1 option into buffer in control usage.

Parameters
[in]bufbuffer to write to
[in]lastonumlast option number (must be < 27)
[in]blockblock option attribute struct
Returns
amount of bytes written to buf

Definition at line 1547 of file nanocoap.h.

◆ coap_opt_put_block2()

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

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]bufbuffer to write to
[in]lastonumnumber of previous option (for delta calculation), must be < 23
[in]slicercoap blockwise slicer helper struct
[in]moremore flag (1 or 0)
Returns
amount of bytes written to buf

Definition at line 1518 of file nanocoap.h.

◆ coap_opt_put_block2_control()

static size_t coap_opt_put_block2_control ( uint8_t *  buf,
uint16_t  lastonum,
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]bufbuffer to write to
[in]lastonumlast option number (must be < 27)
[in]blockblock option attribute struct
Returns
amount of bytes written to buf

Definition at line 1565 of file nanocoap.h.

◆ 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]bufbuffer to write to
[in]lastonumnumber of previous option (for delta calculation), or 0 if first option
[in]locationptr to string holding the location
Returns
amount of bytes written to buf

Definition at line 1618 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]bufbuffer to write to
[in]lastonumnumber of previous option (for delta calculation), or 0 if first option
[in]locationptr to string holding the location
Returns
amount of bytes written to buf

Definition at line 1636 of file nanocoap.h.

◆ coap_opt_put_proxy_uri()

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

Convenience function for inserting PROXY_URI option into buffer.

Parameters
[out]bufbuffer to write to
[in]lastonumnumber of previous option (for delta calculation), or 0 if first option
[in]uriptr to source URI
Returns
amount of bytes written to buf

Definition at line 1705 of file nanocoap.h.

◆ coap_opt_put_string()

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

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

Parameters
[out]bufbuffer to write to
[in]lastonumnumber of previous option (for delta calculation), or 0 if first option
[in]optnumoption number to use
[in]stringstring to encode as option
[in]separatorcharacter used in string to separate parts
Returns
number of bytes written to buf

Definition at line 1600 of file nanocoap.h.

◆ coap_opt_put_string_with_len()

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

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

Parameters
[out]bufbuffer to write to
[in]lastonumnumber of previous option (for delta calculation), or 0 if first option
[in]optnumoption number to use
[in]stringstring to encode as option
[in]lenlength of the string
[in]separatorcharacter used in string to separate parts
Returns
number of bytes written to buf

◆ coap_opt_put_uint()

size_t coap_opt_put_uint ( uint8_t *  buf,
uint16_t  lastonum,
uint16_t  onum,
uint32_t  value 
)

Encode the given uint option into buffer.

Parameters
[out]bufbuffer to write to
[in]lastonumnumber of previous option (for delta calculation), or 0 for first option
[in]onumnumber of option
[in]valuevalue to encode
Returns
amount 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]bufbuffer to write to
[in]lastonumnumber of previous option (for delta calculation), or 0 if first option
[in]uriptr to source URI
Returns
amount of bytes written to buf

Definition at line 1654 of file nanocoap.h.

◆ coap_opt_put_uri_pathquery()

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

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

Parameters
[out]bufbuffer to write to
[in,out]lastonumnumber of previous option (for delta calculation), or 0 if first option
[in]uriptr into a source URI, to the first character after the authority component
Returns
amount of bytes written to buf

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.

◆ 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]bufbuffer to write to
[in]lastonumnumber of previous option (for delta calculation), or 0 if first option
[in]uriptr to source URI
Returns
amount of bytes written to buf

Definition at line 1670 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]pktPacket to remove option from.
[in]optnumOption 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()

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]pktstructure to parse into
[in]bufpointer to raw packet data
[in]lenlength of packet at buf
Returns
0 on success
<0 on 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]pktpkt to which payload was added
[in]lenlength of payload

Definition at line 1974 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]pktpkt to add payload to
[in]datapayload data
[in]lenlength 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]pktpkt to add payload to
[in]ccharacter 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]pktpkt to initialize
[in]bufbuffer to write for pkt, with CoAP header already initialized
[in]lenlength of buf
[in]header_lenlength 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_posbuffer to write to
[in]block1ptr to block1 struct (created by coap_get_block1())
[in]lastonumlast 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 void *  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]bufbuffer to write to
[in]lastonumnumber of previous option (for delta calculation), or 0 for first option
[in]onumnumber of option
[in]odataptr to raw option data (or NULL)
[in]olenlength of odata (if any)
Returns
amount of bytes written to buf

◆ coap_put_option_block1()

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

Insert block1 option into buffer.

Parameters
[out]bufbuffer to write to
[in]lastonumnumber of previous option (for delta calculation), must be < 27
[in]blknumblock number
[in]szxSXZ value
[in]moremore flag (1 or 0)
Returns
amount of bytes written to buf

Definition at line 1760 of file nanocoap.h.

◆ coap_put_option_ct()

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

Insert content type option into buffer.

Parameters
[out]bufbuffer to write to
[in]lastonumnumber of previous option (for delta calculation), or 0 if first option
[in]content_typecontent type to set
Returns
amount of bytes written to buf

Definition at line 1777 of file nanocoap.h.

◆ coap_reply_simple()

ssize_t coap_reply_simple ( coap_pkt_t pkt,
unsigned  code,
uint8_t *  buf,
size_t  len,
unsigned  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]pktpacket to reply to
[in]codereply code (e.g., COAP_CODE_204)
[out]bufbuffer to write reply to
[in]lensize of buf
[in]ctcontent type of payload
[in]payloadptr to payload
[in]payload_lenlength of payload
Returns
size of reply packet on success
<0 on error
-ENOSPC if buf too small

◆ 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]ctxThe request context
Returns
Resource context of the request

◆ 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]ctxThe 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]ctxThe 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]ctxThe 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]ctxPointer to the request context to initialize
[in]remoteRemote endpoint that made the request

◆ coap_size2szx()

static unsigned coap_size2szx ( unsigned  len)
inlinestatic

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

Parameters
[in]lenSize in bytes
Returns
closest SZX value that fits into a buffer of len

Definition at line 1084 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]pktpointer to (parsed) CoAP packet
[out]resp_bufbuffer for response
[in]resp_buf_lensize of response buffer
[in]contextpointer to request context, must contain context to coap_resource_subtree_t instance
Returns
size of the reply packet on success
<0 on error

◆ coap_szx2size()

static unsigned coap_szx2size ( unsigned  szx)
inlinestatic

Helper to decode SZX value to size in bytes.

Parameters
[in]szxSZX value to decode
Returns
SZX value decoded to bytes

Definition at line 1072 of file nanocoap.h.

◆ 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]pktpointer to (parsed) CoAP packet
[out]resp_bufbuffer for response
[in]resp_buf_lensize of response buffer
[in]ctxCoAP request context information
[in]resourcesArray of coap endpoint resources
[in]resources_numoflength of the coap endpoint resources
Returns
size of the reply packet on success
<0 on error