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.
#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
#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.
#define	COAP_OPT_BLOCK_END_BYTE(opt)
	Returns the value of the last byte of opt.
#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.
#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.

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.

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.
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).
int	coap_get_block (const coap_pdu_t *pdu, coap_option_num_t number, coap_block_t *block)
	Initializes block from pdu.
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.
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.
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.
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.
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.
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.
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.
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 pdu that is passed as second parameter.
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)
	Associates given data with the response pdu that is passed as fourth parameter.
COAP_API void	coap_context_set_block_mode (coap_context_t *context, uint32_t block_mode)
	Set the context level CoAP block handling bits for handling RFC7959.
COAP_API int	coap_context_set_max_block_size (coap_context_t *context, size_t max_block_size)
	Set the context level maximum block size that the server supports when sending or receiving packets with Block1 or Block2 options.

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 /* (cl) Don't use pre-emptive Request-Tags */

Definition at line 65 of file coap_block.h.

COAP_BLOCK_NOT_RANDOM_BLOCK1

#define COAP_BLOCK_NOT_RANDOM_BLOCK1

Value:

                                             0x80 /* (svr)Disable server handling random order
                                             block1 */

Definition at line 68 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_STLESS_BLOCK2

#define COAP_BLOCK_STLESS_BLOCK2   0x40 /* (svr)Server is stateless for handling Block2 */

Definition at line 67 of file coap_block.h.

COAP_BLOCK_STLESS_FETCH

#define COAP_BLOCK_STLESS_FETCH   0x20 /* (cl) Assume server supports stateless FETCH */

Definition at line 66 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 80 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 76 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 85 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 89 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 286 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 238 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 252 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 277 of file coap_block.c.

Here is the call graph for this function:

coap_add_data_large_request()

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

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
	)

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 3695 of file coap_block.c.

Here is the call graph for this function:

coap_context_set_block_mode()

COAP_API void coap_context_set_block_mode	(	coap_context_t *	context,
		uint32_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 409 of file coap_block.c.

Here is the call graph for this function:

coap_context_set_max_block_size()

COAP_API int coap_context_set_max_block_size	(	coap_context_t *	context,
		size_t	max_block_size
	)

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.

Parameters

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

Definition at line 431 of file coap_block.c.

Here is the call graph for this function:

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 115 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 62 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 102 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 43 of file coap_block.c.

Here is the call graph for this function:

Here is the caller graph for this function:

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 207 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 174 of file coap_block.c.

Here is the call graph for this function:

Here is the caller graph for this function: