Synchronous sock based messaging with nanocoap More...

Detailed Description

Synchronous sock based messaging with nanocoap

nanocoap sock uses the nanocoap CoAP library to provide a synchronous interface to RIOT's sock networking API to read and write CoAP messages. For a server, nanocoap sock accepts a list of resource paths with callbacks for writing the response. For a client, nanocoap sock provides a function to send a request and waits for the server response. nanocoap sock uses nanocoap's Buffer API to write message options.

Server Operation

See the nanocoap_server example, which is built on the nanocoap_server() function. A server must define CoAP resources for which it responds.

Each coap_resource_t is added to the XFA with NANOCOAP_RESOURCE(name) followed by the declaration of the CoAP resource, e.g.:

NANOCOAP_RESOURCE(board) {
  .path = "/board", .methods = COAP_GET, .handler = _board_handler,
};

nanocoap itself provides the COAP_WELL_KNOWN_CORE_DEFAULT_HANDLER entry for /.well-known/core.

To use the CoAP resource XFA, enable the nanocoap_resources module.

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 functions in the Header and Options Read sections of the nanocoap documentation. 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 use the Buffer API to write the rest of the response. See the instructions in the section Write Options and Payload below.

Client Operation

Follow the instructions in the section Write Options and Payload below.

To send the message and await the response, see nanocoap_sock_request() as well as nanocoap_sock_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 sock uses the nanocoap Buffer API for options. 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.

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 functions in the Options Write Buffer API section of nanocoap to write each option. These functions require the position in the buffer to start writing, and return the number of bytes written. Options must be written in order by option number (see "CoAP option numbers" in CoAP defines).

Note: You must ensure the buffer has enough space remaining to write each option. The API does not verify the safety of writing an option.

If there is a payload, append a payload marker (0xFF). Then write the payload to within the maximum length remaining in the buffer.

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(). Use coap_get_response_hdr_len to get the length of the response header: This will be the offset in the buffer where you should start adding options. The Block2 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	fs.h
	nanoCoAP virtual file system

file	link_format.h
	NanoCoAP Link Format helper functions.

file	nanocoap_sock.h
	nanocoap high-level API

file	nanocoap_vfs.h
	VFS NanoCoAP helper functions.

Data Structures
struct	nanocoap_sock_t
	NanoCoAP socket struct. More...

struct	coap_block_request_t
	Blockwise request helper struct. More...

struct	nanocoap_server_response_ctx_t
	Context from CoAP request for separate response. More...

Macros
#define	CONFIG_NANOCOAP_SOCK_DTLS_TAG (0xc0ab)
	Credman tag used for NanoCoAP Tag together with the credential type (PSK) needs to be unique.

#define	CONFIG_NANOCOAP_SERVER_BUF_SIZE
	CoAP server work buf size Used both for RX and TX, needs to hold payload block + header.

#define	CONFIG_NANOCOAP_SERVER_STACK_SIZE THREAD_STACKSIZE_DEFAULT
	CoAP server thread stack size.

#define	CONFIG_NANOCOAP_SOCK_BLOCK_TOKEN (0)
	Include a random token with block-wise transfers.

Enumerations
enum	nanocoap_socket_type_t { COAP_SOCKET_TYPE_UDP , COAP_SOCKET_TYPE_DTLS }
	NanoCoAP socket types. More...

Functions
int	nanocoap_server_prepare_separate (nanocoap_server_response_ctx_t ctx, coap_pkt_t pkt, const coap_request_ctx_t *req)
	Prepare the context for a separate response.

bool	nanocoap_server_is_remote_in_response_ctx (const nanocoap_server_response_ctx_t ctx, const coap_request_ctx_t req)
	Check if a given separate response context was prepared for the remote endpoint of a given request.

int	nanocoap_server_send_separate (const nanocoap_server_response_ctx_t ctx, unsigned code, unsigned type, const void payload, size_t len)
	Build and send a separate response to a CoAP request.

ssize_t	nanocoap_server_build_separate (const nanocoap_server_response_ctx_t ctx, void buf, size_t buf_len, unsigned code, unsigned type, uint16_t msg_id)
	Build a separate response header to a CoAP request.

int	nanocoap_server_sendv_separate (const nanocoap_server_response_ctx_t ctx, const iolist_t reply)
	Send an already build separate response.

int	nanocoap_register_observer (const coap_request_ctx_t req_ctx, coap_pkt_t req_pkt)
	Register an observer.

void	nanocoap_unregister_observer (const coap_request_ctx_t req_ctx, const coap_pkt_t req_pkt)
	Unregister an observer.

void	nanocoap_unregister_observer_due_to_reset (const sock_udp_ep_t *ep, uint16_t msg_id)
	Unregister a stale observation due to a reset message received.

void	nanocoap_notify_observers (const coap_resource_t res, const iolist_t iol)
	Notify all currently registered observers of the given resource.

void	nanocoap_notify_observers_simple (const coap_resource_t res, uint32_t obs, const void payload, size_t payload_len)
	Build and send notification to observers registered to a specific resource.

static uint16_t	nanocoap_sock_next_msg_id (nanocoap_sock_t *sock)
	Get next consecutive message ID for use when building a new CoAP request.

int	nanocoap_server (sock_udp_ep_t local, uint8_t buf, size_t bufsize)
	Start a nanocoap server instance.

kernel_pid_t	nanocoap_server_start (const sock_udp_ep_t *local)
	Create and start the nanoCoAP server thread.

static int	nanocoap_sock_connect (nanocoap_sock_t sock, const sock_udp_ep_t local, const sock_udp_ep_t *remote)
	Create a CoAP client socket.

int	nanocoap_sock_dtls_connect (nanocoap_sock_t sock, sock_udp_ep_t local, const sock_udp_ep_t *remote, credman_tag_t tag)
	Create a DTLS secured CoAP client socket.

int	nanocoap_sock_url_connect (const char url, nanocoap_sock_t sock)
	Create a CoAP client socket by URL.

static void	nanocoap_sock_close (nanocoap_sock_t *sock)
	Close a CoAP client socket.

ssize_t	nanocoap_sock_get (nanocoap_sock_t sock, const char path, void *buf, size_t len)
	Simple synchronous CoAP (confirmable) GET.

ssize_t	nanocoap_sock_get_non (nanocoap_sock_t sock, const char path, void *response, size_t len_max)
	Simple non-confirmable GET.

ssize_t	nanocoap_sock_put (nanocoap_sock_t sock, const char path, const void request, size_t len, void response, size_t len_max)
	Simple synchronous CoAP (confirmable) PUT.

ssize_t	nanocoap_sock_put_non (nanocoap_sock_t sock, const char path, const void request, size_t len, void response, size_t len_max)
	Simple non-confirmable PUT.

ssize_t	nanocoap_sock_put_url (const char url, const void request, size_t len, void *response, size_t len_max)
	Simple synchronous CoAP (confirmable) PUT to URL.

ssize_t	nanocoap_sock_post (nanocoap_sock_t sock, const char path, const void request, size_t len, void response, size_t len_max)
	Simple synchronous CoAP (confirmable) POST.

ssize_t	nanocoap_sock_post_non (nanocoap_sock_t sock, const char path, const void request, size_t len, void response, size_t len_max)
	Simple non-confirmable POST.

ssize_t	nanocoap_sock_post_url (const char url, const void request, size_t len, void *response, size_t len_max)
	Simple synchronous CoAP (confirmable) POST to URL.

ssize_t	nanocoap_sock_fetch (nanocoap_sock_t sock, const char path, const void request, size_t len, void response, size_t len_max)
	Simple synchronous CoAP (confirmable) FETCH (RFC 8132)

ssize_t	nanocoap_sock_fetch_non (nanocoap_sock_t sock, const char path, const void request, size_t len, void response, size_t len_max)
	Simple non-confirmable FETCH (RFC 8132)

ssize_t	nanocoap_sock_fetch_url (const char url, const void request, size_t len, void *response, size_t len_max)
	Simple synchronous CoAP (confirmable) FETCH to URL (RFC 8132)

ssize_t	nanocoap_sock_delete (nanocoap_sock_t sock, const char path)
	Simple synchronous CoAP (confirmable) DELETE.

ssize_t	nanocoap_sock_delete_url (const char *url)
	Simple synchronous CoAP (confirmable) DELETE for URL.

int	nanocoap_sock_get_blockwise (nanocoap_sock_t sock, const char path, coap_blksize_t blksize, coap_blockwise_cb_t callback, void *arg)
	Performs a blockwise coap get request on a socket.

int	nanocoap_sock_get_slice (nanocoap_sock_t sock, const char path, coap_blksize_t blksize, size_t offset, void *dst, size_t len)
	Performs a blockwise coap get request to the specified url, store the response in a buffer.

int	nanocoap_get_blockwise_url (const char url, coap_blksize_t blksize, coap_blockwise_cb_t callback, void arg)
	Performs a blockwise coap get request to the specified url.

ssize_t	nanocoap_get_blockwise_url_to_buf (const char url, coap_blksize_t blksize, void buf, size_t len)
	Performs a blockwise coap get request to the specified url, store the response in a buffer.

ssize_t	nanocoap_get_blockwise_to_buf (nanocoap_sock_t sock, const char path, coap_blksize_t blksize, void *buf, size_t len)
	Performs a blockwise CoAP GET request, store the response in a buffer.

ssize_t	nanocoap_sock_request (nanocoap_sock_t sock, coap_pkt_t pkt, size_t len)
	Simple synchronous CoAP request.

ssize_t	nanocoap_sock_request_cb (nanocoap_sock_t sock, coap_pkt_t pkt, coap_request_cb_t cb, void *arg)
	Simple synchronous CoAP request with callback.

