nanocoap.h File Reference

nanocoap API More...

Detailed Description

#include <assert.h>
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include <unistd.h>
#include "coap.h"
#include <arpa/inet.h>
+ Include dependency graph for nanocoap.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  coap_hdr_t
 Raw CoAP PDU header structure. More...
 
struct  coap_optpos_t
 CoAP option array entry. More...
 
struct  coap_pkt_t
 CoAP PDU parsing context structure. More...
 
struct  coap_resource_t
 Type for CoAP resource entry. More...
 
struct  coap_block1_t
 Block1 helper struct. More...
 
struct  coap_block_slicer_t
 Blockwise transfer helper struct. More...
 

Macros

#define COAP_FORMAT_NONE   (UINT16_MAX)
 Nanocoap-specific value to indicate no format specified.
 
#define NANOCOAP_NOPTS_MAX   (16)
 Maximum number of Options in a message.
 
#define NANOCOAP_URI_MAX   (64)
 Maximum length of a resource path string read from or written to a message.
 
#define NANOCOAP_BLOCK_SIZE_EXP_MAX   (6)
 Maximum size for a blockwise transfer as a power of 2.
 
#define NANOCOAP_QS_MAX   (64)
 Maximum length of a query string written to a message.
 
#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.
 
typedef uint16_t coap_method_flags_t
 Method flag type. More...
 

Functions

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.
 

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

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 (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 (coap_pkt_t *pkt)
 Get a message's code in decimal format ((class * 100) + detail) More...
 
static unsigned coap_get_code_raw (coap_pkt_t *pkt)
 Get a message's raw code (class + detail) More...
 
static unsigned coap_get_id (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 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_type (coap_pkt_t *pkt)
 Get the message type. More...
 
static unsigned coap_get_ver (coap_pkt_t *pkt)
 Get the CoAP version number. More...
 
static uint8_t * coap_hdr_data_ptr (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.

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_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...
 
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...
 
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...
 
void coap_block_finish (coap_block_slicer_t *slicer, uint16_t option)
 Finish a block request (block1 or block2) More...
 
static void coap_block1_finish (coap_block_slicer_t *slicer)
 Finish a block1 request. More...
 
static void 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 uint8_t *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, unsigned *szx)
 Generic block option getter. More...
 
static unsigned coap_szx2size (unsigned szx)
 Helper to decode SZX value to size in bytes. 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_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 uint8_t *val, size_t val_len)
 Encode the given buffer as an opaque data option into pkt. 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_finish (coap_pkt_t *pkt, uint16_t flags)
 Finalizes options as required and prepares for payload. 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 (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_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 uint8_t *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)
 Handle incoming CoAP request. 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...
 
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_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.
 

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