CoAP Block Client

Presently, RIOT includes server side implementations of block1 and block2. We would like to add client side implementations. At the same time, we are working to complete the struct-based API. So, this document documents how we plan to integrate the client side implementations, including the function names.

Write Option for Descriptive Use

In this scenario, we slice up some large content into smaller blocks and send it to the remote endpoint. This is a client POST/PUT request for block1, and a server GET response for block2.

For block2 server response, use coap_block2_init() to read the block option in request packet. No new functions needed here. This function initializes the slicer struct from the block2 option in the request

For block1 client request, the slicer for the initial request is zeroed in the app. It is up to the client to remember the next block to request. The client may reuse the same slicer struct or create a new one with each request. However, the block option in previous response is not required to generate the next request.

Task	Buffer Functions	Struct Functions
write option	coap_opt_put_block()	coap_opt_add_block()
finish options	write 0xff	coap_opt_finish()
write payload slice	coap_blockwise_put_(bytes|char)	-same-
finalize option (more blocks?)	coap_block_finish()	-same-

Write Option for Control Use

Block1 response

A server must write a block option in the response to a block1 request. So, the response does not include a blockwise payload, although the response to the final request may contain a payload for the overall response to the sequence. For example, /sha256 resource in the nanocoap_server example returns the digest in the final response.

In this case, the application will not have a slicer struct. Instead, the server simply will take the option from the request and put it in the response. The server may request smaller blocks from the client. Create coap_opt_put_block_control() and coap_opt_add_block_control().

Block2 request

A client must write a block2 option in the request to receive a particular block. The client initializes this option for the first request. The client likely retrieves the block option in responses, and increments the offset to request the next block. The client uses a coap_block1_t, not a slicer struct. The client also can use the new coap_opt_put_block_control() and coap_opt_add_block_control().

Read Option

For either block1 or block2, client or server, the user simply wants to retrieve the block into a coap_block1_t struct. Note we need to rework so that the existing coap_get_block1() and coap_get_block2() as inline. They simply return a new coap_get_block() function as currently implemented in coap_get_block1(), which does some extra processing.