Site Tools


Block-Wise Transfer through the IP network transport

OIC client and OIC server can send/receive the large size messages by means of transferring of small block unit. it can be triggered by not only the OIC client but also OIC server.

The large size can be decided by the application scenarios

Use Cases

  • Send Bulk Data : OIC Client & Server can send large-size data to the destination device.
  • Receive Bulk Data : OIC Client & Server can receive large-size data from the source device.


  • Large size data can be transferred by dividing to small size data block.
  • The block size range is form 16 bytes to 1KB.
  • Initially, the data larger than 1KB will be transferred by dividing to 1KB-size block.
  • All blocks have same QoS level. ( i.e CON or NON )
  • Each block be transferred according to the CoAP Spec.
  • Block-wise transferring fails if one block fails
  • Block size can be negotiated based on the CoAP block-wise transfer.
  • Block-wise Transfer is handled by OIC-Base Layer automatically.
  • There will be no dependency of CoAP Spec in App.(even RI layer)
  • Application can’t control Block-Wise Transfer parameters.
  • Application can only receive reassembled bulk data.
  • There is no support early negotiation request in block-option2 and stateless block-wise PUT in block-option1.

Block Options in requests and responses

Block1 is useful with the payload-bearing POST and PUT requests and their responses. and Block2 is useful with GET, POST, PUT requests and their payload-bearing responses.

Three items of information may need to be transferred in a Block (Block1 or Block2) option:

  • The size of the block (SZX)
  • whether more blocks are following (M)
  • the relative number of the block (NUM) within a sequence of blocks with the given size.

the Block options support only a small range of power-of-two block sizes, from 2^4 (16) to 2^10 (1024) bytes. default block size to use in OIC device have to be set before build.

typedef enum {
    CA_BLOCK_SIZE_16_BYTE = 0,     /**< 16 byte */
    CA_BLOCK_SIZE_32_BYTE = 1,     /**< 32 byte */
    CA_BLOCK_SIZE_64_BYTE = 2,     /**< 64 byte */
    CA_BLOCK_SIZE_128_BYTE = 3,    /**< 128 byte */
    CA_BLOCK_SIZE_256_BYTE = 4,    /**< 256 byte */
    CA_BLOCK_SIZE_512_BYTE = 5,    /**< 512 byte */
    CA_BLOCK_SIZE_1_KBYTE = 6      /**< 1 Kbyte */
} CABlockSize_t;

and this items is defined in coap_block_t structure in libCoAP in below.

typedef struct {
    unsigned int num : 20;
    unsigned int m : 1;      /**< 1 if more blocks follow, 0 otherwise */
    unsigned int sze : 3;    /**< block size */
} coap_block_t;

block option 1

  • request
    • NUM(number) : block number
    • M(more bit) : whether futrher blocks need to be transferred
    • SZE(size) : the size of the payload
  • response
    • NUM(number) : block number
    • M(more bit)
      1. request(1), response(1) : it's not the final response block.
      2. request(1), response(0) : it's the final response block.
    • SZE(size) : the largest block size preferred by the server.

block option 2

  • request
    • NUM(number) : the block number of the payload that is being requested to be returned in the response.
    • M(more bit) : no function (it must be set to zero)
    • SZE(size) : the block size of previous blocks receivced
  • response
    • NUM(number) : block number
    • M(more bit) : whether futrher blocks need to be transferred
    • SZE(size) : the size of the payload

Size Options in block-wise transfer

Size options is defined in CoAP specification. when transferring a large resource block by block, it is advantageous to know the total size early in the process. The size options have no other effect on the processing of the request or response. and the size options must not occur more than once.

  • size1 option
    • in a request carrying a block1 option, to indicate the current estimate the client has of the total size of the resource representation
  • size2 option
    • in a response carrying a block2 option, to indicate the current estimate the server has of the total size of the resource representation

Block-wise with negotiation

late negotiation

the client is surprised by the need for a block-wise transfer, and unhappy with the size chosen unilaterally by the server.

As it did not send a size proposal initially, (it needs early negotiation if a size proposal want to be sent initially, but now CA is not support this scope)

the late negotiation only influences the size from the second message exchange onward.

Since the client already obtained both the first and second 64-byte block in the first 128-byte exchange, it goes on requesting the third 64-byte block (“2/0/64”) like below sequence

Block-wise Error Handling

The Block-wise transfer support two response codes additionally more.

  typedef enum
      /* Response status code - START HERE */
      CA_REQUEST_ENTITY_INCOMPLETE = 408, /**< Request Entity Incomplete */
      CA_REQUEST_ENTITY_TOO_LARGE = 413,  /**< Request Entity Too Large */
      /* Response status code - END HERE */
  } CAResponseResult_t;

and this error code is defined in CAResponseResult_t structure in cacommon.h

4.08 Request Entity Incomplete

This response code indicates that the server has not received the blocks of the request body that it needs to proceed. Clients that do not have specific mechanisms to handle this case. therefore should always start with block number zero and send the following blocks in order.

4.13 Request Entity Too Large

The server return this response code at any time during a Block1 transfer to indicate that it does not currently have the resources to store blocks. The response carries a smaller SZX in its Block1 option. If the client receive this response code, the client should continue with a smaller block size.

In case of Block2, we don't use this response code. if client does not have the resource to store blocks, client replaces with smaller SZX in its Block2 option and request next block message to server.

History:Proposal for Block-Wise Transfer through the IP network transport

block-wise_transfer.txt · Last modified: 2015/06/22 06:53 by johyuna