Block Transfer

Internal API for Block Transfer (RC7959) More...

Collaboration diagram for Block Transfer:

Data Structures
struct	coap_lg_range
struct	coap_rblock_t
	Structure to keep track of received blocks. More...
struct	coap_l_block1_t
	Structure to keep track of block1 specific information (Requests) More...
struct	coap_l_block2_t
	Structure to keep track of block2 specific information (Responses) More...
struct	coap_lg_xmit_t
	Structure to hold large body (many blocks) transmission information. More...
struct	coap_lg_crcv_t
	Structure to hold large body (many blocks) client receive information. More...
struct	coap_lg_srcv_t
	Structure to hold large body (many blocks) server receive information. More...

Macros
#define	STATE_MAX_BLK_CNT_BITS   20
#define	STATE_TOKEN_BASE(t)   ((t) & (0xffffffffffffffffULL >> STATE_MAX_BLK_CNT_BITS))
#define	STATE_TOKEN_RETRY(t)   ((uint64_t)(t) >> (64 - STATE_MAX_BLK_CNT_BITS))
#define	STATE_TOKEN_FULL(t, r)   (STATE_TOKEN_BASE(t) + ((uint64_t)(r) << (64 - STATE_MAX_BLK_CNT_BITS)))
#define	COAP_BLOCK_SET_MASK
#define	COAP_BLOCK_MAX_SIZE_MASK   0x7000000 /* (svr)Mask to get the max supported block size */
#define	COAP_BLOCK_MAX_SIZE_SHIFT   24 /* (svr)Mask shift to get the max supported block size */
#define	COAP_BLOCK_MAX_SIZE_GET(a)   (((a) & COAP_BLOCK_MAX_SIZE_MASK) >> COAP_BLOCK_MAX_SIZE_SHIFT)
#define	COAP_BLOCK_MAX_SIZE_SET(a)   (((a) << COAP_BLOCK_MAX_SIZE_SHIFT) & COAP_BLOCK_MAX_SIZE_MASK)
#define	COAP_SINGLE_BLOCK_OR_Q   (COAP_BLOCK_SINGLE_BODY)
#define	COAP_RBLOCK_CNT   4

Typedefs
typedef struct coap_rblock_t	coap_rblock_t
	Structure to keep track of received blocks.
typedef struct coap_l_block1_t	coap_l_block1_t
	Structure to keep track of block1 specific information (Requests)
typedef struct coap_l_block2_t	coap_l_block2_t
	Structure to keep track of block2 specific information (Responses)

Enumerations
enum	coap_recurse_t { COAP_RECURSE_OK , COAP_RECURSE_NO }

