coap.h

Go to the documentation of this file.

/*
 * Copyright (c) 2018 Intel Corporation
 * Copyright (c) 2021 Nordic Semiconductor
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_NET_COAP_H_
#define ZEPHYR_INCLUDE_NET_COAP_H_
 
#include <zephyr/types.h>
#include <stddef.h>
#include <stdbool.h>
#include <zephyr/net/net_ip.h>
#include <zephyr/sys/math_extras.h>
#include <zephyr/sys/slist.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
enum coap_option_num {
        COAP_OPTION_IF_MATCH = 1,        
        COAP_OPTION_URI_HOST = 3,        
        COAP_OPTION_ETAG = 4,            
        COAP_OPTION_IF_NONE_MATCH = 5,   
        COAP_OPTION_OBSERVE = 6,         
        COAP_OPTION_URI_PORT = 7,        
        COAP_OPTION_LOCATION_PATH = 8,   
        COAP_OPTION_URI_PATH = 11,       
        COAP_OPTION_CONTENT_FORMAT = 12, 
        COAP_OPTION_MAX_AGE = 14,        
        COAP_OPTION_URI_QUERY = 15,      
        COAP_OPTION_ACCEPT = 17,         
        COAP_OPTION_LOCATION_QUERY = 20, 
        COAP_OPTION_BLOCK2 = 23,         
        COAP_OPTION_BLOCK1 = 27,         
        COAP_OPTION_SIZE2 = 28,          
        COAP_OPTION_PROXY_URI = 35,      
        COAP_OPTION_PROXY_SCHEME = 39,   
        COAP_OPTION_SIZE1 = 60,          
        COAP_OPTION_ECHO = 252,          
        COAP_OPTION_NO_RESPONSE = 258,   
        COAP_OPTION_REQUEST_TAG = 292    
};
 
enum coap_method {
        COAP_METHOD_GET = 1,     
        COAP_METHOD_POST = 2,    
        COAP_METHOD_PUT = 3,     
        COAP_METHOD_DELETE = 4,  
        COAP_METHOD_FETCH = 5,   
        COAP_METHOD_PATCH = 6,   
        COAP_METHOD_IPATCH = 7,  
};
 
#define COAP_REQUEST_MASK 0x07
 
#define COAP_VERSION_1 1U
 
#define COAP_OBSERVE_MAX_AGE 0xFFFFFF
 
enum coap_msgtype {
        COAP_TYPE_CON = 0,
        COAP_TYPE_NON_CON = 1,
        COAP_TYPE_ACK = 2,
        COAP_TYPE_RESET = 3
};
 
#define COAP_MAKE_RESPONSE_CODE(class, det) ((class << 5) | (det))
 
enum coap_response_code {
        COAP_RESPONSE_CODE_OK = COAP_MAKE_RESPONSE_CODE(2, 0),
        COAP_RESPONSE_CODE_CREATED = COAP_MAKE_RESPONSE_CODE(2, 1),
        COAP_RESPONSE_CODE_DELETED = COAP_MAKE_RESPONSE_CODE(2, 2),
        COAP_RESPONSE_CODE_VALID = COAP_MAKE_RESPONSE_CODE(2, 3),
        COAP_RESPONSE_CODE_CHANGED = COAP_MAKE_RESPONSE_CODE(2, 4),
        COAP_RESPONSE_CODE_CONTENT = COAP_MAKE_RESPONSE_CODE(2, 5),
        COAP_RESPONSE_CODE_CONTINUE = COAP_MAKE_RESPONSE_CODE(2, 31),
        COAP_RESPONSE_CODE_BAD_REQUEST = COAP_MAKE_RESPONSE_CODE(4, 0),
        COAP_RESPONSE_CODE_UNAUTHORIZED = COAP_MAKE_RESPONSE_CODE(4, 1),
        COAP_RESPONSE_CODE_BAD_OPTION = COAP_MAKE_RESPONSE_CODE(4, 2),
        COAP_RESPONSE_CODE_FORBIDDEN = COAP_MAKE_RESPONSE_CODE(4, 3),
        COAP_RESPONSE_CODE_NOT_FOUND = COAP_MAKE_RESPONSE_CODE(4, 4),
        COAP_RESPONSE_CODE_NOT_ALLOWED = COAP_MAKE_RESPONSE_CODE(4, 5),
        COAP_RESPONSE_CODE_NOT_ACCEPTABLE = COAP_MAKE_RESPONSE_CODE(4, 6),
        COAP_RESPONSE_CODE_INCOMPLETE = COAP_MAKE_RESPONSE_CODE(4, 8),
        COAP_RESPONSE_CODE_CONFLICT = COAP_MAKE_RESPONSE_CODE(4, 9),
        COAP_RESPONSE_CODE_PRECONDITION_FAILED = COAP_MAKE_RESPONSE_CODE(4, 12),
        COAP_RESPONSE_CODE_REQUEST_TOO_LARGE = COAP_MAKE_RESPONSE_CODE(4, 13),
        COAP_RESPONSE_CODE_UNSUPPORTED_CONTENT_FORMAT =
                                                COAP_MAKE_RESPONSE_CODE(4, 15),
        COAP_RESPONSE_CODE_UNPROCESSABLE_ENTITY = COAP_MAKE_RESPONSE_CODE(4, 22),
        COAP_RESPONSE_CODE_TOO_MANY_REQUESTS = COAP_MAKE_RESPONSE_CODE(4, 29),
        COAP_RESPONSE_CODE_INTERNAL_ERROR = COAP_MAKE_RESPONSE_CODE(5, 0),
        COAP_RESPONSE_CODE_NOT_IMPLEMENTED = COAP_MAKE_RESPONSE_CODE(5, 1),
        COAP_RESPONSE_CODE_BAD_GATEWAY = COAP_MAKE_RESPONSE_CODE(5, 2),
        COAP_RESPONSE_CODE_SERVICE_UNAVAILABLE = COAP_MAKE_RESPONSE_CODE(5, 3),
        COAP_RESPONSE_CODE_GATEWAY_TIMEOUT = COAP_MAKE_RESPONSE_CODE(5, 4),
        COAP_RESPONSE_CODE_PROXYING_NOT_SUPPORTED =
                                                COAP_MAKE_RESPONSE_CODE(5, 5)
};
 
#define COAP_CODE_EMPTY (0)
 
#define COAP_TOKEN_MAX_LEN 8UL
 
enum coap_content_format {
        COAP_CONTENT_FORMAT_TEXT_PLAIN = 0,             
        COAP_CONTENT_FORMAT_APP_LINK_FORMAT = 40,       
        COAP_CONTENT_FORMAT_APP_XML = 41,               
        COAP_CONTENT_FORMAT_APP_OCTET_STREAM = 42,      
        COAP_CONTENT_FORMAT_APP_EXI = 47,               
        COAP_CONTENT_FORMAT_APP_JSON = 50,              
        COAP_CONTENT_FORMAT_APP_JSON_PATCH_JSON = 51,   
        COAP_CONTENT_FORMAT_APP_MERGE_PATCH_JSON = 52,  
        COAP_CONTENT_FORMAT_APP_CBOR = 60               
};
 
enum coap_no_response {
        COAP_NO_RESPONSE_SUPPRESS_2_XX = 0x02,
        COAP_NO_RESPONSE_SUPPRESS_4_XX = 0x08,
        COAP_NO_RESPONSE_SUPPRESS_5_XX = 0x10,
 
        COAP_NO_RESPONSE_SUPPRESS_ALL = COAP_NO_RESPONSE_SUPPRESS_2_XX |
                                        COAP_NO_RESPONSE_SUPPRESS_4_XX |
                                        COAP_NO_RESPONSE_SUPPRESS_5_XX,
};
 
/* block option helper */
#define GET_BLOCK_NUM(v)        ((v) >> 4)
#define GET_BLOCK_SIZE(v)       (((v) & 0x7))
#define GET_MORE(v)             (!!((v) & 0x08))
 
