1 /* block.h -- block transfer
3 * Copyright (C) 2010--2012,2014 Olaf Bergmann <bergmann@tzi.org>
5 * This file is part of the CoAP library libcoap. Please see
6 * README for terms of use.
10 #define _COAP_BLOCK_H_
17 * @defgroup block Block Transfer
21 #ifndef COAP_MAX_BLOCK_SZX
23 * The largest value for the SZX component in a Block option. Note
24 * that 1 << (COAP_MAX_BLOCK_SZX + 4) should not exceed
27 #define COAP_MAX_BLOCK_SZX 4
28 #endif /* COAP_MAX_BLOCK_SZX */
30 #if (COAP_MAX_PDU_SIZE - 6) < (1 << (COAP_MAX_BLOCK_SZX + 4))
31 #error "COAP_MAX_BLOCK_SZX too large"
35 * Structure of Block options.
38 unsigned int num:20; /**< block number */
39 unsigned int m:1; /**< 1 if more blocks follow, 0 otherwise */
40 unsigned int szx:3; /**< block size */
44 * Returns the value of the least significant byte of a Block option @p opt.
45 * For zero-length options (i.e. num == m == szx == 0), COAP_OPT_BLOCK_LAST
48 #define COAP_OPT_BLOCK_LAST(opt) \
49 (COAP_OPT_LENGTH(opt) ? (COAP_OPT_VALUE(opt) + (COAP_OPT_LENGTH(opt)-1)) : 0)
51 /** Returns the value of the More-bit of a Block option @p opt. */
52 #define COAP_OPT_BLOCK_MORE(opt) \
53 (COAP_OPT_LENGTH(opt) ? (*COAP_OPT_BLOCK_LAST(opt) & 0x08) : 0)
55 /** Returns the value of the SZX-field of a Block option @p opt. */
56 #define COAP_OPT_BLOCK_SZX(opt) \
57 (COAP_OPT_LENGTH(opt) ? (*COAP_OPT_BLOCK_LAST(opt) & 0x07) : 0)
60 * Returns the value of field @c num in the given block option @p
63 unsigned int coap_opt_block_num(const coap_opt_t *block_opt);
66 * Checks if more than @p num blocks are required to deliver @p data_len
67 * bytes of data for a block size of 1 << (@p szx + 4).
70 coap_more_blocks(size_t data_len, unsigned int num, unsigned short szx) {
71 return ((num+1) << (szx + 4)) < data_len;
74 /** Sets the More-bit in @p block_opt */
76 coap_opt_block_set_m(coap_opt_t *block_opt, int m) {
78 *(COAP_OPT_VALUE(block_opt) + (COAP_OPT_LENGTH(block_opt) - 1)) |= 0x08;
80 *(COAP_OPT_VALUE(block_opt) + (COAP_OPT_LENGTH(block_opt) - 1)) &= ~0x08;
84 * Initializes @p block from @p pdu. @p type must be either COAP_OPTION_BLOCK1
85 * or COAP_OPTION_BLOCK2. When option @p type was found in @p pdu, @p block
86 * is initialized with values from this option and the function returns the
87 * value @c 1. Otherwise, @c 0 is returned.
89 * @param pdu The pdu to search for option @p type.
90 * @param type The option to search for (must be COAP_OPTION_BLOCK1 or
92 * @param block The block structure to initilize.
93 * @return @c 1 on success, @c 0 otherwise.
95 int coap_get_block(coap_pdu_t *pdu, unsigned short type, coap_block_t *block);
98 * Writes a block option of type @p type to message @p pdu. If the
99 * requested block size is too large to fit in @p pdu, it is reduced
100 * accordingly. An exception is made for the final block when less
101 * space is required. The actual length of the resource is specified
104 * This function may change *block to reflect the values written to
105 * @p pdu. As the function takes into consideration the remaining space
106 * @p pdu, no more options should be added after coap_write_block_opt()
109 * @param block The block structure to use. On return, this object
110 * is updated according to the values that have been
112 * @param type COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2
113 * @param pdu The message where the block option should be
115 * @param data_length The length of the actual data that will be added
116 * the @p pdu by calling coap_add_block().
117 * @return @c 1 on success, or a negative value on error.
119 int coap_write_block_opt(coap_block_t *block, unsigned short type,
120 coap_pdu_t *pdu, size_t data_length);
123 * Adds the @p block_num block of size 1 << (@p block_szx + 4) from
124 * source @p data to @p pdu.
126 * @param pdu The message to add the block
127 * @param len The length of @p data.
128 * @param data The source data to fill the block with
129 * @param block_num The actual block number
130 * @param block_szx Encoded size of block @p block_number
131 * @return @c 1 on success, @c 0 otherwise.
133 int coap_add_block(coap_pdu_t *pdu, unsigned int len, const unsigned char *data,
134 unsigned int block_num, unsigned char block_szx);
137 #endif /* _COAP_BLOCK_H_ */