Zephyr API Documentation  3.7.0-rc2
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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 <zephyr/net/coap_service.h>

Value:
STRUCT_SECTION_ITERABLE_ALTERNATE(coap_resource_##_service, coap_resource, _name) \
= __VA_ARGS__
#define STRUCT_SECTION_ITERABLE_ALTERNATE(secname, struct_type, varname)
Defines a new element of alternate data type for an iterable section.
Definition: iterable_sections.h:188
Description of CoAP resource.
Definition: coap.h:263

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) {
}
if (gpio_pin_set_dt(&led, payload[0]) < 0) {
}
}
COAP_RESOURCE_DEFINE(my_resource, my_service, {
.put = led_put,
});
#define COAP_RESOURCE_DEFINE(_name, _service,...)
Define a static CoAP resource owned by the service named _service .
Definition: coap_service.h:111
const uint8_t * coap_packet_get_payload(const struct coap_packet *cpkt, uint16_t *len)
Returns the data pointer and length of the CoAP packet.
@ COAP_RESPONSE_CODE_INTERNAL_ERROR
5.00 - Internal Server Error
Definition: coap.h:186
@ COAP_RESPONSE_CODE_CHANGED
2.04 - Changed
Definition: coap.h:151
@ COAP_RESPONSE_CODE_BAD_REQUEST
4.00 - Bad Request
Definition: coap.h:157
#define DT_ALIAS(alias)
Get a node identifier from /aliases.
Definition: devicetree.h:240
#define GPIO_DT_SPEC_GET(node_id, prop)
Equivalent to GPIO_DT_SPEC_GET_BY_IDX(node_id, prop, 0).
Definition: gpio.h:368
static int gpio_pin_set_dt(const struct gpio_dt_spec *spec, int value)
Set logical level of a output pin from a gpio_dt_spec.
Definition: gpio.h:1645
size_t socklen_t
Length of a socket address.
Definition: net_ip.h:168
__UINT8_TYPE__ uint8_t
Definition: stdint.h:88
__UINT16_TYPE__ uint16_t
Definition: stdint.h:89
Representation of a CoAP Packet.
Definition: coap.h:295
Container for GPIO pin information specified in devicetree.
Definition: gpio.h:288
Generic sockaddr struct.
Definition: net_ip.h:385
Parameters
_nameName of the resource.
_serviceName of the associated service.

◆ COAP_RESOURCE_FOREACH

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

#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
_serviceName of CoAP service
_itName of iterator (of type coap_resource)

◆ COAP_SERVICE_AUTOSTART

#define COAP_SERVICE_AUTOSTART   BIT(0)

#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 <zephyr/net/coap_service.h>

Count the number of CoAP services.

Parameters
[out]_dstPointer to location where result is written.

◆ COAP_SERVICE_DEFINE

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

#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
_nameName of the service.
_hostIP address or hostname associated with the service.
[in,out]_portPointer to port associated with the service.
_flagsConfiguration flags
See also
COAP_SERVICE_FLAGS.

◆ COAP_SERVICE_FOREACH

#define COAP_SERVICE_FOREACH (   _it)    STRUCT_SECTION_FOREACH(coap_service, _it)

#include <zephyr/net/coap_service.h>

Iterate over all CoAP services.

Parameters
_itName of iterator (of type CoAP service API)

◆ COAP_SERVICE_FOREACH_RESOURCE

#define COAP_SERVICE_FOREACH_RESOURCE (   _service,
  _it 
)

#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
_servicePointer to COAP service
_itName 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 <zephyr/net/coap_service.h>

Check if service has the specified resource.

Parameters
_servicePointer to a service.
_resourcePointer to a resource.

◆ COAP_SERVICE_RESOURCE_COUNT

#define COAP_SERVICE_RESOURCE_COUNT (   _service)    ((_service)->res_end - (_service)->res_begin)

#include <zephyr/net/coap_service.h>

Count CoAP service static resources.

Parameters
_servicePointer 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 <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
resourcePointer to CoAP resource
requestCoAP request to parse
addrPeer 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 <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
resourcePointer to CoAP resource
addrPeer 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 <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
resourcePointer to CoAP resource
tokenPointer to the token
token_lenLength 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 <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
resourcePointer to CoAP resource
cpktCoAP Packet to send
addrPeer address
addr_lenPeer address length
paramsPointer 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 <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
servicePointer to CoAP service
Return values
1if the service is running
0if the service is stopped
negativein 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 <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
servicePointer to CoAP service
cpktCoAP Packet to send
addrPeer address
addr_lenPeer address length
paramsPointer 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 <zephyr/net/coap_service.h>

Start the provided service .

Note
This function is suitable for a service defined with COAP_SERVICE_DEFINE.
Parameters
servicePointer to CoAP service
Return values
0in case of success.
-EALREADYin case of an already running service.
-ENOTSUPin case the server has no valid host and port configuration.

◆ coap_service_stop()

int coap_service_stop ( const struct coap_service *  service)

#include <zephyr/net/coap_service.h>

Stop the provided service .

Note
This function is suitable for a service defined with COAP_SERVICE_DEFINE.
Parameters
servicePointer to CoAP service
Return values
0in case of success.
-EALREADYin case the service isn't running.