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 "xtimer.h"
409 
410 #ifdef __cplusplus
411 extern "C" {
412 #endif
413 
423 #ifndef CONFIG_GCOAP_PORT
424 #define CONFIG_GCOAP_PORT (5683)
425 #endif
429 #ifndef CONFIG_GCOAPS_PORT
430 #define CONFIG_GCOAPS_PORT (5684)
431 #endif
432 
436 #ifndef CONFIG_GCOAP_DTLS_HANDSHAKE_TIMEOUT_USEC
437 #define CONFIG_GCOAP_DTLS_HANDSHAKE_TIMEOUT_USEC (3 * US_PER_SEC)
438 #endif
439 
445 #ifndef CONFIG_GCOAP_DTLS_MINIMUM_AVAILABLE_SESSIONS
446 #define CONFIG_GCOAP_DTLS_MINIMUM_AVAILABLE_SESSIONS (1)
447 #endif
448 
453 #ifndef CONFIG_GCOAP_DTLS_MINIMUM_AVAILABLE_SESSIONS_TIMEOUT_USEC
454 #define CONFIG_GCOAP_DTLS_MINIMUM_AVAILABLE_SESSIONS_TIMEOUT_USEC (15 * US_PER_SEC)
455 #endif
456 
460 #ifndef CONFIG_GCOAP_PDU_BUF_SIZE
461 #define CONFIG_GCOAP_PDU_BUF_SIZE (128)
462 #endif
463 
467 #ifndef CONFIG_GCOAP_REQ_WAITING_MAX
468 #define CONFIG_GCOAP_REQ_WAITING_MAX (2)
469 #endif
475 #define GCOAP_TOKENLEN_MAX (8)
476 
480 #define GCOAP_HEADER_MAXLEN (sizeof(coap_hdr_t) + GCOAP_TOKENLEN_MAX)
481 
488 #ifndef CONFIG_GCOAP_TOKENLEN
489 #define CONFIG_GCOAP_TOKENLEN (2)
490 #endif
491 
495 #define GCOAP_PAYLOAD_MARKER (0xFF)
496 
503 #ifndef CONFIG_GCOAP_NO_AUTO_INIT
504 #define CONFIG_GCOAP_NO_AUTO_INIT 0
505 #endif
506 
511 #define GCOAP_MEMO_UNUSED (0)
512 #define GCOAP_MEMO_RETRANSMIT (1)
513 #define GCOAP_MEMO_WAIT (2)
514 #define GCOAP_MEMO_RESP (3)
515 #define GCOAP_MEMO_TIMEOUT (4)
516 #define GCOAP_MEMO_ERR (5)
517 #define GCOAP_MEMO_RESP_TRUNC (6)
524 #define GCOAP_SEND_LIMIT_NON (-1)
525 
526 #ifdef DOXYGEN
536 #define CONFIG_GCOAP_NO_RETRANS_BACKOFF
537 #endif
538 
545 #ifndef CONFIG_GCOAP_NON_TIMEOUT
546 #define CONFIG_GCOAP_NON_TIMEOUT (5000000U)
547 #endif
548 
553 #ifndef CONFIG_GCOAP_OBS_CLIENTS_MAX
554 #define CONFIG_GCOAP_OBS_CLIENTS_MAX (2)
555 #endif
556 
561 #ifndef CONFIG_GCOAP_OBS_REGISTRATIONS_MAX
562 #define CONFIG_GCOAP_OBS_REGISTRATIONS_MAX (2)
563 #endif
564 
569 #define GCOAP_OBS_MEMO_UNUSED (0)
570 #define GCOAP_OBS_MEMO_IDLE (1)
571 #define GCOAP_OBS_MEMO_PENDING (2)
594 #ifndef CONFIG_GCOAP_OBS_VALUE_WIDTH
595 #define CONFIG_GCOAP_OBS_VALUE_WIDTH (3)
596 #endif
597 
601 #if (CONFIG_GCOAP_OBS_VALUE_WIDTH == 3)
602 #define GCOAP_OBS_TICK_EXPONENT (5)
603 #elif (CONFIG_GCOAP_OBS_VALUE_WIDTH == 2)
604 #define GCOAP_OBS_TICK_EXPONENT (16)
605 #elif (CONFIG_GCOAP_OBS_VALUE_WIDTH == 1)
606 #define GCOAP_OBS_TICK_EXPONENT (24)
607 #endif
608 
613 #define GCOAP_OBS_INIT_OK (0)
614 #define GCOAP_OBS_INIT_ERR (-1)
615 #define GCOAP_OBS_INIT_UNUSED (-2)
622 #ifndef GCOAP_STACK_SIZE
623 #if IS_USED(MODULE_GCOAP_DTLS)
624 #define GCOAP_DTLS_EXTRA_STACKSIZE (THREAD_STACKSIZE_DEFAULT)
625 #else
626 #define GCOAP_DTLS_EXTRA_STACKSIZE (0)
627 #endif
628 
629 #define GCOAP_STACK_SIZE (THREAD_STACKSIZE_DEFAULT + DEBUG_EXTRA_STACKSIZE \
630  + sizeof(coap_pkt_t) + GCOAP_DTLS_EXTRA_STACKSIZE)
631 #endif
638 #ifndef CONFIG_GCOAP_RESEND_BUFS_MAX
639 #define CONFIG_GCOAP_RESEND_BUFS_MAX (1)
640 #endif
641 
647 #define COAP_LINK_FLAG_INIT_RESLIST (1)
655 typedef struct {
656  unsigned content_format;
657  size_t link_pos;
658  uint16_t flags;
661 
673 typedef ssize_t (*gcoap_link_encoder_t)(const coap_resource_t *resource, char *buf,
674  size_t maxlen, coap_link_encoder_ctx_t *context);
675 
680 #define GCOAP_RESOURCE_FOUND (0)
681 #define GCOAP_RESOURCE_WRONG_METHOD (1)
682 #define GCOAP_RESOURCE_NO_PATH (2)
683 #define GCOAP_RESOURCE_ERROR (3)
689 typedef struct gcoap_listener gcoap_listener_t;
690 
703 typedef int (*gcoap_request_matcher_t)(gcoap_listener_t *listener,
704  const coap_resource_t **resource,
705  const coap_pkt_t *pdu);
706 
713  size_t resources_len;
728 };
729 
734 
741 typedef void (*gcoap_resp_handler_t)(const gcoap_request_memo_t *memo,
742  coap_pkt_t* pdu,
743  const sock_udp_ep_t *remote);
744 
748 typedef struct {
749  uint8_t *pdu_buf;
750  size_t pdu_len;
752 
757  unsigned state;
760  union {
764  } msg;
768  void *context;
771 };
772 
776 typedef struct {
779  uint8_t token[GCOAP_TOKENLEN_MAX];
780  unsigned token_len;
782 
786 typedef enum {
787  GCOAP_SOCKET_TYPE_UNDEF = 0,
788  GCOAP_SOCKET_TYPE_UDP,
789  GCOAP_SOCKET_TYPE_DTLS
791 
795 typedef struct {
797  union {
798  sock_udp_t *udp;
799 #if IS_USED(MODULE_GCOAP_DTLS) || defined(DOXYGEN)
800  sock_dtls_t *dtls;
801 #endif
802  } socket;
803 #if IS_USED(MODULE_GCOAP_DTLS) || defined(DOXYGEN)
807 #endif
809 
820 
837 
858 int gcoap_req_init_path_buffer(coap_pkt_t *pdu, uint8_t *buf, size_t len,
859  unsigned code, const char *path,
860  size_t path_len);
861 
880 static inline int gcoap_req_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
881  unsigned code, const char *path)
882 {
883  return gcoap_req_init_path_buffer(pdu, buf, len, code, path,
884  (path) ? strlen(path) : 0U);
885 }
886 
899 static inline ssize_t gcoap_request(coap_pkt_t *pdu, uint8_t *buf, size_t len,
900  unsigned code, char *path)
901 {
902  return (gcoap_req_init(pdu, buf, len, code, path) == 0)
904  : -1;
905 }
906 
920 ssize_t gcoap_req_send(const uint8_t *buf, size_t len,
921  const sock_udp_ep_t *remote,
922  gcoap_resp_handler_t resp_handler, void *context);
923 
937 int gcoap_resp_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code);
938 
950 static inline ssize_t gcoap_response(coap_pkt_t *pdu, uint8_t *buf,
951  size_t len, unsigned code)
952 {
953  return (gcoap_resp_init(pdu, buf, len, code) == 0)
955  : -1;
956 }
957 
973 int gcoap_obs_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
974  const coap_resource_t *resource);
975 
989 size_t gcoap_obs_send(const uint8_t *buf, size_t len,
990  const coap_resource_t *resource);
991 
999 uint8_t gcoap_op_state(void);
1000 
1019 int gcoap_get_resource_list(void *buf, size_t maxlen, uint8_t cf);
1020 
1034 ssize_t gcoap_encode_link(const coap_resource_t *resource, char *buf,
1035  size_t maxlen, coap_link_encoder_ctx_t *context);
1036 
1037 #if IS_USED(MODULE_GCOAP_DTLS) || defined(DOXYGEN)
1046 #endif
1047 
1048 #ifdef __cplusplus
1049 }
1050 #endif
1051 
1052 #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:125
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:673
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:880
#define GCOAP_TOKENLEN_MAX
Maximum length in bytes for a token.
Definition: gcoap.h:475
int(* gcoap_request_matcher_t)(gcoap_listener_t *listener, const coap_resource_t **resource, const coap_pkt_t *pdu)
Handler function for the request matcher strategy.
Definition: gcoap.h:703
gcoap_socket_type_t
Coap socket types.
Definition: gcoap.h:786
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(void *buf, size_t maxlen, uint8_t cf)
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:480
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:741
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.
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:950
kernel_pid_t gcoap_init(void)
Initializes the gcoap thread and device.
uint8_t gcoap_op_state(void)
Provides important operational statistics.
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:899
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.
#define COAP_OPT_FINISH_NONE
no special handling required
Definition: nanocoap.h:160
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.
nanocoap API
DTLS sock definitions.
UDP sock definitions.
Common IP-based transport layer end point.
Definition: sock.h:212
CoAP PDU parsing context structure.
Definition: nanocoap.h:185
Type for CoAP resource entry.
Definition: nanocoap.h:223
Callback Event structure definition.
Definition: callback.h:48
Timeout Event structure.
Definition: timeout.h:54
A modular collection of resources for a server.
Definition: gcoap.h:710
gcoap_link_encoder_t link_encoder
Writes a link for a resource.
Definition: gcoap.h:714
struct gcoap_listener * next
Next listener in list.
Definition: gcoap.h:715
size_t resources_len
Length of array.
Definition: gcoap.h:713
const coap_resource_t * resources
First element in the array of resources; must order alphabetically.
Definition: gcoap.h:711
gcoap_request_matcher_t request_matcher
Function that picks a suitable request handler from a request.
Definition: gcoap.h:727
Memo for Observe registration and notifications.
Definition: gcoap.h:776
unsigned token_len
Actual length of token attribute.
Definition: gcoap.h:780
const coap_resource_t * resource
Entity being observed.
Definition: gcoap.h:778
sock_udp_ep_t * observer
Client endpoint; unused if null.
Definition: gcoap.h:777
Memo to handle a response for a request.
Definition: gcoap.h:756
void * context
ptr to user defined context data
Definition: gcoap.h:768
gcoap_resp_handler_t resp_handler
Callback for the response.
Definition: gcoap.h:767
event_callback_t resp_tmout_cb
Callback for response timeout.
Definition: gcoap.h:770
unsigned state
State of this memo, a GCOAP_MEMO...
Definition: gcoap.h:757
union gcoap_request_memo::@319 msg
Request message data; if confirmable, supports resending message.
int send_limit
Remaining resends, 0 if none; GCOAP_SEND_LIMIT_NON if non-confirmable.
Definition: gcoap.h:758
gcoap_resend_t data
Endpoint and PDU buffer, for resend.
Definition: gcoap.h:763
sock_udp_ep_t remote_ep
Remote endpoint.
Definition: gcoap.h:766
uint8_t hdr_buf[GCOAP_HEADER_MAXLEN]
Copy of PDU header, if no resends.
Definition: gcoap.h:761
event_timeout_t resp_evt_tmout
Limits wait for response.
Definition: gcoap.h:769
Extends request memo for resending a confirmable request.
Definition: gcoap.h:748
uint8_t * pdu_buf
Buffer containing the PDU.
Definition: gcoap.h:749
size_t pdu_len
Length of pdu_buf.
Definition: gcoap.h:750
Coap socket to handle multiple transport types.
Definition: gcoap.h:795
gcoap_socket_type_t type
Type of stored socket.
Definition: gcoap.h:796
sock_dtls_session_t ctx_dtls_session
Session object for the stored socket.
Definition: gcoap.h:804
Information about remote client connected to the server.
Information about DTLS sock.
UDP sock type.
Definition: sock_types.h:128
xtimer interface definitions