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

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

session	The session that this data is associated with
app_ptr	The 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

pdu	The message to add the block.
len	The length of data.
data	The source data to fill the block with.
block_num	The actual block number.
block_szx	Encoded 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

pdu	The message to add the block.
len	The length of data.
data	The source data to fill the block with.
block	The 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

request	The requesting pdu.
response	The response pdu.
media_type	The format of the data.
maxage	The maxmimum life of the data. If -1, then there is no maxage.
length	The total length of the data.
data	The 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

session	The session to associate the data with.
pdu	The PDU to associate the data with.
length	The length of data to transmit.
data	The data to transmit.
release_func	The function to call to de-allocate data or NULL if the function is not required.
app_ptr	A 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

resource	The resource the data is associated with.
session	The coap session.
request	The requesting pdu.
response	The response pdu.
query	The query taken from the (original) requesting pdu.
media_type	The content format of the data.
maxage	The maxmimum life of the data. If -1, then there is no maxage.
etag	ETag to use if not 0.
length	The total length of the data.
data	The entire data block to transmit.
release_func	The function to call to de-allocate data or NULL if the function is not required.
app_ptr	A 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_data	The pointer to the data for the body holding the representation so far or NULL if the first time.
length	The length of data.
data	The payload data to update the body with.
offset	The offset of the data into the body.
total	The 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

session	The session that is being used for the observe.
token	The original token used to initiate the observation.
message_type	The 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

context	The coap_context_t object.
block_mode	Zero 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

pdu	The pdu to search for option number.
number	The option number to search for (must be COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2).
block	The 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

session	THe session that the pdu is associated with,
pdu	The pdu to search for option number.
number	The option number to search for (must be COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2).
block	The 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

session	The CoAP session.
block	The block structure to use. On return, this object is updated according to the values that have been written to pdu.
number	COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2.
pdu	The message where the block option should be written.
data_length	The 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

block	The block structure to use. On return, this object is updated according to the values that have been written to pdu.
number	COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2.
pdu	The message where the block option should be written.
data_length	The 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: