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 
754  size_t resources_len;
779 };
780 
785 
792 typedef void (*gcoap_resp_handler_t)(const gcoap_request_memo_t *memo,
793  coap_pkt_t* pdu,
794  const sock_udp_ep_t *remote);
795 
799 typedef struct {
800  uint8_t *pdu_buf;
801  size_t pdu_len;
803 
808  unsigned state;
811  union {
815  } msg;
819  void *context;
823 #if IS_USED(MODULE_NANOCOAP_CACHE) || DOXYGEN
830 #endif
831 };
832 
836 typedef struct {
839  uint8_t token[GCOAP_TOKENLEN_MAX];
840  unsigned token_len;
843 
854 
871 
898 int gcoap_req_init_path_buffer(coap_pkt_t *pdu, uint8_t *buf, size_t len,
899  unsigned code, const char *path,
900  size_t path_len);
901 
926 static inline int gcoap_req_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
927  unsigned code, const char *path)
928 {
929  return gcoap_req_init_path_buffer(pdu, buf, len, code, path,
930  (path) ? strlen(path) : 0U);
931 }
932 
945 static inline ssize_t gcoap_request(coap_pkt_t *pdu, uint8_t *buf, size_t len,
946  unsigned code, char *path)
947 {
948  if (gcoap_req_init(pdu, buf, len, code, path) == 0) {
949  if (IS_USED(MODULE_NANOCOAP_CACHE)) {
950  /* remove ETag option slack added for cache validation */
951  coap_opt_remove(pdu, COAP_OPT_ETAG);
952  }
954  }
955  return -1;
956 }
957 
979 ssize_t gcoap_req_send_tl(const uint8_t *buf, size_t len,
980  const sock_udp_ep_t *remote,
981  gcoap_resp_handler_t resp_handler, void *context,
982  gcoap_socket_type_t tl_type);
983 
1000 static inline ssize_t gcoap_req_send(const uint8_t *buf, size_t len,
1001  const sock_udp_ep_t *remote,
1002  gcoap_resp_handler_t resp_handler,
1003  void *context)
1004 {
1005  return gcoap_req_send_tl(buf, len, remote, resp_handler, context,
1007 }
1008 
1022 int gcoap_resp_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code);
1023 
1035 static inline ssize_t gcoap_response(coap_pkt_t *pdu, uint8_t *buf,
1036  size_t len, unsigned code)
1037 {
1038  return (gcoap_resp_init(pdu, buf, len, code) == 0)
1040  : -1;
1041 }
1042 
1058 int gcoap_obs_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
1059  const coap_resource_t *resource);
1060 
1074 size_t gcoap_obs_send(const uint8_t *buf, size_t len,
1075  const coap_resource_t *resource);
1076 
1084 uint8_t gcoap_op_state(void);
1085 
1108 int gcoap_get_resource_list(void *buf, size_t maxlen, uint8_t cf,
1109  gcoap_socket_type_t tl_type);
1110 
1124 ssize_t gcoap_encode_link(const coap_resource_t *resource, char *buf,
1125  size_t maxlen, coap_link_encoder_ctx_t *context);
1126 
1127 #if IS_USED(MODULE_GCOAP_DTLS) || defined(DOXYGEN)
1136 #endif
1137 
1146 {
1147  if (memo->send_limit == GCOAP_SEND_LIMIT_NON) {
1148  return (coap_hdr_t *)&memo->msg.hdr_buf[0];
1149  }
1150  else {
1151  return (coap_hdr_t *)memo->msg.data.pdu_buf;
1152  }
1153 }
1154 
1155 #ifdef __cplusplus
1156 }
1157 #endif
1158 
1159 #endif /* NET_GCOAP_H */
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_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:685
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:926
#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...
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:792
#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:1000
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:1035
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:1145
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:945
@ 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:192
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.
Definition: modules.h:71
nanocoap-cache API
nanocoap API
DTLS sock definitions.
UDP sock definitions.
Common IP-based transport layer end point.
Definition: sock.h:215
Raw CoAP PDU header structure.
Definition: nanocoap.h:200
CoAP PDU parsing context structure.
Definition: nanocoap.h:231
Type for CoAP resource entry.
Definition: nanocoap.h:310
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:765
struct gcoap_listener * next
Next listener in list.
Definition: gcoap.h:766
size_t resources_len
Length of array.
Definition: gcoap.h:754
gcoap_socket_type_t tl_type
Transport type for the listener.
Definition: gcoap.h:764
const coap_resource_t * resources
First element in the array of resources.
Definition: gcoap.h:753
gcoap_request_matcher_t request_matcher
Function that picks a suitable request handler from a request.
Definition: gcoap.h:778
Memo for Observe registration and notifications.
Definition: gcoap.h:836
unsigned token_len
Actual length of token attribute.
Definition: gcoap.h:840
gcoap_socket_t socket
Transport type to observer.
Definition: gcoap.h:841
const coap_resource_t * resource
Entity being observed.
Definition: gcoap.h:838
sock_udp_ep_t * observer
Client endpoint; unused if null.
Definition: gcoap.h:837
Memo to handle a response for a request.
Definition: gcoap.h:807
void * context
ptr to user defined context data
Definition: gcoap.h:819
gcoap_resp_handler_t resp_handler
Callback for the response.
Definition: gcoap.h:818
event_callback_t resp_tmout_cb
Callback for response timeout.
Definition: gcoap.h:821
union gcoap_request_memo::@333 msg
Request message data; if confirmable, supports resending message.
unsigned state
State of this memo, a GCOAP_MEMO...
Definition: gcoap.h:808
int send_limit
Remaining resends, 0 if none; GCOAP_SEND_LIMIT_NON if non-confirmable.
Definition: gcoap.h:809
gcoap_resend_t data
Endpoint and PDU buffer, for resend.
Definition: gcoap.h:814
uint8_t cache_key[CONFIG_NANOCOAP_CACHE_KEY_LENGTH]
Cache key for the request.
Definition: gcoap.h:829
sock_udp_ep_t remote_ep
Remote endpoint.
Definition: gcoap.h:817
gcoap_socket_t socket
Transport type to remote endpoint.
Definition: gcoap.h:822
uint8_t hdr_buf[GCOAP_HEADER_MAXLEN]
Copy of PDU header, if no resends.
Definition: gcoap.h:812
event_timeout_t resp_evt_tmout
Limits wait for response.
Definition: gcoap.h:820
Extends request memo for resending a confirmable request.
Definition: gcoap.h:799
uint8_t * pdu_buf
Buffer containing the PDU.
Definition: gcoap.h:800
size_t pdu_len
Length of pdu_buf.
Definition: gcoap.h:801
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.