libcoap 4.3.2rc2

coap_block.h
Go to the documentation of this file.
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
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
32#ifndef COAP_MAX_BLOCK_SZX
36#define COAP_MAX_BLOCK_SZX 6
37#endif /* COAP_MAX_BLOCK_SZX */
38
42 typedef struct {
43 unsigned int num;
44 unsigned int m:1;
45 unsigned int szx:3;
46} coap_block_t;
47
51 typedef struct {
52 unsigned int num;
53 unsigned int m:1;
54 unsigned int szx:3;
55 unsigned int aszx:3;
56 unsigned int defined:1;
57 unsigned int bert:1;
58 uint32_t chunk_size;
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
72 int coap_q_block_is_supported(void);
73
79#define COAP_OPT_BLOCK_LAST(opt) \
80 (coap_opt_length(opt) ? (coap_opt_value(opt) + (coap_opt_length(opt)-1)) : 0)
81
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
88#define COAP_OPT_BLOCK_MORE(opt) \
89 (coap_opt_length(opt) ? (COAP_OPT_BLOCK_END_BYTE(opt) & 0x08) : 0)
90
92#define COAP_OPT_BLOCK_SZX(opt) \
93 (coap_opt_length(opt) ? (COAP_OPT_BLOCK_END_BYTE(opt) & 0x07) : 0)
94
98 unsigned int coap_opt_block_num(const coap_opt_t *block_opt);
99
104 COAP_STATIC_INLINE int
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
111 COAP_STATIC_INLINE void
112coap_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
133 int coap_get_block(const coap_pdu_t *pdu, coap_option_num_t number,
134 coap_block_t *block);
135
136
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
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);
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
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
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
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
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
289 typedef void (*coap_release_large_data_t)(coap_session_t *session,
290 void *app_ptr);
291
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
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
422 void coap_context_set_block_mode(coap_context_t *context,
423 uint8_t block_mode);
424
438 int coap_cancel_observe(coap_session_t *session, coap_binary_t *token,
439 coap_pdu_type_t message_type);
440
443#endif /* COAP_BLOCK_H_ */
coap_encode.h
Encoding and decoding of CoAP data types.
coap_option.h
Helpers for handling options in CoAP PDUs.
coap_option_num_t
uint16_t coap_option_num_t
Definition: coap_option.h:20
coap_opt_t
uint8_t coap_opt_t
Use byte-oriented access methods here because sliding a complex struct coap_opt_t over the data buffe...
Definition: coap_option.h:26
coap_pdu.h
Pre-defined constants that reflect defaults for CoAP.
coap_context_set_block_mode
void coap_context_set_block_mode(coap_context_t *context, uint8_t block_mode)
Set the context level CoAP block handling bits for handling RFC7959.
Definition: coap_block.c:379
coap_add_data_large_request
int coap_add_data_large_request(coap_session_t *session, coap_pdu_t *pdu, size_t length, const uint8_t *data, coap_release_large_data_t release_func, void *app_ptr)
Associates given data with the pdu that is passed as second parameter.
coap_add_block_b_data
int coap_add_block_b_data(coap_pdu_t *pdu, size_t len, const uint8_t *data, coap_block_b_t *block)
Adds the appropriate payload data of the body to the pdu.
Definition: coap_block.c:248
coap_write_block_b_opt
int coap_write_block_b_opt(coap_session_t *session, coap_block_b_t *block, coap_option_num_t number, coap_pdu_t *pdu, size_t data_length)
Writes a block option of type number to message pdu.
Definition: coap_block.c:203
coap_add_block
int coap_add_block(coap_pdu_t *pdu, size_t len, const uint8_t *data, unsigned int block_num, unsigned char block_szx)
Adds the block_num block of size 1 << (block_szx + 4) from source data to pdu.
Definition: coap_block.c:234
coap_release_large_data_t
void(* coap_release_large_data_t)(coap_session_t *session, void *app_ptr)
Callback handler for de-allocating the data based on app_ptr provided to coap_add_data_large_*() func...
Definition: coap_block.h:289
coap_add_data_blocked_response
void coap_add_data_blocked_response(const coap_pdu_t *request, coap_pdu_t *response, uint16_t media_type, int maxage, size_t length, const uint8_t *data)
Adds the appropriate part of data to the response pdu.
Definition: coap_block.c:273
coap_get_block_b
int coap_get_block_b(const coap_session_t *session, const coap_pdu_t *pdu, coap_option_num_t number, coap_block_b_t *block)
Initializes block from pdu.
Definition: coap_block.c:58
coap_more_blocks
COAP_STATIC_INLINE int coap_more_blocks(size_t data_len, unsigned int num, uint16_t szx)
Checks if more than num blocks are required to deliver data_len bytes of data for a block size of 1 <...
Definition: coap_block.h:105
coap_opt_block_num
unsigned int coap_opt_block_num(const coap_opt_t *block_opt)
Returns the value of field num in the given block option block_opt.
Definition: coap_block.c:39
coap_get_block
int coap_get_block(const coap_pdu_t *pdu, coap_option_num_t number, coap_block_t *block)
Initializes block from pdu.
Definition: coap_block.c:111
coap_q_block_is_supported
int coap_q_block_is_supported(void)
Returns 1 if libcoap was built with option Q-BlockX support, 0 otherwise.
Definition: coap_block.c:33
coap_write_block_opt
int coap_write_block_opt(coap_block_t *block, coap_option_num_t number, coap_pdu_t *pdu, size_t data_length)
Writes a block option of type number to message pdu.
Definition: coap_block.c:170
coap_cancel_observe
int coap_cancel_observe(coap_session_t *session, coap_binary_t *token, coap_pdu_type_t message_type)
Cancel an observe that is being tracked by the client large receive logic.
coap_add_data_large_response
int coap_add_data_large_response(coap_resource_t *resource, coap_session_t *session, const coap_pdu_t *request, coap_pdu_t *response, const coap_string_t *query, uint16_t media_type, int maxage, uint64_t etag, size_t length, const uint8_t *data, coap_release_large_data_t release_func, void *app_ptr)
Associates given data with the response pdu that is passed as fourth parameter.
coap_block_build_body
coap_binary_t * coap_block_build_body(coap_binary_t *body_data, size_t length, const uint8_t *data, size_t offset, size_t total)
Re-assemble payloads into a body.
Definition: coap_block.c:3282
coap_opt_length
uint32_t coap_opt_length(const coap_opt_t *opt)
Returns the length of the given option.
Definition: coap_option.c:212
coap_opt_value
const uint8_t * coap_opt_value(const coap_opt_t *opt)
Returns a pointer to the value of the given option.
Definition: coap_option.c:249
coap_pdu_type_t
coap_pdu_type_t
CoAP PDU message type definitions.
Definition: coap_pdu.h:64
COAP_STATIC_INLINE
#define COAP_STATIC_INLINE
Definition: libcoap.h:53
coap_binary_t
CoAP binary data definition.
Definition: coap_str.h:56
coap_block_b_t
Structure of Block options with BERT support.
Definition: coap_block.h:51
coap_block_b_t::num
unsigned int num
block number
Definition: coap_block.h:52
coap_block_b_t::chunk_size
uint32_t chunk_size
‍1024 if BERT
Definition: coap_block.h:58
coap_block_b_t::bert
unsigned int bert
Operating as BERT.
Definition: coap_block.h:57
coap_block_b_t::aszx
unsigned int aszx
block size (0-7 including BERT
Definition: coap_block.h:55
coap_block_b_t::defined
unsigned int defined
Set if block found.
Definition: coap_block.h:56
coap_block_b_t::m
unsigned int m
1 if more blocks follow, 0 otherwise
Definition: coap_block.h:53
coap_block_b_t::szx
unsigned int szx
block size (0-6)
Definition: coap_block.h:54
coap_block_t
Structure of Block options.
Definition: coap_block.h:42
coap_block_t::num
unsigned int num
block number
Definition: coap_block.h:43
coap_block_t::szx
unsigned int szx
block size
Definition: coap_block.h:45
coap_block_t::m
unsigned int m
1 if more blocks follow, 0 otherwise
Definition: coap_block.h:44
coap_context_t
The CoAP stack's global state is stored in a coap_context_t object.
Definition: coap_net_internal.h:49
coap_pdu_t
structure for CoAP PDUs
Definition: coap_pdu_internal.h:119
coap_resource_t
Abstraction of resource that can be attached to coap_context_t.
Definition: coap_resource_internal.h:53
coap_session_t
Abstraction of virtual session that can be attached to coap_context_t (client) or coap_endpoint_t (se...
Definition: coap_session_internal.h:68
coap_string_t
CoAP string data definition.
Definition: coap_str.h:38