gcoap.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2015-2017 Ken Bannister. All rights reserved.
 * SPDX-FileCopyrightText: 2017 Freie Universität Berlin
 * SPDX-License-Identifier: LGPL-2.1-only
 */
 
#pragma once
 
#include <stdint.h>
 
#include "event/callback.h"
#include "event/timeout.h"
#include "net/ipv6/addr.h"
#include "net/sock/udp.h"
#if IS_USED(MODULE_GCOAP_DTLS)
#include "net/sock/dtls.h"
#endif
#include "net/nanocoap.h"
#include "net/nanocoap/cache.h"
#include "timex.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#ifndef CONFIG_GCOAP_PORT
#define CONFIG_GCOAP_PORT              (5683)
#endif
#ifndef CONFIG_GCOAPS_PORT
#define CONFIG_GCOAPS_PORT             (5684)
#endif
 
#ifndef CONFIG_GCOAP_DTLS_HANDSHAKE_TIMEOUT_MSEC
#define CONFIG_GCOAP_DTLS_HANDSHAKE_TIMEOUT_MSEC    (3 * MS_PER_SEC)
#endif
 
#ifndef CONFIG_GCOAP_DTLS_MINIMUM_AVAILABLE_SESSIONS
#define CONFIG_GCOAP_DTLS_MINIMUM_AVAILABLE_SESSIONS  (1)
#endif
 
#ifndef CONFIG_GCOAP_DTLS_MINIMUM_AVAILABLE_SESSIONS_TIMEOUT_MSEC
#define CONFIG_GCOAP_DTLS_MINIMUM_AVAILABLE_SESSIONS_TIMEOUT_MSEC  (15 * MS_PER_SEC)
#endif
 
#ifndef CONFIG_GCOAP_PDU_BUF_SIZE
#define CONFIG_GCOAP_PDU_BUF_SIZE      (128)
#endif
 
#ifndef CONFIG_GCOAP_REQ_WAITING_MAX
#define CONFIG_GCOAP_REQ_WAITING_MAX   (2)
#endif
#define GCOAP_TOKENLEN_MAX      (8)
 
#define GCOAP_HEADER_MAXLEN     (sizeof(coap_hdr_t) + GCOAP_TOKENLEN_MAX)
 
#ifndef CONFIG_GCOAP_TOKENLEN
#define CONFIG_GCOAP_TOKENLEN          (2)
#endif
 
#define GCOAP_PAYLOAD_MARKER    (0xFF)
 
#ifndef CONFIG_GCOAP_NO_AUTO_INIT
#define CONFIG_GCOAP_NO_AUTO_INIT      0
#endif
 
#define GCOAP_MEMO_UNUSED       (0)     
#define GCOAP_MEMO_RETRANSMIT   (1)     
#define GCOAP_MEMO_WAIT         (2)     
#define GCOAP_MEMO_RESP         (3)     
#define GCOAP_MEMO_TIMEOUT      (4)     
#define GCOAP_MEMO_ERR          (5)     
#define GCOAP_MEMO_RESP_TRUNC   (6)     
#define GCOAP_SEND_LIMIT_NON    (-1)
 
#ifdef DOXYGEN
#define CONFIG_GCOAP_NO_RETRANS_BACKOFF
#endif
 
#ifndef CONFIG_GCOAP_NON_TIMEOUT_MSEC
#define CONFIG_GCOAP_NON_TIMEOUT_MSEC       (5000U)
#endif
 
#ifndef CONFIG_GCOAP_OBS_CLIENTS_MAX
#define CONFIG_GCOAP_OBS_CLIENTS_MAX   (2)
#endif
 
#ifndef CONFIG_GCOAP_OBS_NOTIFIERS_MAX
#define CONFIG_GCOAP_OBS_NOTIFIERS_MAX  (2)
#endif
 
#ifndef CONFIG_GCOAP_OBS_REGISTRATIONS_MAX
#define CONFIG_GCOAP_OBS_REGISTRATIONS_MAX     (2)
#endif
 
