libcoap  4.3.0beta
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, 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...
 
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 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,
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
pduThe message to add the block.
lenThe length of data.
dataThe source data to fill the block with.
block_numThe actual block number.
block_szxEncoded 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
resourceThe resource the data is associated with.
sessionThe coap session.
requestThe requesting pdu.
responseThe response pdu.
tokenThe token taken from the (original) requesting pdu.
media_typeThe format of the data.
maxageThe maxmimum life of the data. If -1, then there is no maxage.
lengthThe total length of the data.
dataThe 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
pduThe pdu to search for option type.
typeThe option to search for (must be COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2).
blockThe 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 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 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
blockThe block structure to use. On return, this object is updated according to the values that have been written to pdu.
typeCOAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2.
pduThe message where the block option should be written.
data_lengthThe 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: