/src/libcoap/include/coap3/coap_block_internal.h

Source
/*
 * 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.
 */

/**
 * @file coap_block_internal.h
 * @brief CoAP block internal information
 */

#ifndef COAP_BLOCK_INTERNAL_H_
#define COAP_BLOCK_INTERNAL_H_

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @ingroup internal_api
 * @defgroup block_internal Block Transfer
 * Internal API for Block Transfer (RFC7959)
 * @{
 */

/*
 * 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

/**
 * Structure to keep track of received blocks
 */
typedef struct coap_rblock_t {
  uint32_t used; /**< Number of range blocks in use */
  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;  /**< Set to block no + 1 when More bit unset */
} coap_rblock_t;

/**
 * Structure to keep track of block1 specific information
 * (Requests)
 */
typedef struct coap_l_block1_t {
  coap_binary_t *app_token; /**< original PDU token */
  uint64_t state_token;  /**< state token */
  size_t bert_size;      /**< size of last BERT block */
  uint32_t count;        /**< the number of packets sent for payload */
  coap_address_t upstream; /* Unicast IP of server if mcast client session */
} coap_l_block1_t;

/**
 * Structure to keep track of block2 specific information
 * (Responses)
 */
typedef struct coap_l_block2_t {
  coap_resource_t *resource; /**< associated resource */
  coap_string_t *query;  /**< Associated query for the resource */
  uint64_t etag;         /**< ETag value */
  coap_pdu_code_t request_method; /**< Method used to request this data */
  uint8_t rtag_set;      /**< Set if RTag is in receive PDU */
  uint8_t rtag_length;   /**< RTag length */
  uint8_t rtag[8];       /**< RTag for block checking */
  coap_time_t maxage_expire; /**< When this entry expires */
} coap_l_block2_t;

typedef struct coap_lg_xmit_data_t {
  const uint8_t *data;   /**< large data ptr */
  size_t length;         /**< large data length */
  coap_get_large_data_t get_func; /**< Where to get data id needed */
  coap_release_large_data_t release_func; /**< large data de-alloc function */
  void *app_ptr;         /**< application provided ptr for de-alloc function */
  uint32_t ref;          /**< Reference count */
} coap_lg_xmit_data_t;

/**
 * Structure to hold large body (many blocks) transmission information
 */
struct coap_lg_xmit_t {
  struct coap_lg_xmit_t *next;
  uint8_t blk_size;      /**< large block transmission size */
  uint16_t option;       /**< large block transmission CoAP option */
  int last_block;        /**< last acknowledged block number Block1
                              last transmitted Q-Block2 */
  coap_lg_xmit_data_t *data_info; /**< Pointer to large data information */
  union {
    coap_l_block1_t b1;
    coap_l_block2_t b2;
  } b;
  coap_pdu_t *sent_pdu;  /**< The sent pdu with all the data */
  coap_tick_t last_payload; /**< Last time MAX_PAYLOAD was sent or 0 */
  coap_tick_t last_sent; /**< Last time any data sent */
  coap_tick_t last_all_sent; /**< Last time all data sent or 0 */
  coap_tick_t last_obs; /**< Last time used (Observe tracking) or 0 */
#if COAP_Q_BLOCK_SUPPORT
  coap_tick_t non_timeout_random_ticks; /** Used for Q-Block */
  coap_rblock_t send_blocks; /**< list of blocks still to send */
#endif /* COAP_Q_BLOCK_SUPPORT */
  uint32_t ref;          /**< Reference count */
};

#if COAP_CLIENT_SUPPORT
/**
 * Structure to hold large body (many blocks) client receive information
 */
struct coap_lg_crcv_t {
  struct coap_lg_crcv_t *next;
  uint8_t observe[3];    /**< Observe data (if observe_set) (only 24 bits) */
  uint8_t observe_length;/**< Length of observe data */
  uint8_t observe_set;   /**< Set if this is an observe receive PDU */
  uint8_t szx;           /**< size of individual blocks */
  uint8_t etag_set;      /**< Set if ETag is in receive PDU */
  uint8_t etag_length;   /**< ETag length */
  uint8_t etag[8];       /**< ETag for block checking */
  uint16_t content_format; /**< Content format for the set of blocks */
  uint8_t last_type;     /**< Last request type (CON/NON) */
  uint8_t initial;       /**< If set, has not been used yet */
  uint16_t block_option; /**< Block option in use */
  uint16_t retry_counter; /**< Retry counter (part of state token) */
  size_t total_len;      /**< Length as indicated by SIZE2 option */
  coap_binary_t *body_data; /**< Used for re-assembling entire body */
  coap_binary_t *app_token; /**< app requesting PDU token */
  coap_bin_const_t **obs_token; /**< Tokens used in setting up Observe
                                  (to handle large FETCH) */
  size_t obs_token_cnt;  /**< number of tokens used to set up Observe */
  uint16_t o_block_option; /**< Block CoAP option used when initiating Observe */
  uint8_t o_blk_size;    /**< Block size used when initiating Observe */
  uint8_t total_len_set; /**< Set if total_len is where the last block ends */
  uint32_t ref;          /**< Reference count */
  uint64_t state_token;  /**< state token */
  coap_pdu_t *sent_pdu;  /**< The sent pdu with all the data */
  coap_rblock_t rec_blocks; /**< list of received blocks */
  coap_tick_t last_used; /**< Last time all data sent or 0 */
  coap_address_t upstream; /**< Unicast IP of server if mcast client session */
  coap_lg_xmit_data_t *obs_data; /**< lg_xmit data info  if large observe request */
};
#endif /* COAP_CLIENT_SUPPORT */

#if COAP_SERVER_SUPPORT
/**
 * Structure to hold large body (many blocks) server receive information
 */
struct coap_lg_srcv_t {
  struct coap_lg_srcv_t *next;
  uint8_t observe[3];    /**< Observe data (if set) (only 24 bits) */
  uint8_t observe_length;/**< Length of observe data */
  uint8_t observe_set;   /**< Set if this is an observe receive PDU */
  uint8_t no_more_seen;  /**< Set if block with more not set seen */
  uint8_t rtag_set;      /**< Set if RTag is in receive PDU */
  uint8_t rtag_length;   /**< RTag length */
  uint8_t rtag[8];       /**< RTag for block checking */
  uint16_t content_format; /**< Content format for the set of blocks */
  uint8_t last_type;     /**< Last request type (CON/NON) */
  uint8_t szx;           /**< size of individual blocks */
  uint16_t block_option; /**< Block option in use */
  uint8_t dont_timeout;  /**< Set if app handler in use */
  uint8_t total_len_set; /**< Set if total_len is where the last block ends */
  coap_tick_t last_used; /**< Last time data sent or 0 */
  size_t total_len;      /**< Length as indicated by SIZE1 option */
  coap_binary_t *body_data; /**< Used for re-assembling entire body */
  coap_resource_t *resource; /**< associated resource */
  coap_rblock_t rec_blocks; /** < list of received blocks */
  coap_bin_const_t *last_token; /**< last used token */
  uint32_t ref;          /**< Reference count */
#if COAP_Q_BLOCK_SUPPORT
  int32_t r_m_payload_set; /**< Last payload set when requested missing blocks */
#endif /* COAP_Q_BLOCK_SUPPORT */
#if COAP_OSCORE_SUPPORT
  oscore_recipient_ctx_t *recipient_ctx; /**< OSCORE recipient context
                                              for lg_srcv_t */
#endif /* COAP_OSCORE_SUPPORT */
  coap_cache_key_t *cache_key; /**< Cache key of (Q-)Block PDU */
};
#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);

/**
 * Remove a lg_crcv.
 * If lg_crcv is being referenced, then the reference counter is decremented
 * but the lg_crcv data still exists until a coap_lg_crcv_release_lkd() is
 * invoked.
 *
 * Note: This function must be called in the locked state.
 *
 * @param session The CoAP session.
 * @param lg_crcv The lg_crcv being used.
 */
void coap_block_delete_lg_crcv(coap_session_t *session,
                               coap_lg_crcv_t *lg_crcv);

/**
 * Decrement reference counter on a lg_crcv.
 * Note that the lg_crcv storage may be deleted as a result and should not be
 * used after this call.
 *
 * Note: This function must be called in the locked state.
 *
 * @param session The CoAP session.
 * @param lg_crcv The lg_crcv being used.
 */
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;
}

/**
 * Increment reference counter on a lg_crcv.
 *
 * Note: This function must be called in the locked state.
 *
 * @param lg_crcv The lg_crcv being used.
 */
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);

/**
 * Check if the next Q-Block1 needs to be sent, else get the next timeout value.
 *
 * @param session The Session to check.
 * @param now     The current time in ticks.
 * @param tim_rem Updated with the remaining timeout time if return is @c 1.
 *
 * @return @c 1 if @p tim_rem is set, else @c 0 if there is no timeout.
 */
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
/**
 * Send the next set of Q-blocks - one if CON, else to the next appropriate MAX_PAYLOAD
 * boundary. Handles if blocks are reported as not being received.
 *
 * If rate limiting when called returns COAP_INVALID_MID.
 *
 * @param session  The current session.
 * @param lg_xmit  Contains information about the list of blocks to send.
 * @param block    The first block to send using @p pdu template.
 * @param pdu      The PDU to model the blocks on. @p pdu is always released
 *                  if send_pdu == COAP_SEND_INC_PDU
 * @param send_pdu Whether @p pdu should be sent first or just used as a PDU model.
 *
 * @return COAP_INVALID_MID if transmission error, else the last transmitted block mid.
 */
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
/**
 * Remove a lg_srcv.
 * If lg_srcv is being referenced, then the reference counter is decremented
 * but the lg_srcv data still exists until a coap_lg_srcv_release_lkd() is
 * invoked.
 *
 * Note: This function must be called in the locked state.
 *
 * @param session The CoAP session.
 * @param lg_srcv The lg_srcv being used.
 */