struct coap_observer;
struct coap_packet;
struct coap_pending;
struct coap_reply;
struct coap_resource;
 
typedef int (*coap_method_t)(struct coap_resource *resource,
                             struct coap_packet *request,
                             struct sockaddr *addr, socklen_t addr_len);
 
typedef void (*coap_notify_t)(struct coap_resource *resource,
                              struct coap_observer *observer);
 
struct coap_resource {
        coap_method_t get, post, put, del, fetch, patch, ipatch;
        coap_notify_t notify;
        const char * const *path;
        void *user_data;
        sys_slist_t observers;
        int age;
};
 
struct coap_observer {
        sys_snode_t list;
        struct sockaddr addr;
        uint8_t token[8];
        uint8_t tkl;
};
 
struct coap_packet {
        uint8_t *data;    
        uint16_t offset;  
        uint16_t max_len; 
        uint8_t hdr_len;  
        uint16_t opt_len; 
        uint16_t delta;   
#if defined(CONFIG_COAP_KEEP_USER_DATA) || defined(DOXYGEN)
        void *user_data;
#endif
};
 
struct coap_option {
        uint16_t delta;     
#if defined(CONFIG_COAP_EXTENDED_OPTIONS_LEN)
        uint16_t len;
        uint8_t value[CONFIG_COAP_EXTENDED_OPTIONS_LEN_VALUE];
#else
        uint8_t len;        
        uint8_t value[12];  
#endif
};
 
typedef int (*coap_reply_t)(const struct coap_packet *response,
                            struct coap_reply *reply,
                            const struct sockaddr *from);
 
struct coap_transmission_parameters {
        uint32_t ack_timeout;
#if defined(CONFIG_COAP_RANDOMIZE_ACK_TIMEOUT) || defined(__DOXYGEN__)
        uint16_t ack_random_percent;
#endif /* defined(CONFIG_COAP_RANDOMIZE_ACK_TIMEOUT) */
        uint16_t coap_backoff_percent;
        uint8_t max_retransmission;
};
 
struct coap_pending {
        struct sockaddr addr; 
        int64_t t0;           
        uint32_t timeout;     
        uint16_t id;          
        uint8_t *data;        
        uint16_t len;         
        uint8_t retries;      
        struct coap_transmission_parameters params; 
};
 
struct coap_reply {
        coap_reply_t reply;
        void *user_data;
        int age;
        uint16_t id;
        uint8_t token[8];
        uint8_t tkl;
};
 
uint8_t coap_header_get_version(const struct coap_packet *cpkt);
 
uint8_t coap_header_get_type(const struct coap_packet *cpkt);
 
uint8_t coap_header_get_token(const struct coap_packet *cpkt, uint8_t *token);
 
uint8_t coap_header_get_code(const struct coap_packet *cpkt);
 
int coap_header_set_code(const struct coap_packet *cpkt, uint8_t code);
 
uint16_t coap_header_get_id(const struct coap_packet *cpkt);
 
const uint8_t *coap_packet_get_payload(const struct coap_packet *cpkt,
                                       uint16_t *len);
 
bool coap_uri_path_match(const char * const *path,
                         struct coap_option *options,
                         uint8_t opt_num);
 
int coap_packet_parse(struct coap_packet *cpkt, uint8_t *data, uint16_t len,
                      struct coap_option *options, uint8_t opt_num);
 
int coap_packet_set_path(struct coap_packet *cpkt, const char *path);
 
int coap_packet_init(struct coap_packet *cpkt, uint8_t *data, uint16_t max_len,
                     uint8_t ver, uint8_t type, uint8_t token_len,
                     const uint8_t *token, uint8_t code, uint16_t id);
 
int coap_ack_init(struct coap_packet *cpkt, const struct coap_packet *req,
                  uint8_t *data, uint16_t max_len, uint8_t code);
 
int coap_rst_init(struct coap_packet *cpkt, const struct coap_packet *req,
                  uint8_t *data, uint16_t max_len);
uint8_t *coap_next_token(void);
 
uint16_t coap_next_id(void);
 
int coap_find_options(const struct coap_packet *cpkt, uint16_t code,
                      struct coap_option *options, uint16_t veclen);
 
int coap_packet_append_option(struct coap_packet *cpkt, uint16_t code,
                              const uint8_t *value, uint16_t len);
 
int coap_packet_remove_option(struct coap_packet *cpkt, uint16_t code);
 
unsigned int coap_option_value_to_int(const struct coap_option *option);
 
int coap_append_option_int(struct coap_packet *cpkt, uint16_t code,
                           unsigned int val);
 
int coap_packet_append_payload_marker(struct coap_packet *cpkt);
 
int coap_packet_append_payload(struct coap_packet *cpkt, const uint8_t *payload,
                               uint16_t payload_len);
 
bool coap_packet_is_request(const struct coap_packet *cpkt);
 
int coap_handle_request_len(struct coap_packet *cpkt,
                            struct coap_resource *resources,
                            size_t resources_len,
                            struct coap_option *options,
                            uint8_t opt_num,
                            struct sockaddr *addr, socklen_t addr_len);
 
int coap_handle_request(struct coap_packet *cpkt,
                        struct coap_resource *resources,
                        struct coap_option *options,
                        uint8_t opt_num,
                        struct sockaddr *addr, socklen_t addr_len);
 
enum coap_block_size {
        COAP_BLOCK_16,   
        COAP_BLOCK_32,   
        COAP_BLOCK_64,   
        COAP_BLOCK_128,  
        COAP_BLOCK_256,  
        COAP_BLOCK_512,  
        COAP_BLOCK_1024, 
};
 
static inline uint16_t coap_block_size_to_bytes(
        enum coap_block_size block_size)
{
        return (1 << (block_size + 4));
}
 
