libcoap 4.3.3
Block Transfer

API for handling PDUs using CoAP Block options (RFC7959) More...

+ Collaboration diagram for Block Transfer:

Data Structures

struct  coap_block_t
 Structure of Block options. More...
 
struct  coap_block_b_t
 Structure of Block options with BERT support. More...
 

Macros

#define COAP_MAX_BLOCK_SZX   6
 The largest value for the SZX component in a Block option. More...
 
#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 /* Don't use pre-emptive Request-Tags */
 
#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 least significant byte of a Block option opt. More...
 
#define COAP_OPT_BLOCK_END_BYTE(opt)
 Returns the value of the last byte of opt. More...
 
#define COAP_OPT_BLOCK_MORE(opt)    (coap_opt_length(opt) ? (COAP_OPT_BLOCK_END_BYTE(opt) & 0x08) : 0)
 Returns the value of the More-bit of a Block option opt. More...
 
#define COAP_OPT_BLOCK_SZX(opt)    (coap_opt_length(opt) ? (COAP_OPT_BLOCK_END_BYTE(opt) & 0x07) : 0)
 Returns the value of the SZX-field of a Block option opt. More...
 

Typedefs

typedef void(* coap_release_large_data_t) (coap_session_t *session, void *app_ptr)
 Callback handler for de-allocating the data based on app_ptr provided to coap_add_data_large_*() functions following transmission of the supplied data. More...
 

Functions

int coap_q_block_is_supported (void)
 Returns 1 if libcoap was built with option Q-BlockX support, 0 otherwise. More...
 
unsigned int coap_opt_block_num (const coap_opt_t *block_opt)
 Returns the value of field num in the given block option block_opt. More...
 
COAP_STATIC_INLINE int coap_more_blocks (size_t data_len, unsigned int num, uint16_t szx)
 Checks if more than num blocks are required to deliver data_len bytes of data for a block size of 1 << (szx + 4). More...
 
int coap_get_block (const coap_pdu_t *pdu, coap_option_num_t number, coap_block_t *block)
 Initializes block from pdu. More...
 
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)
 Initializes block from pdu. More...
 
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 number to message pdu. More...
 
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)
 Writes a block option of type number to message pdu. More...
 
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 block_num block of size 1 << (block_szx + 4) from source data to pdu. More...
 
int coap_add_block_b_data (coap_pdu_t *pdu, size_t len, const uint8_t *data, coap_block_b_t *block)
 Adds the appropriate payload data of the body to the pdu. More...
 
coap_binary_tcoap_block_build_body (coap_binary_t *body_data, size_t length, const uint8_t *data, size_t offset, size_t total)
 Re-assemble payloads into a body. More...
 
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)
 Adds the appropriate part of data to the response pdu. More...
 
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 pdu that is passed as second parameter. More...
 
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)
 Associates given data with the response pdu that is passed as fourth parameter. More...
 
void coap_context_set_block_mode (coap_context_t *context, uint8_t block_mode)
 Set the context level CoAP block handling bits for handling RFC7959. More...
 
int coap_cancel_observe (coap_session_t *session, coap_binary_t *token, coap_pdu_type_t message_type)
 Cancel an observe that is being tracked by the client large receive logic. More...
 

Detailed Description

API for handling PDUs using CoAP Block options (RFC7959)

Macro Definition Documentation

◆ COAP_BLOCK_NO_PREEMPTIVE_RTAG

#define COAP_BLOCK_NO_PREEMPTIVE_RTAG   0x10 /* Don't use pre-emptive Request-Tags */

Definition at line 65 of file coap_block.h.

◆ COAP_BLOCK_SINGLE_BODY

#define COAP_BLOCK_SINGLE_BODY   0x02 /* Deliver the data as a single body */

Definition at line 62 of file coap_block.h.

◆ COAP_BLOCK_TRY_Q_BLOCK

#define COAP_BLOCK_TRY_Q_BLOCK   0x04 /* Try Q-Block method */

Definition at line 63 of file coap_block.h.

◆ COAP_BLOCK_USE_LIBCOAP

#define COAP_BLOCK_USE_LIBCOAP   0x01 /* Use libcoap to do block requests */

Definition at line 61 of file coap_block.h.

◆ COAP_BLOCK_USE_M_Q_BLOCK

#define COAP_BLOCK_USE_M_Q_BLOCK   0x08 /* Use M bit when recovering Q-Block2 */

Definition at line 64 of file coap_block.h.

◆ COAP_MAX_BLOCK_SZX

#define COAP_MAX_BLOCK_SZX   6

The largest value for the SZX component in a Block option.

Definition at line 36 of file coap_block.h.

◆ COAP_OPT_BLOCK_END_BYTE

#define COAP_OPT_BLOCK_END_BYTE (   opt)
Value:
((coap_opt_length(opt) && coap_opt_value(opt)) ? \
*(coap_opt_value(opt) + (coap_opt_length(opt)-1)) : 0)
uint32_t coap_opt_length(const coap_opt_t *opt)
Returns the length of the given option.
Definition: coap_option.c:212
const uint8_t * coap_opt_value(const coap_opt_t *opt)
Returns a pointer to the value of the given option.
Definition: coap_option.c:249

Returns the value of the last byte of opt.

Definition at line 83 of file coap_block.h.

◆ COAP_OPT_BLOCK_LAST

#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 least significant byte of a Block option opt.

For zero-length options (i.e. num == m == szx == 0), COAP_OPT_BLOCK_LAST returns NULL.

Definition at line 79 of file coap_block.h.

◆ COAP_OPT_BLOCK_MORE

#define COAP_OPT_BLOCK_MORE (   opt)     (coap_opt_length(opt) ? (COAP_OPT_BLOCK_END_BYTE(opt) & 0x08) : 0)

Returns the value of the More-bit of a Block option opt.

Definition at line 88 of file coap_block.h.

◆ COAP_OPT_BLOCK_SZX

#define COAP_OPT_BLOCK_SZX (   opt)     (coap_opt_length(opt) ? (COAP_OPT_BLOCK_END_BYTE(opt) & 0x07) : 0)

Returns the value of the SZX-field of a Block option opt.

Definition at line 92 of file coap_block.h.

Typedef Documentation

◆ coap_release_large_data_t

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

Callback handler for de-allocating the data based on app_ptr provided to coap_add_data_large_*() functions following transmission of the supplied data.

Parameters
sessionThe session that this data is associated with
app_ptrThe application provided pointer provided to the coap_add_data_large_* functions.

Definition at line 289 of file coap_block.h.

Function Documentation

◆ coap_add_block()

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 block_num block of size 1 << (block_szx + 4) from source data to pdu.

Parameters
pduThe message to add the block.
lenThe length of data.
dataThe source data to fill the block with.
block_numThe actual block number.
block_szxEncoded size of block block_number.
Returns
1 on success, 0 otherwise.

Definition at line 234 of file coap_block.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_add_block_b_data()

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

Adds the appropriate payload data of the body to the pdu.

Parameters
pduThe message to add the block.
lenThe length of data.
dataThe source data to fill the block with.
blockThe block information (including potentially BERT)
Returns
1 on success, 0 otherwise.

Definition at line 248 of file coap_block.c.

+ Here is the call graph for this function:

◆ coap_add_data_blocked_response()

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 
)

Adds the appropriate part of data to the 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.

Parameters
requestThe requesting pdu.
responseThe response pdu.
media_typeThe format of the data.
maxageThe maxmimum life of the data. If -1, then there is no maxage.
lengthThe total length of the data.
dataThe entire data block to transmit.

Definition at line 273 of file coap_block.c.

+ Here is the call graph for this function:

◆ coap_add_data_large_request()

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 pdu that is passed as second parameter.

This function will fail if data has already been added to the pdu.

If all the data can be transmitted in a single PDU, this is functionally the same as coap_add_data() except 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 release_func (if not NULL) will get called so the application can de-allocate the data based on app_data. It is the responsibility of the application not to change the contents of data until the data transfer has completed.

There is no need for the application to include the (Q-)Block1 option in the 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.

Parameters
sessionThe session to associate the data with.
pduThe PDU to associate the data with.
lengthThe length of data to transmit.
dataThe data to transmit.
release_funcThe function to call to de-allocate data or NULL if the function is not required.
app_ptrA Pointer that the application can provide for when release_func() is called.
Returns
1 if addition is successful, else 0.

◆ coap_add_data_large_response()

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 
)

Associates given data with the response pdu that is passed as fourth parameter.

This function will fail if data has already been added to the pdu.

If all the data can be transmitted in a single PDU, this is functionally the same as coap_add_data() except 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 release_func (if not NULL) will get called so the application can de-allocate the data based on app_data. It is the responsibility of the application not to change the contents of data until the data transfer has completed.

There is no need for the application to include the (Q-)Block2 option in the 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.

