coap_block_internal.h

Go to the documentation of this file.

/*
 * coap_block_internal.h -- Structures, Enums & Functions that are not
 * exposed to application programming
 *
 * Copyright (C) 2010-2026 Olaf Bergmann <bergmann@tzi.org>
 * Copyright (C) 2021-2026 Jon Shallow <supjps-libcoap@jpshallow.com>
 *
 * SPDX-License-Identifier: BSD-2-Clause
 *
 * This file is part of the CoAP library libcoap. Please see README for terms
 * of use.
 */

 
#ifndef COAP_BLOCK_INTERNAL_H_
#define COAP_BLOCK_INTERNAL_H_
 
#ifdef __cplusplus
extern "C" {
#endif

 
/*
 * Use the top 20 bits of a 64 bit token for tracking current block in large transfer.
 * However, if smaller tokens are required. this would be set up to 48, leaving 16 bits
 * for unique tokens.
 */
#ifndef STATE_MAX_BLK_CNT_BITS
#define STATE_MAX_BLK_CNT_BITS 20
#endif /* STATE_MAX_BLK_CNT_BITS */
#define STATE_TOKEN_BASE(t) ((t) & (0xffffffffffffffffULL >> STATE_MAX_BLK_CNT_BITS))
#define STATE_TOKEN_RETRY(t) ((uint64_t)(t) >> (64 - STATE_MAX_BLK_CNT_BITS))
#define STATE_TOKEN_FULL(t,r) (STATE_TOKEN_BASE(t) + ((uint64_t)(r) << (64 - STATE_MAX_BLK_CNT_BITS)))
 
#if COAP_Q_BLOCK_SUPPORT
#define COAP_BLOCK_SET_MASK (COAP_BLOCK_USE_LIBCOAP | \
                             COAP_BLOCK_SINGLE_BODY | \
                             COAP_BLOCK_TRY_Q_BLOCK | \
                             COAP_BLOCK_USE_M_Q_BLOCK | \
                             COAP_BLOCK_NO_PREEMPTIVE_RTAG | \
                             COAP_BLOCK_STLESS_FETCH | \
                             COAP_BLOCK_STLESS_BLOCK2 | \
                             COAP_BLOCK_NOT_RANDOM_BLOCK1 | \
                             COAP_BLOCK_FORCE_Q_BLOCK)
#else /* ! COAP_Q_BLOCK_SUPPORT */
#define COAP_BLOCK_SET_MASK (COAP_BLOCK_USE_LIBCOAP | \
                             COAP_BLOCK_SINGLE_BODY | \
                             COAP_BLOCK_NO_PREEMPTIVE_RTAG | \
                             COAP_BLOCK_STLESS_FETCH | \
                             COAP_BLOCK_STLESS_BLOCK2 | \
                             COAP_BLOCK_NOT_RANDOM_BLOCK1)
#endif /* ! COAP_Q_BLOCK_SUPPORT */
 
#define COAP_BLOCK_MAX_SIZE_MASK 0x7000000 /* (svr)Mask to get the max supported block size */
#define COAP_BLOCK_MAX_SIZE_SHIFT 24    /* (svr)Mask shift to get the max supported block size */
#define COAP_BLOCK_MAX_SIZE_GET(a) (((a) & COAP_BLOCK_MAX_SIZE_MASK) >> COAP_BLOCK_MAX_SIZE_SHIFT)
#define COAP_BLOCK_MAX_SIZE_SET(a) (((a) << COAP_BLOCK_MAX_SIZE_SHIFT) & COAP_BLOCK_MAX_SIZE_MASK)
 
#if COAP_Q_BLOCK_SUPPORT
/* Internal use only and are dropped when setting block_mode */
#define COAP_BLOCK_HAS_Q_BLOCK   0x40000000 /* Set when Q_BLOCK supported */
#define COAP_BLOCK_PROBE_Q_BLOCK 0x80000000 /* Set when Q_BLOCK probing */
 
#define set_block_mode_probe_q(block_mode) \
  do { \
    block_mode |= COAP_BLOCK_PROBE_Q_BLOCK; \
    block_mode &= ~(COAP_BLOCK_TRY_Q_BLOCK | COAP_BLOCK_HAS_Q_BLOCK); \
  } while (0)
 
#define set_block_mode_has_q(block_mode) \
  do { \
    block_mode |= COAP_BLOCK_HAS_Q_BLOCK; \
    block_mode &= ~(COAP_BLOCK_TRY_Q_BLOCK | COAP_BLOCK_PROBE_Q_BLOCK); \
  } while (0)
 
#define set_block_mode_drop_q(block_mode) \
  do { \
    block_mode &= ~(COAP_BLOCK_TRY_Q_BLOCK |\
                    COAP_BLOCK_PROBE_Q_BLOCK |\
                    COAP_BLOCK_HAS_Q_BLOCK | \
                    COAP_BLOCK_USE_M_Q_BLOCK | \
                    COAP_BLOCK_FORCE_Q_BLOCK); \
  } while (0)
 
#define COAP_SINGLE_BLOCK_OR_Q (COAP_BLOCK_SINGLE_BODY|COAP_BLOCK_HAS_Q_BLOCK)
#else /* ! COAP_Q_BLOCK_SUPPORT */
#define COAP_SINGLE_BLOCK_OR_Q (COAP_BLOCK_SINGLE_BODY)
#endif /* ! COAP_Q_BLOCK_SUPPORT */
 
typedef enum {
  COAP_RECURSE_OK,
  COAP_RECURSE_NO
} coap_recurse_t;
 
struct coap_lg_range {
  uint32_t begin;
  uint32_t end;
};
 
#ifndef COAP_RBLOCK_CNT
#define COAP_RBLOCK_CNT 6
#endif
#if COAP_RBLOCK_CNT > COAP_DEFAULT_MAX_PAYLOADS -1
#error COAP_RBLOCK_CNT too large
#endif
#if COAP_RBLOCK_CNT < 2
#error COAP_RBLOCK_CNT too small
#endif

typedef struct coap_rblock_t {
  uint32_t used; 
  uint32_t retry;
#if COAP_Q_BLOCK_SUPPORT
  uint32_t processing_payload_set;
  uint32_t latest_payload_set;
#endif /* COAP_Q_BLOCK_SUPPORT */
  struct coap_lg_range range[COAP_RBLOCK_CNT];
  coap_tick_t last_seen;
  uint32_t total_blocks;  
} coap_rblock_t;

typedef struct coap_l_block1_t {
  coap_binary_t *app_token; 
  uint64_t state_token;  
  size_t bert_size;      
  uint32_t count;        
  coap_address_t upstream; /* Unicast IP of server if mcast client session */
} coap_l_block1_t;

typedef struct coap_l_block2_t {
  coap_resource_t *resource; 
  coap_string_t *query;  
  uint64_t etag;         
  coap_pdu_code_t request_method; 
  uint8_t rtag_set;      
  uint8_t rtag_length;   
  uint8_t rtag[8];       
  coap_time_t maxage_expire; 
} coap_l_block2_t;
 
typedef struct coap_lg_xmit_data_t {
  const uint8_t *data;   
  size_t length;         
  coap_get_large_data_t get_func; 
  coap_release_large_data_t release_func; 
  void *app_ptr;         
  uint32_t ref;          
} coap_lg_xmit_data_t;

struct coap_lg_xmit_t {
  struct coap_lg_xmit_t *next;
  uint8_t blk_size;      
  uint16_t option;       
  int last_block;        
  coap_lg_xmit_data_t *data_info; 
  union {
    coap_l_block1_t b1;
    coap_l_block2_t b2;
  } b;
  coap_pdu_t *sent_pdu;  
  coap_tick_t last_payload; 
  coap_tick_t last_sent; 
  coap_tick_t last_all_sent; 
  coap_tick_t last_obs; 
#if COAP_Q_BLOCK_SUPPORT
  coap_tick_t non_timeout_random_ticks; 
  coap_rblock_t send_blocks; 
#endif /* COAP_Q_BLOCK_SUPPORT */
  uint32_t ref;          
};
 
#if COAP_CLIENT_SUPPORT
struct coap_lg_crcv_t {
  struct coap_lg_crcv_t *next;
  uint8_t observe[3];    
  uint8_t observe_length;
  uint8_t observe_set;   
  uint8_t szx;           
  uint8_t etag_set;      
  uint8_t etag_length;   
  uint8_t etag[8];       
  uint16_t content_format; 
  uint8_t last_type;     
  uint8_t initial;       
  uint16_t block_option; 
  uint16_t retry_counter; 
  size_t total_len;      
  coap_binary_t *body_data; 
  coap_binary_t *app_token; 
  coap_bin_const_t **obs_token; 
  size_t obs_token_cnt;  
  uint16_t o_block_option; 
  uint8_t o_blk_size;    
  uint32_t ref;          
  uint64_t state_token;  
  coap_pdu_t *sent_pdu;  
  coap_rblock_t rec_blocks; 
  coap_tick_t last_used; 
  coap_address_t upstream; 
  coap_lg_xmit_data_t *obs_data; 
};
#endif /* COAP_CLIENT_SUPPORT */
 
#if COAP_SERVER_SUPPORT
struct coap_lg_srcv_t {
  struct coap_lg_srcv_t *next;
  uint8_t observe[3];    
  uint8_t observe_length;
  uint8_t observe_set;   
  uint8_t no_more_seen;  
  uint8_t rtag_set;      
  uint8_t rtag_length;   
  uint8_t rtag[8];       
  uint16_t content_format; 
  uint8_t last_type;     
  uint8_t szx;           
  uint16_t block_option; 
  uint8_t dont_timeout;  
  coap_tick_t last_used; 
  size_t total_len;      
  coap_binary_t *body_data; 
  coap_resource_t *resource; 
  coap_rblock_t rec_blocks; 
  coap_bin_const_t *last_token; 
  uint32_t ref;          
#if COAP_Q_BLOCK_SUPPORT
  int32_t r_m_payload_set; 
#endif /* COAP_Q_BLOCK_SUPPORT */
#if COAP_OSCORE_SUPPORT
  oscore_recipient_ctx_t *recipient_ctx; 
#endif /* COAP_OSCORE_SUPPORT */
  coap_cache_key_t *cache_key; 
};
#endif /* COAP_SERVER_SUPPORT */
 
#if COAP_Q_BLOCK_SUPPORT
typedef enum {
  COAP_SEND_SKIP_PDU,
  COAP_SEND_INC_PDU,
  COAP_SEND_MISSING,
} coap_send_pdu_t;
#endif /* COAP_Q_BLOCK_SUPPORT */
 
#if COAP_CLIENT_SUPPORT
coap_lg_crcv_t *coap_block_new_lg_crcv(coap_session_t *session,
                                       coap_pdu_t *pdu,
                                       coap_lg_xmit_t *lg_xmit);

void coap_block_delete_lg_crcv(coap_session_t *session,
                               coap_lg_crcv_t *lg_crcv);

COAP_STATIC_INLINE void
coap_lg_crcv_release_lkd(coap_session_t *session,coap_lg_crcv_t *lg_crcv) {
  coap_block_delete_lg_crcv(session, lg_crcv);
  return;
}

COAP_STATIC_INLINE void
coap_lg_crcv_reference_lkd(coap_lg_crcv_t *lg_crcv) {
  lg_crcv->ref++;
  return;
}
 
int coap_block_check_lg_crcv_timeouts(coap_session_t *session,
                                      coap_tick_t now,
                                      coap_tick_t *tim_rem);
 
#if COAP_Q_BLOCK_SUPPORT
coap_mid_t coap_send_q_block1(coap_session_t *session,
                              coap_block_b_t block,
                              coap_pdu_t *request,
                              coap_send_pdu_t send_request);

int coap_block_check_q_block1_xmit(coap_session_t *session,
                                   coap_tick_t now, coap_tick_t *tim_rem);
 
coap_mid_t coap_block_test_q_block(coap_session_t *session, coap_pdu_t *actual);
#endif /* COAP_Q_BLOCK_SUPPORT */
 
#endif /* COAP_CLIENT_SUPPORT */
 
#if COAP_Q_BLOCK_SUPPORT
coap_mid_t coap_send_q_blocks(coap_session_t *session,
                              coap_lg_xmit_t *lg_xmit,
                              coap_block_b_t block,
                              coap_pdu_t *pdu,
                              coap_send_pdu_t send_pdu);
#endif /* COAP_Q_BLOCK_SUPPORT */
 
#if COAP_SERVER_SUPPORT
void coap_block_delete_lg_srcv(coap_session_t *session,
                               coap_lg_srcv_t *lg_srcv);

COAP_STATIC_INLINE void
coap_lg_srcv_release_lkd(coap_session_t *session,coap_lg_srcv_t *lg_srcv) {
  coap_block_delete_lg_srcv(session, lg_srcv);
  return;
}

COAP_STATIC_INLINE void
coap_lg_srcv_reference_lkd(coap_lg_srcv_t *lg_srcv) {
  lg_srcv->ref++;
  return;
}
 
int coap_block_check_lg_srcv_timeouts(coap_session_t *session,
                                      coap_tick_t now,
                                      coap_tick_t *tim_rem);
 
#if COAP_Q_BLOCK_SUPPORT
int coap_block_check_q_block2_xmit(coap_session_t *session,
                                   coap_tick_t now, coap_tick_t *tim_rem);
 
coap_mid_t coap_send_q_block2(coap_session_t *session,
                              coap_resource_t *resource,
                              const coap_string_t *query,
                              coap_pdu_code_t request_method,
                              coap_block_b_t block,
                              coap_pdu_t *response,
                              coap_send_pdu_t send_response);
#endif /* COAP_Q_BLOCK_SUPPORT */
 
