1 /*
2 * This file has been copied from the zcbor library.
3 * Commit zcbor 0.7.0
4 */
5
6 /*
7 * Copyright (c) 2020 Nordic Semiconductor ASA
8 *
9 * SPDX-License-Identifier: Apache-2.0
10 */
11
12 #ifndef ZCBOR_DECODE_H__
13 #define ZCBOR_DECODE_H__
14
15 #include <stdint.h>
16 #include <stdbool.h>
17 #include <stddef.h>
18 #include "zcbor_common.h"
19
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23
24 /** The zcbor_decode library provides functions for decoding CBOR data elements.
25 *
26 * See The README for an introduction to CBOR, including the meaning of pint,
27 * nint, bstr etc.
28 */
29
30
31 /** The following applies to all single-value decode functions that don't have docs.
32 *
33 * @param[inout] state The current state of the decoding.
34 * @param[out] result Where to place the decoded value.
35 *
36 * @retval true If the value was decoded correctly.
37 * @retval false If the value has the wrong type, the payload overflowed, the
38 * element count was exhausted, or the value was larger than can
39 * fit in the result variable.
40 */
41
42 /** Decode and consume a pint/nint. */
43 bool zcbor_int32_decode(zcbor_state_t *state, int32_t *result);
44 bool zcbor_int64_decode(zcbor_state_t *state, int64_t *result);
45 bool zcbor_uint32_decode(zcbor_state_t *state, uint32_t *result);
46 bool zcbor_uint64_decode(zcbor_state_t *state, uint64_t *result);
47 bool zcbor_size_decode(zcbor_state_t *state, size_t *result);
48 bool zcbor_int_decode(zcbor_state_t *state, void *result_int, size_t int_size);
49
50 /** The following applies to all _expect() functions that don't have docs.
51 *
52 * @param[inout] state The current state of the decoding.
53 * @param[in] result The expected value.
54 *
55 * @retval true If the result was decoded correctly and has the expected value.
56 * @retval false If the decoding failed or the result doesn't have the
57 * expected value.
58 */
59 /** Consume and expect a pint/nint with a certain value. */
60 bool zcbor_int32_expect(zcbor_state_t *state, int32_t result);
61 bool zcbor_int64_expect(zcbor_state_t *state, int64_t result);
62 bool zcbor_uint32_expect(zcbor_state_t *state, uint32_t result);
63 bool zcbor_uint64_expect(zcbor_state_t *state, uint64_t result);
64 bool zcbor_size_expect(zcbor_state_t *state, size_t result);
65
66 /** Consume and expect a pint/nint with a certain value, within a union.
67 *
68 * Calls @ref zcbor_union_elem_code then @ref zcbor_[u]int[32|64]_expect.
69 */
70 bool zcbor_int32_expect_union(zcbor_state_t *state, int32_t result);
71 bool zcbor_int64_expect_union(zcbor_state_t *state, int64_t result);
72 bool zcbor_uint32_expect_union(zcbor_state_t *state, uint32_t result);
73 bool zcbor_uint64_expect_union(zcbor_state_t *state, uint64_t result);
74
75 /** Decode and consume a bstr/tstr */
76 bool zcbor_bstr_decode(zcbor_state_t *state, struct zcbor_string *result);
77 bool zcbor_bstr_expect(zcbor_state_t *state, struct zcbor_string *result);
78 bool zcbor_tstr_decode(zcbor_state_t *state, struct zcbor_string *result);
79 bool zcbor_tstr_expect(zcbor_state_t *state, struct zcbor_string *result);
80
81 /** Consume and expect a bstr/tstr with the value of the provided string literal.
82 *
83 * @param[inout] state The current state of the encoding.
84 * @param[in] string The value to expect. A pointer to the string.
85 * @param[in] len The length of the string pointed to by @p string.
86 */
zcbor_bstr_expect_ptr(zcbor_state_t * state,char const * ptr,size_t len)87 static inline bool zcbor_bstr_expect_ptr(zcbor_state_t *state, char const *ptr, size_t len)
88 {
89 struct zcbor_string zs = { .value = (const uint8_t *)ptr, .len = len };
90
91 return zcbor_bstr_expect(state, &zs);
92 }
zcbor_tstr_expect_ptr(zcbor_state_t * state,char const * ptr,size_t len)93 static inline bool zcbor_tstr_expect_ptr(zcbor_state_t *state, char const *ptr, size_t len)
94 {
95 struct zcbor_string zs = { .value = (const uint8_t *)ptr, .len = len };
96
97 return zcbor_tstr_expect(state, &zs);
98 }
99
100
101 /** Consume and expect a bstr/tstr with the value of the provided string literal.
102 *
103 * @param[inout] state The current state of the encoding.
104 * @param[in] string The value to expect. A string literal, e.g. "Foo", so
105 * that sizeof(string) - 1 is the length of the string.
106 */
107 #define zcbor_bstr_expect_lit(state, string) \
108 zcbor_bstr_expect_ptr(state, string, sizeof(string) - 1)
109 #define zcbor_tstr_expect_lit(state, string) \
110 zcbor_tstr_expect_ptr(state, string, sizeof(string) - 1)
111
112 /** Consume and expect a bstr/tstr with the value of the provided null-terminated string.
113 *
114 * @param[inout] state The current state of the encoding.
115 * @param[in] string The value to expect. Must be a null-terminated string,
116 * so that strlen can be used.
117 */
118 #define zcbor_bstr_expect_term(state, string) \
119 zcbor_bstr_expect_ptr(state, string, strlen(string))
120 #define zcbor_tstr_expect_term(state, string) \
121 zcbor_tstr_expect_ptr(state, string, strlen(string))
122
123 /** Consume and expect a bstr/tstr with the value of the provided char array literal.
124 *
125 * @param[inout] state The current state of the encoding.
126 * @param[in] string The value to expect. An array literal, e.g. {'F', 'o', 'o'},
127 * so that sizeof(string) is the length of the string.
128 */
129 #define zcbor_bstr_expect_arr(state, string) \
130 zcbor_bstr_expect_ptr(state, string, (sizeof(string)))
131 #define zcbor_tstr_expect_arr(state, string) \
132 zcbor_tstr_expect_ptr(state, string, (sizeof(string)))
133
134 /** Decode and consume a tag. */
135 bool zcbor_tag_decode(zcbor_state_t *state, uint32_t *result);
136 bool zcbor_tag_expect(zcbor_state_t *state, uint32_t result);
137
138 /** Decode and consume a boolean primitive value. */
139 bool zcbor_bool_decode(zcbor_state_t *state, bool *result);
140 bool zcbor_bool_expect(zcbor_state_t *state, bool result);
141
142 /** Decode and consume a float */
143 bool zcbor_float32_decode(zcbor_state_t *state, float *result);
144 bool zcbor_float32_expect(zcbor_state_t *state, float result);
145 bool zcbor_float64_decode(zcbor_state_t *state, double *result);
146 bool zcbor_float64_expect(zcbor_state_t *state, double result);
147 bool zcbor_float_decode(zcbor_state_t *state, double *result);
148 bool zcbor_float_expect(zcbor_state_t *state, double result);
149
150 /** Consume and expect a "nil"/"undefined" primitive value.
151 *
152 * @param[inout] state The current state of the encoding.
153 * @param[in] unused Unused parameter to maintain signature parity with
154 * @ref zcbor_decoder_t.
155 */
156 bool zcbor_nil_expect(zcbor_state_t *state, void *unused);
157 bool zcbor_undefined_expect(zcbor_state_t *state, void *unused);
158
159 /** Skip a single element, regardless of type and value.
160 *
161 * @param[inout] state The current state of the encoding.
162 * @param[in] unused Unused parameter to maintain signature parity with
163 * @ref zcbor_decoder_t.
164 */
165 bool zcbor_any_skip(zcbor_state_t *state, void *unused);
166
167 /** Decode and consume a bstr header.
168 *
169 * The rest of the string can be decoded as CBOR.
170 * A state backup is created to keep track of the element count.
171 * Call @ref zcbor_bstr_end_decode when done decoding the contents of the bstr.
172 *
173 * @retval true Header decoded correctly
174 * @retval false Header decoded incorrectly, or backup failed.
175 */
176 bool zcbor_bstr_start_decode(zcbor_state_t *state, struct zcbor_string *result);
177
178 /** Finalize decoding a CBOR-encoded bstr.
179 *
180 * Restore element count from backup.
181 */
182 bool zcbor_bstr_end_decode(zcbor_state_t *state);
183
184 /** Start decoding a bstr/tstr, even if the payload contains only part of it.
185 *
186 * This must be followed by a call to @ref zcbor_update_state, which can be
187 * followed by a call to @ref zcbor_next_fragment. Do not call this function
188 * again on subsequent fragments of the same string.
189 *
190 * This consumes the remaining payload as long as it belongs to the string.
191 */
192 bool zcbor_bstr_decode_fragment(zcbor_state_t *state, struct zcbor_string_fragment *result);
193 bool zcbor_tstr_decode_fragment(zcbor_state_t *state, struct zcbor_string_fragment *result);
194
195 /** Extract the next fragment of a string.
196 *
197 * Use this function to extract all but the first fragment.
198 */
199 void zcbor_next_fragment(zcbor_state_t *state,
200 struct zcbor_string_fragment *prev_fragment,
201 struct zcbor_string_fragment *result);
202
203 /** Decode and consume a bstr header, assuming the payload does not contain the whole bstr.
204 *
205 * The rest of the string can be decoded as CBOR.
206 * A state backup is created to keep track of the element count.
207 * Call @ref zcbor_update_state followed by @ref zcbor_bstr_next_fragment when
208 * the current payload has been exhausted.
209 * Call @ref zcbor_bstr_end_decode when done decoding the contents of the bstr.
210 */
211 bool zcbor_bstr_start_decode_fragment(zcbor_state_t *state,
212 struct zcbor_string_fragment *result);
213
214 /** Start decoding the next fragment of a string.
215 *
216 * Use this function to extract all but the first fragment of a CBOR-encoded
217 * bstr.
218 */
219 void zcbor_bstr_next_fragment(zcbor_state_t *state,
220 struct zcbor_string_fragment *prev_fragment,
221 struct zcbor_string_fragment *result);
222
223 /** Can be used on any fragment to tell if it is the final fragment of the string. */
224 bool zcbor_is_last_fragment(const struct zcbor_string_fragment *fragment);
225
226 /** Decode and consume a list/map header.
227 *
228 * The contents of the list can be decoded via subsequent function calls.
229 * A state backup is created to keep track of the element count.
230 * Call @ref zcbor_list_end_decode / @ref zcbor_map_end_decode when done
231 * decoding the contents of the list/map
232 *
233 * @retval true Header decoded correctly
234 * @retval false Header decoded incorrectly, or backup failed.
235 */
236 bool zcbor_list_start_decode(zcbor_state_t *state);
237 bool zcbor_map_start_decode(zcbor_state_t *state);
238
239 /** Finalize decoding a list/map
240 *
241 * Check that the list/map had the correct number of elements, and restore the
242 * previous element count from the backup.
243 *
244 * Use @ref zcbor_list_map_end_force_decode to forcibly consume the backup if
245 * something has gone wrong.
246 *
247 * @retval true Everything ok.
248 * @retval false Element count not correct.
249 */
250 bool zcbor_list_end_decode(zcbor_state_t *state);
251 bool zcbor_map_end_decode(zcbor_state_t *state);
252 bool zcbor_list_map_end_force_decode(zcbor_state_t *state);
253
254 /** Decode 0 or more elements with the same type and constraints.
255 *
256 * The decoded values will appear consecutively in the @p result array.
257 *
258 * The following is an example of decoding a list containing 3 INTS followed by
259 * 0 to 2 bstrs:
260 *
261 * @code{c}
262 * uint32_t ints[3];
263 * struct zcbor_string bstrs[2];
264 * uint32_t num_decode;
265 * bool res;
266 *
267 * res = zcbor_list_start_decode(state);
268 * res = res && zcbor_multi_decode(3, 3, &num_decode, zcbor_uint32_decode,
269 * state, ints, sizeof(ints[0]));
270 * res = res && zcbor_multi_decode(0, 2, &num_decode, zcbor_bstr_decode,
271 * state, bstrs, sizeof(bstrs[0]));
272 * res = res && zcbor_list_end_decode(state);
273 * // check res
274 * @endcode
275 *
276 * The @ref zcbor_decoder_t type is designed to be compatible with all single-
277 * value decoder functions in this library, e.g. @ref zcbor_uint32_decode,
278 * @ref zcbor_tstr_expect, @ref zcbor_nil_expect, etc. For _expect() functions,
279 * @p result will be used as a value instead of an array/pointer, so
280 * @p result_len will determine how much the value changes for each call.
281 * To decode the same value multiple times, use a @p result_len of 0.
282 * This function can also be used with custom decoder functions, such as those
283 * generated by the zcbor.py script, which for example decodes larger chunks of
284 * the data at once.
285 *
286 * @param[in] min_decode The minimum acceptable number of elements.
287 * @param[in] max_decode The maximum acceptable number of elements.
288 * @param[out] num_decode The actual number of elements decoded.
289 * @param[in] decoder The decoder function to call under the hood. This
290 * function will be called with the provided arguments
291 * repeatedly until the function fails (returns false)
292 * or until it has been called @p max_decode times.
293 * The result pointer is moved @p result_len bytes for
294 * each call to @p decoder, i.e. @p result refers to
295 * an array of result variables.
296 * @param[out] result Where to place the decoded values. Must be an array
297 * of at least @p max_decode elements.
298 * @param[in] result_len The length of each result variable. Must be the
299 * length of the individual elements of @p result.
300 *
301 * @retval true If at least @p min_decode variables were correctly decoded.
302 * @retval false If @p decoder failed before having decoded @p min_decode
303 * values.
304 */
305 bool zcbor_multi_decode(uint_fast32_t min_decode, uint_fast32_t max_decode, uint_fast32_t *num_decode,
306 zcbor_decoder_t decoder, zcbor_state_t *state, void *result,
307 uint_fast32_t result_len);
308
309 /** Attempt to decode a value that might not be present in the data.
310 *
311 * Works like @ref zcbor_multi_decode, with @p present as num_decode.
312 * Will return true, even if the data is not present.
313 *
314 * @param[out] present Whether or not the data was present and successfully decoded.
315 * @param[in] decoder The decoder to attempt.
316 * @param[out] result The result, if present.
317 *
318 * @return Should always return true.
319 */
320 bool zcbor_present_decode(uint_fast32_t *present,
321 zcbor_decoder_t decoder,
322 zcbor_state_t *state,
323 void *result);
324
325 /** See @ref zcbor_new_state() */
326 void zcbor_new_decode_state(zcbor_state_t *state_array, uint_fast32_t n_states,
327 const uint8_t *payload, size_t payload_len, uint_fast32_t elem_count);
328
329 /** Convenience macro for declaring and initializing a state with backups.
330 *
331 * This gives you a state variable named @p name. The variable functions like
332 * a pointer.
333 *
334 * @param[in] name The name of the new state variable.
335 * @param[in] num_backups The number of backup slots to keep in the state.
336 * @param[in] payload The payload to work on.
337 * @param[in] payload_size The size (in bytes) of @p payload.
338 * @param[in] elem_count The starting elem_count (typically 1).
339 */
340 #define ZCBOR_STATE_D(name, num_backups, payload, payload_size, elem_count) \
341 zcbor_state_t name[((num_backups) + 2)]; \
342 do { \
343 zcbor_new_decode_state(name, ZCBOR_ARRAY_SIZE(name), payload, payload_size, elem_count); \
344 } while(0)
345
346 #ifdef __cplusplus
347 }
348 #endif
349
350 #endif /* ZCBOR_DECODE_H__ */
351
