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 struct coap_resource_t;
18 struct coap_session_t;
19
20 /**
21 * @defgroup block Block Transfer
22 * API functions for handling PDUs using CoAP BLOCK options
23 * @{
24 */
25
26 #ifndef COAP_MAX_BLOCK_SZX
27 /**
28 * The largest value for the SZX component in a Block option.
29 */
30 #define COAP_MAX_BLOCK_SZX 6
31 #endif /* COAP_MAX_BLOCK_SZX */
32
33 /**
34 * Structure of Block options.
35 */
36 typedef struct {
37 unsigned int num; /**< block number */
38 unsigned int m:1; /**< 1 if more blocks follow, 0 otherwise */
39 unsigned int szx:3; /**< block size */
40 } coap_block_t;
41
42 /**
43 * Returns the value of the least significant byte of a Block option @p opt.
44 * For zero-length options (i.e. num == m == szx == 0), COAP_OPT_BLOCK_LAST
45 * returns @c NULL.
46 */
47 #define COAP_OPT_BLOCK_LAST(opt) \
48 (coap_opt_length(opt) ? (coap_opt_value(opt) + (coap_opt_length(opt)-1)) : 0)
49
50 /** Returns the value of the More-bit of a Block option @p opt. */
51 #define COAP_OPT_BLOCK_MORE(opt) \
52 (coap_opt_length(opt) ? (*COAP_OPT_BLOCK_LAST(opt) & 0x08) : 0)
53
54 /** Returns the value of the SZX-field of a Block option @p opt. */
55 #define COAP_OPT_BLOCK_SZX(opt) \
56 (coap_opt_length(opt) ? (*COAP_OPT_BLOCK_LAST(opt) & 0x07) : 0)
57
58 /**
59 * Returns the value of field @c num in the given block option @p block_opt.
60 */
61 unsigned int coap_opt_block_num(const coap_opt_t *block_opt);
62
63 /**
64 * Checks if more than @p num blocks are required to deliver @p data_len
65 * bytes of data for a block size of 1 << (@p szx + 4).
66 */
67 COAP_STATIC_INLINE int
coap_more_blocks(size_t data_len,unsigned int num,uint16_t szx)68 coap_more_blocks(size_t data_len, unsigned int num, uint16_t szx) {
69 return ((num+1) << (szx + 4)) < data_len;
70 }
71
72 #if 0
73 /** Sets the More-bit in @p block_opt */
74 COAP_STATIC_INLINE void
75 coap_opt_block_set_m(coap_opt_t *block_opt, int m) {
76 if (m)
77 *(coap_opt_value(block_opt) + (coap_opt_length(block_opt) - 1)) |= 0x08;
78 else
79 *(coap_opt_value(block_opt) + (coap_opt_length(block_opt) - 1)) &= ~0x08;
80 }
81 #endif
82
83 /**
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 is
86 * initialized with values from this option and the function returns the value
87 * @c 1. Otherwise, @c 0 is returned.
88 *
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
91 * COAP_OPTION_BLOCK2).
92 * @param block The block structure to initilize.
93 *
94 * @return @c 1 on success, @c 0 otherwise.
95 */
96 int coap_get_block(coap_pdu_t *pdu, uint16_t type, coap_block_t *block);
97
98 /**
99 * Writes a block option of type @p type to message @p pdu. If the requested
100 * block size is too large to fit in @p pdu, it is reduced accordingly. An
101 * exception is made for the final block when less space is required. The actual
102 * length of the resource is specified in @p data_length.
103 *
104 * This function may change *block to reflect the values written to @p pdu. As
105 * the function takes into consideration the remaining space @p pdu, no more
106 * options should be added after coap_write_block_opt() has returned.
107 *
108 * @param block The block structure to use. On return, this object is
109 * updated according to the values that have been written to
110 * @p pdu.
111 * @param type COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2.
112 * @param pdu The message where the block option should be written.
113 * @param data_length The length of the actual data that will be added the @p
114 * pdu by calling coap_add_block().
115 *
116 * @return @c 1 on success, or a negative value on error.
117 */
118 int coap_write_block_opt(coap_block_t *block,
119 uint16_t type,
120 coap_pdu_t *pdu,
121 size_t data_length);
122
123 /**
124 * Adds the @p block_num block of size 1 << (@p block_szx + 4) from source @p
125 * data to @p pdu.
126 *
127 * @param pdu The message to add the block.
128 * @param len The length of @p data.
129 * @param data The source data to fill the block with.
130 * @param block_num The actual block number.
131 * @param block_szx Encoded size of block @p block_number.
132 *
133 * @return @c 1 on success, @c 0 otherwise.
134 */
135 int coap_add_block(coap_pdu_t *pdu,
136 unsigned int len,
137 const uint8_t *data,
138 unsigned int block_num,
139 unsigned char block_szx);
140
141 /**
142 * Adds the appropriate part of @p data to the @p response pdu. If blocks are
143 * required, then the appropriate block will be added to the PDU and sent.
144 * Adds a ETAG option that is the hash of the entire data if the data is to be
145 * split into blocks
146 * Used by a GET request handler.
147 *
148 * @param resource The resource the data is associated with.
149 * @param session The coap session.
150 * @param request The requesting pdu.
151 * @param response The response pdu.
152 * @param token The token taken from the (original) requesting pdu.
153 * @param media_type The format of the data.
154 * @param maxage The maxmimum life of the data. If @c -1, then there
155 * is no maxage.
156 * @param length The total length of the data.
157 * @param data The entire data block to transmit.
158 *
159 */
160 void
161 coap_add_data_blocked_response(struct coap_resource_t *resource,
162 struct coap_session_t *session,
163 coap_pdu_t *request,
164 coap_pdu_t *response,
165 const coap_binary_t *token,
166 uint16_t media_type,
167 int maxage,
168 size_t length,
169 const uint8_t* data);
170
171 /**@}*/
172
173 #endif /* COAP_BLOCK_H_ */
174