Block Transfer

## Data Structures

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

## Macros

#define | COAP_MAX_BLOCK_SZX 4
| 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...
static int | coap_more_blocks (size_t data_len, unsigned int num, unsigned short 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...
static void | coap_opt_block_set_m (coap_opt_t *block_opt, int m)
| Sets the More-bit in `block_opt`. More...
int | coap_get_block (coap_pdu_t *pdu, unsigned short type, coap_block_t *block)
| Initializes `block` from `pdu`. More...
int | coap_write_block_opt (coap_block_t *block, unsigned short 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 unsigned char *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...

## Detailed Description

## Macro Definition Documentation

## COAP_MAX_BLOCK_SZX

#define COAP_MAX_BLOCK_SZX 4

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

Note that 1 << (COAP_MAX_BLOCK_SZX + 4) should not exceed COAP_MAX_PDU_SIZE.

Definition at line 27 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 44 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 48 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 52 of file block.h.

## Function Documentation

## coap_add_block()

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

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

## coap_get_block()

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

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

## coap_more_blocks()

static int coap_more_blocks | ( | size_t | data_len,
|  | unsigned int | num,
|  | unsigned short | szx
| ) |  |

inline static

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 65 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 26 of file block.c.

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

## coap_opt_block_set_m()

static void coap_opt_block_set_m | ( | coap_opt_t * | block_opt,
|  | int | m
| ) |  |

inline static

Sets the More-bit in `block_opt`.

Definition at line 71 of file block.h.

Here is the call graph for this function:

## coap_write_block_opt()

int coap_write_block_opt | ( | coap_block_t * | block,
|  | unsigned short | 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 73 of file block.c.

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