gcoap.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015-2017 Ken Bannister. All rights reserved.
3  * 2017 Freie Universit├Ąt Berlin
4  *
5  * This file is subject to the terms and conditions of the GNU Lesser
6  * General Public License v2.1. See the file LICENSE in the top level
7  * directory for more details.
8  */
9 
395 #ifndef NET_GCOAP_H
396 #define NET_GCOAP_H
397 
398 #include <stdint.h>
399 
400 #include "event/callback.h"
401 #include "event/timeout.h"
402 #include "net/ipv6/addr.h"
403 #include "net/sock/udp.h"
404 #if IS_USED(MODULE_GCOAP_DTLS)
405 #include "net/sock/dtls.h"
406 #endif
407 #include "net/nanocoap.h"
408 #include "net/nanocoap/cache.h"
409 #include "timex.h"
410 
411 #ifdef __cplusplus
412 extern "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
476 #define GCOAP_TOKENLEN_MAX (8)
477 
481 #define GCOAP_HEADER_MAXLEN (sizeof(coap_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)
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 
554 #ifndef CONFIG_GCOAP_OBS_CLIENTS_MAX
555 #define CONFIG_GCOAP_OBS_CLIENTS_MAX (2)
556 #endif
557 
562 #ifndef CONFIG_GCOAP_OBS_REGISTRATIONS_MAX
563 #define CONFIG_GCOAP_OBS_REGISTRATIONS_MAX (2)
564 #endif
565 
570 #define GCOAP_OBS_MEMO_UNUSED (0)
571 #define GCOAP_OBS_MEMO_IDLE (1)
572 #define GCOAP_OBS_MEMO_PENDING (2)
595 #ifndef CONFIG_GCOAP_OBS_VALUE_WIDTH
596 #define CONFIG_GCOAP_OBS_VALUE_WIDTH (3)
597 #endif
598 
602 #if (CONFIG_GCOAP_OBS_VALUE_WIDTH == 3)
603 #define GCOAP_OBS_TICK_EXPONENT (5)
604 #elif (CONFIG_GCOAP_OBS_VALUE_WIDTH == 2)
605 #define GCOAP_OBS_TICK_EXPONENT (16)
606 #elif (CONFIG_GCOAP_OBS_VALUE_WIDTH == 1)
607 #define GCOAP_OBS_TICK_EXPONENT (24)
608 #endif
609 
614 #define GCOAP_OBS_INIT_OK (0)
615 #define GCOAP_OBS_INIT_ERR (-1)
616 #define GCOAP_OBS_INIT_UNUSED (-2)
623 #ifndef GCOAP_STACK_SIZE
624 #if IS_USED(MODULE_GCOAP_DTLS)
625 #define GCOAP_DTLS_EXTRA_STACKSIZE (THREAD_STACKSIZE_DEFAULT)
626 #else
627 #define GCOAP_DTLS_EXTRA_STACKSIZE (0)
628 #endif
629 
633 #if IS_USED(MODULE_GCOAP_FILESERVER)
634 #include "vfs.h"
635 #define GCOAP_VFS_EXTRA_STACKSIZE (VFS_DIR_BUFFER_SIZE + VFS_FILE_BUFFER_SIZE)
636 #else
637 #define GCOAP_VFS_EXTRA_STACKSIZE (0)
638 #endif
639 
640 #define GCOAP_STACK_SIZE (THREAD_STACKSIZE_DEFAULT + DEBUG_EXTRA_STACKSIZE \
641  + sizeof(coap_pkt_t) + GCOAP_DTLS_EXTRA_STACKSIZE \
642  + GCOAP_VFS_EXTRA_STACKSIZE)
643 #endif
650 #ifndef CONFIG_GCOAP_RESEND_BUFS_MAX
651 #define CONFIG_GCOAP_RESEND_BUFS_MAX (1)
652 #endif
653 
659 #define COAP_LINK_FLAG_INIT_RESLIST (1)
667 typedef struct {
668  unsigned content_format;
669  size_t link_pos;
670  uint16_t flags;
673 
685 typedef ssize_t (*gcoap_link_encoder_t)(const coap_resource_t *resource, char *buf,
686  size_t maxlen, coap_link_encoder_ctx_t *context);
687 
692 #define GCOAP_RESOURCE_FOUND (0)
693 #define GCOAP_RESOURCE_WRONG_METHOD (1)
694 #define GCOAP_RESOURCE_NO_PATH (2)
695 #define GCOAP_RESOURCE_ERROR (3)
701 typedef struct gcoap_listener gcoap_listener_t;
702 
715 typedef int (*gcoap_request_matcher_t)(gcoap_listener_t *listener,
716  const coap_resource_t **resource,
717  coap_pkt_t *pdu);
718 
725 typedef enum {
730 
734 typedef struct {
736  union {
737  sock_udp_t *udp;
738 #if IS_USED(MODULE_GCOAP_DTLS) || defined(DOXYGEN)
739  sock_dtls_t *dtls;
740 #endif
741  } socket;
742 #if IS_USED(MODULE_GCOAP_DTLS) || defined(DOXYGEN)
746 #endif
748 
755  size_t resources_len;
780 };
781 
786 
793 typedef void (*gcoap_resp_handler_t)(const gcoap_request_memo_t *memo,
794  coap_pkt_t* pdu,
795  const sock_udp_ep_t *remote);
796 
800 typedef struct {
801  uint8_t *pdu_buf;
802  size_t pdu_len;
804 
809  unsigned state;
812  union {
816  } msg;
820  void *context;
824 #if IS_USED(MODULE_NANOCOAP_CACHE) || DOXYGEN
831 #endif
832 };
833 
837 typedef struct {
840  uint8_t token[GCOAP_TOKENLEN_MAX];
841  unsigned token_len;
844 
855 
872 
899 int gcoap_req_init_path_buffer(coap_pkt_t *pdu, uint8_t *buf, size_t len,
900  unsigned code, const char *path,
901  size_t path_len);
902 
927 static inline int gcoap_req_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
928  unsigned code, const char *path)
929 {
930  return gcoap_req_init_path_buffer(pdu, buf, len, code, path,
931  (path) ? strlen(path) : 0U);
932 }
933 
946 static inline ssize_t gcoap_request(coap_pkt_t *pdu, uint8_t *buf, size_t len,
947  unsigned code, char *path)
948 {
949  if (gcoap_req_init(pdu, buf, len, code, path) == 0) {
950  if (IS_USED(MODULE_NANOCOAP_CACHE)) {
951  /* remove ETag option slack added for cache validation */
952  coap_opt_remove(pdu, COAP_OPT_ETAG);
953  }
955  }
956  return -1;
957 }
958 
980 ssize_t gcoap_req_send_tl(const uint8_t *buf, size_t len,
981  const sock_udp_ep_t *remote,
982  gcoap_resp_handler_t resp_handler, void *context,
983  gcoap_socket_type_t tl_type);
984 
1001 static inline ssize_t gcoap_req_send(const uint8_t *buf, size_t len,
1002  const sock_udp_ep_t *remote,
1003  gcoap_resp_handler_t resp_handler,
1004  void *context)
1005 {
1006  return gcoap_req_send_tl(buf, len, remote, resp_handler, context,
1008 }
1009 
1023 int gcoap_resp_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code);
1024 
1036 static inline ssize_t gcoap_response(coap_pkt_t *pdu, uint8_t *buf,
1037  size_t len, unsigned code)
1038 {
1039  return (gcoap_resp_init(pdu, buf, len, code) == 0)
1041  : -1;
1042 }
1043 
1059 int gcoap_obs_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
1060  const coap_resource_t *resource);
1061 
1075 size_t gcoap_obs_send(const uint8_t *buf, size_t len,
1076  const coap_resource_t *resource);
1077 
1085 uint8_t gcoap_op_state(void);
1086 
1113 int gcoap_get_resource_list_tl(void *buf, size_t maxlen, uint8_t cf,
1114  gcoap_socket_type_t tl_type);
1115 
1134 static inline int gcoap_get_resource_list(void *buf, size_t maxlen, uint8_t cf)
1135 {
1136  return gcoap_get_resource_list_tl(buf, maxlen, cf, GCOAP_SOCKET_TYPE_UNDEF);
1137 }
1138 
1152 ssize_t gcoap_encode_link(const coap_resource_t *resource, char *buf,
1153  size_t maxlen, coap_link_encoder_ctx_t *context);
1154 
1155 #if IS_USED(MODULE_GCOAP_DTLS) || defined(DOXYGEN)
1164 #endif
1165 
1174 {
1175  if (memo->send_limit == GCOAP_SEND_LIMIT_NON) {
1176  return (coap_hdr_t *)&memo->msg.hdr_buf[0];
1177  }
1178  else {
1179  return (coap_hdr_t *)memo->msg.data.pdu_buf;
1180  }
1181 }
1182 
1183 #ifdef __cplusplus
1184 }
1185 #endif
1186 
1187 #endif /* NET_GCOAP_H */
nanocoap-cache API
Provides a callback-with-argument event type.
Provides functionality to trigger events after timeout.
int16_t kernel_pid_t
Unique process identifier.
Definition: sched.h:139
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_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:685
void gcoap_register_listener(gcoap_listener_t *listener)
Starts listening for resource paths.
static int gcoap_get_resource_list(void *buf, size_t maxlen, uint8_t cf)
Get the resource list for all transports, currently only CoRE Link Format (COAP_FORMAT_LINK) supporte...
Definition: gcoap.h:1134
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:927
#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:725
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...
int gcoap_get_resource_list_tl(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.
sock_dtls_t * gcoap_get_sock_dtls(void)
Get the underlying DTLS socket of gcoap.
#define GCOAP_HEADER_MAXLEN
Maximum length in bytes for a header, including the token.
Definition: gcoap.h:481
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:793
#define GCOAP_SEND_LIMIT_NON
Value for send_limit in request memo when non-confirmable type.
Definition: gcoap.h:525
static ssize_t gcoap_req_send(const uint8_t *buf, size_t len, const sock_udp_ep_t *remote, gcoap_resp_handler_t resp_handler, void *context)
Sends a buffer containing a CoAP request to the provided endpoint.
Definition: gcoap.h:1001
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.
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.
ssize_t gcoap_req_send_tl(const uint8_t *buf, size_t len, const sock_udp_ep_t *remote, 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 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:1036
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:715
kernel_pid_t gcoap_init(void)
Initializes the gcoap thread and device.
uint8_t gcoap_op_state(void)
Provides important operational statistics.
static coap_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:1173
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:946
@ GCOAP_SOCKET_TYPE_UDP
Unencrypted UDP transport.
Definition: gcoap.h:727
@ GCOAP_SOCKET_TYPE_UNDEF
undefined
Definition: gcoap.h:726
@ GCOAP_SOCKET_TYPE_DTLS
DTLS-over-UDP transport.
Definition: gcoap.h:728
#define CONFIG_NANOCOAP_CACHE_KEY_LENGTH
The length of the cache key in bytes.
Definition: cache.h:48
#define COAP_OPT_FINISH_NONE
no special handling required
Definition: nanocoap.h:180
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.
int socket(int domain, int type, int protocol)
Create an endpoint for communication.
Definitions for IPv6 addresses.
#define IS_USED(module)
Checks whether a module is being used or not.
nanocoap API
DTLS sock definitions.
UDP sock definitions.
Common IP-based transport layer end point.
Definition: sock.h:214
Raw CoAP PDU header structure.
Definition: nanocoap.h:188
CoAP PDU parsing context structure.
Definition: nanocoap.h:219
Type for CoAP resource entry.
Definition: nanocoap.h:294
Callback Event structure definition.
Definition: callback.h:48
Timeout Event structure.
Definition: timeout.h:50
A modular collection of resources for a server.
Definition: gcoap.h:752
gcoap_link_encoder_t link_encoder
Writes a link for a resource.
Definition: gcoap.h:766
struct gcoap_listener * next
Next listener in list.
Definition: gcoap.h:767
size_t resources_len
Length of array.
Definition: gcoap.h:755
gcoap_socket_type_t tl_type
Transport type for the listener.
Definition: gcoap.h:765
const coap_resource_t * resources
First element in the array of resources; must order alphabetically.
Definition: gcoap.h:753
gcoap_request_matcher_t request_matcher
Function that picks a suitable request handler from a request.
Definition: gcoap.h:779
Memo for Observe registration and notifications.
Definition: gcoap.h:837
unsigned token_len
Actual length of token attribute.
Definition: gcoap.h:841
gcoap_socket_t socket
Transport type to observer.
Definition: gcoap.h:842
const coap_resource_t * resource
Entity being observed.
Definition: gcoap.h:839
sock_udp_ep_t * observer
Client endpoint; unused if null.
Definition: gcoap.h:838
Memo to handle a response for a request.
Definition: gcoap.h:808
void * context
ptr to user defined context data
Definition: gcoap.h:820
gcoap_resp_handler_t resp_handler
Callback for the response.
Definition: gcoap.h:819
event_callback_t resp_tmout_cb
Callback for response timeout.
Definition: gcoap.h:822
unsigned state
State of this memo, a GCOAP_MEMO...
Definition: gcoap.h:809
int send_limit
Remaining resends, 0 if none; GCOAP_SEND_LIMIT_NON if non-confirmable.
Definition: gcoap.h:810
gcoap_resend_t data
Endpoint and PDU buffer, for resend.
Definition: gcoap.h:815
uint8_t cache_key[CONFIG_NANOCOAP_CACHE_KEY_LENGTH]
Cache key for the request.
Definition: gcoap.h:830
sock_udp_ep_t remote_ep
Remote endpoint.
Definition: gcoap.h:818
union gcoap_request_memo::@327 msg
Request message data; if confirmable, supports resending message.
gcoap_socket_t socket
Transport type to remote endpoint.
Definition: gcoap.h:823
uint8_t hdr_buf[GCOAP_HEADER_MAXLEN]
Copy of PDU header, if no resends.
Definition: gcoap.h:813
event_timeout_t resp_evt_tmout
Limits wait for response.
Definition: gcoap.h:821
Extends request memo for resending a confirmable request.
Definition: gcoap.h:800
uint8_t * pdu_buf
Buffer containing the PDU.
Definition: gcoap.h:801
size_t pdu_len
Length of pdu_buf.
Definition: gcoap.h:802
CoAP socket to handle multiple transport types.
Definition: gcoap.h:734
gcoap_socket_type_t type
Type of stored socket.
Definition: gcoap.h:735
sock_dtls_session_t ctx_dtls_session
Session object for the stored socket.
Definition: gcoap.h:743
Information about remote client connected to the server.
Information about DTLS sock.
UDP sock type.
Definition: sock_types.h:128
Utility library for comparing and computing timestamps.
VFS layer API declarations.