Nanocoap small CoAP library

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.

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:

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.

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

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.

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   (65535)
 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, 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_uint (coap_pkt_t *pkt, uint16_t optnum, uint32_t value)
 Encode the given uint option into pkt. 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...
 
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)
 

Nanocoap specific maximum values

#define NANOCOAP_NOPTS_MAX   (16)
 
#define NANOCOAP_URI_MAX   (64)
 
#define NANOCOAP_BLOCK_SIZE_EXP_MAX   (6)
 Maximum size for a blockwise transfer as power of 2.
 

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, void *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 1079 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]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()

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]slicerPreallocated 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]pktpacket to work on
[out]slicerPreallocated 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]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 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]slicerslicer to use
[in]bufpospointer to the current payload buffer position
[in]ccharacter 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]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.

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
<0 on error

◆ 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 1050 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 986 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]pktpkt to work on
[out]block1ptr 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]pktpkt to work on
[out]block2ptr 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]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 ( 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 937 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]pktCoAP packet
Returns
message code class

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

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

Definition at line 925 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 ( coap_pkt_t pkt)
inlinestatic

Get the message ID of the given CoAP packet.

Parameters
[in]pktCoAP packet
Returns
message ID

Definition at line 949 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]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 737 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]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 759 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 1062 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]pktCoAP packet
Returns
length of token in the given message (0-8 byte)

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

Definition at line 973 of file nanocoap.h.

◆ coap_get_type()

static unsigned coap_get_type ( 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 877 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]pktpkt to work on
[out]targetbuffer 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 696 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]pktpkt to work on
[out]targetbuffer 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 716 of file nanocoap.h.

◆ coap_get_ver()

static unsigned coap_get_ver ( coap_pkt_t pkt)
inlinestatic

Get the CoAP version number.

Parameters
[in]pktCoAP packet
Returns
CoAP version number

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

Definition at line 1040 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]hdrHeader of CoAP packet in contiguous memory
Returns
pointer to first byte after the header

Definition at line 961 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 997 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 1010 of file nanocoap.h.

◆ coap_method2flag()

static unsigned 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 1026 of file nanocoap.h.

◆ 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]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
-ENOSPC if no available options

◆ 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 reserved for error but not implemented yet

◆ 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

◆ 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]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_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]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

◆ 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 486 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 504 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]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

◆ 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 454 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]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 470 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]pktstructure to parse into
[in]bufpointer to raw packet data
[in]lenlength 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]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,
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]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()

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]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

◆ 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]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

◆ 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. Is payload and payload_len 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

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