CoAP library optimized for minimal resource usage.
More...
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:
- minimal API requires only a reference to the buffer for the message. However, the caller must provide the last option number written as well as the buffer position.
- struct-based API uses a coap_pkt_t struct to conveniently track each option as it is written and prepare for any payload.
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.
|
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.
|
|
|
#define | COAP_GET (0x1) |
|
#define | COAP_POST (0x2) |
|
#define | COAP_PUT (0x4) |
|
#define | COAP_DELETE (0x8) |
|
◆ 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 1099 of file nanocoap.h.
◆ coap_block2_build_reply()
Build reply to CoAP block2 request.
This function can be used to create a reply to a CoAP block2 request packet. In addition to coap_build_reply, this function checks the block2 option and returns an error message to the client if necessary.
- Parameters
-
[in] | pkt | packet to reply to |
[in] | code | reply code (e.g., COAP_CODE_204) |
[out] | rbuf | buffer to write reply to |
[in] | rlen | size of rbuf |
[in] | payload_len | length of payload |
[in] | slicer | slicer to use |
- Returns
- size of reply packet on success
-
<0 on error
◆ coap_block2_finish()
Finish a block2 response.
This function finalizes the block2 response header
Checks whether the more
bit should be set in the block2 option and sets/clears it if required. Doesn't return the number of bytes as this overwrites bytes in the packet, it doesn't add new bytes to the packet.
- Parameters
-
[in,out] | slicer | Preallocated slicer struct to use |
◆ coap_block2_init()
Initialize a block2 slicer struct for writing the payload.
This function determines the size of the response payload based on the size requested by the client in pkt
.
- Parameters
-
[in] | pkt | packet to work on |
[out] | slicer | Preallocated slicer struct to fill |
◆ coap_blockwise_put_bytes()
Add a byte array to a block2 reply.
This function is used to add an array of bytes to a CoAP block2 reply. it checks which parts of the string should be added to the reply and ignores parts that are outside the current block2 request.
- Parameters
-
[in] | slicer | slicer to use |
[in] | bufpos | pointer to the current payload buffer position |
[in] | c | byte array to copy |
[in] | len | length of the byte array |
- Returns
- Number of bytes writen to
bufpos
◆ coap_blockwise_put_char()
Add a single character to a block2 reply.
This function is used to add single characters to a CoAP block2 reply. It checks whether the character should be added to the buffer and ignores it when the character is outside the current block2 request.
- Parameters
-
[in] | slicer | slicer to use |
[in] | bufpos | pointer to the current payload buffer position |
[in] | c | character to write |
- Returns
- Number of bytes writen to
bufpos
◆ coap_build_hdr()
ssize_t coap_build_hdr |
( |
coap_hdr_t * |
hdr, |
|
|
unsigned |
type, |
|
|
uint8_t * |
token, |
|
|
size_t |
token_len, |
|
|
unsigned |
code, |
|
|
uint16_t |
id |
|
) |
| |
Builds a CoAP header.
Caller must ensure hdr
can hold the header and the full token!
- Parameters
-
[out] | hdr | hdr to fill |
[in] | type | CoAP packet type (e.g., COAP_TYPE_CON, ...) |
[in] | token | token |
[in] | token_len | length of token |
[in] | code | CoAP code (e.g., COAP_CODE_204, ...) |
[in] | id | CoAP request id |
- Returns
- length of resulting header
◆ coap_build_reply()
ssize_t coap_build_reply |
( |
coap_pkt_t * |
pkt, |
|
|
unsigned |
code, |
|
|
uint8_t * |
rbuf, |
|
|
unsigned |
rlen, |
|
|
unsigned |
payload_len |
|
) |
| |
Build reply to CoAP request.
This function can be used to create a reply to any CoAP request packet. It will create the reply packet header based on parameters from the request (e.g., id, token).
Passing a non-zero payload_len
will ensure the payload fits into the buffer along with the header. For this validation, payload_len must include any options, the payload marker, as well as the payload proper.
- Parameters
-
[in] | pkt | packet to reply to |
[in] | code | reply code (e.g., COAP_CODE_204) |
[out] | rbuf | buffer to write reply to |
[in] | rlen | size of rbuf |
[in] | payload_len | length of payload |
- Returns
- size of reply packet on success
-
<0 on error
-
-ENOSPC if
rbuf
too small
◆ coap_clear_observe()
static void coap_clear_observe |
( |
coap_pkt_t * |
pkt | ) |
|
|
inlinestatic |
Clears the observe option value from a packet.
- Parameters
-
Definition at line 1070 of file nanocoap.h.
◆ coap_code()
static uint8_t coap_code |
( |
unsigned |
cls, |
|
|
unsigned |
detail |
|
) |
| |
|
inlinestatic |
Encode given code class and code detail to raw code.
- Parameters
-
[in] | cls | message code class |
[in] | detail | message code detail |
- Returns
- raw message code
Definition at line 1006 of file nanocoap.h.
◆ coap_get_block1()
Block1 option getter.
This function gets a CoAP packet's block1 option and parses it into a helper structure.
If no block1 option is present in pkt
, the values in block1
will be initialized with zero. That implies both block1->offset and block1->more are also valid in that case, as packet with offset==0 and more==0 means it contains all the payload for the corresponding request.
- Parameters
-
[in] | pkt | pkt to work on |
[out] | block1 | ptr to preallocated coap_block1_t structure |
- Returns
- 0 if block1 option not present
-
1 if structure has been filled
◆ coap_get_block2()
Block2 option getter.
- Parameters
-
[in] | pkt | pkt to work on |
[out] | block2 | ptr to preallocated coap_block1_t structure |
- Returns
- 0 if block2 option not present
-
1 if structure has been filled
◆ coap_get_blockopt()
int coap_get_blockopt |
( |
coap_pkt_t * |
pkt, |
|
|
uint16_t |
option, |
|
|
uint32_t * |
blknum, |
|
|
unsigned * |
szx |
|
) |
| |
Generic block option getter.
- Parameters
-
[in] | pkt | pkt to work on |
[in] | option | actual block option number to get |
[out] | blknum | block number |
[out] | szx | SZX value |
- Returns
- -1 if option not found
-
0 if more flag is not set
-
1 if more flag is set
◆ coap_get_code()
Get a message's code in decimal format ((class * 100) + detail)
- Parameters
-
- Returns
- message code in decimal format
Definition at line 957 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
-
- Returns
- message code class
Definition at line 921 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
-
- Returns
- message code detail
Definition at line 933 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
-
- Returns
- raw message code
Definition at line 945 of file nanocoap.h.
◆ coap_get_content_type()
unsigned coap_get_content_type |
( |
coap_pkt_t * |
pkt | ) |
|
Get content type from packet.
- Parameters
-
- Returns
- the packet's content type value if included, COAP_FORMAT_NONE otherwise
◆ coap_get_id()
Get the message ID of the given CoAP packet.
- Parameters
-
- Returns
- message ID
Definition at line 969 of file nanocoap.h.
◆ coap_get_location_path()
Convenience function for getting the packet's LOCATION_PATH option.
This function decodes the pkt's LOCATION_PATH option into a '/'-separated and '\0'-terminated string.
Caller must ensure target
can hold at least 2 bytes!
- Parameters
-
[in] | pkt | pkt to work on |
[out] | target | buffer for location path |
[in] | max_len | size of target in bytes |
- Returns
- -ENOSPC if URI option is larger than
max_len
-
nr of bytes written to
target
(including '\0')
Definition at line 757 of file nanocoap.h.
◆ coap_get_location_query()
Convenience function for getting the packet's LOCATION_QUERY option.
This function decodes the pkt's LOCATION_PATH option into a '&'-separated and '\0'-terminated string.
Caller must ensure target
can hold at least 2 bytes!
- Parameters
-
[in] | pkt | pkt to work on |
[out] | target | buffer for location path |
[in] | max_len | size of target in bytes |
- Returns
- -ENOSPC if URI option is larger than
max_len
-
nr of bytes written to
target
(including '\0')
Definition at line 779 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
-
- Returns
- value of the observe option
Definition at line 1082 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
-
- Returns
- length of token in the given message (0-8 byte)
Definition at line 909 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
-
- Returns
- total header length
Definition at line 993 of file nanocoap.h.
◆ coap_get_type()
Get the message type.
- Parameters
-
- Returns
- COAP_TYPE_CON
-
COAP_TYPE_NON
-
COAP_TYPE_ACK
-
COAP_TYPE_RST
Definition at line 897 of file nanocoap.h.
◆ coap_get_uri_path()
Convenience function for getting the packet's URI_PATH.
This function decodes the pkt's URI option into a "/"-separated and '\0'-terminated string.
Caller must ensure target
can hold at least NANOCOAP_URI_MAX bytes!
- Parameters
-
[in] | pkt | pkt to work on |
[out] | target | buffer for target URI |
- Returns
- -ENOSPC if URI option is larger than NANOCOAP_URI_MAX
-
nr of bytes written to
target
(including '\0')
Definition at line 716 of file nanocoap.h.
◆ coap_get_uri_query()
Convenience function for getting the packet's URI_QUERY option.
This function decodes the pkt's URI_QUERY option into a "&"-separated and '\0'-terminated string.
Caller must ensure target
can hold at least NANOCOAP_URI_MAX bytes!
- Parameters
-
[in] | pkt | pkt to work on |
[out] | target | buffer for target URI |
- Returns
- -ENOSPC if URI option is larger than NANOCOAP_URI_MAX
-
nr of bytes written to
target
(including '\0')
Definition at line 736 of file nanocoap.h.
◆ coap_get_ver()
Get the CoAP version number.
- Parameters
-
- Returns
- CoAP version number
Definition at line 882 of file nanocoap.h.
◆ coap_handle_req()
ssize_t coap_handle_req |
( |
coap_pkt_t * |
pkt, |
|
|
uint8_t * |
resp_buf, |
|
|
unsigned |
resp_buf_len |
|
) |
| |
Handle incoming CoAP request.
This function will find the correct handler, call it and write the reply into resp_buf
.
- Parameters
-
[in] | pkt | pointer to (parsed) CoAP packet |
[out] | resp_buf | buffer for response |
[in] | resp_buf_len | size of response buffer |
- Returns
- size of reply packet on success
-
<0 on error
◆ coap_has_observe()
Identifies a packet containing an observe option.
- Parameters
-
- Returns
- true if observe value is set
-
false if not
Definition at line 1060 of file nanocoap.h.
◆ coap_hdr_data_ptr()
static uint8_t* coap_hdr_data_ptr |
( |
coap_hdr_t * |
hdr | ) |
|
|
inlinestatic |
Get the start of data after the header.
- Parameters
-
[in] | hdr | Header of CoAP packet in contiguous memory |
- Returns
- pointer to first byte after the header
Definition at line 981 of file nanocoap.h.
◆ coap_hdr_set_code()
static void coap_hdr_set_code |
( |
coap_hdr_t * |
hdr, |
|
|
uint8_t |
code |
|
) |
| |
|
inlinestatic |
Write the given raw message code to given CoAP header.
- Parameters
-
[out] | hdr | CoAP header to write to |
[in] | code | raw message code |
Definition at line 1017 of file nanocoap.h.
◆ coap_hdr_set_type()
static void coap_hdr_set_type |
( |
coap_hdr_t * |
hdr, |
|
|
unsigned |
type |
|
) |
| |
|
inlinestatic |
Set the message type for the given CoAP header.
- Precondition
- (type := [0-3])
- Parameters
-
[out] | hdr | CoAP header to write |
[in] | type | message type as integer value [0-3] |
Definition at line 1030 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] | code | request code denoting the request method |
- Returns
- bit field corresponding to the given request method
Definition at line 1046 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] | pkt | pkt referencing target buffer |
[in] | optnum | option number to use |
[in] | string | string to encode as option |
[in] | separator | character used in string to separate parts |
- Returns
- number of bytes written to buffer
-
-ENOSPC if no available options
◆ coap_opt_add_uint()
Encode the given uint option into pkt.
- Postcondition
- pkt.payload advanced to first byte after option
-
pkt.payload_len reduced by option length
- Parameters
-
[in,out] | pkt | pkt referencing target buffer |
[in] | optnum | option number to use |
[in] | value | uint to encode |
- Returns
- number of bytes written to buffer
-
<0 reserved for error but not implemented yet
◆ coap_opt_finish()
Finalizes options as required and prepares for payload.
- Postcondition
- pkt.payload advanced to first available byte after options
-
pkt.payload_len is maximum bytes available for payload
- Parameters
-
[in,out] | pkt | pkt to update |
[in] | flags | see COAP_OPT_FINISH... macros |
- Returns
- total number of bytes written to buffer
◆ coap_opt_get_string()
ssize_t coap_opt_get_string |
( |
const coap_pkt_t * |
pkt, |
|
|
uint16_t |
optnum, |
|
|
uint8_t * |
target, |
|
|
size_t |
max_len, |
|
|
char |
separator |
|
) |
| |
Read a full option as null terminated string into the target buffer.
This function is for reading and concatenating string based, multi-part CoAP options like COAP_OPT_URI_PATH or COAP_OPT_LOCATION_PATH. It will write all parts of the given option into the target buffer, separating the parts using the given separator
. The resulting string is \0
terminated.
- Parameters
-
[in] | pkt | packet to read from |
[in] | optnum | absolute option number |
[out] | target | target buffer |
[in] | max_len | size of target |
[in] | separator | character used for separating the option parts |
- Returns
- -ENOSPC if the complete option does not fit into
target
-
nr of bytes written to
target
(including '\0')
◆ coap_opt_put_block2()
Insert block2 option into buffer.
When calling this function to initialize a packet with a block2 option, the more flag must be set to prevent the creation of an option with a length too small to contain the size bit.
- Parameters
-
[out] | buf | buffer to write to |
[in] | lastonum | number of previous option (for delta calculation), must be < 23 |
[in] | slicer | coap blockwise slicer helper struct |
[in] | more | more flag (1 or 0) |
- Returns
- amount of bytes written to
buf
◆ coap_opt_put_location_path()
static size_t coap_opt_put_location_path |
( |
uint8_t * |
buf, |
|
|
uint16_t |
lastonum, |
|
|
const char * |
location |
|
) |
| |
|
inlinestatic |
Convenience function for inserting LOCATION_PATH option into buffer.
- Parameters
-
[out] | buf | buffer to write to |
[in] | lastonum | number of previous option (for delta calculation), or 0 if first option |
[in] | location | ptr to string holding the location |
- Returns
- amount of bytes written to
buf
Definition at line 506 of file nanocoap.h.
◆ coap_opt_put_location_query()
static size_t coap_opt_put_location_query |
( |
uint8_t * |
buf, |
|
|
uint16_t |
lastonum, |
|
|
const char * |
location |
|
) |
| |
|
inlinestatic |
Convenience function for inserting LOCATION_QUERY option into buffer.
- Parameters
-
[out] | buf | buffer to write to |
[in] | lastonum | number of previous option (for delta calculation), or 0 if first option |
[in] | location | ptr to string holding the location |
- Returns
- amount of bytes written to
buf
Definition at line 524 of file nanocoap.h.
◆ coap_opt_put_string()
size_t coap_opt_put_string |
( |
uint8_t * |
buf, |
|
|
uint16_t |
lastonum, |
|
|
uint16_t |
optnum, |
|
|
const char * |
string, |
|
|
char |
separator |
|
) |
| |
Encode the given string as multi-part option into buffer.
- Parameters
-
[out] | buf | buffer to write to |
[in] | lastonum | number of previous option (for delta calculation), or 0 if first option |
[in] | optnum | option number to use |
[in] | string | string to encode as option |
[in] | separator | character used in string to separate parts |
- Returns
- number of bytes written to
buf
◆ coap_opt_put_uri_path()
static size_t coap_opt_put_uri_path |
( |
uint8_t * |
buf, |
|
|
uint16_t |
lastonum, |
|
|
const char * |
uri |
|
) |
| |
|
inlinestatic |
Convenience function for inserting URI_PATH option into buffer.
- Parameters
-
[out] | buf | buffer to write to |
[in] | lastonum | number of previous option (for delta calculation), or 0 if first option |
[in] | uri | ptr to source URI |
- Returns
- amount of bytes written to
buf
Definition at line 474 of file nanocoap.h.
◆ coap_opt_put_uri_query()
static size_t coap_opt_put_uri_query |
( |
uint8_t * |
buf, |
|
|
uint16_t |
lastonum, |
|
|
const char * |
uri |
|
) |
| |
|
inlinestatic |
Convenience function for inserting URI_QUERY option into buffer.
- Parameters
-
[out] | buf | buffer to write to |
[in] | lastonum | number of previous option (for delta calculation), or 0 if first option |
[in] | uri | ptr to source URI |
- Returns
- amount of bytes written to
buf
Definition at line 490 of file nanocoap.h.
◆ coap_parse()
Parse a CoAP PDU.
This function parses a raw CoAP PDU from buf
with size len
and fills the structure pointed to by pkt
. pkt
must point to a preallocated coap_pkt_t structure.
- Parameters
-
[out] | pkt | structure to parse into |
[in] | buf | pointer to raw packet data |
[in] | len | length of packet at buf |
- Returns
- 0 on success
-
<0 on error
◆ coap_pkt_init()
Initialize a packet struct, to build a message buffer.
- Precondition
- buf CoAP header already initialized
- Postcondition
- pkt.flags all zeroed
-
pkt.payload points to first byte after header
-
pkt.payload_len set to maximum space available for options + payload
- Parameters
-
[out] | pkt | pkt to initialize |
[in] | buf | buffer to write for pkt, with CoAP header already initialized |
[in] | len | length of buf |
[in] | header_len | length of header in buf, including token |
◆ coap_put_block1_ok()
Insert block1 option into buffer (from coap_block1_t)
This function is wrapper around coap_put_option_block1(), taking its arguments from a coap_block1_t struct.
It will write option Nr. 27 (COAP_OPT_BLOCK1).
It is safe to be called when block1
was generated for a non-blockwise request.
- Parameters
-
[in] | pkt_pos | buffer to write to |
[in] | block1 | ptr to block1 struct (created by coap_get_block1()) |
[in] | lastonum | last option number (must be < 27) |
- Returns
- amount of bytes written to
pkt_pos
◆ coap_put_option()
size_t coap_put_option |
( |
uint8_t * |
buf, |
|
|
uint16_t |
lastonum, |
|
|
uint16_t |
onum, |
|
|
uint8_t * |
odata, |
|
|
size_t |
olen |
|
) |
| |
Insert a CoAP option into buffer.
This function writes a CoAP option with nr. onum
to buf
. It handles calculating the option delta (from lastonum
), encoding the length from olen
and copying the option data from odata
.
- Parameters
-
[out] | buf | buffer to write to |
[in] | lastonum | number of previous option (for delta calculation), or 0 for first option |
[in] | onum | number of option |
[in] | odata | ptr to raw option data (or NULL) |
[in] | olen | length of odata (if any) |
- Returns
- amount of bytes written to
buf
◆ coap_put_option_block1()
size_t coap_put_option_block1 |
( |
uint8_t * |
buf, |
|
|
uint16_t |
lastonum, |
|
|
unsigned |
blknum, |
|
|
unsigned |
szx, |
|
|
int |
more |
|
) |
| |
Insert block1 option into buffer.
- Parameters
-
[out] | buf | buffer to write to |
[in] | lastonum | number of previous option (for delta calculation), must be < 27 |
[in] | blknum | block number |
[in] | szx | SXZ value |
[in] | more | more flag (1 or 0) |
- Returns
- amount of bytes written to
buf
◆ coap_put_option_ct()
size_t coap_put_option_ct |
( |
uint8_t * |
buf, |
|
|
uint16_t |
lastonum, |
|
|
uint16_t |
content_type |
|
) |
| |
Insert content type option into buffer.
- Parameters
-
[out] | buf | buffer to write to |
[in] | lastonum | number of previous option (for delta calculation), or 0 if first option |
[in] | content_type | content type to set |
- Returns
- amount of bytes written to
buf
◆ coap_reply_simple()
ssize_t coap_reply_simple |
( |
coap_pkt_t * |
pkt, |
|
|
unsigned |
code, |
|
|
uint8_t * |
buf, |
|
|
size_t |
len, |
|
|
unsigned |
ct, |
|
|
const uint8_t * |
payload, |
|
|
uint8_t |
payload_len |
|
) |
| |
Create CoAP reply (convenience function)
This is a simple wrapper that allows for building CoAP replies for simple use-cases.
The reply will be written to buf
. If payload
and payload_len
are non-zero, the payload will be copied into the resulting reply packet.
- Parameters
-
[in] | pkt | packet to reply to |
[in] | code | reply code (e.g., COAP_CODE_204) |
[out] | buf | buffer to write reply to |
[in] | len | size of buf |
[in] | ct | content type of payload |
[in] | payload | ptr to payload |
[in] | payload_len | length of payload |
- Returns
- size of reply packet on success
-
<0 on error
-
-ENOSPC if
buf
too small
◆ coap_szx2size()
static unsigned coap_szx2size |
( |
unsigned |
szx | ) |
|
|
inlinestatic |
Helper to decode SZX value to size in bytes.
- Parameters
-
[in] | szx | SZX value to decode |
- Returns
- SZX value decoded to bytes
Definition at line 870 of file nanocoap.h.