Block Transfer

API functions for handling PDUs using CoAP BLOCK options. More...

## Data Structures

struct | coap_block_t
| Structure of Block options. More...

## Macros

#define | COAP_MAX_BLOCK_SZX 6
| The largest value for the SZX component in a Block option. More...
#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_MORE(opt) (coap_opt_length(opt) ? (*COAP_OPT_BLOCK_LAST(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_LAST(opt) & 0x07) : 0)
| Returns the value of the SZX-field of a Block option `opt`. More...

## 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`. 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 (coap_pdu_t *pdu, uint16_t type, coap_block_t *block)
| Initializes `block` from `pdu`. More...
int | coap_write_block_opt (coap_block_t *block, uint16_t type, coap_pdu_t *pdu, size_t data_length)
| Writes a block option of type `type` to message `pdu`. More...
int | coap_add_block (coap_pdu_t *pdu, unsigned int 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...
void | coap_add_data_blocked_response (struct coap_resource_t *resource, struct coap_session_t *session, coap_pdu_t *request, coap_pdu_t *response, const coap_binary_t *token, uint16_t media_type, int maxage, size_t length, const uint8_t *data)
| Adds the appropriate part of `data` to the `response` pdu. More...

## Detailed Description

API functions for handling PDUs using CoAP BLOCK options.

## Macro Definition Documentation

## COAP_MAX_BLOCK_SZX

#define COAP_MAX_BLOCK_SZX 6

The largest value for the SZX component in a Block option.

Definition at line 30 of file 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 47 of file block.h.

## COAP_OPT_BLOCK_MORE

#define COAP_OPT_BLOCK_MORE | ( |  | opt | ) | (coap_opt_length(opt) ? (*COAP_OPT_BLOCK_LAST(opt) & 0x08) : 0)

Returns the value of the More-bit of a Block option `opt`.

Definition at line 51 of file block.h.

## COAP_OPT_BLOCK_SZX

#define COAP_OPT_BLOCK_SZX | ( |  | opt | ) | (coap_opt_length(opt) ? (*COAP_OPT_BLOCK_LAST(opt) & 0x07) : 0)

Returns the value of the SZX-field of a Block option `opt`.

Definition at line 55 of file block.h.

## Function Documentation

## coap_add_block()

int coap_add_block | ( | coap_pdu_t * | pdu,
|  | unsigned int | 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 125 of file block.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_add_data_blocked_response()

void coap_add_data_blocked_response | ( | struct coap_resource_t * | resource,
|  | struct coap_session_t * | session,
|  | coap_pdu_t * | request,
|  | coap_pdu_t * | response,
|  | const coap_binary_t * | token,
|  | 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 GET request handler.

Parameters

  resource | The resource the data is associated with.
  session | The coap session.
  request | The requesting pdu.
  response | The response pdu.
  token | The token taken from the (original) requesting 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 142 of file block.c.

Here is the call graph for this function:

## coap_get_block()

int coap_get_block | ( | coap_pdu_t * | pdu,
|  | uint16_t | type,
|  | coap_block_t * | block
| ) |  |

Initializes `block` from `pdu`.

`type` must be either COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2. When option `type` 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 `type`.
  type | The option to search for (must be COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2).
  block | The block structure to initilize.

Returns
  `1` on success, `0` otherwise.

Definition at line 36 of file 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 68 of file 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 17 of file block.c.

Here is the call graph for this function:
Here is the caller graph for this function:

## coap_write_block_opt()

int coap_write_block_opt | ( | coap_block_t * | block,
|  | uint16_t | type,
|  | coap_pdu_t * | pdu,
|  | size_t | data_length
| ) |  |

Writes a block option of type `type` 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`.
  type | 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 64 of file block.c.

Here is the call graph for this function:
Here is the caller graph for this function: