coap_option.h

Go to the documentation of this file.

/*
 * coap_option.h -- helpers for handling options in CoAP PDUs
 *
 * Copyright (C) 2010-2013,2022-2026 Olaf Bergmann <bergmann@tzi.org>
 *
 * SPDX-License-Identifier: BSD-2-Clause
 *
 * This file is part of the CoAP library libcoap. Please see README for terms
 * of use.
 */

 
#ifndef COAP_OPTION_H_
#define COAP_OPTION_H_
 
#if defined(RIOT_VERSION)
#include <thread.h>
#endif /* RIOT_VERSION */
 
#if defined(_WIN32)
#include <stddef.h>
#include <stdint.h>
#endif /* _WIN32 */
 
#ifndef NULL
#define NULL 0
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef uint16_t coap_option_num_t;
 
/*
 * CoAP option numbers (be sure to update coap_option_check_critical()
 * and coap_option_check_repeatable() when adding options).
 */
 
/*
 * The C, U, and N flags indicate the properties
 * Critical, Unsafe, and NoCacheKey, respectively.
 * If U is set, then N has no meaning as per
 * https://rfc-editor.org/rfc/rfc7252#section-5.10
 * and is set to a -.
 *
 * Separately, R is for the options that can be repeated
 *
 * The least significant byte of the option is set as followed
 * as per https://rfc-editor.org/rfc/rfc7252#section-5.4.6
 *
 *   0   1   2   3   4   5   6   7
 * --+---+---+---+---+---+---+---+
 *           | NoCacheKey| U | C |
 * --+---+---+---+---+---+---+---+
 *
 * https://rfc-editor.org/rfc/rfc8613#section-4 goes on to define E, I and U
 * properties Encrypted and Integrity Protected, Integrity Protected Only, and
 * Unprotected respectively.  Integrity Protected Only is not currently used.
 *
 * An Option is tagged with CUNREIU with any of the letters replaced with _ if
 * not set, or - for N if U is set (see above) for aiding understanding of the
 * Option.
 */
 
typedef enum coap_code_opt_num_t {
  COAP_OPTION_IF_MATCH      =   1, /* C__RE__, opaque,      0-8 B, none, RFC7252 */
  COAP_OPTION_URI_HOST      =   3, /* CU-___U, String,    1-255 B, none, RFC7252 */
  COAP_OPTION_ETAG          =   4, /* ___RE__, opaque,      1-8 B, none, RFC7252 */
  COAP_OPTION_IF_NONE_MATCH =   5, /* C___E__, empty,         0 B, none, RFC7252 */
  COAP_OPTION_OBSERVE       =   6, /* _U-_E_U, empty/uint,0/0-3 B, none, RFC7641 */
  COAP_OPTION_URI_PORT      =   7, /* CU-___U, uint,        0-2 B, none, RFC7252 */
  COAP_OPTION_LOCATION_PATH =   8, /* ___RE__, String,    0-255 B, none, RFC7252 */
  COAP_OPTION_OSCORE        =   9, /* C_____U, *,         0-255 B, none, RFC8613 */
  COAP_OPTION_URI_PATH      =  11, /* CU-RE__, String,    0-255 B, none, RFC7252 */
  COAP_OPTION_CONTENT_FORMAT=  12, /* ____E__, uint,        0-2 B, none, RFC7252 */
  COAP_OPTION_URI_PATH_ABB  =  13, /* C___E__, uint,        0-4 B, none, RFC TBD */
  /* COAP_OPTION_MAXAGE default 60 seconds if not set */
  COAP_OPTION_MAXAGE        =  14, /* _U-_E_U, uint,        0-4 B, 60,   RFC7252 */
  COAP_OPTION_URI_QUERY     =  15, /* CU-RE__, String,    1-255 B, none, RFC7252 */
  COAP_OPTION_HOP_LIMIT     =  16, /* ______U, uint,          1 B, none, RFC8768 */
  COAP_OPTION_ACCEPT        =  17, /* C___E__, uint,        0-2 B, none, RFC7252 */
  COAP_OPTION_Q_BLOCK1      =  19, /* CU__E_U, uint,        0-3 B, none, RFC9177 */
  COAP_OPTION_LOCATION_QUERY=  20, /* ___RE__, String,    0-255 B, none, RFC7252 */
  COAP_OPTION_EDHOC         =  21, /* C_____U, empty,         0 B, none, RFC9668 */
  COAP_OPTION_BLOCK2        =  23, /* CU-_E_U, uint,        0-3 B, none, RFC7959 */
  COAP_OPTION_BLOCK1        =  27, /* CU-_E_U, uint,        0-3 B, none, RFC7959 */
  COAP_OPTION_SIZE2         =  28, /* __N_E_U, uint,        0-4 B, none, RFC7959 */
  COAP_OPTION_Q_BLOCK2      =  31, /* CU_RE_U, uint,        0-3 B, none, RFC9177 */
  COAP_OPTION_PROXY_URI     =  35, /* CU-___U, String,   1-1034 B, none, RFC7252 */
  COAP_OPTION_PROXY_SCHEME  =  39, /* CU-___U, String,    1-255 B, none, RFC7252 */
  COAP_OPTION_SIZE1         =  60, /* __N_E_U, uint,        0-4 B, none, RFC7252 */
  COAP_OPTION_ECHO          = 252, /* __N_E_U, opaque,     0-40 B, none, RFC9175 */
  COAP_OPTION_NORESPONSE    = 258, /* _U-_E_U, uint,        0-1 B, none, RFC7967 */
  COAP_OPTION_RTAG          = 292, /* ___RE_U, opaque,      0-8 B, none, RFC9175 */
} coap_code_opt_num_t;
 
#define  COAP_OPTION_CONTENT_TYPE COAP_OPTION_CONTENT_FORMAT
 
#if (UINT_MAX > 65535)
#define COAP_MAX_OPT 65535 
#else /* UINT_MAX <= 65535 */
#define COAP_MAX_OPT 65534 
#endif /* UINT_MAX <= 65535 */
 
/* Signaling options */
 
/* Applies to COAP_SIGNALING_CSM (7.01) */
typedef enum coap_sig_csm_opt_t {
  COAP_SIG_OPT_MAX_MESSAGE_SIZE      = 2, /* ____E_U, uint,     0-4 B, 1152, RFC8323 */
  COAP_SIG_OPT_BLOCK_WISE_TRANSFER   = 4, /* ____E_U, empty,      0 B, none, RFC8323 */
  COAP_SIG_OPT_EXTENDED_TOKEN_LENGTH = 6, /* ____E_U, uint,     0-3 B, 8,    RFC8974 */
} coap_sig_csm_opt_t;
 
/* Applies to COAP_SIGNALING_PING / COAP_SIGNALING_PONG (7.02 / 7.03) */
typedef enum coap_sig_ping_opt_t {
  COAP_SIG_OPT_CUSTODY               = 2, /* ____E_U, empty,      0 B, none, RFC8323 */
} coap_sig_ping_opt_t;
 
/* Applies to COAP_SIGNALING_RELEASE (7.04) */
typedef enum coap_sig_release_opt_t {
  COAP_SIG_OPT_ALTERNATIVE_ADDRESS   = 2, /* ___RE_U, String, 1-255 B, none, RFC8323 */
  COAP_SIG_OPT_HOLD_OFF              = 4, /* ____E_U, uint,     0-3 B, none, RFC8323 */
} coap_sig_release_opt_t;
 
/* Applies to COAP_SIGNALING_ABORT (7.05 )*/
typedef enum coap_sig_abort_opt_t {
  COAP_SIG_OPT_BAD_CSM_OPTION        = 2, /* ____E_U, uint,     0-2 B, none, RFC8323 */
} coap_sig_abort_opt_t;
 
/* Backward Application compatability */
#define COAP_SIGNALING_OPTION_MAX_MESSAGE_SIZE      COAP_SIG_OPT_MAX_MESSAGE_SIZE
#define COAP_SIGNALING_OPTION_BLOCK_WISE_TRANSFER   COAP_SIG_OPT_BLOCK_WISE_TRANSFER
#define COAP_SIGNALING_OPTION_EXTENDED_TOKEN_LENGTH COAP_SIG_OPT_EXTENDED_TOKEN_LENGTH
#define COAP_SIGNALING_OPTION_CUSTODY               COAP_SIG_OPT_CUSTODY
#define COAP_SIGNALING_OPTION_ALTERNATIVE_ADDRESS   COAP_SIG_OPT_ALTERNATIVE_ADDRESS
#define COAP_SIGNALING_OPTION_HOLD_OFF              COAP_SIG_OPT_HOLD_OFF
#define COAP_SIGNALING_OPTION_BAD_CSM_OPTION        COAP_SIG_OPT_BAD_CSM_OPTION

typedef uint8_t coap_opt_t;
#define PCHAR(p) ((coap_opt_t *)(p))

typedef struct {
  uint16_t delta;
  size_t length;
  const uint8_t *value;
} coap_option_t;

size_t coap_opt_parse(const coap_opt_t *opt,
                      size_t length,
                      coap_option_t *result);

size_t coap_opt_size(const coap_opt_t *opt);


#define COAP_OPT_FILTER_SHORT 6

#define COAP_OPT_FILTER_LONG  2
 
/* Ensure that COAP_OPT_FILTER_SHORT and COAP_OPT_FILTER_LONG are set
 * correctly. */
#if (COAP_OPT_FILTER_SHORT + COAP_OPT_FILTER_LONG > 16)
#error COAP_OPT_FILTER_SHORT + COAP_OPT_FILTER_LONG must be less or equal 16
#endif /* (COAP_OPT_FILTER_SHORT + COAP_OPT_FILTER_LONG > 16) */
 
/*
 * mask contains a bit vector that indicates which fields in the long_opts[]
 * and subsequent short_opts[] are used. The first COAP_OPT_FILTER_LONG bits
 * correspond to the long option types that are stored in long_opts[]
 * elements. The next COAP_OPT_FILTER_SHORT bits correspond to the short
 * option types that are stored in short_opts[].
 */
typedef struct coap_opt_filter_t {
  uint16_t mask;
  uint16_t long_opts[COAP_OPT_FILTER_LONG];
  uint8_t short_opts[COAP_OPT_FILTER_SHORT];
} coap_opt_filter_t;

#define COAP_OPT_ALL NULL

void coap_option_filter_clear(coap_opt_filter_t *filter);

int coap_option_filter_set(coap_opt_filter_t *filter, coap_option_num_t number);

int coap_option_filter_unset(coap_opt_filter_t *filter,
                             coap_option_num_t number);

int coap_option_filter_get(coap_opt_filter_t *filter, coap_option_num_t number);

typedef struct {
  size_t length;                
  coap_option_num_t number;     
  unsigned int bad:1;           
  unsigned int filtered:1;      
  coap_opt_t *next_option;      
  coap_opt_filter_t filter;     
} coap_opt_iterator_t;

coap_opt_iterator_t *coap_option_iterator_init(const coap_pdu_t *pdu,
                                               coap_opt_iterator_t *oi,
                                               const coap_opt_filter_t *filter);

coap_opt_t *coap_option_next(coap_opt_iterator_t *oi);

coap_opt_t *coap_check_option(const coap_pdu_t *pdu,
                              coap_option_num_t number,
                              coap_opt_iterator_t *oi);

size_t coap_opt_setheader(coap_opt_t *opt,
                          size_t maxlen,
                          uint16_t delta,
                          size_t length);

size_t coap_opt_encode_size(uint16_t delta, size_t length);

size_t coap_opt_encode(coap_opt_t *opt,
                       size_t n,
                       uint16_t delta,
                       const uint8_t *val,
                       size_t length);

uint32_t coap_opt_length(const coap_opt_t *opt);

const uint8_t *coap_opt_value(const coap_opt_t *opt);

typedef struct coap_optlist_t {
  struct coap_optlist_t *next;  
  coap_option_num_t number;     
  size_t length;                
  uint8_t *data;                
} coap_optlist_t;

coap_optlist_t *coap_new_optlist(coap_option_num_t number,
                                 size_t length,
                                 const uint8_t *data);

int coap_add_optlist_pdu(coap_pdu_t *pdu, coap_optlist_t **optlist_chain);
 

int coap_sort_optlist(coap_optlist_t **options);

int coap_insert_optlist(coap_optlist_t **optlist_chain,
                        coap_optlist_t *optlist);

void coap_delete_optlist(coap_optlist_t *optlist_chain);


COAP_STATIC_INLINE COAP_DEPRECATED int
coap_option_setb(coap_opt_filter_t *filter, coap_option_num_t type) {
  return coap_option_filter_set(filter, type) ? 1 : -1;
}

COAP_STATIC_INLINE COAP_DEPRECATED int
coap_option_clrb(coap_opt_filter_t *filter, coap_option_num_t type) {
  return coap_option_filter_unset(filter, type) ? 1 : -1;
}

COAP_STATIC_INLINE COAP_DEPRECATED int
coap_option_getb(coap_opt_filter_t *filter, coap_option_num_t type) {
  return coap_option_filter_get(filter, type);
}
 
#ifdef __cplusplus
}
#endif
 
#endif /* COAP_OPTION_H_ */