CoAP client API

CoAP client API. More...

Data Structures
struct	coap_client_response_data
	Representation for CoAP client response data. More...
struct	coap_client_request
	Representation of a CoAP client request. More...
struct	coap_client_option
	Representation of extra options for the CoAP client request. More...

Macros
#define	MAX_COAP_MSG_LEN
	Maximum size of a CoAP message.

Typedefs
typedef void(*	coap_client_response_cb_t) (const struct coap_client_response_data *data, void *user_data)
	Callback for CoAP request.
typedef int(*	coap_client_payload_cb_t) (size_t offset, const uint8_t **payload, size_t *len, bool *last_block, void *user_data)
	Callback for providing a payload for the CoAP request.

Functions
int	coap_client_init (struct coap_client *client, const char *info)
	Initialize the CoAP client.
int	coap_client_req (struct coap_client *client, int sock, const struct sockaddr *addr, struct coap_client_request *req, struct coap_transmission_parameters *params)
	Send CoAP request.
void	coap_client_cancel_requests (struct coap_client *client)
	Cancel all current requests.
void	coap_client_cancel_request (struct coap_client *client, struct coap_client_request *req)
	Cancel matching requests.
struct coap_client_option	coap_client_option_initial_block2 (void)
	Initialise a Block2 option to be added to a request.
bool	coap_client_has_ongoing_exchange (struct coap_client *client)
	Check if client has ongoing exchange.

Detailed Description

CoAP client API.

Since

3.4

Version

0.1.0

Macro Definition Documentation

MAX_COAP_MSG_LEN

#define MAX_COAP_MSG_LEN

#include <zephyr/net/coap_client.h>

Value:

                          (CONFIG_COAP_CLIENT_MESSAGE_HEADER_SIZE + \
                          CONFIG_COAP_CLIENT_MESSAGE_SIZE)

Maximum size of a CoAP message.

Typedef Documentation

coap_client_payload_cb_t

typedef int(* coap_client_payload_cb_t) (size_t offset, const uint8_t **payload, size_t *len, bool *last_block, void *user_data)

#include <zephyr/net/coap_client.h>

Callback for providing a payload for the CoAP request.

An optional callback for providing a payload for CoAP client requests. If set in coap_client_request, the CoAP client library will call this callback when preparing a PUT/POST request (note that this is also true for retransmissions).

When called, the library provides the application with the current payload offset for the transfer and the payload block size. In return, the application sets the payload pointer, payload size and information whether more data blocks are expected. Setting the last_block parameter to false on the initial callback call triggers a block transfer upload. The library will keep calling the callback until the last_block parameter is set to false.

Note

If block transfer is used, the application is expected to provide full blocks of payload. Only the final block (i.e. when last_block is set to true) can be shorter than the requested block size.

Parameters

offset	Payload offset from the beginning of a blockwise transfer.
payload	A pointer for the buffer containing the payload block.
len	Requested (maximum) block size on input. The actual payload length on output.
last_block	A pointer to the flag indicating whether more payload blocks are expected.
user_data	User provided context.

Returns

Zero on success, a negative error code to abort upload.

coap_client_response_cb_t

typedef void(* coap_client_response_cb_t) (const struct coap_client_response_data *data, void *user_data)

#include <zephyr/net/coap_client.h>

Callback for CoAP request.

This callback is called for responses to CoAP client requests. It is used to indicate errors, response codes from server or to deliver payload. Blockwise transfers cause this callback to be called sequentially with increasing payload offset and only partial content in buffer pointed by payload parameter.

Parameters

data	The CoAP response data.
user_data	User provided context.

Function Documentation

coap_client_cancel_request()

void coap_client_cancel_request	(	struct coap_client *	client,
		struct coap_client_request *	req )

#include <zephyr/net/coap_client.h>

Cancel matching requests.

This function cancels all CoAP client request that matches the given request. The request is matched based on the method, path, callback and user_data, if provided. Any field set to NULL is considered a wildcard.

(struct coap_client_request){0} cancels all requests. (struct coap_client_request){.method = COAP_METHOD_GET} cancels all GET requests.

Parameters

client	Pointer to the CoAP client instance.
req	Pointer to the CoAP client request to be canceled.

coap_client_cancel_requests()

void coap_client_cancel_requests

(

struct coap_client *

client

)

#include <zephyr/net/coap_client.h>

Cancel all current requests.

This is intended for canceling long-running requests (e.g. GETs with the OBSERVE option set) which has gone stale for some reason. The function should also be called before the corresponding client socket is closed, to prevent the socket from being monitored by the internal polling thread.

Parameters

client

Client instance.

coap_client_has_ongoing_exchange()

bool coap_client_has_ongoing_exchange

(

struct coap_client *

client

)

#include <zephyr/net/coap_client.h>

Check if client has ongoing exchange.

Note

Function not only considers ongoing requests, but also lifetime of completed requests (which provides graceful duplicates handling).

For socket handling. Function does no consider a socket POLL that has started before this call, therefore it is recommended to wait out POLL timeout before closing socket (e.g. call coap_client_cancel_requests() which applies delay for timeout).

Parameters

client

Pointer to the CoAP client instance.

Returns

true if there is an ongoing exchange, false otherwise.

coap_client_init()

int coap_client_init	(	struct coap_client *	client,
		const char *	info )

#include <zephyr/net/coap_client.h>

Initialize the CoAP client.

Parameters

[in]	client	Client instance.
[in]	info	Name for the receiving thread of the client. Setting this NULL will result as default name of "coap_client".

Returns

int Zero on success, otherwise a negative error code.

coap_client_option_initial_block2()

struct coap_client_option coap_client_option_initial_block2

(

void

)

#include <zephyr/net/coap_client.h>

Initialise a Block2 option to be added to a request.

If the application expects a request to require a blockwise transfer, it may pre-emptively suggest a maximum block size to the server - see RFC7959 Figure 3: Block-Wise GET with Early Negotiation.

This helper function returns a Block2 option to send with the initial request.

Returns

CoAP client initial Block2 option structure

coap_client_req()

int coap_client_req	(	struct coap_client *	client,
		int	sock,
		const struct sockaddr *	addr,
		struct coap_client_request *	req,
		struct coap_transmission_parameters *	params )

#include <zephyr/net/coap_client.h>

Send CoAP request.

Operation is handled asynchronously using a background thread. If the socket isn't connected to a destination address, user must provide a destination address, otherwise the address should be set as NULL. Once the callback is called with last block set as true, socket can be closed or used for another query.

Parameters

client	Client instance.
sock	Open socket file descriptor.
addr	the destination address of the request, NULL if socket is already connected.
req	CoAP request structure
params	Pointer to transmission parameters structure or NULL to use default values.

Returns

zero when operation started successfully or negative error code otherwise.