Parameters
resourceThe resource the data is associated with.
sessionThe coap session.
requestThe requesting pdu.
responseThe response pdu.
queryThe query taken from the (original) requesting pdu.
media_typeThe content format of the data.
maxageThe maxmimum life of the data. If -1, then there is no maxage.
etagETag to use if not 0.
lengthThe total length of the data.
dataThe entire data block to transmit.
release_funcThe function to call to de-allocate data or NULL if the function is not required.
app_ptrA Pointer that the application can provide for when release_func() is called.
Returns
1 if addition is successful, else 0.

◆ coap_block_build_body()

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 
)

Re-assemble payloads into a body.

Parameters
body_dataThe pointer to the data for the body holding the representation so far or NULL if the first time.
lengthThe length of data.
dataThe payload data to update the body with.
offsetThe offset of the data into the body.
totalThe estimated total size of the body.
Returns
The current representation of the body or NULL if error. If NULL, body_data will have been de-allocated.

Definition at line 3285 of file coap_block.c.

+ Here is the call graph for this function:

◆ coap_cancel_observe()

int coap_cancel_observe ( coap_session_t session,
coap_binary_t token,
coap_pdu_type_t  message_type 
)

Cancel an observe that is being tracked by the client large receive logic.

(coap_context_set_block_mode() has to be called) This will trigger the sending of an observe cancel pdu to the server.

Parameters
sessionThe session that is being used for the observe.
tokenThe original token used to initiate the observation.
message_typeThe COAP_MESSAGE_ type (NON or CON) to send the observe cancel pdu as.
Returns
1 if observe cancel transmission initiation is successful, else 0.
+ Here is the caller graph for this function:

◆ coap_context_set_block_mode()

void coap_context_set_block_mode ( coap_context_t context,
uint8_t  block_mode 
)

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).

Parameters
contextThe coap_context_t object.
block_modeZero or more COAP_BLOCK_ or'd options

Definition at line 379 of file coap_block.c.

◆ coap_get_block()

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

Initializes block from pdu.

number must be either COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2. When option number was found in pdu, block is initialized with values from this option and the function returns the value 1. Otherwise, 0 is returned.

Parameters
pduThe pdu to search for option number.
numberThe option number to search for (must be COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2).
blockThe block structure to initialize.
Returns
1 on success, 0 otherwise.

Definition at line 111 of file coap_block.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_get_block_b()

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 
)

Initializes block from pdu.

number must be either COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2. When option number was found in pdu, block is initialized with values from this option and the function returns the value 1. Otherwise, 0 is returned. BERT information is abstracted as appropriate.

Parameters
sessionTHe session that the pdu is associated with,
pduThe pdu to search for option number.
numberThe option number to search for (must be COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2).
blockThe block structure to initialize.
Returns
1 on success, 0 otherwise.

Definition at line 58 of file coap_block.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_more_blocks()

COAP_STATIC_INLINE int coap_more_blocks ( size_t  data_len,
unsigned int  num,
uint16_t  szx 
)

Checks if more than num blocks are required to deliver data_len bytes of data for a block size of 1 << (szx + 4).

Definition at line 105 of file coap_block.h.

◆ coap_opt_block_num()

unsigned int coap_opt_block_num ( const coap_opt_t block_opt)

Returns the value of field num in the given block option block_opt.

Definition at line 39 of file coap_block.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ coap_q_block_is_supported()

int coap_q_block_is_supported ( void  )

Returns 1 if libcoap was built with option Q-BlockX support, 0 otherwise.

Definition at line 33 of file coap_block.c.

◆ coap_write_block_b_opt()

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 
)

Writes a block option of type number to message pdu.

If the requested block size is too large to fit in 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 data_length.

This function may change *block to reflect the values written to pdu. As the function takes into consideration the remaining space pdu, no more options should be added after coap_write_block_opt() has returned.

Parameters
sessionThe CoAP session.
blockThe block structure to use. On return, this object is updated according to the values that have been written to pdu.
numberCOAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2.
pduThe message where the block option should be written.
data_lengthThe length of the actual data that will be added the pdu by calling coap_add_block().
Returns
1 on success, or a negative value on error.

Definition at line 203 of file coap_block.c.

+ Here is the call graph for this function:

◆ coap_write_block_opt()

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 number to message pdu.

If the requested block size is too large to fit in 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 data_length.

This function may change *block to reflect the values written to pdu. As the function takes into consideration the remaining space pdu, no more options should be added after coap_write_block_opt() has returned.

Parameters
blockThe block structure to use. On return, this object is updated according to the values that have been written to pdu.
numberCOAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2.
pduThe message where the block option should be written.
data_lengthThe length of the actual data that will be added the pdu by calling coap_add_block().
Returns
1 on success, or a negative value on error.

Definition at line 170 of file coap_block.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function: