/src/libcoap/include/coap3/coap_block.h

Source
/*
 * coap_block.h -- block transfer
 *
 * Copyright (C) 2010-2012,2014-2015 Olaf Bergmann <bergmann@tzi.org>
 * Copyright (C) 2022-2025           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.h
 * @brief CoAP Block information
 */

#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

/**
 * @ingroup application_api
 * @defgroup block Block Transfer
 * API for handling PDUs using CoAP Block options (RFC7959)
 * @{
 */

#ifndef COAP_MAX_BLOCK_SZX
/**
 * The largest value for the SZX component in a Block option.
 */
#define COAP_MAX_BLOCK_SZX      6
#endif /* COAP_MAX_BLOCK_SZX */

/**
 * Structure of Block options.
 */
typedef struct {
  unsigned int num;       /**< block number */
  unsigned int m:1;       /**< 1 if more blocks follow, 0 otherwise */
  unsigned int szx:3;     /**< block size */
} coap_block_t;

/**
 * Structure of Block options with BERT support.
 */
typedef struct {
  unsigned int num;       /**< block number */
  unsigned int m:1;       /**< 1 if more blocks follow, 0 otherwise */
  unsigned int szx:3;     /**< block size (0-6) */
  unsigned int aszx:3;    /**< block size (0-7 including BERT */
  unsigned int defined:1; /**< Set if block found */
  unsigned int bert:1;    /**< Operating as BERT */
  uint32_t chunk_size;    /**< > 1024 if BERT */
} 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_CACHE_RESPONSE 0x100 /* (svr)Cache CON request's response */
#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 */

/**
 * Returns the value of the least significant byte of a Block option @p opt.
 * For zero-length options (i.e. num == m == szx == 0), COAP_OPT_BLOCK_LAST
 * returns @c NULL.
 */
#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)

/**
 * Returns the value of field @c num in the given block option @p block_opt.
 */
unsigned int coap_opt_block_num(const coap_opt_t *block_opt);

/**
 * Checks if more than @p num blocks are required to deliver @p data_len
 * bytes of data for a block size of 1 << (@p szx + 4).
 */
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
/** Sets the More-bit in @p block_opt */
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

/**
 * Initializes @p block from @p pdu. @p number must be either COAP_OPTION_BLOCK1
 * or COAP_OPTION_BLOCK2. When option @p number was found in @p pdu, @p block is
 * initialized with values from this option and the function returns the value
 * @c 1. Otherwise, @c 0 is returned.
 *
 * @param pdu    The pdu to search for option @p number.
 * @param number The option number to search for (must be COAP_OPTION_BLOCK1 or
 *               COAP_OPTION_BLOCK2).
 * @param block  The block structure to initialize.
 *
 * @return       @c 1 on success, @c 0 otherwise.
 */
int coap_get_block(const coap_pdu_t *pdu, coap_option_num_t number,
                   coap_block_t *block);


/**
 * Initializes @p block from @p pdu. @p number must be either COAP_OPTION_BLOCK1
 * or COAP_OPTION_BLOCK2. When option @p number was found in @p pdu, @p block is
 * initialized with values from this option and the function returns the value
 * @c 1. Otherwise, @c 0 is returned. BERT information is abstracted as
 * appropriate.
 *
 * @param session THe session that the pdu is associated with,
 * @param pdu    The pdu to search for option @p number.
 * @param number The option number to search for (must be COAP_OPTION_BLOCK1 or
 *               COAP_OPTION_BLOCK2).
 * @param block  The block structure to initialize.
 *
 * @return       @c 1 on success, @c 0 otherwise.
 */
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);

/**
 * Writes a block option of type @p number to message @p pdu. If the requested
 * block size is too large to fit in @p pdu, it is reduced accordingly. An
 * exception is made for the final block when less space is required. The actual
 * length of the resource is specified in @p data_length.
 *
 * This function may change *block to reflect the values written to @p pdu. As
 * the function takes into consideration the remaining space @p pdu, no more
 * options should be added after coap_write_block_opt() has returned.
 *
 * @param block       The block structure to use. On return, this object is
 *                    updated according to the values that have been written to
 *                    @p pdu.
 * @param number      COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2.
 * @param pdu         The message where the block option should be written.
 * @param data_length The length of the actual data that will be added the @p
 *                    pdu by calling coap_add_block().
 *
 * @return            @c 1 on success, or a negative value on error.
 */
