CoAP service API

CoAP Service API. More...

Macros
#define	COAP_RESOURCE_DEFINE(_name, _service, ...)
	Define a static CoAP resource owned by the service named _service .
#define	COAP_SERVICE_DEFINE(_name, _host, _port, _flags)
	Define a CoAP service with static resources.
#define	COAP_SERVICE_COUNT(_dst)   STRUCT_SECTION_COUNT(coap_service, _dst)
	Count the number of CoAP services.
#define	COAP_SERVICE_RESOURCE_COUNT(_service)   ((_service)->res_end - (_service)->res_begin)
	Count CoAP service static resources.
#define	COAP_SERVICE_HAS_RESOURCE(_service, _resource)    ((_service)->res_begin <= _resource && _resource < (_service)->res_end)
	Check if service has the specified resource.
#define	COAP_SERVICE_FOREACH(_it)   STRUCT_SECTION_FOREACH(coap_service, _it)
	Iterate over all CoAP services.
#define	COAP_RESOURCE_FOREACH(_service, _it)    STRUCT_SECTION_FOREACH_ALTERNATE(coap_resource_##_service, coap_resource, _it)
	Iterate over static CoAP resources associated with a given _service.
#define	COAP_SERVICE_FOREACH_RESOURCE(_service, _it)
	Iterate over all static resources associated with _service .

Functions
int	coap_service_start (const struct coap_service *service)
	Start the provided service .
int	coap_service_stop (const struct coap_service *service)
	Stop the provided service .
int	coap_service_is_running (const struct coap_service *service)
	Query the provided service running state.
int	coap_service_send (const struct coap_service *service, const struct coap_packet *cpkt, const struct sockaddr *addr, socklen_t addr_len, const struct coap_transmission_parameters *params)
	Send a CoAP message from the provided service .
int	coap_resource_send (const struct coap_resource *resource, const struct coap_packet *cpkt, const struct sockaddr *addr, socklen_t addr_len, const struct coap_transmission_parameters *params)
	Send a CoAP message from the provided resource .
int	coap_resource_parse_observe (struct coap_resource *resource, const struct coap_packet *request, const struct sockaddr *addr)
	Parse a CoAP observe request for the provided resource .
int	coap_resource_remove_observer_by_addr (struct coap_resource *resource, const struct sockaddr *addr)
	Lookup an observer by address and remove it from the resource .
int	coap_resource_remove_observer_by_token (struct coap_resource *resource, const uint8_t *token, uint8_t token_len)
	Lookup an observer by token and remove it from the resource .

CoAP Service configuration flags
#define	COAP_SERVICE_AUTOSTART   BIT(0)
	Start the service on boot.

Detailed Description

CoAP Service API.

Macro Definition Documentation

COAP_RESOURCE_DEFINE

#define COAP_RESOURCE_DEFINE	(		_name,
			_service,
			...
	)

#include <include/zephyr/net/coap_service.h>

Value:

        STRUCT_SECTION_ITERABLE_ALTERNATE(coap_resource_##_service, coap_resource, _name)       \
                = __VA_ARGS__

Define a static CoAP resource owned by the service named _service .

Note

The handlers registered with the resource can return a CoAP response code to reply with an acknowledge without any payload, nothing is sent if the return value is 0 or negative. As seen in the example.

static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(DT_ALIAS(led0), gpios);
 
static int led_put(struct coap_resource *resource, struct coap_packet *request,
                   struct sockaddr *addr, socklen_t addr_len)
{
        const uint8_t *payload;
        uint16_t payload_len;
 
        payload = coap_packet_get_payload(request, &payload_len);
        if (payload_len != 1) {
                return COAP_RESPONSE_CODE_BAD_REQUEST;
        }
 
        if (gpio_pin_set_dt(&led, payload[0]) < 0) {
                return COAP_RESPONSE_CODE_INTERNAL_ERROR;
        }
 
        return COAP_RESPONSE_CODE_CHANGED;
}
 
COAP_RESOURCE_DEFINE(my_resource, my_service, {
        .put = led_put,
});

Parameters

_name	Name of the resource.
_service	Name of the associated service.

COAP_RESOURCE_FOREACH

#define COAP_RESOURCE_FOREACH	(		_service,
			_it
	)		STRUCT_SECTION_FOREACH_ALTERNATE(coap_resource_##_service, coap_resource, _it)

#include <include/zephyr/net/coap_service.h>

Iterate over static CoAP resources associated with a given _service.

Note

This macro requires that _service is defined with COAP_SERVICE_DEFINE.

Parameters

_service	Name of CoAP service
_it	Name of iterator (of type coap_resource)

COAP_SERVICE_AUTOSTART

#define COAP_SERVICE_AUTOSTART   BIT(0)

#include <include/zephyr/net/coap_service.h>

Start the service on boot.

COAP_SERVICE_COUNT

#define COAP_SERVICE_COUNT

(

_dst

)

STRUCT_SECTION_COUNT(coap_service, _dst)

#include <include/zephyr/net/coap_service.h>

Count the number of CoAP services.

Parameters

[out]

_dst

Pointer to location where result is written.

COAP_SERVICE_DEFINE

#define COAP_SERVICE_DEFINE	(		_name,
			_host,
			_port,
			_flags
	)

#include <include/zephyr/net/coap_service.h>

Value:

        extern struct coap_resource _CONCAT(_coap_resource_##_name, _list_start)[];             \
        extern struct coap_resource _CONCAT(_coap_resource_##_name, _list_end)[];               \
        __z_coap_service_define(_name, _host, _port, _flags,                                    \
                                &_CONCAT(_coap_resource_##_name, _list_start)[0],               \
                                &_CONCAT(_coap_resource_##_name, _list_end)[0])

Define a CoAP service with static resources.

Note

The _host parameter can be NULL. If not, it is used to specify an IP address either in IPv4 or IPv6 format a fully-qualified hostname or a virtual host, otherwise the any address is used.

The _port parameter must be non-NULL. It points to a location that specifies the port number to use for the service. If the specified port number is zero, then an ephemeral port number will be used and the actual port number assigned will be written back to memory. For ephemeral port numbers, the memory pointed to by _port must be writeable.

Parameters

	_name	Name of the service.
	_host	IP address or hostname associated with the service.
[in,out]	_port	Pointer to port associated with the service.
	_flags	Configuration flags

See also

COAP_SERVICE_FLAGS.

COAP_SERVICE_FOREACH

#define COAP_SERVICE_FOREACH

(

_it

)

STRUCT_SECTION_FOREACH(coap_service, _it)

#include <include/zephyr/net/coap_service.h>

Iterate over all CoAP services.

Parameters

_it	Name of iterator (of type CoAP service API)

COAP_SERVICE_FOREACH_RESOURCE

#define COAP_SERVICE_FOREACH_RESOURCE	(		_service,
			_it
	)

#include <include/zephyr/net/coap_service.h>

Value:

        for (struct coap_resource *_it = (_service)->res_begin; ({                              \
                __ASSERT(_it <= (_service)->res_end, "unexpected list end location");           \
                _it < (_service)->res_end;                                                      \
        }); _it++)

Iterate over all static resources associated with _service .

Note

This macro is suitable for a _service defined with COAP_SERVICE_DEFINE.

Parameters

_service	Pointer to COAP service
_it	Name of iterator (of type coap_resource)

COAP_SERVICE_HAS_RESOURCE

#define COAP_SERVICE_HAS_RESOURCE	(		_service,
			_resource
	)		((_service)->res_begin <= _resource && _resource < (_service)->res_end)

#include <include/zephyr/net/coap_service.h>

Check if service has the specified resource.

Parameters

_service	Pointer to a service.
_resource	Pointer to a resource.

COAP_SERVICE_RESOURCE_COUNT

#define COAP_SERVICE_RESOURCE_COUNT

(

_service

)

((_service)->res_end - (_service)->res_begin)

#include <include/zephyr/net/coap_service.h>

Count CoAP service static resources.

Parameters

_service

Pointer to a service.

Function Documentation

coap_resource_parse_observe()

int coap_resource_parse_observe	(	struct coap_resource *	resource,
		const struct coap_packet *	request,
		const struct sockaddr *	addr
	)

#include <include/zephyr/net/coap_service.h>

Parse a CoAP observe request for the provided resource .

Note

This function is suitable for a resource defined with COAP_RESOURCE_DEFINE.

If the observe option value is equal to 0, an observer will be added, if the value is equal to 1, an existing observer will be removed.

Parameters

resource	Pointer to CoAP resource
request	CoAP request to parse
addr	Peer address

Returns

the observe option value in case of success or negative in case of error.

coap_resource_remove_observer_by_addr()

int coap_resource_remove_observer_by_addr	(	struct coap_resource *	resource,
		const struct sockaddr *	addr
	)

#include <include/zephyr/net/coap_service.h>

Lookup an observer by address and remove it from the resource .

Note

This function is suitable for a resource defined with COAP_RESOURCE_DEFINE.

Parameters

resource	Pointer to CoAP resource
addr	Peer address

Returns

0 in case of success or negative in case of error.

coap_resource_remove_observer_by_token()

int coap_resource_remove_observer_by_token	(	struct coap_resource *	resource,
		const uint8_t *	token,
		uint8_t	token_len
	)

#include <include/zephyr/net/coap_service.h>

Lookup an observer by token and remove it from the resource .

Note

This function is suitable for a resource defined with COAP_RESOURCE_DEFINE.

Parameters

resource	Pointer to CoAP resource
token	Pointer to the token
token_len	Length of valid bytes in the token

Returns

0 in case of success or negative in case of error.

coap_resource_send()

int coap_resource_send	(	const struct coap_resource *	resource,
		const struct coap_packet *	cpkt,
		const struct sockaddr *	addr,
		socklen_t	addr_len,
		const struct coap_transmission_parameters *	params
	)

#include <include/zephyr/net/coap_service.h>

Send a CoAP message from the provided resource .

Note

This function is suitable for a resource defined with COAP_RESOURCE_DEFINE.

Parameters

resource	Pointer to CoAP resource
cpkt	CoAP Packet to send
addr	Peer address
addr_len	Peer address length
params	Pointer to transmission parameters structure or NULL to use default values.

Returns

0 in case of success or negative in case of error.

coap_service_is_running()

int coap_service_is_running

(

const struct coap_service *

service

)

#include <include/zephyr/net/coap_service.h>

Query the provided service running state.

Note

This function is suitable for a service defined with COAP_SERVICE_DEFINE.

Parameters

service

Pointer to CoAP service

Return values

1	if the service is running
0	if the service is stopped
negative	in case of an error.

coap_service_send()

int coap_service_send	(	const struct coap_service *	service,
		const struct coap_packet *	cpkt,
		const struct sockaddr *	addr,
		socklen_t	addr_len,
		const struct coap_transmission_parameters *	params
	)

#include <include/zephyr/net/coap_service.h>

Send a CoAP message from the provided service .

Note

This function is suitable for a service defined with COAP_SERVICE_DEFINE.

Parameters

service	Pointer to CoAP service
cpkt	CoAP Packet to send
addr	Peer address
addr_len	Peer address length
params	Pointer to transmission parameters structure or NULL to use default values.

Returns

0 in case of success or negative in case of error.

coap_service_start()

int coap_service_start

(

const struct coap_service *

service

)

#include <include/zephyr/net/coap_service.h>

Start the provided service .

Note

This function is suitable for a service defined with COAP_SERVICE_DEFINE.

Parameters

service

Pointer to CoAP service

Return values

0	in case of success.
-EALREADY	in case of an already running service.
-ENOTSUP	in case the server has no valid host and port configuration.

coap_service_stop()

int coap_service_stop

(

const struct coap_service *

service

)

#include <include/zephyr/net/coap_service.h>

Stop the provided service .

Note

This function is suitable for a service defined with COAP_SERVICE_DEFINE.

Parameters

service

Pointer to CoAP service

Return values

0	in case of success.
-EALREADY	in case the service isn't running.