#define GCOAP_OBS_MEMO_UNUSED   (0) 
#define GCOAP_OBS_MEMO_IDLE     (1) 
#define GCOAP_OBS_MEMO_PENDING  (2) 
#ifndef CONFIG_GCOAP_OBS_VALUE_WIDTH
#define CONFIG_GCOAP_OBS_VALUE_WIDTH   (3)
#endif
 
#if (CONFIG_GCOAP_OBS_VALUE_WIDTH == 3)
#define GCOAP_OBS_TICK_EXPONENT (0)
#elif (CONFIG_GCOAP_OBS_VALUE_WIDTH == 2)
#define GCOAP_OBS_TICK_EXPONENT (6)
#elif (CONFIG_GCOAP_OBS_VALUE_WIDTH == 1)
#define GCOAP_OBS_TICK_EXPONENT (14)
#endif
 
#define GCOAP_OBS_INIT_OK       (0)
#define GCOAP_OBS_INIT_ERR      (-1)
#define GCOAP_OBS_INIT_UNUSED   (-2)
#ifndef GCOAP_DTLS_EXTRA_STACKSIZE
#if IS_USED(MODULE_GCOAP_DTLS)
#define GCOAP_DTLS_EXTRA_STACKSIZE  (THREAD_STACKSIZE_DEFAULT)
#else
#define GCOAP_DTLS_EXTRA_STACKSIZE  (0)
#endif
#endif
 
#if IS_USED(MODULE_GCOAP_FILESERVER)
#include "vfs.h"
#define GCOAP_VFS_EXTRA_STACKSIZE   (VFS_DIR_BUFFER_SIZE + VFS_FILE_BUFFER_SIZE)
#else
#define GCOAP_VFS_EXTRA_STACKSIZE   (0)
#endif
 
#ifndef GCOAP_STACK_SIZE
#define GCOAP_STACK_SIZE (THREAD_STACKSIZE_DEFAULT + DEBUG_EXTRA_STACKSIZE \
                          + sizeof(coap_pkt_t) + GCOAP_DTLS_EXTRA_STACKSIZE \
                          + GCOAP_VFS_EXTRA_STACKSIZE)
#endif
#ifndef CONFIG_GCOAP_RESEND_BUFS_MAX
#define CONFIG_GCOAP_RESEND_BUFS_MAX      (1)
#endif
 
#define COAP_LINK_FLAG_INIT_RESLIST  (1)  
typedef struct {
    unsigned content_format;            
    size_t link_pos;                    
    uint16_t flags;                     
} coap_link_encoder_ctx_t;
 
typedef ssize_t (*gcoap_link_encoder_t)(const coap_resource_t *resource, char *buf,
                                        size_t maxlen, coap_link_encoder_ctx_t *context);
 
#define GCOAP_RESOURCE_FOUND        (0)
#define GCOAP_RESOURCE_WRONG_METHOD (1)
#define GCOAP_RESOURCE_NO_PATH      (2)
#define GCOAP_RESOURCE_ERROR        (3)
typedef struct gcoap_listener gcoap_listener_t;
 
typedef int (*gcoap_request_matcher_t)(gcoap_listener_t *listener,
                                       const coap_resource_t **resource,
                                       coap_pkt_t *pdu);
 
typedef enum {
    GCOAP_SOCKET_TYPE_UNDEF = 0x0,      
    GCOAP_SOCKET_TYPE_UDP = 0x1,        
    GCOAP_SOCKET_TYPE_DTLS = 0x2,       
} gcoap_socket_type_t;
 
typedef struct {
    gcoap_socket_type_t type;                
    union {
        sock_udp_t *udp;
#if IS_USED(MODULE_GCOAP_DTLS) || defined(DOXYGEN)
        sock_dtls_t *dtls;
#endif
    } socket;                               
#if IS_USED(MODULE_GCOAP_DTLS) || defined(DOXYGEN)
    sock_dtls_session_t ctx_dtls_session;   
#endif
} gcoap_socket_t;
 
struct gcoap_listener {
    const coap_resource_t *resources;   
    size_t resources_len;               
    gcoap_socket_type_t tl_type;
    gcoap_link_encoder_t link_encoder;  
    struct gcoap_listener *next;        
    gcoap_request_matcher_t request_matcher;
};
 
typedef struct gcoap_request_memo gcoap_request_memo_t;
 
typedef void (*gcoap_resp_handler_t)(const gcoap_request_memo_t *memo,
                                     coap_pkt_t* pdu,
                                     const sock_udp_ep_t *remote);
 
typedef struct {
    uint8_t *pdu_buf;                   
    size_t pdu_len;                     
} gcoap_resend_t;
 
struct gcoap_request_memo {
    unsigned state;                     
    int send_limit;                     
    union {
        uint8_t hdr_buf[GCOAP_HEADER_MAXLEN];
        gcoap_resend_t data;            
    } msg;                              
    sock_udp_ep_t remote_ep;            
    gcoap_resp_handler_t resp_handler;  
    void *context;                      
    event_timeout_t resp_evt_tmout;     
    event_callback_t resp_tmout_cb;     
    gcoap_socket_t socket;              
#if IS_USED(MODULE_NANOCOAP_CACHE) || DOXYGEN
    uint8_t cache_key[CONFIG_NANOCOAP_CACHE_KEY_LENGTH];
#endif
};
 
typedef struct {
    sock_udp_ep_t *observer;            
    sock_udp_ep_t *notifier;            
    const coap_resource_t *resource;    
    uint8_t token[GCOAP_TOKENLEN_MAX];  
    uint16_t last_msgid;                
    unsigned token_len;                 
    gcoap_socket_t socket;              
} gcoap_observe_memo_t;
 
kernel_pid_t gcoap_init(void);
 
void gcoap_register_listener(gcoap_listener_t *listener);
 
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);
 
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);
 
static inline int gcoap_req_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
                                 unsigned code, const char *path)
{
    return gcoap_req_init_path_buffer(pdu, buf, len, code, path,
                                      (path) ? strlen(path) : 0U);
}
 
static inline ssize_t gcoap_request(coap_pkt_t *pdu, uint8_t *buf, size_t len,
                                    unsigned code, char *path)
{
    if (gcoap_req_init(pdu, buf, len, code, path) == 0) {
        if (IS_USED(MODULE_NANOCOAP_CACHE)) {
            /* remove ETag option slack added for cache validation */
            coap_opt_remove(pdu, COAP_OPT_ETAG);
        }
        return coap_opt_finish(pdu, COAP_OPT_FINISH_NONE);
    }
    return -1;
}
 
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);
 
int gcoap_resp_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code);
 
static inline ssize_t gcoap_response(coap_pkt_t *pdu, uint8_t *buf,
                                     size_t len, unsigned code)
{
    return (gcoap_resp_init(pdu, buf, len, code) == 0)
                ? coap_opt_finish(pdu, COAP_OPT_FINISH_NONE)
                : -1;
}
 
int gcoap_obs_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
                   const coap_resource_t *resource);
 
size_t gcoap_obs_send(const uint8_t *buf, size_t len,
                      const coap_resource_t *resource);
 
int gcoap_obs_req_forget(const sock_udp_ep_t *remote, const uint8_t *token,
                         size_t tokenlen);
 
uint8_t gcoap_op_state(void);
 
int gcoap_get_resource_list(void *buf, size_t maxlen, uint8_t cf,
                               gcoap_socket_type_t tl_type);
 
ssize_t gcoap_encode_link(const coap_resource_t *resource, char *buf,
                          size_t maxlen, coap_link_encoder_ctx_t *context);
 
#if IS_USED(MODULE_GCOAP_DTLS) || defined(DOXYGEN)
sock_dtls_t *gcoap_get_sock_dtls(void);
#endif
 
static inline coap_hdr_t *gcoap_request_memo_get_hdr(const gcoap_request_memo_t *memo)
{
    if (memo->send_limit == GCOAP_SEND_LIMIT_NON) {
        return (coap_hdr_t *)&memo->msg.hdr_buf[0];
    }
    else {
        return (coap_hdr_t *)memo->msg.data.pdu_buf;
    }
}
 
#ifdef __cplusplus
}
#endif