static inline enum coap_block_size coap_bytes_to_block_size(uint16_t bytes)
{
        int sz = u32_count_trailing_zeros(bytes) - 4;
 
        if (sz < COAP_BLOCK_16) {
                return COAP_BLOCK_16;
        }
        if (sz > COAP_BLOCK_1024) {
                return COAP_BLOCK_1024;
        }
        return (enum coap_block_size)sz;
}
 
struct coap_block_context {
        size_t total_size;
        size_t current;
        enum coap_block_size block_size;
};
 
int coap_block_transfer_init(struct coap_block_context *ctx,
                             enum coap_block_size block_size,
                             size_t total_size);
 
int coap_append_descriptive_block_option(struct coap_packet *cpkt, struct coap_block_context *ctx);
 
bool coap_has_descriptive_block_option(struct coap_packet *cpkt);
 
int coap_remove_descriptive_block_option(struct coap_packet *cpkt);
 
bool coap_block_has_more(struct coap_packet *cpkt);
 
int coap_append_block1_option(struct coap_packet *cpkt,
                              struct coap_block_context *ctx);
 
int coap_append_block2_option(struct coap_packet *cpkt,
                              struct coap_block_context *ctx);
 
int coap_append_size1_option(struct coap_packet *cpkt,
                             struct coap_block_context *ctx);
 
int coap_append_size2_option(struct coap_packet *cpkt,
                             struct coap_block_context *ctx);
 
int coap_get_option_int(const struct coap_packet *cpkt, uint16_t code);
 
int coap_get_block1_option(const struct coap_packet *cpkt, bool *has_more, uint32_t *block_number);
 
int coap_get_block2_option(const struct coap_packet *cpkt, bool *has_more,
                           uint32_t *block_number);
 
int coap_update_from_block(const struct coap_packet *cpkt,
                           struct coap_block_context *ctx);
 
int coap_next_block_for_option(const struct coap_packet *cpkt,
                               struct coap_block_context *ctx,
                               enum coap_option_num option);
 
size_t coap_next_block(const struct coap_packet *cpkt,
                       struct coap_block_context *ctx);
 
void coap_observer_init(struct coap_observer *observer,
                        const struct coap_packet *request,
                        const struct sockaddr *addr);
 
bool coap_register_observer(struct coap_resource *resource,
                            struct coap_observer *observer);
 
bool coap_remove_observer(struct coap_resource *resource,
                          struct coap_observer *observer);
 
struct coap_observer *coap_find_observer(
        struct coap_observer *observers, size_t len,
        const struct sockaddr *addr,
        const uint8_t *token, uint8_t token_len);
 
struct coap_observer *coap_find_observer_by_addr(
        struct coap_observer *observers, size_t len,
        const struct sockaddr *addr);
 
struct coap_observer *coap_find_observer_by_token(
        struct coap_observer *observers, size_t len,
        const uint8_t *token, uint8_t token_len);
 
struct coap_observer *coap_observer_next_unused(
        struct coap_observer *observers, size_t len);
 
void coap_reply_init(struct coap_reply *reply,
                     const struct coap_packet *request);
 
int coap_pending_init(struct coap_pending *pending,
                      const struct coap_packet *request,
                      const struct sockaddr *addr,
                      const struct coap_transmission_parameters *params);
 
struct coap_pending *coap_pending_next_unused(
        struct coap_pending *pendings, size_t len);
 
struct coap_reply *coap_reply_next_unused(
        struct coap_reply *replies, size_t len);
 
struct coap_pending *coap_pending_received(
        const struct coap_packet *response,
        struct coap_pending *pendings, size_t len);
 
struct coap_reply *coap_response_received(
        const struct coap_packet *response,
        const struct sockaddr *from,
        struct coap_reply *replies, size_t len);
 
struct coap_pending *coap_pending_next_to_expire(
        struct coap_pending *pendings, size_t len);
 
bool coap_pending_cycle(struct coap_pending *pending);
 
void coap_pending_clear(struct coap_pending *pending);
 
void coap_pendings_clear(struct coap_pending *pendings, size_t len);
 
size_t coap_pendings_count(struct coap_pending *pendings, size_t len);
 
void coap_reply_clear(struct coap_reply *reply);
 
void coap_replies_clear(struct coap_reply *replies, size_t len);
 
int coap_resource_notify(struct coap_resource *resource);
 
bool coap_request_is_observe(const struct coap_packet *request);
 
struct coap_transmission_parameters coap_get_transmission_parameters(void);
 
void coap_set_transmission_parameters(const struct coap_transmission_parameters *params);
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_NET_COAP_H_ */