int coap_handle_request_send_block(coap_session_t *session,
                                   coap_pdu_t *pdu,
                                   coap_pdu_t *response,
                                   coap_resource_t *resource,
                                   coap_string_t *query);

int coap_handle_request_put_block(coap_context_t *context,
                                  coap_session_t *session,
                                  coap_pdu_t *pdu,
                                  coap_pdu_t *response,
                                  coap_resource_t *resource,
                                  coap_opt_t *observe,
                                  int *added_block,
                                  coap_lg_srcv_t **free_lg_srcv);
 
coap_lg_xmit_t *coap_find_lg_xmit_response(const coap_session_t *session,
                                           const coap_pdu_t *request,
                                           const coap_resource_t *resource,
                                           const coap_string_t *query);

int coap_add_data_large_response_lkd(coap_resource_t *resource,
                                     coap_session_t *session,
                                     const coap_pdu_t *request,
                                     coap_pdu_t *response,
                                     const coap_string_t *query,
                                     uint16_t media_type,
                                     int maxage,
                                     uint64_t etag,
                                     size_t length,
                                     const uint8_t *data,
                                     coap_release_large_data_t release_func,
                                     void *app_ptr);
 
#endif /* COAP_SERVER_SUPPORT */
 
#if COAP_CLIENT_SUPPORT
int coap_handle_response_send_block(coap_session_t *session, coap_pdu_t *sent,
                                    coap_pdu_t *rcvd);
 
int coap_handle_response_get_block(coap_context_t *context,
                                   coap_session_t *session,
                                   coap_pdu_t *sent,
                                   coap_pdu_t *rcvd,
                                   coap_recurse_t recursive);
 
coap_mid_t coap_retransmit_oscore_pdu(coap_session_t *session,
                                      coap_pdu_t *pdu,
                                      coap_opt_t *echo);

coap_lg_crcv_t *coap_find_lg_crcv(coap_session_t *session, coap_pdu_t *pdu);
 
#endif /* COAP_CLIENT_SUPPORT */

coap_lg_xmit_t *coap_find_lg_xmit(coap_session_t *session, coap_pdu_t *pdu);

void coap_block_delete_lg_xmit(coap_session_t *session,
                               coap_lg_xmit_t *lg_xmit);

COAP_STATIC_INLINE void
coap_lg_xmit_release_lkd(coap_session_t *session,coap_lg_xmit_t *lg_xmit) {
  coap_block_delete_lg_xmit(session, lg_xmit);
  return;
}

COAP_STATIC_INLINE void
coap_lg_xmit_reference_lkd(coap_lg_xmit_t *lg_xmit) {
  lg_xmit->ref++;
  return;
}
 
int coap_block_check_lg_xmit_timeouts(coap_session_t *session,
                                      coap_tick_t now,
                                      coap_tick_t *tim_rem);
 
#if COAP_Q_BLOCK_SUPPORT
int coap_block_drop_resp_q_block_xmit(coap_session_t *session,
                                      coap_lg_xmit_t *lg_xmit);
 
int coap_block_drop_resp_q_block2_crcv(coap_session_t *session,
                                       coap_lg_crcv_t *lg_crcv,
                                       coap_pdu_t *sent);
#endif /* COAP_Q_BLOCK_SUPPORT */

void coap_check_code_lg_xmit(const coap_session_t *session,
                             const coap_pdu_t *request,
                             coap_pdu_t *response,
                             const coap_resource_t *resource,
                             const coap_string_t *query);

void coap_context_set_block_mode_lkd(coap_context_t *context,
                                     uint32_t block_mode);

int coap_context_set_max_block_size_lkd(coap_context_t *context, size_t max_block_size);

coap_binary_t *coap_block_build_body_lkd(coap_binary_t *body_data, size_t length,
                                         const uint8_t *data, size_t offset, size_t total);
 
#if COAP_CLIENT_SUPPORT
int coap_add_data_large_request_lkd(coap_session_t *session,
                                    coap_pdu_t *pdu,
                                    size_t length,
                                    const uint8_t *data,
                                    coap_release_large_data_t release_func,
                                    void *app_ptr);

int coap_add_data_large_request_app_lkd(coap_session_t *session,
                                        coap_pdu_t *pdu,
                                        size_t length,
                                        coap_release_large_data_t release_func,
                                        coap_get_large_data_t get_func,
                                        void *app_ptr);

void coap_check_update_token(coap_session_t *session, coap_pdu_t *pdu);
#else /* ! COAP_CLIENT_SUPPORT */
#define coap_check_update_token(a,b)
#endif /* ! COAP_CLIENT_SUPPORT */

 
#ifdef __cplusplus
}
#endif
 
#endif /* COAP_BLOCK_INTERNAL_H_ */