void coap_block_delete_lg_srcv(coap_session_t *session,
                               coap_lg_srcv_t *lg_srcv);

/**
 * Decrement reference counter on a lg_srcv.
 * Note that the lg_srcv storage may be deleted as a result and should not be
 * used after this call.
 *
 * Note: This function must be called in the locked state.
 *
 * @param session The CoAP session.
 * @param lg_srcv The lg_srcv being used.
 */
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;
}

/**
 * Increment reference counter on a lg_srcv.
 *
 * Note: This function must be called in the locked state.
 *
 * @param lg_srcv The lg_srcv being used.
 */
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
/**
 * Check if the next Q-Block2 needs to be sent, else get the next timeout value.
 *
 * @param session The Session to check.
 * @param now     The current time in ticks.
 * @param tim_rem Updated with the remaining timeout time if return is @c 1.
 *
 * @return @c 1 if @p tim_rem is set, else @c 0 if there is no timeout.
 */
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);

/**
 * Handle the next incoming PUT/POST PDU - if (Q-)Block1 option, handle accordingly.
 *
 * @param context  The context.
 * @param session  The incoming session.
 * @param pdu      The incoming PDU.
 * @param response The PDU set up for the response.
 * @param resource The matching resource (could be unknown / proxy).
 * @param observe  The Observe option in the incoming PDU (if any).
 * @param added_block Set to 1 if block option added to response.
 * @param free_lg_srcv Contains the lg_srcv_t to release if set.
 *
 * @return @c 0 to invoke application handler, else @c 1 to just send response.
 */
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);

/**
 * Associates given data with the @p response pdu that is passed as fourth
 * parameter.
 *
 * This function will fail if data has already been added to the @p pdu.
 *
 * If all the data can be transmitted in a single PDU, this is functionally
 * the same as coap_add_data() except @p release_func (if not NULL) will get
 * invoked after data transmission. The Content-Format, Max-Age and ETag
 * options may be added in as appropriate.
 *
 * Used by a server request handler to create the response.
 *
 * If the data spans multiple PDUs, then the data will get transmitted using
 * (Q-)Block2 (response) option with the addition of the Size2 and ETag
 * options. The underlying library will handle the transmission of the
 * individual blocks. Once the body of data has been transmitted (or a
 * failure occurred), then @p release_func (if not NULL) will get called so the
 * application can de-allocate the @p data based on @p app_data. It is the
 * responsibility of the application not to change the contents of @p data
 * until the data transfer has completed.
 *
 * There is no need for the application to include the (Q-)Block2 option in the
 * @p pdu.
 *
 * coap_add_data_large_response_lkd() (or the alternative coap_add_data_large_*()
 * functions) must be called only once per PDU and must be the last PDU update
 * before returning from the request handler function.
 *
 * Note: COAP_BLOCK_USE_LIBCOAP must be set by coap_context_set_block_mode()
 * for libcoap to work correctly when using this function.
 *
 * Note: This function must be called in the locked state.
 *
 * @param resource   The resource the data is associated with.
 * @param session    The coap session.
 * @param request    The requesting pdu.
 * @param response   The response pdu.
 * @param query      The query taken from the (original) requesting pdu.
 * @param media_type The content format of the data.
 * @param maxage     The maximum life of the data. If @c -1, then there
 *                   is no maxage.
 * @param etag       ETag to use if not 0.
 * @param length     The total length of the data.
 * @param data       The entire data block to transmit.
 * @param release_func The function to call to de-allocate @p data or NULL if
 *                   the function is not required.
 * @param app_ptr    A Pointer that the application can provide for when
 *                   release_func() is called.
 *
 * @return @c 1 if addition is successful, else @c 0.
 */
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);

/**
 * Find the current lg_crcv for the session that matches the pdu.
 * If base lg_xmit is a mcast send, then create a secondorary lg_crcv.
 *
 * @param session The current session.
 * @param pdu     The pdu that contains the appropriate token.
 *
 * @return The found lg_crcv or NULL.
 */
coap_lg_crcv_t *coap_find_lg_crcv(coap_session_t *session, coap_pdu_t *pdu);

#endif /* COAP_CLIENT_SUPPORT */

/**
 * Find the current lg_xmit for the session that matches the pdu.
 * If client and base lg_xmit is a mcast send, then create a secondorary lg_xmit.
 *
 * @param session The current session.
 * @param pdu     The pdu that contains the appropriate token.
 *
 * @return The found lg_xmit or NULL.
 */
coap_lg_xmit_t *coap_find_lg_xmit(coap_session_t *session, coap_pdu_t *pdu);

/**
 * Remove a lg_xmit.
 * If lg_xmit is being referenced, then the reference counter is decremented
 * but the lg_xmit data still exists until a coap_lg_xmit_release_lkd() is
 * invoked.
 *
 * Note: This function must be called in the locked state.
 *
 * @param session The CoAP session.
 * @param lg_xmit The lg_xmit being used.
 */
void coap_block_delete_lg_xmit(coap_session_t *session,
                               coap_lg_xmit_t *lg_xmit);

/**
 * Decrement reference counter on a lg_xmit.
 * Note that the lg_xmit storage may be deleted as a result and should not be
 * used after this call.
 *
 * Note: This function must be called in the locked state.
 *
 * @param session The CoAP session.
 * @param lg_xmit The lg_xmit being used.
 */
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;
}

/**
 * Increment reference counter on a lg_xmit.
 *
 * Note: This function must be called in the locked state.
 *
 * @param lg_xmit The lg_xmit being used.
 */
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 */

/**
 * The function checks that the code in a newly formed lg_xmit created by
 * coap_add_data_large_response_lkd() is updated.
 *
 * @param session  The session.
 * @param request  The request PDU to to check.
 * @param response The response PDU to to update with response->code.
 * @param resource The requested resource.
 * @param query    The requested query.
 */
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);

/**
 * Set the context level CoAP block handling bits for handling RFC7959.
 * These bits flow down to a session when a session is created and if the peer
 * does not support something, an appropriate bit may get disabled in the
 * session block_mode.
 * The session block_mode then flows down into coap_crcv_t or coap_srcv_t where
 * again an appropriate bit may get disabled.
 *
 * Note: This function must be called before the session is set up.
 *
 * Note: COAP_BLOCK_USE_LIBCOAP must be set if libcoap is to do all the
 * block tracking and requesting, otherwise the application will have to do
 * all of this work (the default if coap_context_set_block_mode() is not
 * called).
 *
 * @param context        The coap_context_t object.
 * @param block_mode     Zero or more COAP_BLOCK_ or'd options
 */
void coap_context_set_block_mode_lkd(coap_context_t *context,
                                     uint32_t block_mode);

/**
 * Set the context level maximum block size that the server supports when sending
 * or receiving packets with Block1 or Block2 options.
 * This maximum block size flows down to a session when a session is created.
 *
 * Note: This function must be called before the session is set up.
 *
 * Note: COAP_BLOCK_USE_LIBCOAP must be set using coap_context_set_block_mode()
 * if libcoap is to do this work.
 *
 * @param context        The coap_context_t object.
 * @param max_block_size The maximum block size a server supports.  Can be 0
 *                       (reset), or must be 16, 32, 64, 128, 256, 512 or 1024.
 */
int coap_context_set_max_block_size_lkd(coap_context_t *context, size_t max_block_size);

/**
 * Re-assemble payloads into a body.
 *
 * Note: This function must be called in the locked state.
 *
 * @param body_data The pointer to the data for the body holding the
 *                  representation so far or NULL if the first time.
 * @param length    The length of @p data.
 * @param data      The payload data to update the body with.
 * @param offset    The offset of the @p data into the body.
 * @param total     The estimated total size of the body.
 *
 * @return          The current representation of the body or @c NULL if error.
 *                  If NULL, @p body_data will have been de-allocated.
 */
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
/**
 * Associates given data with the @p pdu that is passed as second parameter.
 *
 * This function will fail if data has already been added to the @p pdu.
 *
 * If all the data can be transmitted in a single PDU, this is functionally
 * the same as coap_add_data_lkd() except @p release_func (if not NULL) will get
 * invoked after data transmission.
 *
 * Used for a client request.
 *
 * If the data spans multiple PDUs, then the data will get transmitted using
 * (Q-)Block1 option with the addition of the Size1 and Request-Tag options.
 * The underlying library will handle the transmission of the individual blocks.
 * Once the body of data has been transmitted (or a failure occurred), then
 * @p release_func (if not NULL) will get called so the application can
 * de-allocate the @p data based on @p app_data. It is the responsibility of
 * the application not to change the contents of @p data until the data
 * transfer has completed.
 *
 * There is no need for the application to include the (Q-)Block1 option in the
 * @p pdu.
 *
 * coap_add_data_large_request_lkd() (or the alternative coap_add_data_large_*()
 * functions) must be called only once per PDU and must be the last PDU update
 * before the PDU is transmitted. The (potentially) initial data will get
 * transmitted when coap_send() is invoked.
 *
 * Note: COAP_BLOCK_USE_LIBCOAP must be set by coap_context_set_block_mode()
 * for libcoap to work correctly when using this function.
 *
 * Note: This function must be called in the locked state.
 *
 * @param session  The session to associate the data with.
 * @param pdu      The PDU to associate the data with.
 * @param length   The length of data to transmit.
 * @param data     The data to transmit.
 * @param release_func The function to call to de-allocate @p app_ptr or @c NULL
 *                 if the function is not required.
 * @param app_ptr  A Pointer that the application can provide for when
 *                 release_func() is called.
 *
 * @return @c 1 if addition is successful, else @c 0.
 */
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);

/**
 * Associates given data callback with the @p pdu that is passed as second parameter.
 *
 * This function will fail if data has already been added to the @p pdu.
 *
 * Used for a client request.
 *
 * If the data spans multiple PDUs, then the data will get transmitted using
 * (Q-)Block1 option with the addition of the Size1 and Request-Tag options.
 * The underlying library will handle the transmission of the individual blocks.
 *
 * Each individual block of data will get requested by the use of a call-back
 * function @p get_func before transmission.
 *
 * There is no need for the application to include the (Q-)Block1 option in the
 * @p pdu.
 *
 * coap_add_data_large_request_app() (or the alternative coap_add_data_large_*()
 * functions) must be called only once per PDU and must be the last PDU update
 * before the PDU is transmitted. The (potentially) initial data will get
 * transmitted when coap_send() is invoked.
 *
 * Note: COAP_BLOCK_USE_LIBCOAP must be set by coap_context_set_block_mode()
 * for libcoap to work correctly when using this function.
 *
 * Note: This function must be called in the locked state.
 *
 * @param session  The session to associate the data with.
 * @param pdu      The PDU to associate the data with.
 * @param length   The length of data to transmit.
 * @param release_func The function to call to de-allocate @p app_ptr or @c NULL
 *                 if the function is not required.
 * @param get_func The function to call to get the next block of data
 *                 for transmission.
 * @param app_ptr  A Pointer that the application can provide for when
 *                 @p get_func is called.
 *
 * @return @c 1 if addition is successful, else @c 0.
 */
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);

/**
 * The function checks if the token needs to be updated before PDU is
 * presented to the application (only relevant to clients).
 *
 * @param session The session.
 * @param pdu     The PDU to to check for updating.
 */
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_ */

Coverage Report

Created: 2026-11-12 06:14