nanocoap.h File Reference

nanocoap API More...

Detailed Description

nanocoap API

Author

Kaspar Schleiser kaspa.nosp@m.r@sc.nosp@m.hleis.nosp@m.er.d.nosp@m.e

Ken Bannister kb2ma.nosp@m.@run.nosp@m.box.c.nosp@m.om

Hauke Petersen hauke.nosp@m..pet.nosp@m.ersen.nosp@m.@fu-.nosp@m.berli.nosp@m.n.de

Definition in file nanocoap.h.

#include <assert.h>
#include <errno.h>
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include <string.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	CONFIG_NANOCOAP_NOPTS_MAX   (16)
	Maximum number of Options in a message.
#define	CONFIG_NANOCOAP_URI_MAX   (64)
	Maximum length of a resource path string read from or written to a message.
#define	CONFIG_NANOCOAP_BLOCK_SIZE_EXP_MAX   (6)
	Maximum size for a blockwise transfer as a power of 2.
#define	CONFIG_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. More...
typedef uint16_t	coap_method_flags_t
	Method flag type. More...

Functions
static ssize_t	coap_get_proxy_uri (const 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.

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 (const 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...
int	coap_opt_get_uint (const coap_pkt_t *pkt, uint16_t optnum, uint32_t *value)
	Get a uint32 option value. 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 (const 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_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...
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...
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 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...
ssize_t	coap_tree_handler (coap_pkt_t *pkt, uint8_t *resp_buf, unsigned resp_buf_len, const coap_resource_t *resources, size_t resources_numof)
	Pass a coap request to a matching 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 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...