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