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