Functions
coap_lg_crcv_t *	coap_block_new_lg_crcv (coap_session_t *session, coap_pdu_t *pdu, coap_lg_xmit_t *lg_xmit)
void	coap_block_delete_lg_crcv (coap_session_t *session, coap_lg_crcv_t *lg_crcv)
int	coap_block_check_lg_crcv_timeouts (coap_session_t *session, coap_tick_t now, coap_tick_t *tim_rem)
void	coap_block_delete_lg_srcv (coap_session_t *session, coap_lg_srcv_t *lg_srcv)
int	coap_block_check_lg_srcv_timeouts (coap_session_t *session, coap_tick_t now, coap_tick_t *tim_rem)
int	coap_handle_request_send_block (coap_session_t *session, coap_pdu_t *pdu, coap_pdu_t *response, coap_resource_t *resource, coap_string_t *query)
int	coap_handle_request_put_block (coap_context_t *context, coap_session_t *session, coap_pdu_t *pdu, coap_pdu_t *response, coap_resource_t *resource, coap_string_t *uri_path, coap_opt_t *observe, int *added_block, coap_lg_srcv_t **free_lg_srcv)
coap_lg_xmit_t *	coap_find_lg_xmit_response (const coap_session_t *session, const coap_pdu_t *request, const coap_resource_t *resource, const coap_string_t *query)
int	coap_add_data_large_response_lkd (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.
int	coap_handle_response_send_block (coap_session_t *session, coap_pdu_t *sent, coap_pdu_t *rcvd)
int	coap_handle_response_get_block (coap_context_t *context, coap_session_t *session, coap_pdu_t *sent, coap_pdu_t *rcvd, coap_recurse_t recursive)
coap_mid_t	coap_retransmit_oscore_pdu (coap_session_t *session, coap_pdu_t *pdu, coap_opt_t *echo)
void	coap_block_delete_lg_xmit (coap_session_t *session, coap_lg_xmit_t *lg_xmit)
int	coap_block_check_lg_xmit_timeouts (coap_session_t *session, coap_tick_t now, coap_tick_t *tim_rem)
void	coap_check_code_lg_xmit (const coap_session_t *session, const coap_pdu_t *request, coap_pdu_t *response, const coap_resource_t *resource, const coap_string_t *query)
	The function checks that the code in a newly formed lg_xmit created by coap_add_data_large_response_lkd() is updated.
void	coap_context_set_block_mode_lkd (coap_context_t *context, uint32_t block_mode)
	Set the context level CoAP block handling bits for handling RFC7959.
int	coap_context_set_max_block_size_lkd (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.
int	coap_add_data_large_request_lkd (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.
void	coap_check_update_token (coap_session_t *session, coap_pdu_t *pdu)
	The function checks if the token needs to be updated before PDU is presented to the application (only relevant to clients).

Detailed Description

Internal API for Block Transfer (RC7959)

Macro Definition Documentation

COAP_BLOCK_MAX_SIZE_GET

#define COAP_BLOCK_MAX_SIZE_GET

(

a

)

(((a) & COAP_BLOCK_MAX_SIZE_MASK) >> COAP_BLOCK_MAX_SIZE_SHIFT)

Definition at line 59 of file coap_block_internal.h.

COAP_BLOCK_MAX_SIZE_MASK

#define COAP_BLOCK_MAX_SIZE_MASK   0x7000000 /* (svr)Mask to get the max supported block size */

Definition at line 57 of file coap_block_internal.h.

COAP_BLOCK_MAX_SIZE_SET

#define COAP_BLOCK_MAX_SIZE_SET

(

a

)

(((a) << COAP_BLOCK_MAX_SIZE_SHIFT) & COAP_BLOCK_MAX_SIZE_MASK)

Definition at line 60 of file coap_block_internal.h.

COAP_BLOCK_MAX_SIZE_SHIFT

#define COAP_BLOCK_MAX_SIZE_SHIFT   24 /* (svr)Mask shift to get the max supported block size */

Definition at line 58 of file coap_block_internal.h.

COAP_BLOCK_SET_MASK

#define COAP_BLOCK_SET_MASK

Value:

                             (COAP_BLOCK_USE_LIBCOAP | \
                             COAP_BLOCK_SINGLE_BODY | \
                             COAP_BLOCK_NO_PREEMPTIVE_RTAG | \
                             COAP_BLOCK_STLESS_FETCH | \
                             COAP_BLOCK_STLESS_BLOCK2 | \
                             COAP_BLOCK_NOT_RANDOM_BLOCK1)

Definition at line 49 of file coap_block_internal.h.

COAP_RBLOCK_CNT

#define COAP_RBLOCK_CNT   4

Definition at line 102 of file coap_block_internal.h.

COAP_SINGLE_BLOCK_OR_Q

#define COAP_SINGLE_BLOCK_OR_Q   (COAP_BLOCK_SINGLE_BODY)

Definition at line 89 of file coap_block_internal.h.

STATE_MAX_BLK_CNT_BITS

#define STATE_MAX_BLK_CNT_BITS   20

Definition at line 34 of file coap_block_internal.h.

STATE_TOKEN_BASE

#define STATE_TOKEN_BASE

(

t

)

((t) & (0xffffffffffffffffULL >> STATE_MAX_BLK_CNT_BITS))

Definition at line 35 of file coap_block_internal.h.

STATE_TOKEN_FULL

#define STATE_TOKEN_FULL	(		t,
			r
	)		(STATE_TOKEN_BASE(t) + ((uint64_t)(r) << (64 - STATE_MAX_BLK_CNT_BITS)))

Definition at line 37 of file coap_block_internal.h.

STATE_TOKEN_RETRY

#define STATE_TOKEN_RETRY

(

t

)

((uint64_t)(t) >> (64 - STATE_MAX_BLK_CNT_BITS))

Definition at line 36 of file coap_block_internal.h.

Typedef Documentation

coap_l_block1_t

typedef struct coap_l_block1_t coap_l_block1_t

Structure to keep track of block1 specific information (Requests)

coap_l_block2_t

typedef struct coap_l_block2_t coap_l_block2_t

Structure to keep track of block2 specific information (Responses)

coap_rblock_t

typedef struct coap_rblock_t coap_rblock_t

Structure to keep track of received blocks.

Enumeration Type Documentation

coap_recurse_t

enum coap_recurse_t

Enumerator
COAP_RECURSE_OK
COAP_RECURSE_NO

Definition at line 92 of file coap_block_internal.h.

Function Documentation

coap_add_data_large_request_lkd()

int coap_add_data_large_request_lkd	(	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_lkd() 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_lkd() (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.

Note: This function must be called in the locked state.

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

int coap_add_data_large_response_lkd	(	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_lkd() (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.

Note: This function must be called in the locked state.

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

int coap_block_check_lg_crcv_timeouts	(	coap_session_t *	session,
		coap_tick_t	now,
		coap_tick_t *	tim_rem
	)

Here is the caller graph for this function:

coap_block_check_lg_srcv_timeouts()

int coap_block_check_lg_srcv_timeouts	(	coap_session_t *	session,
		coap_tick_t	now,
		coap_tick_t *	tim_rem
	)

Here is the caller graph for this function:

coap_block_check_lg_xmit_timeouts()

int coap_block_check_lg_xmit_timeouts	(	coap_session_t *	session,
		coap_tick_t	now,
		coap_tick_t *	tim_rem
	)

Definition at line 1336 of file coap_block.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_block_delete_lg_crcv()

void coap_block_delete_lg_crcv	(	coap_session_t *	session,
		coap_lg_crcv_t *	lg_crcv
	)

Here is the caller graph for this function:

coap_block_delete_lg_srcv()

void coap_block_delete_lg_srcv	(	coap_session_t *	session,
		coap_lg_srcv_t *	lg_srcv
	)

Here is the caller graph for this function:

coap_block_delete_lg_xmit()

void coap_block_delete_lg_xmit	(	coap_session_t *	session,
		coap_lg_xmit_t *	lg_xmit
	)

Definition at line 2406 of file coap_block.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_block_new_lg_crcv()

coap_lg_crcv_t * coap_block_new_lg_crcv	(	coap_session_t *	session,
		coap_pdu_t *	pdu,
		coap_lg_xmit_t *	lg_xmit
	)

Here is the caller graph for this function:

coap_check_code_lg_xmit()

void coap_check_code_lg_xmit	(	const coap_session_t *	session,
		const coap_pdu_t *	request,
		coap_pdu_t *	response,
		const coap_resource_t *	resource,
		const coap_string_t *	query
	)

The function checks that the code in a newly formed lg_xmit created by coap_add_data_large_response_lkd() is updated.

Parameters

session	The session.
request	The request PDU to to check.
response	The response PDU to to update with response->code.
resource	The requested resource.
query	The requested query.

coap_check_update_token()

void coap_check_update_token	(	coap_session_t *	session,
		coap_pdu_t *	pdu
	)

The function checks if the token needs to be updated before PDU is presented to the application (only relevant to clients).

Parameters

session	The session.
pdu	The PDU to to check for updating.

Here is the caller graph for this function:

coap_context_set_block_mode_lkd()

void coap_context_set_block_mode_lkd	(	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 417 of file coap_block.c.

Here is the caller graph for this function:

coap_context_set_max_block_size_lkd()

int coap_context_set_max_block_size_lkd	(	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: 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 442 of file coap_block.c.

Here is the call graph for this function:

Here is the caller graph for this function:

coap_find_lg_xmit_response()

coap_lg_xmit_t * coap_find_lg_xmit_response	(	const coap_session_t *	session,
		const coap_pdu_t *	request,
		const coap_resource_t *	resource,
		const coap_string_t *	query
	)

Here is the caller graph for this function:

coap_handle_request_put_block()

int coap_handle_request_put_block	(	coap_context_t *	context,
		coap_session_t *	session,
		coap_pdu_t *	pdu,
		coap_pdu_t *	response,
		coap_resource_t *	resource,
		coap_string_t *	uri_path,
		coap_opt_t *	observe,
		int *	added_block,
		coap_lg_srcv_t **	free_lg_srcv
	)

coap_handle_request_send_block()

int coap_handle_request_send_block	(	coap_session_t *	session,
		coap_pdu_t *	pdu,
		coap_pdu_t *	response,
		coap_resource_t *	resource,
		coap_string_t *	query
	)

coap_handle_response_get_block()

int coap_handle_response_get_block	(	coap_context_t *	context,
		coap_session_t *	session,
		coap_pdu_t *	sent,
		coap_pdu_t *	rcvd,
		coap_recurse_t	recursive
	)

coap_handle_response_send_block()

int coap_handle_response_send_block	(	coap_session_t *	session,
		coap_pdu_t *	sent,
		coap_pdu_t *	rcvd
	)

coap_retransmit_oscore_pdu()

coap_mid_t coap_retransmit_oscore_pdu	(	coap_session_t *	session,
		coap_pdu_t *	pdu,
		coap_opt_t *	echo
	)