libcoap 4.3.2rc2

Data Structures | Macros | Typedefs | Functions
Block Transfer
Application API

API for handling PDUs using CoAP Block options (RFC7959) More...

## 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)
coap_opt_length
uint32_t coap_opt_length(const coap_opt_t *opt)
Returns the length of the given option.
Definition: coap_option.c:212
coap_opt_value
const uint8_t * coap_opt_value(const coap_opt_t *opt)
Returns a pointer to the value of the given option.
Definition: coap_option.c:249

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.

## ◆ 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.

## ◆ 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.

## ◆ 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 3282 of file coap_block.c.

## ◆ 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`.

## ◆ 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.

## ◆ 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.

## ◆ 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.

## ◆ 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.

## ◆ 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.