libcoap  4.3.0rc1
Block Transfer

API functions for handling PDUs using CoAP BLOCK options. More...

Data Structures

struct  coap_block_t
 Structure of Block options. 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_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_MORE(opt)    (coap_opt_length(opt) ? (*COAP_OPT_BLOCK_LAST(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_LAST(opt) & 0x07) : 0)
 Returns the value of the SZX-field of a Block option opt. More...
 

Typedefs

typedef void(* coap_release_large_data_t) (struct 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

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 (coap_pdu_t *pdu, uint16_t type, coap_block_t *block)
 Initializes block from pdu. More...
 
int coap_write_block_opt (coap_block_t *block, uint16_t type, coap_pdu_t *pdu, size_t data_length)
 Writes a block option of type type 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...
 
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 (coap_resource_t *resource, struct coap_session_t *session, coap_pdu_t *request, coap_pdu_t *response, const coap_binary_t *token, 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 (struct 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, struct coap_session_t *session, coap_pdu_t *request, coap_pdu_t *response, const coap_binary_t *token, 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, uint8_t message_type)
 Cancel an observe that is being tracked by the client large receive logic when using coap_send_large(). More...
 

Detailed Description

API functions for handling PDUs using CoAP BLOCK options.

Macro Definition Documentation

◆ COAP_BLOCK_SINGLE_BODY

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

Definition at line 40 of file block.h.

◆ COAP_BLOCK_USE_LIBCOAP

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

Definition at line 39 of file 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 27 of file 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 47 of file block.h.

◆ COAP_OPT_BLOCK_MORE

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

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

Definition at line 51 of file block.h.

◆ COAP_OPT_BLOCK_SZX

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

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

Definition at line 55 of file block.h.

Typedef Documentation

◆ coap_release_large_data_t

typedef void(* coap_release_large_data_t) (struct 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 200 of file 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 124 of file block.c.

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

◆ coap_add_data_blocked_response()

void coap_add_data_blocked_response ( coap_resource_t resource,
struct coap_session_t session,
coap_pdu_t request,
coap_pdu_t response,
const coap_binary_t token,
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
resourceThe resource the data is associated with.
sessionThe coap session.
requestThe requesting pdu.
responseThe response pdu.
tokenThe token taken from the (original) requesting 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 141 of file block.c.

+ Here is the call graph for this function:

◆ coap_add_data_large_request()

int coap_add_data_large_request ( struct 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.

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 BLOCK1 option with the addition of the SIZE1 option. 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 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() or preferably coap_send_large() 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.

Definition at line 629 of file block.c.

+ Here is the call graph for this function:

◆ coap_add_data_large_response()

int coap_add_data_large_response ( coap_resource_t resource,
struct coap_session_t session,
coap_pdu_t request,
coap_pdu_t response,
const coap_binary_t token,
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.

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 MEDIA_TYPE, MAXAGE 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 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 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.
tokenThe token taken from the (original) requesting pdu.
queryThe query taken from the (original) requesting pdu.
media_typeThe 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.

Definition at line 640 of file block.c.

+ Here is the call graph for this function:

◆ 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 1578 of file block.c.

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

◆ coap_cancel_observe()

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

Cancel an observe that is being tracked by the client large receive logic when using coap_send_large().

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.

Definition at line 293 of file block.c.

+ Here is the call graph for this function:
+ 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 263 of file block.c.

◆ coap_get_block()

int coap_get_block ( coap_pdu_t pdu,
uint16_t  type,
coap_block_t block 
)

Initializes block from pdu.

type must be either COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2. When option type 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 type.
typeThe option to search for (must be COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2).
blockThe block structure to initilize.
Returns
1 on success, 0 otherwise.

Definition at line 35 of file 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 68 of file 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 16 of file block.c.

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

◆ coap_write_block_opt()

int coap_write_block_opt ( coap_block_t block,
uint16_t  type,
coap_pdu_t pdu,
size_t  data_length 
)

Writes a block option of type type 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.
typeCOAP_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 63 of file block.c.

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