Loading...
Searching...
No Matches
gcoap.h
Go to the documentation of this file.
1/*
2 * SPDX-FileCopyrightText: 2015-2017 Ken Bannister. All rights reserved.
3 * SPDX-FileCopyrightText: 2017 Freie Universität Berlin
4 * SPDX-License-Identifier: LGPL-2.1-only
5 */
6
7#pragma once
8
395
396#include <stdint.h>
397
398#include "event/callback.h"
399#include "event/timeout.h"
400#include "net/sock/udp.h"
401#include "net/nanocoap.h"
402#include "time_units.h"
403
404#if IS_USED(MODULE_GCOAP_DTLS)
405# include "net/sock/dtls.h"
406#endif
407#if IS_USED(MODULE_NANOCOAP_CACHE)
408# include "net/nanocoap/cache.h"
409#endif
410
411#ifdef __cplusplus
412extern "C" {
413#endif
414
424#ifndef CONFIG_GCOAP_PORT
425#define CONFIG_GCOAP_PORT (5683)
426#endif
430#ifndef CONFIG_GCOAPS_PORT
431#define CONFIG_GCOAPS_PORT (5684)
432#endif
433
437#ifndef CONFIG_GCOAP_DTLS_HANDSHAKE_TIMEOUT_MSEC
438#define CONFIG_GCOAP_DTLS_HANDSHAKE_TIMEOUT_MSEC (3 * MS_PER_SEC)
439#endif
440
446#ifndef CONFIG_GCOAP_DTLS_MINIMUM_AVAILABLE_SESSIONS
447#define CONFIG_GCOAP_DTLS_MINIMUM_AVAILABLE_SESSIONS (1)
448#endif
449
454#ifndef CONFIG_GCOAP_DTLS_MINIMUM_AVAILABLE_SESSIONS_TIMEOUT_MSEC
455#define CONFIG_GCOAP_DTLS_MINIMUM_AVAILABLE_SESSIONS_TIMEOUT_MSEC (15 * MS_PER_SEC)
456#endif
457
461#ifndef CONFIG_GCOAP_PDU_BUF_SIZE
462#define CONFIG_GCOAP_PDU_BUF_SIZE (128)
463#endif
464
468#ifndef CONFIG_GCOAP_REQ_WAITING_MAX
469#define CONFIG_GCOAP_REQ_WAITING_MAX (2)
470#endif
472
476#define GCOAP_TOKENLEN_MAX (8)
477
481#define GCOAP_HEADER_MAXLEN (sizeof(coap_udp_hdr_t) + GCOAP_TOKENLEN_MAX)
482
489#ifndef CONFIG_GCOAP_TOKENLEN
490#define CONFIG_GCOAP_TOKENLEN (2)
491#endif
492
496#define GCOAP_PAYLOAD_MARKER (0xFF)
497
504#ifndef CONFIG_GCOAP_NO_AUTO_INIT
505#define CONFIG_GCOAP_NO_AUTO_INIT 0
506#endif
507
512#define GCOAP_MEMO_UNUSED (0)
513#define GCOAP_MEMO_RETRANSMIT (1)
514#define GCOAP_MEMO_WAIT (2)
515#define GCOAP_MEMO_RESP (3)
516#define GCOAP_MEMO_TIMEOUT (4)
517#define GCOAP_MEMO_ERR (5)
518#define GCOAP_MEMO_RESP_TRUNC (6)
521
525#define GCOAP_SEND_LIMIT_NON (-1)
526
527#ifdef DOXYGEN
537#define CONFIG_GCOAP_NO_RETRANS_BACKOFF
538#endif
539
546#ifndef CONFIG_GCOAP_NON_TIMEOUT_MSEC
547#define CONFIG_GCOAP_NON_TIMEOUT_MSEC (5000U)
548#endif
549
558#ifndef CONFIG_GCOAP_OBS_CLIENTS_MAX
559#define CONFIG_GCOAP_OBS_CLIENTS_MAX (2)
560#endif
561
571#ifndef CONFIG_GCOAP_OBS_NOTIFIERS_MAX
572#define CONFIG_GCOAP_OBS_NOTIFIERS_MAX (2)
573#endif
574
583#ifndef CONFIG_GCOAP_OBS_REGISTRATIONS_MAX
584#define CONFIG_GCOAP_OBS_REGISTRATIONS_MAX (2)
585#endif
586
591#define GCOAP_OBS_MEMO_UNUSED (0)
592#define GCOAP_OBS_MEMO_IDLE (1)
593#define GCOAP_OBS_MEMO_PENDING (2)
595
616#ifndef CONFIG_GCOAP_OBS_VALUE_WIDTH
617#define CONFIG_GCOAP_OBS_VALUE_WIDTH (3)
618#endif
619
623#if (CONFIG_GCOAP_OBS_VALUE_WIDTH == 3)
624#define GCOAP_OBS_TICK_EXPONENT (0)
625#elif (CONFIG_GCOAP_OBS_VALUE_WIDTH == 2)
626#define GCOAP_OBS_TICK_EXPONENT (6)
627#elif (CONFIG_GCOAP_OBS_VALUE_WIDTH == 1)
628#define GCOAP_OBS_TICK_EXPONENT (14)
629#endif
630
635#define GCOAP_OBS_INIT_OK (0)
636#define GCOAP_OBS_INIT_ERR (-1)
637#define GCOAP_OBS_INIT_UNUSED (-2)
639
644#ifndef GCOAP_DTLS_EXTRA_STACKSIZE
645#if IS_USED(MODULE_GCOAP_DTLS)
646#define GCOAP_DTLS_EXTRA_STACKSIZE (THREAD_STACKSIZE_DEFAULT)
647#else
648#define GCOAP_DTLS_EXTRA_STACKSIZE (0)
649#endif
650#endif
651
655#if IS_USED(MODULE_GCOAP_FILESERVER)
656#include "vfs.h"
657#define GCOAP_VFS_EXTRA_STACKSIZE (VFS_DIR_BUFFER_SIZE + VFS_FILE_BUFFER_SIZE)
658#else
659#define GCOAP_VFS_EXTRA_STACKSIZE (0)
660#endif
661
662#ifndef GCOAP_STACK_SIZE
663#define GCOAP_STACK_SIZE (THREAD_STACKSIZE_DEFAULT + DEBUG_EXTRA_STACKSIZE \
664 + sizeof(coap_pkt_t) + GCOAP_DTLS_EXTRA_STACKSIZE \
665 + GCOAP_VFS_EXTRA_STACKSIZE)
666#endif
668
673#ifndef CONFIG_GCOAP_RESEND_BUFS_MAX
674#define CONFIG_GCOAP_RESEND_BUFS_MAX (1)
675#endif
676
682#define COAP_LINK_FLAG_INIT_RESLIST (1)
684
686
690typedef struct {
691 unsigned content_format;
692 size_t link_pos;
693 uint16_t flags;
696
708typedef ssize_t (*gcoap_link_encoder_t)(const coap_resource_t *resource, char *buf,
709 size_t maxlen, coap_link_encoder_ctx_t *context);
710
715#define GCOAP_RESOURCE_FOUND (0)
716#define GCOAP_RESOURCE_WRONG_METHOD (1)
717#define GCOAP_RESOURCE_NO_PATH (2)
718#define GCOAP_RESOURCE_ERROR (3)
720
725
739 const coap_resource_t **resource,
740 coap_pkt_t *pdu);
741
753
757typedef struct {
759 union {
760 sock_udp_t *udp;
761#if IS_USED(MODULE_GCOAP_DTLS) || defined(DOXYGEN)
762 sock_dtls_t *dtls;
763#endif
765#if IS_USED(MODULE_GCOAP_DTLS) || defined(DOXYGEN)
769#endif
771
803
808
815typedef void (*gcoap_resp_handler_t)(const gcoap_request_memo_t *memo,
816 coap_pkt_t* pdu,
817 const sock_udp_ep_t *remote);
818
822typedef struct {
823 uint8_t *pdu_buf;
824 size_t pdu_len;
826
855
868
879
896
910 const coap_resource_t *last_resource,
911 const char *uri_path);
912
939int gcoap_req_init_path_buffer(coap_pkt_t *pdu, uint8_t *buf, size_t len,
940 unsigned code, const char *path,
941 size_t path_len);
942
967static inline int gcoap_req_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
968 unsigned code, const char *path)
969{
970 return gcoap_req_init_path_buffer(pdu, buf, len, code, path,
971 (path) ? strlen(path) : 0U);
972}
973
986static inline ssize_t gcoap_request(coap_pkt_t *pdu, uint8_t *buf, size_t len,
987 unsigned code, char *path)
988{
989 if (gcoap_req_init(pdu, buf, len, code, path) == 0) {
990 if (IS_USED(MODULE_NANOCOAP_CACHE)) {
991 /* remove ETag option slack added for cache validation */
992 coap_opt_remove(pdu, COAP_OPT_ETAG);
993 }
995 }
996 return -1;
997}
998
1021ssize_t gcoap_req_send(const uint8_t *buf, size_t len,
1022 const sock_udp_ep_t *remote, const sock_udp_ep_t *local,
1023 gcoap_resp_handler_t resp_handler, void *context,
1024 gcoap_socket_type_t tl_type);
1025
1039int gcoap_resp_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code);
1040
1052static inline ssize_t gcoap_response(coap_pkt_t *pdu, uint8_t *buf,
1053 size_t len, unsigned code)
1054{
1055 return (gcoap_resp_init(pdu, buf, len, code) == 0)
1057 : -1;
1058}
1059
1078int gcoap_obs_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
1079 const coap_resource_t *resource);
1080
1094size_t gcoap_obs_send(const uint8_t *buf, size_t len,
1095 const coap_resource_t *resource);
1096
1125int gcoap_obs_req_forget(const sock_udp_ep_t *remote, const uint8_t *token,
1126 size_t tokenlen);
1127
1135uint8_t gcoap_op_state(void);
1136
1159int gcoap_get_resource_list(void *buf, size_t maxlen, uint8_t cf,
1160 gcoap_socket_type_t tl_type);
1161
1175ssize_t gcoap_encode_link(const coap_resource_t *resource, char *buf,
1176 size_t maxlen, coap_link_encoder_ctx_t *context);
1177
1178#if IS_USED(MODULE_GCOAP_DTLS) || defined(DOXYGEN)
1187#endif
1188
1197{
1198 if (memo->send_limit == GCOAP_SEND_LIMIT_NON) {
1199 return &memo->msg.hdr_buf[0];
1200 }
1201
1202 return memo->msg.data.pdu_buf;
1203}
1204
1215{
1216 gcoap_request_memo_t *evil_cast_is_evil = (gcoap_request_memo_t *)memo;
1217 return (coap_udp_hdr_t *)gcoap_request_memo_get_buf(evil_cast_is_evil);
1218}
1219
1227static inline size_t gcoap_request_memo_get_tkl(const gcoap_request_memo_t *memo)
1228{
1229 const coap_udp_hdr_t *hdr = gcoap_request_memo_get_hdr(memo);
1230 /*
1231 * Layout of first byte of header (cut out of Figure 7 of RFC7252)
1232 * see https://datatracker.ietf.org/doc/html/rfc7252#section-3
1233 * 0 1 2 3 4 5 6 7
1234 * +-+-+-+-+-+-+-+-+
1235 * |Ver| T | TKL |
1236 * +-+-+-+-+-+-+-+-+
1237 */
1238 return hdr->ver_t_tkl & 0xf;
1239}
1240
1252{
1253 /* CoAP header without options is static header plus Token */
1254 return sizeof(coap_udp_hdr_t) + gcoap_request_memo_get_tkl(memo);
1255}
1256
1265{
1266 uint8_t *buf = gcoap_request_memo_get_buf(memo);
1267 return buf + sizeof(coap_udp_hdr_t);
1268}
1269
1270#ifdef __cplusplus
1271}
1272#endif
1273
Provides a callback-with-argument event type.
int16_t kernel_pid_t
Unique process identifier.
Definition sched.h:138
int gcoap_req_init_path_buffer(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code, const char *path, size_t path_len)
Initializes a CoAP request PDU on a buffer.
int gcoap_get_resource_list(void *buf, size_t maxlen, uint8_t cf, gcoap_socket_type_t tl_type)
Get the resource list, currently only CoRE Link Format (COAP_FORMAT_LINK) supported.
int gcoap_resp_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code)
Initializes a CoAP response packet on a buffer.
ssize_t(* gcoap_link_encoder_t)(const coap_resource_t *resource, char *buf, size_t maxlen, coap_link_encoder_ctx_t *context)
Handler function to write a resource link.
Definition gcoap.h:708
void gcoap_register_listener(gcoap_listener_t *listener)
Starts listening for resource paths.
static int gcoap_req_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code, const char *path)
Initializes a CoAP request PDU on a buffer.
Definition gcoap.h:967
#define GCOAP_TOKENLEN_MAX
Maximum length in bytes for a token.
Definition gcoap.h:476
gcoap_socket_type_t
CoAP socket types.
Definition gcoap.h:748
int gcoap_obs_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, const coap_resource_t *resource)
Initializes a CoAP Observe notification packet on a buffer, for the observer registered for a resourc...
ssize_t gcoap_req_send(const uint8_t *buf, size_t len, const sock_udp_ep_t *remote, const sock_udp_ep_t *local, gcoap_resp_handler_t resp_handler, void *context, gcoap_socket_type_t tl_type)
Sends a buffer containing a CoAP request to the provided endpoint.
static size_t gcoap_request_memo_get_tkl(const gcoap_request_memo_t *memo)
Get the request header's Token length from a gcoap_request_memo_t.
Definition gcoap.h:1227
static void * gcoap_request_memo_get_token(gcoap_request_memo_t *memo)
Get the request header's CoAP token from a gcoap_request_memo_t.
Definition gcoap.h:1264
const coap_resource_t * gcoap_get_resource_by_path_iterator(const gcoap_listener_t **last_listener, const coap_resource_t *last_resource, const char *uri_path)
Iterate through all registered listeners and check for a resource, matching by uri_path.
#define GCOAP_HEADER_MAXLEN
Maximum length in bytes for a header, including the token.
Definition gcoap.h:481
sock_dtls_t * gcoap_get_sock_dtls(void)
Get the underlying DTLS socket of gcoap.
void(* gcoap_resp_handler_t)(const gcoap_request_memo_t *memo, coap_pkt_t *pdu, const sock_udp_ep_t *remote)
Handler function for a server response, including the state for the originating request.
Definition gcoap.h:815
#define GCOAP_SEND_LIMIT_NON
Value for send_limit in request memo when non-confirmable type.
Definition gcoap.h:525
static uint8_t * gcoap_request_memo_get_buf(gcoap_request_memo_t *memo)
Get the buffer from a gcoap_request_memo_t.
Definition gcoap.h:1196
ssize_t gcoap_encode_link(const coap_resource_t *resource, char *buf, size_t maxlen, coap_link_encoder_ctx_t *context)
Writes a resource in CoRE Link Format to a provided buffer.
struct gcoap_request_memo gcoap_request_memo_t
Forward declaration of the request memo type.
Definition gcoap.h:807
struct gcoap_listener gcoap_listener_t
Forward declaration of the gcoap listener state container.
Definition gcoap.h:724
size_t gcoap_obs_send(const uint8_t *buf, size_t len, const coap_resource_t *resource)
Sends a buffer containing a CoAP Observe notification to the observer registered for a resource.
int gcoap_obs_req_forget(const sock_udp_ep_t *remote, const uint8_t *token, size_t tokenlen)
Forgets (invalidates) an existing observe request.
static ssize_t gcoap_response(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code)
Writes a complete CoAP response PDU when there is no payload.
Definition gcoap.h:1052
static coap_udp_hdr_t * gcoap_request_memo_get_hdr(const gcoap_request_memo_t *memo)
Get the header of a request from a gcoap_request_memo_t.
Definition gcoap.h:1214
int(* gcoap_request_matcher_t)(gcoap_listener_t *listener, const coap_resource_t **resource, coap_pkt_t *pdu)
Handler function for the request matcher strategy.
Definition gcoap.h:738
kernel_pid_t gcoap_init(void)
Initializes the gcoap thread and device.
uint8_t gcoap_op_state(void)
Provides important operational statistics.
static size_t gcoap_request_memo_get_hdr_len(const gcoap_request_memo_t *memo)
Get the request header length from a gcoap_request_memo_t.
Definition gcoap.h:1251
static ssize_t gcoap_request(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code, char *path)
Writes a complete CoAP request PDU when there is not a payload.
Definition gcoap.h:986
@ GCOAP_SOCKET_TYPE_UDP
Unencrypted UDP transport.
Definition gcoap.h:750
@ GCOAP_SOCKET_TYPE_UNDEF
undefined
Definition gcoap.h:749
@ GCOAP_SOCKET_TYPE_DTLS
DTLS-over-UDP transport.
Definition gcoap.h:751
#define CONFIG_NANOCOAP_CACHE_KEY_LENGTH
The length of the cache key in bytes.
Definition cache.h:44
#define COAP_OPT_FINISH_NONE
no special handling required
Definition nanocoap.h:177
ssize_t coap_opt_remove(coap_pkt_t *pkt, uint16_t optnum)
Removes an option previously added with function in the coap_opt_add_...() group.
ssize_t coap_opt_finish(coap_pkt_t *pkt, uint16_t flags)
Finalizes options as required and prepares for payload.
struct sock_udp sock_udp_t
forward declare for async
Definition types.h:136
struct sock_dtls sock_dtls_t
forward declare for async
Definition types.h:44
struct sock_dtls_session sock_dtls_session_t
Information about a created session.
Definition dtls.h:635
struct _sock_tl_ep sock_udp_ep_t
An end point for a UDP sock object.
Definition udp.h:292
int socket(int domain, int type, int protocol)
Create an endpoint for communication.
#define IS_USED(module)
Checks whether a module is being used or not.
Definition modules.h:67
nanocoap API
DTLS sock definitions.
UDP sock definitions.
CoAP PDU parsing context structure.
Definition nanocoap.h:217
Type for CoAP resource entry.
Definition nanocoap.h:301
Raw CoAP over UDP PDU header structure.
Definition nanocoap.h:185
uint8_t ver_t_tkl
version, token, token length
Definition nanocoap.h:186
Callback Event structure definition.
Definition callback.h:45
Timeout Event structure.
Definition timeout.h:46
A modular collection of resources for a server.
Definition gcoap.h:775
gcoap_link_encoder_t link_encoder
Writes a link for a resource.
Definition gcoap.h:788
struct gcoap_listener * next
Next listener in list.
Definition gcoap.h:789
size_t resources_len
Length of array.
Definition gcoap.h:777
gcoap_socket_type_t tl_type
Transport type for the listener.
Definition gcoap.h:787
const coap_resource_t * resources
First element in the array of resources.
Definition gcoap.h:776
gcoap_request_matcher_t request_matcher
Function that picks a suitable request handler from a request.
Definition gcoap.h:801
Memo for Observe registration and notifications.
Definition gcoap.h:859
unsigned token_len
Actual length of token attribute.
Definition gcoap.h:865
uint8_t token[GCOAP_TOKENLEN_MAX]
Client token for notifications.
Definition gcoap.h:863
gcoap_socket_t socket
Transport type to observer.
Definition gcoap.h:866
const coap_resource_t * resource
Entity being observed.
Definition gcoap.h:862
sock_udp_ep_t * notifier
Local endpoint to send notifications.
Definition gcoap.h:861
uint16_t last_msgid
Message ID of last notification.
Definition gcoap.h:864
sock_udp_ep_t * observer
Client endpoint; unused if null.
Definition gcoap.h:860
Memo to handle a response for a request.
Definition gcoap.h:830
void * context
ptr to user defined context data
Definition gcoap.h:842
gcoap_resp_handler_t resp_handler
Callback for the response.
Definition gcoap.h:841
event_callback_t resp_tmout_cb
Callback for response timeout.
Definition gcoap.h:844
unsigned state
State of this memo, a GCOAP_MEMO...
Definition gcoap.h:831
int send_limit
Remaining resends, 0 if none; GCOAP_SEND_LIMIT_NON if non-confirmable.
Definition gcoap.h:832
gcoap_resend_t data
Endpoint and PDU buffer, for resend.
Definition gcoap.h:837
uint8_t cache_key[CONFIG_NANOCOAP_CACHE_KEY_LENGTH]
Cache key for the request.
Definition gcoap.h:852
sock_udp_ep_t remote_ep
Remote endpoint.
Definition gcoap.h:840
union gcoap_request_memo::@376103145064361232062134223007277344126205344350 msg
Request message data; if confirmable, supports resending message.
gcoap_socket_t socket
Transport type to remote endpoint.
Definition gcoap.h:845
uint8_t hdr_buf[GCOAP_HEADER_MAXLEN]
Copy of PDU header, if no resends.
Definition gcoap.h:835
event_timeout_t resp_evt_tmout
Limits wait for response.
Definition gcoap.h:843
Extends request memo for resending a confirmable request.
Definition gcoap.h:822
uint8_t * pdu_buf
Buffer containing the PDU.
Definition gcoap.h:823
size_t pdu_len
Length of pdu_buf.
Definition gcoap.h:824
CoAP socket to handle multiple transport types.
Definition gcoap.h:757
gcoap_socket_type_t type
Type of stored socket.
Definition gcoap.h:758
sock_dtls_session_t ctx_dtls_session
Session object for the stored socket.
Definition gcoap.h:766
nanocoap-cache API
Utility header providing time unit defines.
Provides functionality to trigger events after timeout.