1 /*
2 * block.h -- block transfer
3 *
4 * Copyright (C) 2010-2012,2014-2015 Olaf Bergmann <bergmann@tzi.org>
5 *
6 * SPDX-License-Identifier: BSD-2-Clause
7 *
8 * This file is part of the CoAP library libcoap. Please see README for terms
9 * of use.
10 */
11
12 #ifndef COAP_BLOCK_H_
13 #define COAP_BLOCK_H_
14
15 #include "encode.h"
16 #include "option.h"
17 #include "pdu.h"
18
19 /**
20 * @defgroup block Block Transfer
21 * API functions for handling PDUs using CoAP BLOCK options
22 * @{
23 */
24
25 #ifndef COAP_MAX_BLOCK_SZX
26 /**
27 * The largest value for the SZX component in a Block option.
28 */
29 #define COAP_MAX_BLOCK_SZX 6
30 #endif /* COAP_MAX_BLOCK_SZX */
31
32 /**
33 * Structure of Block options.
34 */
35 typedef struct {
36 unsigned int num; /**< block number */
37 unsigned int m:1; /**< 1 if more blocks follow, 0 otherwise */
38 unsigned int szx:3; /**< block size */
39 } coap_block_t;
40
41 #define COAP_BLOCK_USE_LIBCOAP 0x01 /* Use libcoap to do block requests */
42 #define COAP_BLOCK_SINGLE_BODY 0x02 /* Deliver the data as a single body */
43
44 /**
45 * Returns the value of the least significant byte of a Block option @p opt.
46 * For zero-length options (i.e. num == m == szx == 0), COAP_OPT_BLOCK_LAST
47 * returns @c NULL.
48 */
49 #define COAP_OPT_BLOCK_LAST(opt) \
50 (coap_opt_length(opt) ? (coap_opt_value(opt) + (coap_opt_length(opt)-1)) : 0)
51
52 /** Returns the value of the More-bit of a Block option @p opt. */
53 #define COAP_OPT_BLOCK_MORE(opt) \
54 (coap_opt_length(opt) ? (*COAP_OPT_BLOCK_LAST(opt) & 0x08) : 0)
55
56 /** Returns the value of the SZX-field of a Block option @p opt. */
57 #define COAP_OPT_BLOCK_SZX(opt) \
58 (coap_opt_length(opt) ? (*COAP_OPT_BLOCK_LAST(opt) & 0x07) : 0)
59
60 /**
61 * Returns the value of field @c num in the given block option @p block_opt.
62 */
63 unsigned int coap_opt_block_num(const coap_opt_t *block_opt);
64
65 /**
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).
68 */
69 COAP_STATIC_INLINE int
coap_more_blocks(size_t data_len,unsigned int num,uint16_t szx)70 coap_more_blocks(size_t data_len, unsigned int num, uint16_t szx) {
71 return ((num+1) << (szx + 4)) < data_len;
72 }
73
74 #if 0
75 /** Sets the More-bit in @p block_opt */
76 COAP_STATIC_INLINE void
77 coap_opt_block_set_m(coap_opt_t *block_opt, int m) {
78 if (m)
79 *(coap_opt_value(block_opt) + (coap_opt_length(block_opt) - 1)) |= 0x08;
80 else
81 *(coap_opt_value(block_opt) + (coap_opt_length(block_opt) - 1)) &= ~0x08;
82 }
83 #endif
84
85 /**
86 * Initializes @p block from @p pdu. @p number must be either COAP_OPTION_BLOCK1
87 * or COAP_OPTION_BLOCK2. When option @p number was found in @p pdu, @p block is
88 * initialized with values from this option and the function returns the value
89 * @c 1. Otherwise, @c 0 is returned.
90 *
91 * @param pdu The pdu to search for option @p number.
92 * @param number The option number to search for (must be COAP_OPTION_BLOCK1 or
93 * COAP_OPTION_BLOCK2).
94 * @param block The block structure to initilize.
95 *
96 * @return @c 1 on success, @c 0 otherwise.
97 */
98 int coap_get_block(const coap_pdu_t *pdu, coap_option_num_t number,
99 coap_block_t *block);
100
101 /**
102 * Writes a block option of type @p number to message @p pdu. If the requested
103 * block size is too large to fit in @p pdu, it is reduced accordingly. An
104 * exception is made for the final block when less space is required. The actual
105 * length of the resource is specified in @p data_length.
106 *
107 * This function may change *block to reflect the values written to @p pdu. As
108 * the function takes into consideration the remaining space @p pdu, no more
109 * options should be added after coap_write_block_opt() has returned.
110 *
111 * @param block The block structure to use. On return, this object is
112 * updated according to the values that have been written to
113 * @p pdu.
114 * @param number COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2.
115 * @param pdu The message where the block option should be written.
116 * @param data_length The length of the actual data that will be added the @p
117 * pdu by calling coap_add_block().
118 *
119 * @return @c 1 on success, or a negative value on error.
120 */
121 int coap_write_block_opt(coap_block_t *block,
122 coap_option_num_t number,
123 coap_pdu_t *pdu,
124 size_t data_length);
125
126 /**
127 * Adds the @p block_num block of size 1 << (@p block_szx + 4) from source @p
128 * data to @p pdu.
129 *
130 * @param pdu The message to add the block.
131 * @param len The length of @p data.
132 * @param data The source data to fill the block with.
133 * @param block_num The actual block number.
134 * @param block_szx Encoded size of block @p block_number.
135 *
136 * @return @c 1 on success, @c 0 otherwise.
137 */
138 int coap_add_block(coap_pdu_t *pdu,
139 size_t len,
140 const uint8_t *data,
141 unsigned int block_num,
142 unsigned char block_szx);
143
144 /**
145 * Re-assemble payloads into a body
146 *
147 * @param body_data The pointer to the data for the body holding the
148 * representation so far or NULL if the first time.
149 * @param length The length of @p data.
150 * @param data The payload data to update the body with.
151 * @param offset The offset of the @p data into the body.
152 * @param total The estimated total size of the body.
153 *
154 * @return The current representation of the body or @c NULL if error.
155 * If NULL, @p body_data will have been de-allocated.
156 */
157 coap_binary_t *
158 coap_block_build_body(coap_binary_t *body_data, size_t length,
159 const uint8_t *data, size_t offset, size_t total);
160
161 /**
162 * Adds the appropriate part of @p data to the @p response pdu. If blocks are
163 * required, then the appropriate block will be added to the PDU and sent.
164 * Adds a ETAG option that is the hash of the entire data if the data is to be
165 * split into blocks
166 * Used by a request handler.
167 *
168 * Note: The application will get called for every packet of a large body to
169 * process. Consider using coap_add_data_response_large() instead.
170 *
171 * @param request The requesting pdu.
172 * @param response The response pdu.
173 * @param media_type The format of the data.
174 * @param maxage The maxmimum life of the data. If @c -1, then there
175 * is no maxage.
176 * @param length The total length of the data.
177 * @param data The entire data block to transmit.
178 *
179 */
180 void
181 coap_add_data_blocked_response(const coap_pdu_t *request,
182 coap_pdu_t *response,
183 uint16_t media_type,
184 int maxage,
185 size_t length,
186 const uint8_t* data);
187
188 /**
189 * Callback handler for de-allocating the data based on @p app_ptr provided to
190 * coap_add_data_large_*() functions following transmission of the supplied
191 * data.
192 *
193 * @param session The session that this data is associated with
194 * @param app_ptr The application provided pointer provided to the
195 * coap_add_data_large_* functions.
196 */
197 typedef void (*coap_release_large_data_t)(coap_session_t *session,
198 void *app_ptr);
199
200 /**
201 * Associates given data with the @p pdu that is passed as second parameter.
202 *
203 * If all the data can be transmitted in a single PDU, this is functionally
204 * the same as coap_add_data() except @p release_func (if not NULL) will get
205 * invoked after data transmission.
206 *
207 * Used for a client request.
208 *
209 * If the data spans multiple PDUs, then the data will get transmitted using
210 * BLOCK1 option with the addition of the SIZE1 option.
211 * The underlying library will handle the transmission of the individual blocks.
212 * Once the body of data has been transmitted (or a failure occurred), then
213 * @p release_func (if not NULL) will get called so the application can
214 * de-allocate the @p data based on @p app_data. It is the responsibility of
215 * the application not to change the contents of @p data until the data
216 * transfer has completed.
217 *
218 * There is no need for the application to include the BLOCK1 option in the
219 * @p pdu.
220 *
221 * coap_add_data_large_request() (or the alternative coap_add_data_large_*()
222 * functions) must be called only once per PDU and must be the last PDU update
223 * before the PDU is transmitted. The (potentially) initial data will get
224 * transmitted when coap_send() is invoked.
225 *
226 * Note: COAP_BLOCK_USE_LIBCOAP must be set by coap_context_set_block_mode()
227 * for libcoap to work correctly when using this function.
228 *
229 * @param session The session to associate the data with.
230 * @param pdu The PDU to associate the data with.
231 * @param length The length of data to transmit.
232 * @param data The data to transmit.
233 * @param release_func The function to call to de-allocate @p data or @c NULL
234 * if the function is not required.
235 * @param app_ptr A Pointer that the application can provide for when
236 * release_func() is called.
237 *
238 * @return @c 1 if addition is successful, else @c 0.
239 */
240 int coap_add_data_large_request(coap_session_t *session,
241 coap_pdu_t *pdu,
242 size_t length,
243 const uint8_t *data,
244 coap_release_large_data_t release_func,
245 void *app_ptr);
246
247 /**
248 * Associates given data with the @p response pdu that is passed as fourth
249 * parameter.
250 *
251 * If all the data can be transmitted in a single PDU, this is functionally
252 * the same as coap_add_data() except @p release_func (if not NULL) will get
253 * invoked after data transmission. The MEDIA_TYPE, MAXAGE and ETAG options may
254 * be added in as appropriate.
255 *
256 * Used by a server request handler to create the response.
257 *
258 * If the data spans multiple PDUs, then the data will get transmitted using
259 * BLOCK2 (response) option with the addition of the SIZE2 and ETAG
260 * options. The underlying library will handle the transmission of the
261 * individual blocks. Once the body of data has been transmitted (or a
262 * failure occurred), then @p release_func (if not NULL) will get called so the
263 * application can de-allocate the @p data based on @p app_data. It is the
264 * responsibility of the application not to change the contents of @p data
265 * until the data transfer has completed.
266 *
267 * There is no need for the application to include the BLOCK2 option in the
268 * @p pdu.
269 *
270 * coap_add_data_large_response() (or the alternative coap_add_data_large*()
271 * functions) must be called only once per PDU and must be the last PDU update
272 * before returning from the request handler function.
273 *
274 * Note: COAP_BLOCK_USE_LIBCOAP must be set by coap_context_set_block_mode()
275 * for libcoap to work correctly when using this function.
276 *
277 * @param resource The resource the data is associated with.
278 * @param session The coap session.
279 * @param request The requesting pdu.
280 * @param response The response pdu.
281 * @param query The query taken from the (original) requesting pdu.
282 * @param media_type The format of the data.
283 * @param maxage The maxmimum life of the data. If @c -1, then there
284 * is no maxage.
285 * @param etag ETag to use if not 0.
286 * @param length The total length of the data.
287 * @param data The entire data block to transmit.
288 * @param release_func The function to call to de-allocate @p data or NULL if
289 * the function is not required.
290 * @param app_ptr A Pointer that the application can provide for when
291 * release_func() is called.
292 *
293 * @return @c 1 if addition is successful, else @c 0.
294 */
295 int
296 coap_add_data_large_response(coap_resource_t *resource,
297 coap_session_t *session,
298 const coap_pdu_t *request,
299 coap_pdu_t *response,
300 const coap_string_t *query,
301 uint16_t media_type,
302 int maxage,
303 uint64_t etag,
304 size_t length,
305 const uint8_t *data,
306 coap_release_large_data_t release_func,
307 void *app_ptr);
308
309 /**
310 * Set the context level CoAP block handling bits for handling RFC7959.
311 * These bits flow down to a session when a session is created and if the peer
312 * does not support something, an appropriate bit may get disabled in the
313 * session block_mode.
314 * The session block_mode then flows down into coap_crcv_t or coap_srcv_t where
315 * again an appropriate bit may get disabled.
316 *
317 * Note: This function must be called before the session is set up.
318 *
319 * Note: COAP_BLOCK_USE_LIBCOAP must be set if libcoap is to do all the
320 * block tracking and requesting, otherwise the application will have to do
321 * all of this work (the default if coap_context_set_block_mode() is not
322 * called).
323 *
324 * @param context The coap_context_t object.
325 * @param block_mode Zero or more COAP_BLOCK_ or'd options
326 */
327 void coap_context_set_block_mode(coap_context_t *context,
328 uint8_t block_mode);
329
330 /**
331 * Cancel an observe that is being tracked by the client large receive logic.
332 * (coap_context_set_block_mode() has to be called)
333 * This will trigger the sending of an observe cancel pdu to the server.
334 *
335 * @param session The session that is being used for the observe.
336 * @param token The original token used to initiate the observation.
337 * @param message_type The COAP_MESSAGE_ type (NON or CON) to send the observe
338 * cancel pdu as.
339 *
340 * @return @c 1 if observe cancel transmission initiation is successful,
341 * else @c 0.
342 */
343 int coap_cancel_observe(coap_session_t *session, coap_binary_t *token,
344 coap_pdu_type_t message_type);
345
346 /**@}*/
347
348 #endif /* COAP_BLOCK_H_ */
349