Loading...
Searching...
No Matches
Block Transfer
Libcoap Internal API

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_TOKEN_BASE(t)
#define | STATE_TOKEN_RETRY(t)
#define | STATE_TOKEN_FULL(t, r)
#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)
#define | COAP_BLOCK_MAX_SIZE_SET(a)
#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 | ) |

Value:
(((a) & COAP_BLOCK_MAX_SIZE_MASK) >> COAP_BLOCK_MAX_SIZE_SHIFT)
COAP_BLOCK_MAX_SIZE_MASK
#define COAP_BLOCK_MAX_SIZE_MASK
Definition coap_block_internal.h:55
COAP_BLOCK_MAX_SIZE_SHIFT
#define COAP_BLOCK_MAX_SIZE_SHIFT
Definition coap_block_internal.h:56

Definition at line 57 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 55 of file coap_block_internal.h.

## COAP_BLOCK_MAX_SIZE_SET

#define COAP_BLOCK_MAX_SIZE_SET | ( |  | a | ) |

Value:
(((a) << COAP_BLOCK_MAX_SIZE_SHIFT) & COAP_BLOCK_MAX_SIZE_MASK)

Definition at line 58 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 56 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)
COAP_BLOCK_STLESS_BLOCK2
#define COAP_BLOCK_STLESS_BLOCK2
Definition coap_block.h:67
COAP_BLOCK_STLESS_FETCH
#define COAP_BLOCK_STLESS_FETCH
Definition coap_block.h:66
COAP_BLOCK_SINGLE_BODY
#define COAP_BLOCK_SINGLE_BODY
Definition coap_block.h:62
COAP_BLOCK_NO_PREEMPTIVE_RTAG
#define COAP_BLOCK_NO_PREEMPTIVE_RTAG
Definition coap_block.h:65
COAP_BLOCK_NOT_RANDOM_BLOCK1
#define COAP_BLOCK_NOT_RANDOM_BLOCK1
Definition coap_block.h:68
COAP_BLOCK_USE_LIBCOAP
#define COAP_BLOCK_USE_LIBCOAP
Definition coap_block.h:61

Definition at line 47 of file coap_block_internal.h.

## COAP_RBLOCK_CNT

#define COAP_RBLOCK_CNT 4

Definition at line 100 of file coap_block_internal.h.

## COAP_SINGLE_BLOCK_OR_Q

#define COAP_SINGLE_BLOCK_OR_Q (COAP_BLOCK_SINGLE_BODY)

Definition at line 87 of file coap_block_internal.h.

## STATE_TOKEN_BASE

#define STATE_TOKEN_BASE | ( |  | t | ) |

Value:
((t) & 0xffffffffffffULL)

Definition at line 33 of file coap_block_internal.h.

## STATE_TOKEN_FULL

#define STATE_TOKEN_FULL | ( |  | t,
|  |  | r )

Value:
(STATE_TOKEN_BASE(t) + ((uint64_t)(r) << 48))
STATE_TOKEN_BASE
#define STATE_TOKEN_BASE(t)
Definition coap_block_internal.h:33

Definition at line 35 of file coap_block_internal.h.

## STATE_TOKEN_RETRY

#define STATE_TOKEN_RETRY | ( |  | t | ) |

Value:
((uint64_t)(t) >> 48)

Definition at line 34 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 90 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 1274 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 2347 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 383 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 408 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 )