File syn_coap.h¶

Constrained Application Protocol (CoAP - RFC 7252) implementation.

#include "../common/syn_defs.h"
#include "../port/syn_port_socket.h"
#include "../pt/syn_pt.h"
#include "../sched/syn_task.h"
#include "../util/syn_backoff.h"
#include "syn_dtls.h"
#include "syn_transport.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Classes¶

Type	Name
struct	SYN_CoapBlock CoAP Blockwise Transfer Parameter (RFC 7959).
struct	SYN_CoapMsg Parsed or to-be-serialized CoAP message header.
struct	SYN_CoapOption Single CoAP option (number + opaque value).
struct	SYN_CoapRequest CoAP client request context.
struct	SYN_CoapTransportRequest CoAP request context over generic SYN_Transport (e.g. DTLS 1.3 / UDP / Serial).
struct	SYN_CoapsClient CoAP over DTLS 1.3 Client Session (RFC 7252 Section 12.1.2 & RFC 9147).

Public Functions¶

Type	Name
bool	syn_coap_decode_block_opt (const uint8_t * opt_val, size_t opt_len, SYN_CoapBlock * block) Decode a CoAP Blockwise Option (Block1 / Block2) value (RFC 7959).
size_t	syn_coap_encode_block_opt (const SYN_CoapBlock * block, uint8_t buf) Encode a CoAP Blockwise Option (Block1 / Block2) value (RFC 7959).
SYN_Status	syn_coap_parse (SYN_CoapMsg * msg, SYN_CoapOption * options, size_t max_options, size_t * option_count, const uint8_t * buf, size_t buf_len) Parse a raw CoAP packet into a message structure.
void	syn_coap_request_init (SYN_CoapRequest * r, const SYN_SockAddr * server_addr, const SYN_CoapMsg * msg, uint32_t timeout_ms, uint8_t retries) Initialize a CoAP request context.
SYN_PT_Status	syn_coap_request_task (SYN_PT * pt, SYN_Task * task) Cooperative protothread task to execute a CoAP client request.
size_t	syn_coap_serialize (const SYN_CoapMsg * msg, const SYN_CoapOption * options, size_t option_count, uint8_t * buf, size_t max_buf_len) Serialize a CoAP message into a byte buffer.
void	syn_coap_transport_request_init (SYN_CoapTransportRequest * r, SYN_Transport * transport, const SYN_CoapMsg * msg, uint32_t timeout_ms, uint8_t retries) Initialize a CoAP request context over a SYN_Transport .
SYN_PT_Status	syn_coap_transport_request_task (SYN_PT * pt, SYN_Task * task) Cooperative protothread task for executing a CoAP request over SYN_Transport .
SYN_Status	syn_coap_transport_send_request (SYN_Transport * transport, const SYN_CoapMsg * req, const SYN_CoapOption * req_opts, size_t req_opt_cnt, SYN_CoapMsg * resp, SYN_CoapOption * resp_opts, size_t max_resp_opts, size_t * resp_opt_cnt, uint8_t * resp_buf, size_t resp_buf_sz) Send a CoAP request and await matching response over SYN_Transport .
bool	syn_coaps_client_handshake (SYN_CoapsClient * client) Advance or complete DTLS 1.3 handshake for CoAPS client.
bool	syn_coaps_client_init (SYN_CoapsClient * client, const SYN_DTLS_Config * config, SYN_Transport * underlying_transport, uint8_t * rx_buf, size_t rx_buf_size, uint8_t * tx_buf, size_t tx_buf_size) Initialize a CoAP over DTLS 1.3 Client.
SYN_Status	syn_coaps_client_send_request (SYN_CoapsClient * client, const SYN_CoapMsg * req, const SYN_CoapOption * req_opts, size_t req_opt_cnt, SYN_CoapMsg * resp, SYN_CoapOption * resp_opts, size_t max_resp_opts, size_t * resp_opt_cnt, uint8_t * resp_buf, size_t resp_buf_sz) Send a CoAPS request and receive response via DTLS 1.3 datagram channel.

Macros¶

Type	Name
define	COAP_VERSION `1`

Public Functions Documentation¶

function syn_coap_decode_block_opt¶

Decode a CoAP Blockwise Option (Block1 / Block2) value (RFC 7959).

bool syn_coap_decode_block_opt (
    const uint8_t * opt_val,
    size_t opt_len,
    SYN_CoapBlock * block
)

Parameters:

opt_val Pointer to option value bytes.
opt_len Option length in bytes (1, 2, or 3).
block [out] Parsed block parameters.

Returns:

true on success, false on invalid length or format.

function syn_coap_encode_block_opt¶

Encode a CoAP Blockwise Option (Block1 / Block2) value (RFC 7959).

size_t syn_coap_encode_block_opt (
    const SYN_CoapBlock * block,
    uint8_t buf
)

Parameters:

block Block parameters.
buf [out] Output buffer for encoded uint (up to 3 bytes).

Returns:

Number of bytes encoded (1, 2, or 3 bytes).

function syn_coap_parse¶

Parse a raw CoAP packet into a message structure.

SYN_Status syn_coap_parse (
    SYN_CoapMsg * msg,
    SYN_CoapOption * options,
    size_t max_options,
    size_t * option_count,
    const uint8_t * buf,
    size_t buf_len
)

Parameters:

msg [out] Parsed message header.
options [out] Array to receive parsed options.
max_options Capacity of the options array.
option_count [out] Number of options actually parsed.
buf Raw packet buffer.
buf_len Length of the raw packet in bytes.

Returns:

SYN_OK on success, SYN_ERROR on malformed input.

function syn_coap_request_init¶

Initialize a CoAP request context.

void syn_coap_request_init (
    SYN_CoapRequest * r,
    const SYN_SockAddr * server_addr,
    const SYN_CoapMsg * msg,
    uint32_t timeout_ms,
    uint8_t retries
)

Parameters:

r Request context.
server_addr Target server address.
msg Request header/token/payload.
timeout_ms Initial retransmit timeout (ms).
retries Maximum number of retransmissions.

function syn_coap_request_task¶

Cooperative protothread task to execute a CoAP client request.

SYN_PT_Status syn_coap_request_task (
    SYN_PT * pt,
    SYN_Task * task
)

Parameters:

pt Protothread state.
task Scheduler task (user_data must point to a SYN_CoapRequest).

Returns:

Protothread status.

function syn_coap_serialize¶

Serialize a CoAP message into a byte buffer.

size_t syn_coap_serialize (
    const SYN_CoapMsg * msg,
    const SYN_CoapOption * options,
    size_t option_count,
    uint8_t * buf,
    size_t max_buf_len
)

Parameters:

msg Message header to serialize.
options Options array (will be sorted by option number).
option_count Number of options.
buf [out] Destination buffer.
max_buf_len Capacity of the destination buffer.

Returns:

Number of bytes written, or 0 on error (buffer too small).

function syn_coap_transport_request_init¶

Initialize a CoAP request context over a SYN_Transport .

void syn_coap_transport_request_init (
    SYN_CoapTransportRequest * r,
    SYN_Transport * transport,
    const SYN_CoapMsg * msg,
    uint32_t timeout_ms,
    uint8_t retries
)

Parameters:

r Request context.
transport Transport instance.
msg Request message header.
timeout_ms Initial retransmit timeout (ms).
retries Maximum number of retransmissions.

function syn_coap_transport_request_task¶

Cooperative protothread task for executing a CoAP request over SYN_Transport .

SYN_PT_Status syn_coap_transport_request_task (
    SYN_PT * pt,
    SYN_Task * task
)

Parameters:

pt Protothread context.
task Scheduler task (user_data pointing to SYN_CoapTransportRequest).

Returns:

Protothread status.

function syn_coap_transport_send_request¶

Send a CoAP request and await matching response over SYN_Transport .

SYN_Status syn_coap_transport_send_request (
    SYN_Transport * transport,
    const SYN_CoapMsg * req,
    const SYN_CoapOption * req_opts,
    size_t req_opt_cnt,
    SYN_CoapMsg * resp,
    SYN_CoapOption * resp_opts,
    size_t max_resp_opts,
    size_t * resp_opt_cnt,
    uint8_t * resp_buf,
    size_t resp_buf_sz
)

Parameters:

transport Transport instance.
req Request message.
req_opts Request options.
req_opt_cnt Request option count.
resp [out] Parsed response message.
resp_opts [out] Parsed response options array.
max_resp_opts Capacity of response options array.
resp_opt_cnt [out] Number of parsed response options.
resp_buf [out] Buffer for raw received packet.
resp_buf_sz Capacity of response buffer.

Returns:

SYN_OK on success, error code otherwise.

function syn_coaps_client_handshake¶

Advance or complete DTLS 1.3 handshake for CoAPS client.

bool syn_coaps_client_handshake (
    SYN_CoapsClient * client
)

Parameters:

client CoAPS client context.

Returns:

true on handshake success, false on error.

function syn_coaps_client_init¶

Initialize a CoAP over DTLS 1.3 Client.

bool syn_coaps_client_init (
    SYN_CoapsClient * client,
    const SYN_DTLS_Config * config,
    SYN_Transport * underlying_transport,
    uint8_t * rx_buf,
    size_t rx_buf_size,
    uint8_t * tx_buf,
    size_t tx_buf_size
)

Parameters:

client CoAPS client context.
config DTLS 1.3 configuration.
underlying_transport Underlying datagram transport (e.g. UDP socket).
rx_buf Caller-owned RX record buffer.
rx_buf_size Capacity of RX record buffer.
tx_buf Caller-owned TX record buffer.
tx_buf_size Capacity of TX record buffer.

Returns:

true on success, false on invalid parameters.

function syn_coaps_client_send_request¶

Send a CoAPS request and receive response via DTLS 1.3 datagram channel.

SYN_Status syn_coaps_client_send_request (
    SYN_CoapsClient * client,
    const SYN_CoapMsg * req,
    const SYN_CoapOption * req_opts,
    size_t req_opt_cnt,
    SYN_CoapMsg * resp,
    SYN_CoapOption * resp_opts,
    size_t max_resp_opts,
    size_t * resp_opt_cnt,
    uint8_t * resp_buf,
    size_t resp_buf_sz
)

Parameters:

client CoAPS client context.
req Request message.
req_opts Request options.
req_opt_cnt Request option count.
resp [out] Parsed response message.
resp_opts [out] Parsed response options array.
max_resp_opts Capacity of response options array.
resp_opt_cnt [out] Number of parsed response options.
resp_buf [out] Buffer for decrypted response payload.
resp_buf_sz Capacity of response buffer.

Returns:

SYN_OK on success, error code otherwise.

Macro Definition Documentation¶

define COAP_VERSION¶

#define COAP_VERSION `1`

CoAP protocol version

The documentation for this class was generated from the following file src/syntropic/net/syn_coap.h