coap_block.h

Go to the documentation of this file.

/*
 * coap_block.h -- block transfer
 *
 * Copyright (C) 2010-2012,2014-2015 Olaf Bergmann <bergmann@tzi.org>
 * Copyright (C) 2022-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_H_
#define COAP_BLOCK_H_
 
#include "coap_encode.h"
#include "coap_option.h"
#include "coap_pdu.h"
 
#ifdef __cplusplus
extern "C" {
#endif

 
#ifndef COAP_MAX_BLOCK_SZX
#define COAP_MAX_BLOCK_SZX      6
#endif /* COAP_MAX_BLOCK_SZX */

typedef struct {
  unsigned int num;       
  unsigned int m:1;       
  unsigned int szx:3;     
} coap_block_t;

typedef struct {
  unsigned int num;       
  unsigned int m:1;       
  unsigned int szx:3;     
  unsigned int aszx:3;    
  unsigned int defined:1; 
  unsigned int bert:1;    
  uint32_t chunk_size;    
} coap_block_b_t;
 
#define COAP_BLOCK_USE_LIBCOAP  0x01 /* Use libcoap to do block requests */
#define COAP_BLOCK_SINGLE_BODY  0x02 /* Deliver the data as a single body */
#define COAP_BLOCK_TRY_Q_BLOCK   0x04 /* Try Q-Block method */
#define COAP_BLOCK_USE_M_Q_BLOCK 0x08 /* Use M bit when recovering Q-Block2 */
#define COAP_BLOCK_NO_PREEMPTIVE_RTAG 0x10 /* (cl) Don't use pre-emptive Request-Tags */
#define COAP_BLOCK_STLESS_FETCH  0x20 /* (cl) Assume server supports stateless FETCH */
#define COAP_BLOCK_STLESS_BLOCK2 0x40 /* (svr)Server is stateless for handling Block2 */
#define COAP_BLOCK_NOT_RANDOM_BLOCK1 0x80 /* (svr)Disable server handling random order
                                             block1 */
#define COAP_BLOCK_FORCE_Q_BLOCK  0x200 /* force Q-Block method without support check */
/* WARNING: Added defined values must not encroach into 0xff000000 which are defined elsewhere */

 */
#define COAP_OPT_BLOCK_LAST(opt) \
  (coap_opt_length(opt) ? (coap_opt_value(opt) + (coap_opt_length(opt)-1)) : 0)

/** Returns the value of the last byte of @p opt. */
#define COAP_OPT_BLOCK_END_BYTE(opt) \
  ((coap_opt_length(opt) && coap_opt_value(opt)) ? \
   *(coap_opt_value(opt) + (coap_opt_length(opt)-1)) : 0)

/** Returns the value of the More-bit of a Block option @p opt. */
#define COAP_OPT_BLOCK_MORE(opt) \
  (coap_opt_length(opt) ? (COAP_OPT_BLOCK_END_BYTE(opt) & 0x08) : 0)

/** Returns the value of the SZX-field of a Block option @p opt. */
#define COAP_OPT_BLOCK_SZX(opt)  \
  (coap_opt_length(opt) ? (COAP_OPT_BLOCK_END_BYTE(opt) & 0x07) : 0)

unsigned int coap_opt_block_num(const coap_opt_t *block_opt);

COAP_STATIC_INLINE int
coap_more_blocks(size_t data_len, unsigned int num, uint16_t szx) {
  return ((num+1) << (szx + 4)) < data_len;
}
 
#if 0
COAP_STATIC_INLINE void
coap_opt_block_set_m(coap_opt_t *block_opt, int m) {
  if (m)
    *(coap_opt_value(block_opt) + (coap_opt_length(block_opt) - 1)) |= 0x08;
  else
    *(coap_opt_value(block_opt) + (coap_opt_length(block_opt) - 1)) &= ~0x08;
}
#endif

int coap_get_block(const coap_pdu_t *pdu, coap_option_num_t number,
                   coap_block_t *block);
 

int coap_get_block_b(const coap_session_t *session, const coap_pdu_t *pdu,
                     coap_option_num_t number, coap_block_b_t *block);

int coap_write_block_opt(coap_block_t *block,
                         coap_option_num_t number,
                         coap_pdu_t *pdu,
                         size_t data_length);
int coap_write_block_b_opt(coap_session_t *session,
                           coap_block_b_t *block,
                           coap_option_num_t number,
                           coap_pdu_t *pdu,
                           size_t data_length);
 

int coap_add_block(coap_pdu_t *pdu,
                   size_t len,
                   const uint8_t *data,
                   unsigned int block_num,
                   unsigned char block_szx);

int coap_add_block_b_data(coap_pdu_t *pdu, size_t len, const uint8_t *data,
                          coap_block_b_t *block);

COAP_API coap_binary_t *coap_block_build_body(coap_binary_t *body_data, size_t length,
                                              const uint8_t *data, size_t offset, size_t total);

void coap_add_data_blocked_response(const coap_pdu_t *request,
                                    coap_pdu_t *response,
                                    uint16_t media_type,
                                    int maxage,
                                    size_t length,
                                    const uint8_t *data);

typedef void (*coap_release_large_data_t)(coap_session_t *session,
                                          void *app_ptr);

COAP_API int coap_add_data_large_request(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);

typedef int (*coap_get_large_data_t)(coap_session_t *session, size_t max,
                                     size_t offset,
                                     uint8_t *data, size_t *length,
                                     void *app_ptr);
COAP_API int coap_add_data_large_request_app(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);

COAP_API int coap_add_data_large_response(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);

COAP_API void coap_context_set_block_mode(coap_context_t *context,
                                          uint32_t block_mode);

COAP_API int coap_context_set_max_block_size(coap_context_t *context, size_t max_block_size);

 
#ifdef __cplusplus
}
#endif
 
#endif /* COAP_BLOCK_H_ */