1 /*
2 * block.h -- block transfer
3 *
4 * Copyright (C) 2010-2012,2014-2015 Olaf Bergmann <bergmann@tzi.org>
5 *
6 * This file is part of the CoAP library libcoap. Please see README for terms
7 * of use.
8 */
9
10 #ifndef _COAP_BLOCK_H_
11 #define _COAP_BLOCK_H_
12
13 #include "encode.h"
14 #include "option.h"
15 #include "pdu.h"
16
17 /**
18 * @defgroup block Block Transfer
19 * @{
20 */
21
22 #ifndef COAP_MAX_BLOCK_SZX
23 /**
24 * The largest value for the SZX component in a Block option. Note that
25 * 1 << (COAP_MAX_BLOCK_SZX + 4) should not exceed COAP_MAX_PDU_SIZE.
26 */
27 #define COAP_MAX_BLOCK_SZX 4
28 #endif /* COAP_MAX_BLOCK_SZX */
29
30 /**
31 * Structure of Block options.
32 */
33 typedef struct {
34 unsigned int num; /**< block number */
35 unsigned int m:1; /**< 1 if more blocks follow, 0 otherwise */
36 unsigned int szx:3; /**< block size */
37 } coap_block_t;
38
39 /**
40 * Returns the value of the least significant byte of a Block option @p opt.
41 * For zero-length options (i.e. num == m == szx == 0), COAP_OPT_BLOCK_LAST
42 * returns @c NULL.
43 */
44 #define COAP_OPT_BLOCK_LAST(opt) \
45 (COAP_OPT_LENGTH(opt) ? (COAP_OPT_VALUE(opt) + (COAP_OPT_LENGTH(opt)-1)) : 0)
46
47 /** Returns the value of the More-bit of a Block option @p opt. */
48 #define COAP_OPT_BLOCK_MORE(opt) \
49 (COAP_OPT_LENGTH(opt) ? (*COAP_OPT_BLOCK_LAST(opt) & 0x08) : 0)
50
51 /** Returns the value of the SZX-field of a Block option @p opt. */
52 #define COAP_OPT_BLOCK_SZX(opt) \
53 (COAP_OPT_LENGTH(opt) ? (*COAP_OPT_BLOCK_LAST(opt) & 0x07) : 0)
54
55 /**
56 * Returns the value of field @c num in the given block option @p block_opt.
57 */
58 unsigned int coap_opt_block_num(const coap_opt_t *block_opt);
59
60 /**
61 * Checks if more than @p num blocks are required to deliver @p data_len
62 * bytes of data for a block size of 1 << (@p szx + 4).
63 */
64 static inline int
coap_more_blocks(size_t data_len,unsigned int num,unsigned short szx)65 coap_more_blocks(size_t data_len, unsigned int num, unsigned short szx) {
66 return ((num+1) << (szx + 4)) < data_len;
67 }
68
69 /** Sets the More-bit in @p block_opt */
70 static inline void
coap_opt_block_set_m(coap_opt_t * block_opt,int m)71 coap_opt_block_set_m(coap_opt_t *block_opt, int m) {
72 if (m)
73 *(COAP_OPT_VALUE(block_opt) + (COAP_OPT_LENGTH(block_opt) - 1)) |= 0x08;
74 else
75 *(COAP_OPT_VALUE(block_opt) + (COAP_OPT_LENGTH(block_opt) - 1)) &= ~0x08;
76 }
77
78 /**
79 * Initializes @p block from @p pdu. @p type must be either COAP_OPTION_BLOCK1
80 * or COAP_OPTION_BLOCK2. When option @p type was found in @p pdu, @p block is
81 * initialized with values from this option and the function returns the value
82 * @c 1. Otherwise, @c 0 is returned.
83 *
84 * @param pdu The pdu to search for option @p type.
85 * @param type The option to search for (must be COAP_OPTION_BLOCK1 or
86 * COAP_OPTION_BLOCK2).
87 * @param block The block structure to initilize.
88 *
89 * @return @c 1 on success, @c 0 otherwise.
90 */
91 int coap_get_block(coap_pdu_t *pdu, unsigned short type, coap_block_t *block);
92
93 /**
94 * Writes a block option of type @p type to message @p pdu. If the requested
95 * block size is too large to fit in @p pdu, it is reduced accordingly. An
96 * exception is made for the final block when less space is required. The actual
97 * length of the resource is specified in @p data_length.
98 *
99 * This function may change *block to reflect the values written to @p pdu. As
100 * the function takes into consideration the remaining space @p pdu, no more
101 * options should be added after coap_write_block_opt() has returned.
102 *
103 * @param block The block structure to use. On return, this object is
104 * updated according to the values that have been written to
105 * @p pdu.
106 * @param type COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2.
107 * @param pdu The message where the block option should be written.
108 * @param data_length The length of the actual data that will be added the @p
109 * pdu by calling coap_add_block().
110 *
111 * @return @c 1 on success, or a negative value on error.
112 */
113 int coap_write_block_opt(coap_block_t *block,
114 unsigned short type,
115 coap_pdu_t *pdu,
116 size_t data_length);
117
118 /**
119 * Adds the @p block_num block of size 1 << (@p block_szx + 4) from source @p
120 * data to @p pdu.
121 *
122 * @param pdu The message to add the block.
123 * @param len The length of @p data.
124 * @param data The source data to fill the block with.
125 * @param block_num The actual block number.
126 * @param block_szx Encoded size of block @p block_number.
127 *
128 * @return @c 1 on success, @c 0 otherwise.
129 */
130 int coap_add_block(coap_pdu_t *pdu,
131 unsigned int len,
132 const unsigned char *data,
133 unsigned int block_num,
134 unsigned char block_szx);
135 /**@}*/
136
137 #endif /* _COAP_BLOCK_H_ */
138