int coap_write_block_opt(coap_block_t *block,
                         coap_option_num_t number,
                         coap_pdu_t *pdu,
                         size_t data_length);
/**
 * Writes a block option of type @p number to message @p pdu. If the requested
 * block size is too large to fit in @p pdu, it is reduced accordingly. An
 * exception is made for the final block when less space is required. The actual
 * length of the resource is specified in @p data_length.
 *
 * This function may change *block to reflect the values written to @p pdu. As
 * the function takes into consideration the remaining space @p pdu, no more
 * options should be added after coap_write_block_opt() has returned.
 *
 * @param session     The CoAP session.
 * @param block       The block structure to use. On return, this object is
 *                    updated according to the values that have been written to
 *                    @p pdu.
 * @param number      COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2.
 * @param pdu         The message where the block option should be written.
 * @param data_length The length of the actual data that will be added the @p
 *                    pdu by calling coap_add_block().
 *
 * @return            @c 1 on success, or a negative value on error.
 */
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);


/**
 * Adds the @p block_num block of size 1 << (@p block_szx + 4) from source @p
 * data to @p pdu.
 *
 * @param pdu       The message to add the block.
 * @param len       The length of @p data.
 * @param data      The source data to fill the block with.
 * @param block_num The actual block number.
 * @param block_szx Encoded size of block @p block_number.
 *
 * @return          @c 1 on success, @c 0 otherwise.
 */
int coap_add_block(coap_pdu_t *pdu,
                   size_t len,
                   const uint8_t *data,
                   unsigned int block_num,
                   unsigned char block_szx);

/**
 * Adds the appropriate payload data of the body to the @p pdu.
 *
 * @param pdu       The message to add the block.
 * @param len       The length of @p data.
 * @param data      The source data to fill the block with.
 * @param block     The block information (including potentially BERT)
 *
 * @return          @c 1 on success, @c 0 otherwise.
 */
int coap_add_block_b_data(coap_pdu_t *pdu, size_t len, const uint8_t *data,
                          coap_block_b_t *block);

/**
 * Re-assemble payloads into a body
 *
 * @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(coap_binary_t *body_data, size_t length,
                                     const uint8_t *data, size_t offset, size_t total);

/**
 * Adds the appropriate part of @p data to the @p response pdu.  If blocks are
 * required, then the appropriate block will be added to the PDU and sent.
 * Adds a ETag option that is the hash of the entire data if the data is to be
 * split into blocks
 * Used by a request handler.
 *
 * Note: The application will get called for every packet of a large body to
 * process. Consider using coap_add_data_response_large() instead.
 *
 * @param request    The requesting pdu.
 * @param response   The response pdu.
 * @param media_type The format of the data.
 * @param maxage     The maxmimum life of the data. If @c -1, then there
 *                   is no maxage.
 * @param length     The total length of the data.
 * @param data       The entire data block to transmit.
 *
 */
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);

/**
 * Callback handler for de-allocating the data based on @p app_ptr provided to
 * coap_add_data_large_*() functions following transmission of the supplied
 * data.
 *
 * @param session The session that this data is associated with
 * @param app_ptr The application provided pointer provided to the
 *                coap_add_data_large_* functions.
 */
typedef void (*coap_release_large_data_t)(coap_session_t *session,
                                          void *app_ptr);

/**
 * 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() 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() (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.
 *
 * @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 data 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.
 */
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);

/**
 * 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() (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.
 *
 * @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 maxmimum 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.
 */
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);

/**
 * 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
 */
COAP_API void coap_context_set_block_mode(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.
 */
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_ */

Coverage Report

Created: 2025-11-01 06:14

Line	Count	Source
1		/*
2		* coap_block.h -- block transfer
3		*
4		* Copyright (C) 2010-2012,2014-2015 Olaf Bergmann <bergmann@tzi.org>
5		* Copyright (C) 2022-2025 Jon Shallow <supjps-libcoap@jpshallow.com>
6		*
7		* SPDX-License-Identifier: BSD-2-Clause
8		*
9		* This file is part of the CoAP library libcoap. Please see README for terms
10		* of use.
11		*/
12
13		/**
14		* @file coap_block.h
15		* @brief CoAP Block information
16		*/
17
18		#ifndef COAP_BLOCK_H_
19		#define COAP_BLOCK_H_
20
21		#include "coap_encode.h"
22		#include "coap_option.h"
23		#include "coap_pdu.h"
24
25		#ifdef __cplusplus
26		extern "C" {
27		#endif
28
29		/**
30		* @ingroup application_api
31		* @defgroup block Block Transfer
32		* API for handling PDUs using CoAP Block options (RFC7959)
33		* @{
34		*/
35
36		#ifndef COAP_MAX_BLOCK_SZX
37		/**
38		* The largest value for the SZX component in a Block option.
39		*/
40		#define COAP_MAX_BLOCK_SZX 6
41		#endif /* COAP_MAX_BLOCK_SZX */
42
43		/**
44		* Structure of Block options.
45		*/
46		typedef struct {
47		unsigned int num; /*< block number /
48		unsigned int m:1; /*< 1 if more blocks follow, 0 otherwise /
49		unsigned int szx:3; /*< block size /
50		} coap_block_t;
51
52		/**
53		* Structure of Block options with BERT support.
54		*/
55		typedef struct {
56		unsigned int num; /*< block number /
57		unsigned int m:1; /*< 1 if more blocks follow, 0 otherwise /
58		unsigned int szx:3; /*< block size (0-6) /
59		unsigned int aszx:3; /*< block size (0-7 including BERT /
60		unsigned int defined:1; /*< Set if block found /
61		unsigned int bert:1; /*< Operating as BERT /
62		uint32_t chunk_size; /*< > 1024 if BERT /
63		} coap_block_b_t;
64
65	0	#define COAP_BLOCK_USE_LIBCOAP 0x01 /* Use libcoap to do block requests */
66	0	#define COAP_BLOCK_SINGLE_BODY 0x02 /* Deliver the data as a single body */
67	0	#define COAP_BLOCK_TRY_Q_BLOCK 0x04 /* Try Q-Block method */
68	0	#define COAP_BLOCK_USE_M_Q_BLOCK 0x08 /* Use M bit when recovering Q-Block2 */
69	0	#define COAP_BLOCK_NO_PREEMPTIVE_RTAG 0x10 /* (cl) Don't use pre-emptive Request-Tags */
70	0	#define COAP_BLOCK_STLESS_FETCH 0x20 /* (cl) Assume server supports stateless FETCH */
71	0	#define COAP_BLOCK_STLESS_BLOCK2 0x40 /* (svr)Server is stateless for handling Block2 */
72	0	#define COAP_BLOCK_NOT_RANDOM_BLOCK1 0x80 /* (svr)Disable server handling random order
73		block1 */
74	0	#define COAP_BLOCK_CACHE_RESPONSE 0x100 /* (svr)Cache CON request's response */
75	0	#define COAP_BLOCK_FORCE_Q_BLOCK 0x200 /* force Q-Block method without support check */
76		/* WARNING: Added defined values must not encroach into 0xff000000 which are defined elsewhere */
77
78		/**
79		* Returns the value of the least significant byte of a Block option @p opt.
80		* For zero-length options (i.e. num == m == szx == 0), COAP_OPT_BLOCK_LAST
81		* returns @c NULL.
82		*/
83		#define COAP_OPT_BLOCK_LAST(opt) \
84		(coap_opt_length(opt) ? (coap_opt_value(opt) + (coap_opt_length(opt)-1)) : 0)
85
86		/** Returns the value of the last byte of @p opt. */
87		#define COAP_OPT_BLOCK_END_BYTE(opt) \
88	20.7k	((coap_opt_length(opt) && coap_opt_value(opt)) ? \
89	20.7k	*(coap_opt_value(opt) + (coap_opt_length(opt)-1)) : 0)
90
91		/** Returns the value of the More-bit of a Block option @p opt. */
92		#define COAP_OPT_BLOCK_MORE(opt) \
93	220k	(coap_opt_length(opt) ? (COAP_OPT_BLOCK_END_BYTE(opt) & 0x08) : 0)
94
95		/** Returns the value of the SZX-field of a Block option @p opt. */
96		#define COAP_OPT_BLOCK_SZX(opt) \
97	438k	(coap_opt_length(opt) ? (COAP_OPT_BLOCK_END_BYTE(opt) & 0x07) : 0)
98
99		/**
100		* Returns the value of field @c num in the given block option @p block_opt.
101		*/
102		unsigned int coap_opt_block_num(const coap_opt_t *block_opt);
103
104		/**
105		* Checks if more than @p num blocks are required to deliver @p data_len
106		* bytes of data for a block size of 1 << (@p szx + 4).
107		*/
108		COAP_STATIC_INLINE int
109	0	coap_more_blocks(size_t data_len, unsigned int num, uint16_t szx) {
110	0	return ((num+1) << (szx + 4)) < data_len;
111	0	} Unexecuted instantiation: coap_debug.c:coap_more_blocks Unexecuted instantiation: coap_encode.c:coap_more_blocks Unexecuted instantiation: coap_net.c:coap_more_blocks Unexecuted instantiation: coap_netif.c:coap_more_blocks Unexecuted instantiation: coap_notls.c:coap_more_blocks Unexecuted instantiation: coap_option.c:coap_more_blocks Unexecuted instantiation: coap_oscore.c:coap_more_blocks Unexecuted instantiation: coap_pdu.c:coap_more_blocks Unexecuted instantiation: coap_proxy.c:coap_more_blocks Unexecuted instantiation: coap_prng.c:coap_more_blocks Unexecuted instantiation: coap_resource.c:coap_more_blocks Unexecuted instantiation: coap_session.c:coap_more_blocks Unexecuted instantiation: coap_sha1.c:coap_more_blocks Unexecuted instantiation: coap_str.c:coap_more_blocks Unexecuted instantiation: coap_strm_posix.c:coap_more_blocks Unexecuted instantiation: coap_subscribe.c:coap_more_blocks Unexecuted instantiation: coap_threadsafe.c:coap_more_blocks Unexecuted instantiation: coap_time.c:coap_more_blocks Unexecuted instantiation: coap_uri.c:coap_more_blocks Unexecuted instantiation: coap_ws.c:coap_more_blocks Unexecuted instantiation: oscore.c:coap_more_blocks Unexecuted instantiation: oscore_cbor.c:coap_more_blocks Unexecuted instantiation: oscore_context.c:coap_more_blocks Unexecuted instantiation: oscore_cose.c:coap_more_blocks Unexecuted instantiation: oscore_crypto.c:coap_more_blocks Unexecuted instantiation: coap_address.c:coap_more_blocks Unexecuted instantiation: coap_async.c:coap_more_blocks Unexecuted instantiation: coap_block.c:coap_more_blocks Unexecuted instantiation: coap_cache.c:coap_more_blocks Unexecuted instantiation: coap_dgrm_posix.c:coap_more_blocks Unexecuted instantiation: coap_dtls.c:coap_more_blocks Unexecuted instantiation: coap_hashkey.c:coap_more_blocks Unexecuted instantiation: coap_io.c:coap_more_blocks Unexecuted instantiation: coap_io_posix.c:coap_more_blocks Unexecuted instantiation: coap_layers.c:coap_more_blocks Unexecuted instantiation: coap_mem.c:coap_more_blocks
112
113		#if 0
114		/** Sets the More-bit in @p block_opt */
115		COAP_STATIC_INLINE void
116		coap_opt_block_set_m(coap_opt_t *block_opt, int m) {
117		if (m)
118		*(coap_opt_value(block_opt) + (coap_opt_length(block_opt) - 1)) \|= 0x08;
119		else
120		*(coap_opt_value(block_opt) + (coap_opt_length(block_opt) - 1)) &= ~0x08;
121		}
122		#endif
123
124		/**
125		* Initializes @p block from @p pdu. @p number must be either COAP_OPTION_BLOCK1
126		* or COAP_OPTION_BLOCK2. When option @p number was found in @p pdu, @p block is
127		* initialized with values from this option and the function returns the value
128		* @c 1. Otherwise, @c 0 is returned.
129		*
130		* @param pdu The pdu to search for option @p number.
131		* @param number The option number to search for (must be COAP_OPTION_BLOCK1 or
132		* COAP_OPTION_BLOCK2).
133		* @param block The block structure to initialize.
134		*
135		* @return @c 1 on success, @c 0 otherwise.
136		*/
137		int coap_get_block(const coap_pdu_t *pdu, coap_option_num_t number,
138		coap_block_t *block);
139
140
141		/**
142		* Initializes @p block from @p pdu. @p number must be either COAP_OPTION_BLOCK1
143		* or COAP_OPTION_BLOCK2. When option @p number was found in @p pdu, @p block is
144		* initialized with values from this option and the function returns the value
145		* @c 1. Otherwise, @c 0 is returned. BERT information is abstracted as
146		* appropriate.
147		*
148		* @param session THe session that the pdu is associated with,
149		* @param pdu The pdu to search for option @p number.
150		* @param number The option number to search for (must be COAP_OPTION_BLOCK1 or
151		* COAP_OPTION_BLOCK2).
152		* @param block The block structure to initialize.
153		*
154		* @return @c 1 on success, @c 0 otherwise.
155		*/
156		int coap_get_block_b(const coap_session_t session, const coap_pdu_t pdu,
157		coap_option_num_t number, coap_block_b_t *block);
158
159		/**
160		* Writes a block option of type @p number to message @p pdu. If the requested
161		* block size is too large to fit in @p pdu, it is reduced accordingly. An
162		* exception is made for the final block when less space is required. The actual
163		* length of the resource is specified in @p data_length.
164		*
165		* This function may change *block to reflect the values written to @p pdu. As
166		* the function takes into consideration the remaining space @p pdu, no more
167		* options should be added after coap_write_block_opt() has returned.
168		*
169		* @param block The block structure to use. On return, this object is
170		* updated according to the values that have been written to
171		* @p pdu.
172		* @param number COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2.
173		* @param pdu The message where the block option should be written.
174		* @param data_length The length of the actual data that will be added the @p
175		* pdu by calling coap_add_block().
176		*
177		* @return @c 1 on success, or a negative value on error.
178		*/
179		int coap_write_block_opt(coap_block_t *block,
180		coap_option_num_t number,
181		coap_pdu_t *pdu,
182		size_t data_length);
183		/**
184		* Writes a block option of type @p number to message @p pdu. If the requested
185		* block size is too large to fit in @p pdu, it is reduced accordingly. An
186		* exception is made for the final block when less space is required. The actual
187		* length of the resource is specified in @p data_length.
188		*
189		* This function may change *block to reflect the values written to @p pdu. As
190		* the function takes into consideration the remaining space @p pdu, no more
191		* options should be added after coap_write_block_opt() has returned.
192		*
193		* @param session The CoAP session.
194		* @param block The block structure to use. On return, this object is
195		* updated according to the values that have been written to
196		* @p pdu.
197		* @param number COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2.
198		* @param pdu The message where the block option should be written.
199		* @param data_length The length of the actual data that will be added the @p
200		* pdu by calling coap_add_block().
201		*
202		* @return @c 1 on success, or a negative value on error.
203		*/
204		int coap_write_block_b_opt(coap_session_t *session,
205		coap_block_b_t *block,
206		coap_option_num_t number,
207		coap_pdu_t *pdu,
208		size_t data_length);
209
210
211		/**
212		* Adds the @p block_num block of size 1 << (@p block_szx + 4) from source @p
213		* data to @p pdu.
214		*
215		* @param pdu The message to add the block.
216		* @param len The length of @p data.
217		* @param data The source data to fill the block with.
218		* @param block_num The actual block number.
219		* @param block_szx Encoded size of block @p block_number.
220		*
221		* @return @c 1 on success, @c 0 otherwise.
222		*/
223		int coap_add_block(coap_pdu_t *pdu,
224		size_t len,
225		const uint8_t *data,
226		unsigned int block_num,
227		unsigned char block_szx);
228
229		/**
230		* Adds the appropriate payload data of the body to the @p pdu.
231		*
232		* @param pdu The message to add the block.
233		* @param len The length of @p data.
234		* @param data The source data to fill the block with.
235		* @param block The block information (including potentially BERT)
236		*
237		* @return @c 1 on success, @c 0 otherwise.
238		*/
239		int coap_add_block_b_data(coap_pdu_t pdu, size_t len, const uint8_t data,
240		coap_block_b_t *block);
241
242		/**
243		* Re-assemble payloads into a body
244		*
245		* @param body_data The pointer to the data for the body holding the
246		* representation so far or NULL if the first time.
247		* @param length The length of @p data.
248		* @param data The payload data to update the body with.
249		* @param offset The offset of the @p data into the body.
250		* @param total The estimated total size of the body.
251		*
252		* @return The current representation of the body or @c NULL if error.
253		* If NULL, @p body_data will have been de-allocated.
254		*/
255		coap_binary_t coap_block_build_body(coap_binary_t body_data, size_t length,
256		const uint8_t *data, size_t offset, size_t total);
257
258		/**
259		* Adds the appropriate part of @p data to the @p response pdu. If blocks are
260		* required, then the appropriate block will be added to the PDU and sent.
261		* Adds a ETag option that is the hash of the entire data if the data is to be
262		* split into blocks
263		* Used by a request handler.
264		*
265		* Note: The application will get called for every packet of a large body to
266		* process. Consider using coap_add_data_response_large() instead.
267		*
268		* @param request The requesting pdu.
269		* @param response The response pdu.
270		* @param media_type The format of the data.
271		* @param maxage The maxmimum life of the data. If @c -1, then there
272		* is no maxage.
273		* @param length The total length of the data.
274		* @param data The entire data block to transmit.
275		*
276		*/
277		void coap_add_data_blocked_response(const coap_pdu_t *request,
278		coap_pdu_t *response,
279		uint16_t media_type,
280		int maxage,
281		size_t length,
282		const uint8_t *data);
283
284		/**
285		* Callback handler for de-allocating the data based on @p app_ptr provided to
286		* coap_add_data_large_*() functions following transmission of the supplied
287		* data.
288		*
289		* @param session The session that this data is associated with
290		* @param app_ptr The application provided pointer provided to the
291		* coap_add_data_large_* functions.
292		*/
293		typedef void (coap_release_large_data_t)(coap_session_t session,
294		void *app_ptr);
295
296		/**
297		* Associates given data with the @p pdu that is passed as second parameter.
298		*
299		* This function will fail if data has already been added to the @p pdu.
300		*
301		* If all the data can be transmitted in a single PDU, this is functionally
302		* the same as coap_add_data() except @p release_func (if not NULL) will get
303		* invoked after data transmission.
304		*
305		* Used for a client request.
306		*
307		* If the data spans multiple PDUs, then the data will get transmitted using
308		* (Q-)Block1 option with the addition of the Size1 and Request-Tag options.
309		* The underlying library will handle the transmission of the individual blocks.
310		* Once the body of data has been transmitted (or a failure occurred), then
311		* @p release_func (if not NULL) will get called so the application can
312		* de-allocate the @p data based on @p app_data. It is the responsibility of
313		* the application not to change the contents of @p data until the data
314		* transfer has completed.
315		*
316		* There is no need for the application to include the (Q-)Block1 option in the
317		* @p pdu.
318		*
319		* coap_add_data_large_request() (or the alternative coap_add_data_large_*()
320		* functions) must be called only once per PDU and must be the last PDU update
321		* before the PDU is transmitted. The (potentially) initial data will get
322		* transmitted when coap_send() is invoked.
323		*
324		* Note: COAP_BLOCK_USE_LIBCOAP must be set by coap_context_set_block_mode()
325		* for libcoap to work correctly when using this function.
326		*
327		* @param session The session to associate the data with.
328		* @param pdu The PDU to associate the data with.
329		* @param length The length of data to transmit.
330		* @param data The data to transmit.
331		* @param release_func The function to call to de-allocate @p data or @c NULL
332		* if the function is not required.
333		* @param app_ptr A Pointer that the application can provide for when
334		* release_func() is called.
335		*
336		* @return @c 1 if addition is successful, else @c 0.
337		*/
338		COAP_API int coap_add_data_large_request(coap_session_t *session,
339		coap_pdu_t *pdu,
340		size_t length,
341		const uint8_t *data,
342		coap_release_large_data_t release_func,
343		void *app_ptr);
344
345		/**
346		* Associates given data with the @p response pdu that is passed as fourth
347		* parameter.
348		*
349		* This function will fail if data has already been added to the @p pdu.
350		*
351		* If all the data can be transmitted in a single PDU, this is functionally
352		* the same as coap_add_data() except @p release_func (if not NULL) will get
353		* invoked after data transmission. The Content-Format, Max-Age and ETag
354		* options may be added in as appropriate.
355		*
356		* Used by a server request handler to create the response.
357		*
358		* If the data spans multiple PDUs, then the data will get transmitted using
359		* (Q-)Block2 (response) option with the addition of the Size2 and ETag
360		* options. The underlying library will handle the transmission of the
361		* individual blocks. Once the body of data has been transmitted (or a
362		* failure occurred), then @p release_func (if not NULL) will get called so the
363		* application can de-allocate the @p data based on @p app_data. It is the
364		* responsibility of the application not to change the contents of @p data
365		* until the data transfer has completed.
366		*
367		* There is no need for the application to include the (Q-)Block2 option in the
368		* @p pdu.
369		*
370		* coap_add_data_large_response() (or the alternative coap_add_data_large_*()
371		* functions) must be called only once per PDU and must be the last PDU update
372		* before returning from the request handler function.
373		*
374		* Note: COAP_BLOCK_USE_LIBCOAP must be set by coap_context_set_block_mode()
375		* for libcoap to work correctly when using this function.
376		*
377		* @param resource The resource the data is associated with.
378		* @param session The coap session.
379		* @param request The requesting pdu.
380		* @param response The response pdu.
381		* @param query The query taken from the (original) requesting pdu.
382		* @param media_type The content format of the data.
383		* @param maxage The maxmimum life of the data. If @c -1, then there
384		* is no maxage.
385		* @param etag ETag to use if not 0.
386		* @param length The total length of the data.
387		* @param data The entire data block to transmit.
388		* @param release_func The function to call to de-allocate @p data or NULL if
389		* the function is not required.
390		* @param app_ptr A Pointer that the application can provide for when
391		* release_func() is called.
392		*
393		* @return @c 1 if addition is successful, else @c 0.
394		*/
395		COAP_API int coap_add_data_large_response(coap_resource_t *resource,
396		coap_session_t *session,
397		const coap_pdu_t *request,
398		coap_pdu_t *response,
399		const coap_string_t *query,
400		uint16_t media_type,
401		int maxage,
402		uint64_t etag,
403		size_t length,
404		const uint8_t *data,
405		coap_release_large_data_t release_func,
406		void *app_ptr);
407
408		/**
409		* Set the context level CoAP block handling bits for handling RFC7959.
410		* These bits flow down to a session when a session is created and if the peer
411		* does not support something, an appropriate bit may get disabled in the
412		* session block_mode.
413		* The session block_mode then flows down into coap_crcv_t or coap_srcv_t where
414		* again an appropriate bit may get disabled.
415		*
416		* Note: This function must be called before the session is set up.
417		*
418		* Note: COAP_BLOCK_USE_LIBCOAP must be set if libcoap is to do all the
419		* block tracking and requesting, otherwise the application will have to do
420		* all of this work (the default if coap_context_set_block_mode() is not
421		* called).
422		*
423		* @param context The coap_context_t object.
424		* @param block_mode Zero or more COAP_BLOCK_ or'd options
425		*/
426		COAP_API void coap_context_set_block_mode(coap_context_t *context,
427		uint32_t block_mode);
428
429		/**
430		* Set the context level maximum block size that the server supports when sending
431		* or receiving packets with Block1 or Block2 options.
432		* This maximum block size flows down to a session when a session is created.
433		*
434		* Note: This function must be called before the session is set up.
435		*
436		* Note: COAP_BLOCK_USE_LIBCOAP must be set using coap_context_set_block_mode()
437		* if libcoap is to do this work.
438		*
439		* @param context The coap_context_t object.
440		* @param max_block_size The maximum block size a server supports. Can be 0
441		* (reset), or must be 16, 32, 64, 128, 256, 512 or 1024.
442		*/
443		COAP_API int coap_context_set_max_block_size(coap_context_t *context, size_t max_block_size);
444
445		/*@}/
446
447		#ifdef __cplusplus
448		}
449		#endif
450
451		#endif /* COAP_BLOCK_H_ */