ssize_t	nanocoap_request (coap_pkt_t pkt, const sock_udp_ep_t local, const sock_udp_ep_t *remote, size_t len)
	Simple synchronous CoAP request.

static int	nanocoap_block_request_connect_url (coap_block_request_t ctx, nanocoap_sock_t sock, const char *url, coap_method_t method, coap_blksize_t blksize)
	Initialize block request context by URL and connect a socket.

int	nanocoap_sock_block_request (coap_block_request_t ctx, const void data, size_t len, bool more, coap_request_cb_t cb, void *arg)
	Do a block-wise request, send a single block.

Macro Definition Documentation

◆ CONFIG_NANOCOAP_SERVER_BUF_SIZE

#define CONFIG_NANOCOAP_SERVER_BUF_SIZE

Value:

((1 << (CONFIG_NANOCOAP_BLOCKSIZE_DEFAULT + 3)) \

+ CONFIG_NANOCOAP_URI_MAX + 16)

CONFIG_NANOCOAP_BLOCKSIZE_DEFAULT

#define CONFIG_NANOCOAP_BLOCKSIZE_DEFAULT

CoAP block-wise-transfer size that should be used by default.

Definition nanocoap.h:168

CONFIG_NANOCOAP_URI_MAX

#define CONFIG_NANOCOAP_URI_MAX

Maximum length of a resource path string read from or written to a message.

Definition nanocoap.h:154

CoAP server work buf size Used both for RX and TX, needs to hold payload block + header.

Definition at line 170 of file nanocoap_sock.h.

◆ CONFIG_NANOCOAP_SERVER_STACK_SIZE

#define CONFIG_NANOCOAP_SERVER_STACK_SIZE THREAD_STACKSIZE_DEFAULT

CoAP server thread stack size.

Definition at line 178 of file nanocoap_sock.h.

◆ CONFIG_NANOCOAP_SOCK_BLOCK_TOKEN

#define CONFIG_NANOCOAP_SOCK_BLOCK_TOKEN (0)

Include a random token with block-wise transfers.

This is a workaround for buggy CoPA implementations (e.g. go-coap) that expect to identify block-wise transfers based on the token.

See https://github.com/plgd-dev/go-coap/issues/512

Definition at line 190 of file nanocoap_sock.h.

◆ CONFIG_NANOCOAP_SOCK_DTLS_TAG

#define CONFIG_NANOCOAP_SOCK_DTLS_TAG (0xc0ab)

Credman tag used for NanoCoAP Tag together with the credential type (PSK) needs to be unique.

Definition at line 162 of file nanocoap_sock.h.

Enumeration Type Documentation

◆ nanocoap_socket_type_t

enum nanocoap_socket_type_t

NanoCoAP socket types.

Enumerator
COAP_SOCKET_TYPE_UDP	transport is plain UDP
COAP_SOCKET_TYPE_DTLS	transport is DTLS

Definition at line 196 of file nanocoap_sock.h.

Function Documentation

◆ nanocoap_block_request_connect_url()

static int nanocoap_block_request_connect_url	(	coap_block_request_t *	ctx,
		nanocoap_sock_t *	sock,
		const char *	url,
		coap_method_t	method,
		coap_blksize_t	blksize )

inlinestatic

Initialize block request context by URL and connect a socket.

Parameters

[out]	ctx	The block request context to initialize
[out]	sock	Socket to initialize and use for the request
[in]	url	The request URL
[in]	method	Request method (`COAP_METHOD_{GET\|PUT\|POST\|FETCH}`)
[in]	blksize	Request blocksize exponent

Return values

0	Success
<0	Error (see nanocoap_sock_url_connect for details)

Definition at line 935 of file nanocoap_sock.h.

◆ nanocoap_get_blockwise_to_buf()

ssize_t nanocoap_get_blockwise_to_buf	(	nanocoap_sock_t *	sock,
		const char *	path,
		coap_blksize_t	blksize,
		void *	buf,
		size_t	len )

Performs a blockwise CoAP GET request, store the response in a buffer.

This function will fetch the content of the specified resource path via block-wise-transfer. The blocks will be re-assembled into buf

Parameters

[in]	sock	socket to use for the request
[in]	path	pointer to source path
[in]	blksize	sender suggested SZX for the COAP block request
[in]	buf	Target buffer
[in]	len	Target buffer length

Returns: <0 on error; -EINVAL if an invalid url is provided; -ENOBUFS if the provided buffer was too small; size of the response payload on success

◆ nanocoap_get_blockwise_url()

int nanocoap_get_blockwise_url	(	const char *	url,
		coap_blksize_t	blksize,
		coap_blockwise_cb_t	callback,
		void *	arg )

Performs a blockwise coap get request to the specified url.

This function will fetch the content of the specified resource path via block-wise-transfer. A coap_blockwise_cb_t will be called on each received block.

Parameters

[in]	url	Absolute URL pointer to source path (i.e. not containing a fragment identifier)
[in]	blksize	sender suggested SZX for the COAP block request
[in]	callback	callback to be executed on each received block
[in]	arg	optional function arguments

Returns: -EINVAL if an invalid url is provided; -1 if failed to fetch the url content; 0 on success

◆ nanocoap_get_blockwise_url_to_buf()

ssize_t nanocoap_get_blockwise_url_to_buf	(	const char *	url,
		coap_blksize_t	blksize,
		void *	buf,
		size_t	len )

Performs a blockwise coap get request to the specified url, store the response in a buffer.

This function will fetch the content of the specified resource path via block-wise-transfer. The blocks will be re-assembled into buf

Parameters

[in]	url	Absolute URL pointer to source path (i.e. not containing a fragment identifier)
[in]	blksize	sender suggested SZX for the COAP block request
[in]	buf	Target buffer
[in]	len	Target buffer length

Returns: <0 on error; -EINVAL if an invalid url is provided; -ENOBUFS if the provided buffer was too small; size of the response payload on success

◆ nanocoap_notify_observers()

void nanocoap_notify_observers	(	const coap_resource_t *	res,
		const iolist_t *	iol )

Notify all currently registered observers of the given resource.

Parameters

[in]	res	Resource to send updates for
[in]	iol	I/O list containing the CoAP Options, payload marker, and payload of the update to send up

Precondition: iol contains everything but the CoAP header needed to send out. This will at least be a CoAP observe option, a payload marker, and a payload

Postcondition: For each registered observer a CoAP packet header is generated and the concatenation of that header and the provided list is sent

◆ nanocoap_notify_observers_simple()

void nanocoap_notify_observers_simple	(	const coap_resource_t *	res,
		uint32_t	obs,
		const void *	payload,
		size_t	payload_len )

Build and send notification to observers registered to a specific resource.

Note: Use nanocoap_notify_observers for more control (such as adding custom options) over the notification(s) to send.

Parameters

[in]	res	Resource to send updates for
[in]	obs	24-bit number to add as observe option
[in]	payload	Payload to send out
[in]	payload_len	Length of `payload` in bytes

◆ nanocoap_register_observer()

int nanocoap_register_observer	(	const coap_request_ctx_t *	req_ctx,
		coap_pkt_t *	req_pkt )

Register an observer.

Parameters

[in]	req_ctx	Request context belonging to `req_pkt`
[in,out]	req_pkt	Request that contained the observe registration request

Warning: This depends on module nanocoap_server_observe

Note: If the same endpoint already was registered on the same resource, it will just update the token and keep the existing entry. This way duplicate detection is not needed and we eagerly can reclaim resources when a client lost state.

Warning: Preventing the same endpoint to registers more than once (using different tokens) to the same resource deviates from RFC 7641.

The deviation here is intentional. A server can receive a second registration from the same endpoint for the same resource for one of the following reasons:

Reaffirming the registration by using the same token again.
Losing state on the client side.
A malicious client trying to exhaust resources.
The same resource has different representations depending on the request. (E.g. /.well-known/core can yield a wildly different response depending on filters provided via URI-Query Options.)

For case 1 updating the registration is matching what the spec mandates. For two the old registration will not be of value for the client, and overwriting it makes more efficient use of network bandwidth and RAM. For 3 the deviation forces the adversary to send observe requests from different ports to exhaust resources, which is a very minor improvement. For 4 the deviation is a problem. However, the observe API does not allow to send out different notification messages for the same resource anyway, so case 4 cannot occur here.

Return values

0	Success
-ENOMEM	Not enough resources to register another observer
<0	Negative errno code indicating error

◆ nanocoap_request()

ssize_t nanocoap_request	(	coap_pkt_t *	pkt,
		const sock_udp_ep_t *	local,
		const sock_udp_ep_t *	remote,
		size_t	len )

Simple synchronous CoAP request.

Parameters

[in,out]	pkt	Packet struct containing the request. Is reused for the response
[in]	local	Local UDP endpoint, may be NULL
[in]	remote	remote UDP endpoint
[in]	len	Total length of the buffer associated with the request

Returns: length of response on success

See also: nanocoap_sock_request_cb on error

◆ nanocoap_server()

int nanocoap_server	(	sock_udp_ep_t *	local,
		uint8_t *	buf,
		size_t	bufsize )

Start a nanocoap server instance.

This function only returns if there's an error binding to local, or if receiving of UDP packets fails.

Parameters

[in]	local	local UDP endpoint to bind to
[in]	buf	input buffer to use
[in]	bufsize	size of `buf`

Returns: -1 on error

◆ nanocoap_server_build_separate()

ssize_t nanocoap_server_build_separate	(	const nanocoap_server_response_ctx_t *	ctx,
		void *	buf,
		size_t	buf_len,
		unsigned	code,
		unsigned	type,
		uint16_t	msg_id )

Build a separate response header to a CoAP request.

This builds the response packet header. You may add CoAP Options, a payload marker and a payload as needed after the header.

Precondition: nanocoap_server_prepare_separate has been called on ctx inside the CoAP handler; Synchronization between calls of this function and calls of nanocoap_server_prepare_separate is ensured

Warning: This function is only available when using the module nanocoap_server_separate

Parameters

[in]	ctx	Context information for the CoAP response
[out]	buf	Buffer to write the header to
[in]	buf_len	Length of `buf` in bytes
[in]	code	CoAP response code
[in]	type	Response type, may be `COAP_TYPE_NON`
[in]	msg_id	Message ID to send

Returns: Length of the header build in bytes

Return values

-ECANCELED	Request contained no-response option that did match the given `code`
<0	Negative errno code indicating the error

◆ nanocoap_server_is_remote_in_response_ctx()

bool nanocoap_server_is_remote_in_response_ctx	(	const nanocoap_server_response_ctx_t *	ctx,
		const coap_request_ctx_t *	req )

Check if a given separate response context was prepared for the remote endpoint of a given request.

Parameters

[in]	ctx	Separate response context to check
[in]	req	Request from the remote to check for

Return values

true	The remote endpoint given by `req` is in `ctx`
false	`ctx` was prepared for a different remote endpoint

◆ nanocoap_server_prepare_separate()

int nanocoap_server_prepare_separate	(	nanocoap_server_response_ctx_t *	ctx,
		coap_pkt_t *	pkt,
		const coap_request_ctx_t *	req )

Prepare the context for a separate response.

This function serializes the CoAP request information so that a separate response can be generated outside the CoAP handler.

The CoAP handler should then respond with an empty ACK by calling coap_build_empty_ack

Warning: This function is only available when using the module nanocoap_server_separate

Parameters

[out]	ctx	Context information for separate response
[in]	pkt	CoAP packet to which the response will be generated
[in]	req	Context of the CoAP request

Return values

0	Success
-EOVERFLOW	Storing context would have overflown buffers in `ctx` (e.g. RFC 8974 (module `nanocoap_token_ext`) is in use and token too long)
<0	Other error

◆ nanocoap_server_send_separate()

int nanocoap_server_send_separate	(	const nanocoap_server_response_ctx_t *	ctx,
		unsigned	code,
		unsigned	type,
		const void *	payload,
		size_t	len )

Build and send a separate response to a CoAP request.

This sends a response to a CoAP request outside the CoAP handler

Precondition: nanocoap_server_prepare_separate has been called on ctx inside the CoAP handler; Synchronization between calls of this function and calls of nanocoap_server_prepare_separate is ensured

Warning: This function is only available when using the module nanocoap_server_separate

Parameters

[in]	ctx	Context information for the CoAP response
[in]	code	CoAP response code
[in]	type	Response type, may be `COAP_TYPE_NON`
[in]	payload	Response payload
[in]	len	Payload length

Return values

0	Success
-ECANCELED	Request contained no-response option that did match the given `code`
<0	Negative errno code indicating the error

◆ nanocoap_server_sendv_separate()

int nanocoap_server_sendv_separate	(	const nanocoap_server_response_ctx_t *	ctx,
		const iolist_t *	reply )

Send an already build separate response.

Precondition: nanocoap_server_prepare_separate has been called on ctx inside the CoAP handler; Synchronization between calls of this function and calls of nanocoap_server_prepare_separate is ensured; nanocoap_server_build_separate has been used to build the header in msg

Warning: This function is only available when using the module nanocoap_server_separate

Parameters

[in]	ctx	Context information for the CoAP response
[in]	reply	I/O list containing the reply to send

Return values

0	Success
<0	negative errno code indicating the error

◆ nanocoap_server_start()

kernel_pid_t nanocoap_server_start ( const sock_udp_ep_t * local )

Create and start the nanoCoAP server thread.

To automatically start the nanoCoAP server on startup, select the nanocoap_server_auto_init module.

Parameters

[in] local UDP endpoint to bind to

Returns: pid of the server thread

◆ nanocoap_sock_block_request()

int nanocoap_sock_block_request	(	coap_block_request_t *	ctx,
		const void *	data,
		size_t	len,
		bool	more,
		coap_request_cb_t	cb,
		void *	arg )

Do a block-wise request, send a single block.

     This method is expected to be called in a loop until all
     payload blocks have been transferred.

Precondition: ctx was initialized with nanocoap_block_request_connect_url or manually.

Parameters

[in]	ctx	blockwise request context
[in]	data	payload to send
[in]	len	payload length
[in]	more	more blocks after this one (will be set automatically if `len` > block size)
[in]	cb	callback for response
[in]	arg	callback context

Returns: Number of payload bytes written on success Negative error on failure

◆ nanocoap_sock_close()

static void nanocoap_sock_close ( nanocoap_sock_t * sock )

inlinestatic

Close a CoAP client socket.

Parameters

[in] sock CoAP UDP socket

Definition at line 542 of file nanocoap_sock.h.

◆ nanocoap_sock_connect()

static int nanocoap_sock_connect	(	nanocoap_sock_t *	sock,
		const sock_udp_ep_t *	local,
		const sock_udp_ep_t *	remote )

inlinestatic

Create a CoAP client socket.

Parameters

[out]	sock	CoAP UDP socket
[in]	local	Local UDP endpoint, may be NULL
[in]	remote	remote UDP endpoint

Returns: 0 on success; <0 on error

Definition at line 497 of file nanocoap_sock.h.

◆ nanocoap_sock_delete()

ssize_t nanocoap_sock_delete	(	nanocoap_sock_t *	sock,
		const char *	path )

Simple synchronous CoAP (confirmable) DELETE.

Parameters

[in]	sock	socket to use for the request
[in]	path	remote path (with query) to delete

Returns: 0 on success

See also: nanocoap_sock_request_cb on error

◆ nanocoap_sock_delete_url()

ssize_t nanocoap_sock_delete_url ( const char * url )

Simple synchronous CoAP (confirmable) DELETE for URL.

Parameters

[in] url URL of the resource that should be deleted

Returns: 0 on success; <0 on error

◆ nanocoap_sock_dtls_connect()

int nanocoap_sock_dtls_connect	(	nanocoap_sock_t *	sock,
		sock_udp_ep_t *	local,
		const sock_udp_ep_t *	remote,
		credman_tag_t	tag )

Create a DTLS secured CoAP client socket.

Parameters

[out]	sock	CoAP UDP socket
[in]	local	Local UDP endpoint, may be NULL
[in]	remote	remote UDP endpoint
[in]	tag	Tag of the PSK credential to use Has to be added with credman_add

Returns: 0 on success; <0 on error

◆ nanocoap_sock_fetch()

ssize_t nanocoap_sock_fetch	(	nanocoap_sock_t *	sock,
		const char *	path,
		const void *	request,
		size_t	len,
		void *	response,
		size_t	len_max )

Simple synchronous CoAP (confirmable) FETCH (RFC 8132)

Parameters

[in]	sock	socket to use for the request
[in]	path	remote path and query
[in]	request	buffer containing the payload
[in]	len	length of the payload to send
[out]	response	buffer for the response, may be NULL
[in]	len_max	length of `response`

Returns: length of response payload on success

See also: nanocoap_sock_request_cb on error

◆ nanocoap_sock_fetch_non()

ssize_t nanocoap_sock_fetch_non	(	nanocoap_sock_t *	sock,
		const char *	path,
		const void *	request,
		size_t	len,
		void *	response,
		size_t	len_max )

Simple non-confirmable FETCH (RFC 8132)

Parameters

[in]	sock	socket to use for the request
[in]	path	remote path and query
[in]	request	buffer containing the payload
[in]	len	length of the payload to send
[out]	response	buffer for the response, may be NULL
[in]	len_max	length of `response`

Returns: length of response payload on success; 0 if the request was sent and no response buffer was provided, independently of success (because no response is requested in that case)

See also: nanocoap_sock_request_cb on error

◆ nanocoap_sock_fetch_url()

ssize_t nanocoap_sock_fetch_url	(	const char *	url,
		const void *	request,
		size_t	len,
		void *	response,
		size_t	len_max )

Simple synchronous CoAP (confirmable) FETCH to URL (RFC 8132)

Parameters

[in]	url	Absolute URL pointer to source path
[in]	request	buffer containing the payload
[in]	len	length of the payload to send
[out]	response	buffer for the response, may be NULL
[in]	len_max	length of `response`

Returns: length of response payload on success; <0 on error

◆ nanocoap_sock_get()

ssize_t nanocoap_sock_get	(	nanocoap_sock_t *	sock,
		const char *	path,
		void *	buf,
		size_t	len )

Simple synchronous CoAP (confirmable) GET.

Parameters

[in]	sock	socket to use for the request
[in]	path	remote path and query
[out]	buf	buffer to write response to
[in]	len	length of `buffer`

Returns: length of response payload on success

See also: nanocoap_sock_request_cb on error

◆ nanocoap_sock_get_blockwise()

int nanocoap_sock_get_blockwise	(	nanocoap_sock_t *	sock,
		const char *	path,
		coap_blksize_t	blksize,
		coap_blockwise_cb_t	callback,
		void *	arg )

Performs a blockwise coap get request on a socket.

This function will fetch the content of the specified resource path via block-wise-transfer. A coap_blockwise_cb_t will be called on each received block.

Parameters

[in]	sock	socket to use for the request
[in]	path	pointer to source path
[in]	blksize	sender suggested SZX for the COAP block request
[in]	callback	callback to be executed on each received block
[in]	arg	optional function arguments

Returns: -1 if failed to fetch the url content; 0 on success

◆ nanocoap_sock_get_non()

ssize_t nanocoap_sock_get_non	(	nanocoap_sock_t *	sock,
		const char *	path,
		void *	response,
		size_t	len_max )

Simple non-confirmable GET.

Parameters

[in]	sock	socket to use for the request
[in]	path	remote path and query
[out]	response	buffer for the response, may be NULL
[in]	len_max	length of `response`

Returns: length of response payload on success

See also: nanocoap_sock_request_cb on error

◆ nanocoap_sock_get_slice()

int nanocoap_sock_get_slice	(	nanocoap_sock_t *	sock,
		const char *	path,
		coap_blksize_t	blksize,
		size_t	offset,
		void *	dst,
		size_t	len )

Performs a blockwise coap get request to the specified url, store the response in a buffer.

Parameters

[in]	sock	socket to use for the request
[in]	path	Absolute URL pointer to source path
[in]	blksize	sender suggested SZX for the COAP block request
[in]	offset	Offset in bytes from the start of the resource
[in]	dst	Target buffer
[in]	len	Target buffer length

Returns: <0 on error; -EINVAL if an invalid url is provided; size of the response payload on success

◆ nanocoap_sock_next_msg_id()

static uint16_t nanocoap_sock_next_msg_id ( nanocoap_sock_t * sock )

inlinestatic

Get next consecutive message ID for use when building a new CoAP request.

Parameters

[in] sock CoAP socket on which the ID is used

Returns: A new message ID that can be used for a request or response.

Definition at line 456 of file nanocoap_sock.h.

◆ nanocoap_sock_post()

ssize_t nanocoap_sock_post	(	nanocoap_sock_t *	sock,
		const char *	path,
		const void *	request,
		size_t	len,
		void *	response,
		size_t	len_max )

Simple synchronous CoAP (confirmable) POST.

Parameters

[in]	sock	socket to use for the request
[in]	path	remote path and query
[in]	request	buffer containing the payload
[in]	len	length of the payload to send
[out]	response	buffer for the response, may be NULL
[in]	len_max	length of `response`

Returns: length of response payload on success

See also: nanocoap_sock_request_cb on error

◆ nanocoap_sock_post_non()

ssize_t nanocoap_sock_post_non	(	nanocoap_sock_t *	sock,
		const char *	path,
		const void *	request,
		size_t	len,
		void *	response,
		size_t	len_max )

Simple non-confirmable POST.

Parameters

[in]	sock	socket to use for the request
[in]	path	remote path and query
[in]	request	buffer containing the payload
[in]	len	length of the payload to send
[out]	response	buffer for the response, may be NULL
[in]	len_max	length of `response`

Returns: length of response payload on success; 0 if the request was sent and no response buffer was provided, independently of success (because no response is requested in that case)

See also: nanocoap_sock_request_cb on error

◆ nanocoap_sock_post_url()

ssize_t nanocoap_sock_post_url	(	const char *	url,
		const void *	request,
		size_t	len,
		void *	response,
		size_t	len_max )

Simple synchronous CoAP (confirmable) POST to URL.

Parameters

[in]	url	Absolute URL pointer to source path
[in]	request	buffer containing the payload
[in]	len	length of the payload to send
[out]	response	buffer for the response, may be NULL
[in]	len_max	length of `response`

Returns: length of response payload on success; <0 on error

◆ nanocoap_sock_put()

ssize_t nanocoap_sock_put	(	nanocoap_sock_t *	sock,
		const char *	path,
		const void *	request,
		size_t	len,
		void *	response,
		size_t	len_max )

Simple synchronous CoAP (confirmable) PUT.

Parameters

[in]	sock	socket to use for the request
[in]	path	remote path and query
[in]	request	buffer containing the payload
[in]	len	length of the payload to send
[out]	response	buffer for the response, may be NULL
[in]	len_max	length of `response`

Returns: length of response payload on success

See also: nanocoap_sock_request_cb on error

◆ nanocoap_sock_put_non()

ssize_t nanocoap_sock_put_non	(	nanocoap_sock_t *	sock,
		const char *	path,
		const void *	request,
		size_t	len,
		void *	response,
		size_t	len_max )

Simple non-confirmable PUT.

Parameters

[in]	sock	socket to use for the request
[in]	path	remote path and query
[in]	request	buffer containing the payload
[in]	len	length of the payload to send
[out]	response	buffer for the response, may be NULL
[in]	len_max	length of `response`

Returns: length of response payload on success; 0 if the request was sent and no response buffer was provided, independently of success (because no response is requested in that case)

See also: nanocoap_sock_request_cb on error

◆ nanocoap_sock_put_url()

ssize_t nanocoap_sock_put_url	(	const char *	url,
		const void *	request,
		size_t	len,
		void *	response,
		size_t	len_max )

Simple synchronous CoAP (confirmable) PUT to URL.

Parameters

[in]	url	Absolute URL pointer to source path
[in]	request	buffer containing the payload
[in]	len	length of the payload to send
[out]	response	buffer for the response, may be NULL
[in]	len_max	length of `response`

Returns: length of response payload on success; <0 on error

◆ nanocoap_sock_request()

ssize_t nanocoap_sock_request	(	nanocoap_sock_t *	sock,
		coap_pkt_t *	pkt,
		size_t	len )

Simple synchronous CoAP request.

Parameters

[in]	sock	socket to use for the request
[in,out]	pkt	Packet struct containing the request. Is reused for the response
[in]	len	Total length of the buffer associated with the request

Returns: length of response on success; <0 on error

◆ nanocoap_sock_request_cb()

ssize_t nanocoap_sock_request_cb	(	nanocoap_sock_t *	sock,
		coap_pkt_t *	pkt,
		coap_request_cb_t	cb,
		void *	arg )

Simple synchronous CoAP request with callback.

     The response will be handled by a callback, which avoids copying the
     response packet out of the network stack internal buffer.

Parameters

[in]	sock	socket to use for the request
[in,out]	pkt	Packet struct containing the request. Is reused for the response
[in]	cb	Callback executed for response packet
[in]	arg	Optional callback argumnent

Returns: length of response on success; 0 for a request for which no response is expected, indicated by cb == NULL, or for a 2.xx response; -ETIMEDOUT, if no matching ACK or no response was received; -EBADMSG, if a matching RST was received; -ENXIO, if cb == NULL and the response indicates a 4.xx client error; -ENETRESET, if cb == NULL and the response indicates a 5.xx server error; any error on

See also: sock_udp_sendv or; sock_dtls_sendv

Returns: any error on

See also: sock_udp_recv_buf or; sock_dtls_recv_buf

Returns: any return value of cb for a matching response

◆ nanocoap_sock_url_connect()

int nanocoap_sock_url_connect	(	const char *	url,
		nanocoap_sock_t *	sock )

Create a CoAP client socket by URL.

Parameters

[in]	url	URL with server information to connect to
[out]	sock	CoAP UDP socket

Returns: 0 on success; <0 on error

◆ nanocoap_unregister_observer()

void nanocoap_unregister_observer	(	const coap_request_ctx_t *	req_ctx,
		const coap_pkt_t *	req_pkt )

Unregister an observer.

Parameters

req_ctx	Request context belonging to `req_pkt`
req_pkt	Received request for unregistration

Warning: This depends on module nanocoap_server_observe

Note: It is safe to call this multiple times, e.g. duplicate detection is not needed for this.

◆ nanocoap_unregister_observer_due_to_reset()

void nanocoap_unregister_observer_due_to_reset	(	const sock_udp_ep_t *	ep,
		uint16_t	msg_id )

Unregister a stale observation due to a reset message received.

Parameters

[in]	ep	Endpoint to wipe from the observer list
[in]	msg_id	Message ID of the notification send.

Detailed Description

Server Operation

Handler functions

Client Operation

Write Options and Payload

Create a Block-wise Response (Block2)

Files

Data Structures

Macros

Enumerations

Functions

Macro Definition Documentation

◆ CONFIG_NANOCOAP_SERVER_BUF_SIZE

◆ CONFIG_NANOCOAP_SERVER_STACK_SIZE

◆ CONFIG_NANOCOAP_SOCK_BLOCK_TOKEN

◆ CONFIG_NANOCOAP_SOCK_DTLS_TAG

Enumeration Type Documentation

◆ nanocoap_socket_type_t

Function Documentation

◆ nanocoap_block_request_connect_url()

◆ nanocoap_get_blockwise_to_buf()

◆ nanocoap_get_blockwise_url()

◆ nanocoap_get_blockwise_url_to_buf()

◆ nanocoap_notify_observers()

◆ nanocoap_notify_observers_simple()

◆ nanocoap_register_observer()

◆ nanocoap_request()

◆ nanocoap_server()

◆ nanocoap_server_build_separate()

◆ nanocoap_server_is_remote_in_response_ctx()

◆ nanocoap_server_prepare_separate()

◆ nanocoap_server_send_separate()

◆ nanocoap_server_sendv_separate()

◆ nanocoap_server_start()

◆ nanocoap_sock_block_request()

◆ nanocoap_sock_close()

◆ nanocoap_sock_connect()

◆ nanocoap_sock_delete()

◆ nanocoap_sock_delete_url()

◆ nanocoap_sock_dtls_connect()

◆ nanocoap_sock_fetch()

◆ nanocoap_sock_fetch_non()

◆ nanocoap_sock_fetch_url()

◆ nanocoap_sock_get()

◆ nanocoap_sock_get_blockwise()

◆ nanocoap_sock_get_non()

◆ nanocoap_sock_get_slice()

◆ nanocoap_sock_next_msg_id()

◆ nanocoap_sock_post()

◆ nanocoap_sock_post_non()

◆ nanocoap_sock_post_url()

◆ nanocoap_sock_put()

◆ nanocoap_sock_put_non()

◆ nanocoap_sock_put_url()

◆ nanocoap_sock_request()

◆ nanocoap_sock_request_cb()

◆ nanocoap_sock_url_connect()

◆ nanocoap_unregister_observer()

◆ nanocoap_unregister_observer_due_to_reset()