1/*
2 * Copyright (c) 2015-2021 Nicholas Fraser and the MPack authors
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a copy of
5 * this software and associated documentation files (the "Software"), to deal in
6 * the Software without restriction, including without limitation the rights to
7 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
8 * the Software, and to permit persons to whom the Software is furnished to do so,
9 * subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice shall be included in all
12 * copies or substantial portions of the Software.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
16 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
17 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
18 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
19 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
20 */
21
22/**
23 * @file
24 *
25 * Declares the MPack static Expect API.
26 */
27
28#ifndef MPACK_EXPECT_H
29#define MPACK_EXPECT_H 1
30
31#include "mpack-reader.h"
32
33MPACK_SILENCE_WARNINGS_BEGIN
34MPACK_EXTERN_C_BEGIN
35
36#if MPACK_EXPECT
37
38#if !MPACK_READER
39#error "MPACK_EXPECT requires MPACK_READER."
40#endif
41
42/**
43 * @defgroup expect Expect API
44 *
45 * The MPack Expect API allows you to easily read MessagePack data when you
46 * expect it to follow a predefined schema.
47 *
48 * @note If you are not writing code for an embedded device (or otherwise do
49 * not need maximum performance with minimal memory usage), you should not use
50 * this. You probably want to use the @link node Node API@endlink instead.
51 *
52 * See @ref docs/expect.md for examples.
53 *
54 * The main purpose of the Expect API is convenience, so the API is lax. It
55 * automatically converts between similar types where there is no loss of
56 * precision.
57 *
58 * When using any of the expect functions, if the type or value of what was
59 * read does not match what is expected, @ref mpack_error_type is raised.
60 *
61 * @{
62 */
63
64/**
65 * @name Basic Number Functions
66 * @{
67 */
68
69/**
70 * Reads an 8-bit unsigned integer.
71 *
72 * The underlying type may be an integer type of any size and signedness,
73 * as long as the value can be represented in an 8-bit unsigned int.
74 *
75 * Returns zero if an error occurs.
76 */
77uint8_t mpack_expect_u8(mpack_reader_t* reader);
78
79/**
80 * Reads a 16-bit unsigned integer.
81 *
82 * The underlying type may be an integer type of any size and signedness,
83 * as long as the value can be represented in a 16-bit unsigned int.
84 *
85 * Returns zero if an error occurs.
86 */
87uint16_t mpack_expect_u16(mpack_reader_t* reader);
88
89/**
90 * Reads a 32-bit unsigned integer.
91 *
92 * The underlying type may be an integer type of any size and signedness,
93 * as long as the value can be represented in a 32-bit unsigned int.
94 *
95 * Returns zero if an error occurs.
96 */
97uint32_t mpack_expect_u32(mpack_reader_t* reader);
98
99/**
100 * Reads a 64-bit unsigned integer.
101 *
102 * The underlying type may be an integer type of any size and signedness,
103 * as long as the value can be represented in a 64-bit unsigned int.
104 *
105 * Returns zero if an error occurs.
106 */
107uint64_t mpack_expect_u64(mpack_reader_t* reader);
108
109/**
110 * Reads an 8-bit signed integer.
111 *
112 * The underlying type may be an integer type of any size and signedness,
113 * as long as the value can be represented in an 8-bit signed int.
114 *
115 * Returns zero if an error occurs.
116 */
117int8_t mpack_expect_i8(mpack_reader_t* reader);
118
119/**
120 * Reads a 16-bit signed integer.
121 *
122 * The underlying type may be an integer type of any size and signedness,
123 * as long as the value can be represented in a 16-bit signed int.
124 *
125 * Returns zero if an error occurs.
126 */
127int16_t mpack_expect_i16(mpack_reader_t* reader);
128
129/**
130 * Reads a 32-bit signed integer.
131 *
132 * The underlying type may be an integer type of any size and signedness,
133 * as long as the value can be represented in a 32-bit signed int.
134 *
135 * Returns zero if an error occurs.
136 */
137int32_t mpack_expect_i32(mpack_reader_t* reader);
138
139/**
140 * Reads a 64-bit signed integer.
141 *
142 * The underlying type may be an integer type of any size and signedness,
143 * as long as the value can be represented in a 64-bit signed int.
144 *
145 * Returns zero if an error occurs.
146 */
147int64_t mpack_expect_i64(mpack_reader_t* reader);
148
149#if MPACK_FLOAT
150/**
151 * Reads a number, returning the value as a float. The underlying value can be an
152 * integer, float or double; the value is converted to a float.
153 *
154 * @note Reading a double or a large integer with this function can incur a
155 * loss of precision.
156 *
157 * @throws mpack_error_type if the underlying value is not a float, double or integer.
158 */
159float mpack_expect_float(mpack_reader_t* reader);
160#endif
161
162#if MPACK_DOUBLE
163/**
164 * Reads a number, returning the value as a double. The underlying value can be an
165 * integer, float or double; the value is converted to a double.
166 *
167 * @note Reading a very large integer with this function can incur a
168 * loss of precision.
169 *
170 * @throws mpack_error_type if the underlying value is not a float, double or integer.
171 */
172double mpack_expect_double(mpack_reader_t* reader);
173#endif
174
175#if MPACK_FLOAT
176/**
177 * Reads a float. The underlying value must be a float, not a double or an integer.
178 * This ensures no loss of precision can occur.
179 *
180 * @throws mpack_error_type if the underlying value is not a float.
181 */
182float mpack_expect_float_strict(mpack_reader_t* reader);
183#endif
184
185#if MPACK_DOUBLE
186/**
187 * Reads a double. The underlying value must be a float or double, not an integer.
188 * This ensures no loss of precision can occur.
189 *
190 * @throws mpack_error_type if the underlying value is not a float or double.
191 */
192double mpack_expect_double_strict(mpack_reader_t* reader);
193#endif
194
195#if !MPACK_FLOAT
196/**
197 * Reads a float as a raw uint32_t. The underlying value must be a float, not a
198 * double or an integer.
199 *
200 * @throws mpack_error_type if the underlying value is not a float.
201 */
202uint32_t mpack_expect_raw_float(mpack_reader_t* reader);
203#endif
204
205#if !MPACK_DOUBLE
206/**
207 * Reads a double as a raw uint64_t. The underlying value must be a double, not a
208 * float or an integer.
209 *
210 * @throws mpack_error_type if the underlying value is not a double.
211 */
212uint64_t mpack_expect_raw_double(mpack_reader_t* reader);
213#endif
214
215/**
216 * @}
217 */
218
219/**
220 * @name Ranged Number Functions
221 * @{
222 */
223
224/**
225 * Reads an 8-bit unsigned integer, ensuring that it falls within the given range.
226 *
227 * The underlying type may be an integer type of any size and signedness,
228 * as long as the value can be represented in an 8-bit unsigned int.
229 *
230 * Returns min_value if an error occurs.
231 */
232uint8_t mpack_expect_u8_range(mpack_reader_t* reader, uint8_t min_value, uint8_t max_value);
233
234/**
235 * Reads a 16-bit unsigned integer, ensuring that it falls within the given range.
236 *
237 * The underlying type may be an integer type of any size and signedness,
238 * as long as the value can be represented in a 16-bit unsigned int.
239 *
240 * Returns min_value if an error occurs.
241 */
242uint16_t mpack_expect_u16_range(mpack_reader_t* reader, uint16_t min_value, uint16_t max_value);
243
244/**
245 * Reads a 32-bit unsigned integer, ensuring that it falls within the given range.
246 *
247 * The underlying type may be an integer type of any size and signedness,
248 * as long as the value can be represented in a 32-bit unsigned int.
249 *
250 * Returns min_value if an error occurs.
251 */
252uint32_t mpack_expect_u32_range(mpack_reader_t* reader, uint32_t min_value, uint32_t max_value);
253
254/**
255 * Reads a 64-bit unsigned integer, ensuring that it falls within the given range.
256 *
257 * The underlying type may be an integer type of any size and signedness,
258 * as long as the value can be represented in a 64-bit unsigned int.
259 *
260 * Returns min_value if an error occurs.
261 */
262uint64_t mpack_expect_u64_range(mpack_reader_t* reader, uint64_t min_value, uint64_t max_value);
263
264/**
265 * Reads an unsigned integer, ensuring that it falls within the given range.
266 *
267 * The underlying type may be an integer type of any size and signedness,
268 * as long as the value can be represented in an unsigned int.
269 *
270 * Returns min_value if an error occurs.
271 */
272MPACK_INLINE unsigned int mpack_expect_uint_range(mpack_reader_t* reader, unsigned int min_value, unsigned int max_value) {
273 // This should be true at compile-time, so this just wraps the 32-bit
274 // function. We fallback to 64-bit if for some reason sizeof(int) isn't 4.
275 if (sizeof(unsigned int) == 4)
276 return (unsigned int)mpack_expect_u32_range(reader, (uint32_t)min_value, (uint32_t)max_value);
277 return (unsigned int)mpack_expect_u64_range(reader, min_value, max_value);
278}
279
280/**
281 * Reads an 8-bit unsigned integer, ensuring that it is at most @a max_value.
282 *
283 * The underlying type may be an integer type of any size and signedness,
284 * as long as the value can be represented in an 8-bit unsigned int.
285 *
286 * Returns 0 if an error occurs.
287 */
288MPACK_INLINE uint8_t mpack_expect_u8_max(mpack_reader_t* reader, uint8_t max_value) {
289 return mpack_expect_u8_range(reader, 0, max_value);
290}
291
292/**
293 * Reads a 16-bit unsigned integer, ensuring that it is at most @a max_value.
294 *
295 * The underlying type may be an integer type of any size and signedness,
296 * as long as the value can be represented in a 16-bit unsigned int.
297 *
298 * Returns 0 if an error occurs.
299 */
300MPACK_INLINE uint16_t mpack_expect_u16_max(mpack_reader_t* reader, uint16_t max_value) {
301 return mpack_expect_u16_range(reader, 0, max_value);
302}
303
304/**
305 * Reads a 32-bit unsigned integer, ensuring that it is at most @a max_value.
306 *
307 * The underlying type may be an integer type of any size and signedness,
308 * as long as the value can be represented in a 32-bit unsigned int.
309 *
310 * Returns 0 if an error occurs.
311 */
312MPACK_INLINE uint32_t mpack_expect_u32_max(mpack_reader_t* reader, uint32_t max_value) {
313 return mpack_expect_u32_range(reader, 0, max_value);
314}
315
316/**
317 * Reads a 64-bit unsigned integer, ensuring that it is at most @a max_value.
318 *
319 * The underlying type may be an integer type of any size and signedness,
320 * as long as the value can be represented in a 64-bit unsigned int.
321 *
322 * Returns 0 if an error occurs.
323 */
324MPACK_INLINE uint64_t mpack_expect_u64_max(mpack_reader_t* reader, uint64_t max_value) {
325 return mpack_expect_u64_range(reader, 0, max_value);
326}
327
328/**
329 * Reads an unsigned integer, ensuring that it is at most @a max_value.
330 *
331 * The underlying type may be an integer type of any size and signedness,
332 * as long as the value can be represented in an unsigned int.
333 *
334 * Returns 0 if an error occurs.
335 */
336MPACK_INLINE unsigned int mpack_expect_uint_max(mpack_reader_t* reader, unsigned int max_value) {
337 return mpack_expect_uint_range(reader, 0, max_value);
338}
339
340/**
341 * Reads an 8-bit signed integer, ensuring that it falls within the given range.
342 *
343 * The underlying type may be an integer type of any size and signedness,
344 * as long as the value can be represented in an 8-bit signed int.
345 *
346 * Returns min_value if an error occurs.
347 */
348int8_t mpack_expect_i8_range(mpack_reader_t* reader, int8_t min_value, int8_t max_value);
349
350/**
351 * Reads a 16-bit signed integer, ensuring that it falls within the given range.
352 *
353 * The underlying type may be an integer type of any size and signedness,
354 * as long as the value can be represented in a 16-bit signed int.
355 *
356 * Returns min_value if an error occurs.
357 */
358int16_t mpack_expect_i16_range(mpack_reader_t* reader, int16_t min_value, int16_t max_value);
359
360/**
361 * Reads a 32-bit signed integer, ensuring that it falls within the given range.
362 *
363 * The underlying type may be an integer type of any size and signedness,
364 * as long as the value can be represented in a 32-bit signed int.
365 *
366 * Returns min_value if an error occurs.
367 */
368int32_t mpack_expect_i32_range(mpack_reader_t* reader, int32_t min_value, int32_t max_value);
369
370/**
371 * Reads a 64-bit signed integer, ensuring that it falls within the given range.
372 *
373 * The underlying type may be an integer type of any size and signedness,
374 * as long as the value can be represented in a 64-bit signed int.
375 *
376 * Returns min_value if an error occurs.
377 */
378int64_t mpack_expect_i64_range(mpack_reader_t* reader, int64_t min_value, int64_t max_value);
379
380/**
381 * Reads a signed integer, ensuring that it falls within the given range.
382 *
383 * The underlying type may be an integer type of any size and signedness,
384 * as long as the value can be represented in a signed int.
385 *
386 * Returns min_value if an error occurs.
387 */
388MPACK_INLINE int mpack_expect_int_range(mpack_reader_t* reader, int min_value, int max_value) {
389 // This should be true at compile-time, so this just wraps the 32-bit
390 // function. We fallback to 64-bit if for some reason sizeof(int) isn't 4.
391 if (sizeof(int) == 4)
392 return (int)mpack_expect_i32_range(reader, (int32_t)min_value, (int32_t)max_value);
393 return (int)mpack_expect_i64_range(reader, min_value, max_value);
394}
395
396/**
397 * Reads an 8-bit signed integer, ensuring that it is at least zero and at
398 * most @a max_value.
399 *
400 * The underlying type may be an integer type of any size and signedness,
401 * as long as the value can be represented in an 8-bit signed int.
402 *
403 * Returns 0 if an error occurs.
404 */
405MPACK_INLINE int8_t mpack_expect_i8_max(mpack_reader_t* reader, int8_t max_value) {
406 return mpack_expect_i8_range(reader, 0, max_value);
407}
408
409/**
410 * Reads a 16-bit signed integer, ensuring that it is at least zero and at
411 * most @a max_value.
412 *
413 * The underlying type may be an integer type of any size and signedness,
414 * as long as the value can be represented in a 16-bit signed int.
415 *
416 * Returns 0 if an error occurs.
417 */
418MPACK_INLINE int16_t mpack_expect_i16_max(mpack_reader_t* reader, int16_t max_value) {
419 return mpack_expect_i16_range(reader, 0, max_value);
420}
421
422/**
423 * Reads a 32-bit signed integer, ensuring that it is at least zero and at
424 * most @a max_value.
425 *
426 * The underlying type may be an integer type of any size and signedness,
427 * as long as the value can be represented in a 32-bit signed int.
428 *
429 * Returns 0 if an error occurs.
430 */
431MPACK_INLINE int32_t mpack_expect_i32_max(mpack_reader_t* reader, int32_t max_value) {
432 return mpack_expect_i32_range(reader, 0, max_value);
433}
434
435/**
436 * Reads a 64-bit signed integer, ensuring that it is at least zero and at
437 * most @a max_value.
438 *
439 * The underlying type may be an integer type of any size and signedness,
440 * as long as the value can be represented in a 64-bit signed int.
441 *
442 * Returns 0 if an error occurs.
443 */
444MPACK_INLINE int64_t mpack_expect_i64_max(mpack_reader_t* reader, int64_t max_value) {
445 return mpack_expect_i64_range(reader, 0, max_value);
446}
447
448/**
449 * Reads an int, ensuring that it is at least zero and at most @a max_value.
450 *
451 * The underlying type may be an integer type of any size and signedness,
452 * as long as the value can be represented in a signed int.
453 *
454 * Returns 0 if an error occurs.
455 */
456MPACK_INLINE int mpack_expect_int_max(mpack_reader_t* reader, int max_value) {
457 return mpack_expect_int_range(reader, 0, max_value);
458}
459
460#if MPACK_FLOAT
461/**
462 * Reads a number, ensuring that it falls within the given range and returning
463 * the value as a float. The underlying value can be an integer, float or
464 * double; the value is converted to a float.
465 *
466 * @note Reading a double or a large integer with this function can incur a
467 * loss of precision.
468 *
469 * @throws mpack_error_type if the underlying value is not a float, double or integer.
470 */
471float mpack_expect_float_range(mpack_reader_t* reader, float min_value, float max_value);
472#endif
473
474#if MPACK_DOUBLE
475/**
476 * Reads a number, ensuring that it falls within the given range and returning
477 * the value as a double. The underlying value can be an integer, float or
478 * double; the value is converted to a double.
479 *
480 * @note Reading a very large integer with this function can incur a
481 * loss of precision.
482 *
483 * @throws mpack_error_type if the underlying value is not a float, double or integer.
484 */
485double mpack_expect_double_range(mpack_reader_t* reader, double min_value, double max_value);
486#endif
487
488/**
489 * @}
490 */
491
492
493
494// These are additional Basic Number functions that wrap inline range functions.
495
496/**
497 * @name Basic Number Functions
498 * @{
499 */
500
501/**
502 * Reads an unsigned int.
503 *
504 * The underlying type may be an integer type of any size and signedness,
505 * as long as the value can be represented in an unsigned int.
506 *
507 * Returns zero if an error occurs.
508 */
509MPACK_INLINE unsigned int mpack_expect_uint(mpack_reader_t* reader) {
510
511 // This should be true at compile-time, so this just wraps the 32-bit function.
512 if (sizeof(unsigned int) == 4)
513 return (unsigned int)mpack_expect_u32(reader);
514
515 // Otherwise we wrap the max function to ensure it fits.
516 return (unsigned int)mpack_expect_u64_max(reader, MPACK_UINT_MAX);
517
518}
519
520/**
521 * Reads a signed int.
522 *
523 * The underlying type may be an integer type of any size and signedness,
524 * as long as the value can be represented in a signed int.
525 *
526 * Returns zero if an error occurs.
527 */
528MPACK_INLINE int mpack_expect_int(mpack_reader_t* reader) {
529
530 // This should be true at compile-time, so this just wraps the 32-bit function.
531 if (sizeof(int) == 4)
532 return (int)mpack_expect_i32(reader);
533
534 // Otherwise we wrap the range function to ensure it fits.
535 return (int)mpack_expect_i64_range(reader, MPACK_INT_MIN, MPACK_INT_MAX);
536
537}
538
539/**
540 * @}
541 */
542
543
544
545/**
546 * @name Matching Number Functions
547 * @{
548 */
549
550/**
551 * Reads an unsigned integer, ensuring that it exactly matches the given value.
552 *
553 * mpack_error_type is raised if the value is not representable as an unsigned
554 * integer or if it does not exactly match the given value.
555 */
556void mpack_expect_uint_match(mpack_reader_t* reader, uint64_t value);
557
558/**
559 * Reads a signed integer, ensuring that it exactly matches the given value.
560 *
561 * mpack_error_type is raised if the value is not representable as a signed
562 * integer or if it does not exactly match the given value.
563 */
564void mpack_expect_int_match(mpack_reader_t* reader, int64_t value);
565
566/**
567 * @}
568 */
569
570/**
571 * @name Other Basic Types
572 * @{
573 */
574
575/**
576 * Reads a nil, raising @ref mpack_error_type if the value is not nil.
577 */
578void mpack_expect_nil(mpack_reader_t* reader);
579
580/**
581 * Reads a boolean.
582 *
583 * @note Integers will raise mpack_error_type; the value must be strictly a boolean.
584 */
585bool mpack_expect_bool(mpack_reader_t* reader);
586
587/**
588 * Reads a boolean, raising @ref mpack_error_type if its value is not @c true.
589 */
590void mpack_expect_true(mpack_reader_t* reader);
591
592/**
593 * Reads a boolean, raising @ref mpack_error_type if its value is not @c false.
594 */
595void mpack_expect_false(mpack_reader_t* reader);
596
597/**
598 * @}
599 */
600
601/**
602 * @name Extension Functions
603 * @{
604 */
605
606#if MPACK_EXTENSIONS
607/**
608 * Reads a timestamp.
609 *
610 * @note This requires @ref MPACK_EXTENSIONS.
611 */
612mpack_timestamp_t mpack_expect_timestamp(mpack_reader_t* reader);
613
614/**
615 * Reads a timestamp in seconds, truncating the nanoseconds (if any).
616 *
617 * @note This requires @ref MPACK_EXTENSIONS.
618 */
619int64_t mpack_expect_timestamp_truncate(mpack_reader_t* reader);
620#endif
621
622/**
623 * @}
624 */
625
626/**
627 * @name Compound Types
628 * @{
629 */
630
631/**
632 * Reads the start of a map, returning its element count.
633 *
634 * A number of values follow equal to twice the element count of the map,
635 * alternating between keys and values. @ref mpack_done_map() must be called
636 * once all elements have been read.
637 *
638 * @note Maps in JSON are unordered, so it is recommended not to expect
639 * a specific ordering for your map values in case your data is converted
640 * to/from JSON.
641 *
642 * @warning This call is dangerous! It does not have a size limit, and it
643 * does not have any way of checking whether there is enough data in the
644 * message (since the data could be coming from a stream.) When looping
645 * through the map's contents, you must check for errors on each iteration
646 * of the loop. Otherwise an attacker could craft a message declaring a map
647 * of a billion elements which would throw your parsing code into an
648 * infinite loop! You should strongly consider using mpack_expect_map_max()
649 * with a safe maximum size instead.
650 *
651 * @throws mpack_error_type if the value is not a map.
652 */
653uint32_t mpack_expect_map(mpack_reader_t* reader);
654
655/**
656 * Reads the start of a map with a number of elements in the given range, returning
657 * its element count.
658 *
659 * A number of values follow equal to twice the element count of the map,
660 * alternating between keys and values. @ref mpack_done_map() must be called
661 * once all elements have been read.
662 *
663 * @note Maps in JSON are unordered, so it is recommended not to expect
664 * a specific ordering for your map values in case your data is converted
665 * to/from JSON.
666 *
667 * min_count is returned if an error occurs.
668 *
669 * @throws mpack_error_type if the value is not a map or if its size does
670 * not fall within the given range.
671 */
672uint32_t mpack_expect_map_range(mpack_reader_t* reader, uint32_t min_count, uint32_t max_count);
673
674/**
675 * Reads the start of a map with a number of elements at most @a max_count,
676 * returning its element count.
677 *
678 * A number of values follow equal to twice the element count of the map,
679 * alternating between keys and values. @ref mpack_done_map() must be called
680 * once all elements have been read.
681 *
682 * @note Maps in JSON are unordered, so it is recommended not to expect
683 * a specific ordering for your map values in case your data is converted
684 * to/from JSON.
685 *
686 * Zero is returned if an error occurs.
687 *
688 * @throws mpack_error_type if the value is not a map or if its size is
689 * greater than max_count.
690 */
691MPACK_INLINE uint32_t mpack_expect_map_max(mpack_reader_t* reader, uint32_t max_count) {
692 return mpack_expect_map_range(reader, 0, max_count);
693}
694
695/**
696 * Reads the start of a map of the exact size given.
697 *
698 * A number of values follow equal to twice the element count of the map,
699 * alternating between keys and values. @ref mpack_done_map() must be called
700 * once all elements have been read.
701 *
702 * @note Maps in JSON are unordered, so it is recommended not to expect
703 * a specific ordering for your map values in case your data is converted
704 * to/from JSON.
705 *
706 * @throws mpack_error_type if the value is not a map or if its size
707 * does not match the given count.
708 */
709void mpack_expect_map_match(mpack_reader_t* reader, uint32_t count);
710
711/**
712 * Reads a nil node or the start of a map, returning whether a map was
713 * read and placing its number of key/value pairs in count.
714 *
715 * If a map was read, a number of values follow equal to twice the element count
716 * of the map, alternating between keys and values. @ref mpack_done_map() should
717 * also be called once all elements have been read (only if a map was read.)
718 *
719 * @note Maps in JSON are unordered, so it is recommended not to expect
720 * a specific ordering for your map values in case your data is converted
721 * to/from JSON.
722 *
723 * @warning This call is dangerous! It does not have a size limit, and it
724 * does not have any way of checking whether there is enough data in the
725 * message (since the data could be coming from a stream.) When looping
726 * through the map's contents, you must check for errors on each iteration
727 * of the loop. Otherwise an attacker could craft a message declaring a map
728 * of a billion elements which would throw your parsing code into an
729 * infinite loop! You should strongly consider using mpack_expect_map_max_or_nil()
730 * with a safe maximum size instead.
731 *
732 * @returns @c true if a map was read successfully; @c false if nil was read
733 * or an error occurred.
734 * @throws mpack_error_type if the value is not a nil or map.
735 */
736bool mpack_expect_map_or_nil(mpack_reader_t* reader, uint32_t* count);
737
738/**
739 * Reads a nil node or the start of a map with a number of elements at most
740 * max_count, returning whether a map was read and placing its number of
741 * key/value pairs in count.
742 *
743 * If a map was read, a number of values follow equal to twice the element count
744 * of the map, alternating between keys and values. @ref mpack_done_map() should
745 * anlso be called once all elements have been read (only if a map was read.)
746 *
747 * @note Maps in JSON are unordered, so it is recommended not to expect
748 * a specific ordering for your map values in case your data is converted
749 * to/from JSON. Consider using mpack_expect_key_cstr() or mpack_expect_key_uint()
750 * to switch on the key; see @ref docs/expect.md for examples.
751 *
752 * @returns @c true if a map was read successfully; @c false if nil was read
753 * or an error occurred.
754 * @throws mpack_error_type if the value is not a nil or map.
755 */
756bool mpack_expect_map_max_or_nil(mpack_reader_t* reader, uint32_t max_count, uint32_t* count);
757
758/**
759 * Reads the start of an array, returning its element count.
760 *
761 * A number of values follow equal to the element count of the array.
762 * @ref mpack_done_array() must be called once all elements have been read.
763 *
764 * @warning This call is dangerous! It does not have a size limit, and it
765 * does not have any way of checking whether there is enough data in the
766 * message (since the data could be coming from a stream.) When looping
767 * through the array's contents, you must check for errors on each iteration
768 * of the loop. Otherwise an attacker could craft a message declaring an array
769 * of a billion elements which would throw your parsing code into an
770 * infinite loop! You should strongly consider using mpack_expect_array_max()
771 * with a safe maximum size instead.
772 */
773uint32_t mpack_expect_array(mpack_reader_t* reader);
774
775/**
776 * Reads the start of an array with a number of elements in the given range,
777 * returning its element count.
778 *
779 * A number of values follow equal to the element count of the array.
780 * @ref mpack_done_array() must be called once all elements have been read.
781 *
782 * min_count is returned if an error occurs.
783 *
784 * @throws mpack_error_type if the value is not an array or if its size does
785 * not fall within the given range.
786 */
787uint32_t mpack_expect_array_range(mpack_reader_t* reader, uint32_t min_count, uint32_t max_count);
788
789/**
790 * Reads the start of an array with a number of elements at most @a max_count,
791 * returning its element count.
792 *
793 * A number of values follow equal to the element count of the array.
794 * @ref mpack_done_array() must be called once all elements have been read.
795 *
796 * Zero is returned if an error occurs.
797 *
798 * @throws mpack_error_type if the value is not an array or if its size is
799 * greater than max_count.
800 */
801MPACK_INLINE uint32_t mpack_expect_array_max(mpack_reader_t* reader, uint32_t max_count) {
802 return mpack_expect_array_range(reader, 0, max_count);
803}
804
805/**
806 * Reads the start of an array of the exact size given.
807 *
808 * A number of values follow equal to the element count of the array.
809 * @ref mpack_done_array() must be called once all elements have been read.
810 *
811 * @throws mpack_error_type if the value is not an array or if its size does
812 * not match the given count.
813 */
814void mpack_expect_array_match(mpack_reader_t* reader, uint32_t count);
815
816/**
817 * Reads a nil node or the start of an array, returning whether an array was
818 * read and placing its number of elements in count.
819 *
820 * If an array was read, a number of values follow equal to the element count
821 * of the array. @ref mpack_done_array() should also be called once all elements
822 * have been read (only if an array was read.)
823 *
824 * @warning This call is dangerous! It does not have a size limit, and it
825 * does not have any way of checking whether there is enough data in the
826 * message (since the data could be coming from a stream.) When looping
827 * through the array's contents, you must check for errors on each iteration
828 * of the loop. Otherwise an attacker could craft a message declaring an array
829 * of a billion elements which would throw your parsing code into an
830 * infinite loop! You should strongly consider using mpack_expect_array_max_or_nil()
831 * with a safe maximum size instead.
832 *
833 * @returns @c true if an array was read successfully; @c false if nil was read
834 * or an error occurred.
835 * @throws mpack_error_type if the value is not a nil or array.
836 */
837bool mpack_expect_array_or_nil(mpack_reader_t* reader, uint32_t* count);
838
839/**
840 * Reads a nil node or the start of an array with a number of elements at most
841 * max_count, returning whether an array was read and placing its number of
842 * key/value pairs in count.
843 *
844 * If an array was read, a number of values follow equal to the element count
845 * of the array. @ref mpack_done_array() should also be called once all elements
846 * have been read (only if an array was read.)
847 *
848 * @returns @c true if an array was read successfully; @c false if nil was read
849 * or an error occurred.
850 * @throws mpack_error_type if the value is not a nil or array.
851 */
852bool mpack_expect_array_max_or_nil(mpack_reader_t* reader, uint32_t max_count, uint32_t* count);
853
854#ifdef MPACK_MALLOC
855/**
856 * @hideinitializer
857 *
858 * Reads the start of an array and allocates storage for it, placing its
859 * size in out_count. A number of objects follow equal to the element count
860 * of the array. You must call @ref mpack_done_array() when done (even
861 * if the element count is zero.)
862 *
863 * If an error occurs, NULL is returned and the reader is placed in an
864 * error state.
865 *
866 * If the count is zero, NULL is returned. This does not indicate error.
867 * You should not check the return value for NULL to check for errors; only
868 * check the reader's error state.
869 *
870 * The allocated array must be freed with MPACK_FREE() (or simply free()
871 * if MPack's allocator hasn't been customized.)
872 *
873 * @throws mpack_error_type if the value is not an array or if its size is
874 * greater than max_count.
875 */
876#define mpack_expect_array_alloc(reader, Type, max_count, out_count) \
877 ((Type*)mpack_expect_array_alloc_impl(reader, sizeof(Type), max_count, out_count, false))
878
879/**
880 * @hideinitializer
881 *
882 * Reads a nil node or the start of an array and allocates storage for it,
883 * placing its size in out_count. A number of objects follow equal to the element
884 * count of the array if a non-empty array was read.
885 *
886 * If an error occurs, NULL is returned and the reader is placed in an
887 * error state.
888 *
889 * If a nil node was read, NULL is returned. If an empty array was read,
890 * mpack_done_array() is called automatically and NULL is returned. These
891 * do not indicate error. You should not check the return value for NULL
892 * to check for errors; only check the reader's error state.
893 *
894 * The allocated array must be freed with MPACK_FREE() (or simply free()
895 * if MPack's allocator hasn't been customized.)
896 *
897 * @warning You must call @ref mpack_done_array() if and only if a non-zero
898 * element count is read. This function does not differentiate between nil
899 * and an empty array.
900 *
901 * @throws mpack_error_type if the value is not an array or if its size is
902 * greater than max_count.
903 */
904#define mpack_expect_array_or_nil_alloc(reader, Type, max_count, out_count) \
905 ((Type*)mpack_expect_array_alloc_impl(reader, sizeof(Type), max_count, out_count, true))
906#endif
907
908/**
909 * @}
910 */
911
912/** @cond */
913#ifdef MPACK_MALLOC
914void* mpack_expect_array_alloc_impl(mpack_reader_t* reader,
915 size_t element_size, uint32_t max_count, uint32_t* out_count, bool allow_nil);
916#endif
917/** @endcond */
918
919
920/**
921 * @name String Functions
922 * @{
923 */
924
925/**
926 * Reads the start of a string, returning its size in bytes.
927 *
928 * The bytes follow and must be read separately with mpack_read_bytes()
929 * or mpack_read_bytes_inplace(). mpack_done_str() must be called
930 * once all bytes have been read.
931 *
932 * NUL bytes are allowed in the string, and no encoding checks are done.
933 *
934 * mpack_error_type is raised if the value is not a string.
935 */
936uint32_t mpack_expect_str(mpack_reader_t* reader);
937
938/**
939 * Reads a string of at most the given size, writing it into the
940 * given buffer and returning its size in bytes.
941 *
942 * This does not add a null-terminator! Use mpack_expect_cstr() to
943 * add a null-terminator.
944 *
945 * NUL bytes are allowed in the string, and no encoding checks are done.
946 */
947size_t mpack_expect_str_buf(mpack_reader_t* reader, char* buf, size_t bufsize);
948
949/**
950 * Reads a string into the given buffer, ensuring it is a valid UTF-8 string
951 * and returning its size in bytes.
952 *
953 * This does not add a null-terminator! Use mpack_expect_utf8_cstr() to
954 * add a null-terminator.
955 *
956 * This does not accept any UTF-8 variant such as Modified UTF-8, CESU-8 or
957 * WTF-8. Only pure UTF-8 is allowed.
958 *
959 * NUL bytes are allowed in the string (as they are in UTF-8.)
960 *
961 * Raises mpack_error_too_big if there is not enough room for the string.
962 * Raises mpack_error_type if the value is not a string or is not a valid UTF-8 string.
963 */
964size_t mpack_expect_utf8(mpack_reader_t* reader, char* buf, size_t bufsize);
965
966/**
967 * Reads the start of a string, raising an error if its length is not
968 * at most the given number of bytes (not including any null-terminator.)
969 *
970 * The bytes follow and must be read separately with mpack_read_bytes()
971 * or mpack_read_bytes_inplace(). @ref mpack_done_str() must be called
972 * once all bytes have been read.
973 *
974 * @throws mpack_error_type If the value is not a string.
975 * @throws mpack_error_too_big If the string's length in bytes is larger than the given maximum size.
976 */
977MPACK_INLINE uint32_t mpack_expect_str_max(mpack_reader_t* reader, uint32_t maxsize) {
978 uint32_t length = mpack_expect_str(reader);
979 if (length > maxsize) {
980 mpack_reader_flag_error(reader, mpack_error_too_big);
981 return 0;
982 }
983 return length;
984}
985
986/**
987 * Reads the start of a string, raising an error if its length is not
988 * exactly the given number of bytes (not including any null-terminator.)
989 *
990 * The bytes follow and must be read separately with mpack_read_bytes()
991 * or mpack_read_bytes_inplace(). @ref mpack_done_str() must be called
992 * once all bytes have been read.
993 *
994 * mpack_error_type is raised if the value is not a string or if its
995 * length does not match.
996 */
997MPACK_INLINE void mpack_expect_str_length(mpack_reader_t* reader, uint32_t count) {
998 if (mpack_expect_str(reader) != count)
999 mpack_reader_flag_error(reader, mpack_error_type);
1000}
1001
1002/**
1003 * Reads a string, ensuring it exactly matches the given string.
1004 *
1005 * Remember that maps are unordered in JSON. Don't use this for map keys
1006 * unless the map has only a single key!
1007 */
1008void mpack_expect_str_match(mpack_reader_t* reader, const char* str, size_t length);
1009
1010/**
1011 * Reads a string into the given buffer, ensures it has no null bytes,
1012 * and adds a null-terminator at the end.
1013 *
1014 * Raises mpack_error_too_big if there is not enough room for the string and null-terminator.
1015 * Raises mpack_error_type if the value is not a string or contains a null byte.
1016 */
1017void mpack_expect_cstr(mpack_reader_t* reader, char* buf, size_t size);
1018
1019/**
1020 * Reads a string into the given buffer, ensures it is a valid UTF-8 string
1021 * without NUL characters, and adds a null-terminator at the end.
1022 *
1023 * This does not accept any UTF-8 variant such as Modified UTF-8, CESU-8 or
1024 * WTF-8. Only pure UTF-8 is allowed, but without the NUL character, since
1025 * it cannot be represented in a null-terminated string.
1026 *
1027 * Raises mpack_error_too_big if there is not enough room for the string and null-terminator.
1028 * Raises mpack_error_type if the value is not a string or is not a valid UTF-8 string.
1029 */
1030void mpack_expect_utf8_cstr(mpack_reader_t* reader, char* buf, size_t size);
1031
1032#ifdef MPACK_MALLOC
1033/**
1034 * Reads a string with the given total maximum size (including space for a
1035 * null-terminator), allocates storage for it, ensures it has no null-bytes,
1036 * and adds a null-terminator at the end. You assume ownership of the
1037 * returned pointer if reading succeeds.
1038 *
1039 * The allocated string must be freed with MPACK_FREE() (or simply free()
1040 * if MPack's allocator hasn't been customized.)
1041 *
1042 * @throws mpack_error_too_big If the string plus null-terminator is larger than the given maxsize.
1043 * @throws mpack_error_type If the value is not a string or contains a null byte.
1044 */
1045char* mpack_expect_cstr_alloc(mpack_reader_t* reader, size_t maxsize);
1046
1047/**
1048 * Reads a string with the given total maximum size (including space for a
1049 * null-terminator), allocates storage for it, ensures it is valid UTF-8
1050 * with no null-bytes, and adds a null-terminator at the end. You assume
1051 * ownership of the returned pointer if reading succeeds.
1052 *
1053 * The length in bytes of the string, not including the null-terminator,
1054 * will be written to size.
1055 *
1056 * This does not accept any UTF-8 variant such as Modified UTF-8, CESU-8 or
1057 * WTF-8. Only pure UTF-8 is allowed, but without the NUL character, since
1058 * it cannot be represented in a null-terminated string.
1059 *
1060 * The allocated string must be freed with MPACK_FREE() (or simply free()
1061 * if MPack's allocator hasn't been customized.)
1062 * if you want a null-terminator.
1063 *
1064 * @throws mpack_error_too_big If the string plus null-terminator is larger
1065 * than the given maxsize.
1066 * @throws mpack_error_type If the value is not a string or contains
1067 * invalid UTF-8 or a null byte.
1068 */
1069char* mpack_expect_utf8_cstr_alloc(mpack_reader_t* reader, size_t maxsize);
1070#endif
1071
1072/**
1073 * Reads a string, ensuring it exactly matches the given null-terminated
1074 * string.
1075 *
1076 * Remember that maps are unordered in JSON. Don't use this for map keys
1077 * unless the map has only a single key!
1078 */
1079MPACK_INLINE void mpack_expect_cstr_match(mpack_reader_t* reader, const char* cstr) {
1080 mpack_assert(cstr != NULL, "cstr pointer is NULL");
1081 mpack_expect_str_match(reader, cstr, mpack_strlen(cstr));
1082}
1083
1084/**
1085 * @}
1086 */
1087
1088/**
1089 * @name Binary Data
1090 * @{
1091 */
1092
1093/**
1094 * Reads the start of a binary blob, returning its size in bytes.
1095 *
1096 * The bytes follow and must be read separately with mpack_read_bytes()
1097 * or mpack_read_bytes_inplace(). @ref mpack_done_bin() must be called
1098 * once all bytes have been read.
1099 *
1100 * mpack_error_type is raised if the value is not a binary blob.
1101 */
1102uint32_t mpack_expect_bin(mpack_reader_t* reader);
1103
1104/**
1105 * Reads the start of a binary blob, raising an error if its length is not
1106 * at most the given number of bytes.
1107 *
1108 * The bytes follow and must be read separately with mpack_read_bytes()
1109 * or mpack_read_bytes_inplace(). @ref mpack_done_bin() must be called
1110 * once all bytes have been read.
1111 *
1112 * mpack_error_type is raised if the value is not a binary blob or if its
1113 * length does not match.
1114 */
1115MPACK_INLINE uint32_t mpack_expect_bin_max(mpack_reader_t* reader, uint32_t maxsize) {
1116 uint32_t length = mpack_expect_bin(reader);
1117 if (length > maxsize) {
1118 mpack_reader_flag_error(reader, mpack_error_type);
1119 return 0;
1120 }
1121 return length;
1122}
1123
1124/**
1125 * Reads the start of a binary blob, raising an error if its length is not
1126 * exactly the given number of bytes.
1127 *
1128 * The bytes follow and must be read separately with mpack_read_bytes()
1129 * or mpack_read_bytes_inplace(). @ref mpack_done_bin() must be called
1130 * once all bytes have been read.
1131 *
1132 * @throws mpack_error_type if the value is not a binary blob or if its size
1133 * does not match.
1134 */
1135MPACK_INLINE void mpack_expect_bin_size(mpack_reader_t* reader, uint32_t count) {
1136 if (mpack_expect_bin(reader) != count)
1137 mpack_reader_flag_error(reader, mpack_error_type);
1138}
1139
1140/**
1141 * Reads a binary blob into the given buffer, returning its size in bytes.
1142 *
1143 * For compatibility, this will accept if the underlying type is string or
1144 * binary (since in MessagePack 1.0, strings and binary data were combined
1145 * under the "raw" type which became string in 1.1.)
1146 */
1147size_t mpack_expect_bin_buf(mpack_reader_t* reader, char* buf, size_t size);
1148
1149/**
1150 * Reads a binary blob with the exact given size into the given buffer.
1151 *
1152 * For compatibility, this will accept if the underlying type is string or
1153 * binary (since in MessagePack 1.0, strings and binary data were combined
1154 * under the "raw" type which became string in 1.1.)
1155 *
1156 * @throws mpack_error_type if the value is not a binary blob or if its size
1157 * does not match.
1158 */
1159void mpack_expect_bin_size_buf(mpack_reader_t* reader, char* buf, uint32_t size);
1160
1161/**
1162 * Reads a binary blob with the given total maximum size, allocating storage for it.
1163 */
1164char* mpack_expect_bin_alloc(mpack_reader_t* reader, size_t maxsize, size_t* size);
1165
1166/**
1167 * @}
1168 */
1169
1170/**
1171 * @name Extension Functions
1172 * @{
1173 */
1174
1175#if MPACK_EXTENSIONS
1176/**
1177 * Reads the start of an extension blob, returning its size in bytes and
1178 * placing the type into @p type.
1179 *
1180 * The bytes follow and must be read separately with mpack_read_bytes()
1181 * or mpack_read_bytes_inplace(). @ref mpack_done_ext() must be called
1182 * once all bytes have been read.
1183 *
1184 * @p type will be a user-defined type in the range [0,127] or a reserved type
1185 * in the range [-128,-2].
1186 *
1187 * mpack_error_type is raised if the value is not an extension blob. The @p
1188 * type value is zero if an error occurs.
1189 *
1190 * @note This cannot be used to match a timestamp. @ref mpack_error_type will
1191 * be flagged if the value is a timestamp. Use mpack_expect_timestamp() or
1192 * mpack_expect_timestamp_truncate() instead.
1193 *
1194 * @note This requires @ref MPACK_EXTENSIONS.
1195 *
1196 * @warning Be careful when using reserved types. They may no longer be ext
1197 * types in the future, and previously valid data containing reserved types may
1198 * become invalid in the future.
1199 */
1200uint32_t mpack_expect_ext(mpack_reader_t* reader, int8_t* type);
1201
1202/**
1203 * Reads the start of an extension blob, raising an error if its length is not
1204 * at most the given number of bytes and placing the type into @p type.
1205 *
1206 * The bytes follow and must be read separately with mpack_read_bytes()
1207 * or mpack_read_bytes_inplace(). @ref mpack_done_ext() must be called
1208 * once all bytes have been read.
1209 *
1210 * mpack_error_type is raised if the value is not an extension blob or if its
1211 * length does not match. The @p type value is zero if an error is raised.
1212 *
1213 * @p type will be a user-defined type in the range [0,127] or a reserved type
1214 * in the range [-128,-2].
1215 *
1216 * @note This cannot be used to match a timestamp. @ref mpack_error_type will
1217 * be flagged if the value is a timestamp. Use mpack_expect_timestamp() or
1218 * mpack_expect_timestamp_truncate() instead.
1219 *
1220 * @note This requires @ref MPACK_EXTENSIONS.
1221 *
1222 * @warning Be careful when using reserved types. They may no longer be ext
1223 * types in the future, and previously valid data containing reserved types may
1224 * become invalid in the future.
1225 *
1226 * @see mpack_expect_ext()
1227 */
1228MPACK_INLINE uint32_t mpack_expect_ext_max(mpack_reader_t* reader, int8_t* type, uint32_t maxsize) {
1229 uint32_t length = mpack_expect_ext(reader, type);
1230 if (length > maxsize) {
1231 mpack_reader_flag_error(reader, mpack_error_type);
1232 return 0;
1233 }
1234 return length;
1235}
1236
1237/**
1238 * Reads the start of an extension blob, raising an error if its length is not
1239 * exactly the given number of bytes and placing the type into @p type.
1240 *
1241 * The bytes follow and must be read separately with mpack_read_bytes()
1242 * or mpack_read_bytes_inplace(). @ref mpack_done_ext() must be called
1243 * once all bytes have been read.
1244 *
1245 * mpack_error_type is raised if the value is not an extension blob or if its
1246 * length does not match. The @p type value is zero if an error is raised.
1247 *
1248 * @p type will be a user-defined type in the range [0,127] or a reserved type
1249 * in the range [-128,-2].
1250 *
1251 * @note This cannot be used to match a timestamp. @ref mpack_error_type will
1252 * be flagged if the value is a timestamp. Use mpack_expect_timestamp() or
1253 * mpack_expect_timestamp_truncate() instead.
1254 *
1255 * @note This requires @ref MPACK_EXTENSIONS.
1256 *
1257 * @warning Be careful when using reserved types. They may no longer be ext
1258 * types in the future, and previously valid data containing reserved types may
1259 * become invalid in the future.
1260 *
1261 * @see mpack_expect_ext()
1262 */
1263MPACK_INLINE void mpack_expect_ext_size(mpack_reader_t* reader, int8_t* type, uint32_t count) {
1264 if (mpack_expect_ext(reader, type) != count) {
1265 *type = 0;
1266 mpack_reader_flag_error(reader, mpack_error_type);
1267 }
1268}
1269
1270/**
1271 * Reads an extension blob into the given buffer, returning its size in bytes
1272 * and placing the type into @p type.
1273 *
1274 * mpack_error_type is raised if the value is not an extension blob or if its
1275 * length does not match. The @p type value is zero if an error is raised.
1276 *
1277 * @p type will be a user-defined type in the range [0,127] or a reserved type
1278 * in the range [-128,-2].
1279 *
1280 * @note This cannot be used to match a timestamp. @ref mpack_error_type will
1281 * be flagged if the value is a timestamp. Use mpack_expect_timestamp() or
1282 * mpack_expect_timestamp_truncate() instead.
1283 *
1284 * @warning Be careful when using reserved types. They may no longer be ext
1285 * types in the future, and previously valid data containing reserved types may
1286 * become invalid in the future.
1287 *
1288 * @note This requires @ref MPACK_EXTENSIONS.
1289 *
1290 * @see mpack_expect_ext()
1291 */
1292size_t mpack_expect_ext_buf(mpack_reader_t* reader, int8_t* type, char* buf, size_t size);
1293#endif
1294
1295#if MPACK_EXTENSIONS && defined(MPACK_MALLOC)
1296/**
1297 * Reads an extension blob with the given total maximum size, allocating
1298 * storage for it, and placing the type into @p type.
1299 *
1300 * mpack_error_type is raised if the value is not an extension blob or if its
1301 * length does not match. The @p type value is zero if an error is raised.
1302 *
1303 * @p type will be a user-defined type in the range [0,127] or a reserved type
1304 * in the range [-128,-2].
1305 *
1306 * @note This cannot be used to match a timestamp. @ref mpack_error_type will
1307 * be flagged if the value is a timestamp. Use mpack_expect_timestamp() or
1308 * mpack_expect_timestamp_truncate() instead.
1309 *
1310 * @warning Be careful when using reserved types. They may no longer be ext
1311 * types in the future, and previously valid data containing reserved types may
1312 * become invalid in the future.
1313 *
1314 * @note This requires @ref MPACK_EXTENSIONS and @ref MPACK_MALLOC.
1315 *
1316 * @see mpack_expect_ext()
1317 */
1318char* mpack_expect_ext_alloc(mpack_reader_t* reader, int8_t* type, size_t maxsize, size_t* size);
1319#endif
1320
1321/**
1322 * @}
1323 */
1324
1325/**
1326 * @name Special Functions
1327 * @{
1328 */
1329
1330/**
1331 * Reads a MessagePack object header (an MPack tag), expecting it to exactly
1332 * match the given tag.
1333 *
1334 * If the type is compound (i.e. is a map, array, string, binary or
1335 * extension type), additional reads are required to get the contained
1336 * data, and the corresponding done function must be called when done.
1337 *
1338 * @throws mpack_error_type if the tag does not match
1339 *
1340 * @see mpack_read_bytes()
1341 * @see mpack_done_array()
1342 * @see mpack_done_map()
1343 * @see mpack_done_str()
1344 * @see mpack_done_bin()
1345 * @see mpack_done_ext()
1346 */
1347void mpack_expect_tag(mpack_reader_t* reader, mpack_tag_t tag);
1348
1349/**
1350 * Expects a string matching one of the strings in the given array,
1351 * returning its array index.
1352 *
1353 * If the value does not match any of the given strings,
1354 * @ref mpack_error_type is flagged. Use mpack_expect_enum_optional()
1355 * if you want to allow other values than the given strings.
1356 *
1357 * If any error occurs or the reader is in an error state, @a count
1358 * is returned.
1359 *
1360 * This can be used to quickly parse a string into an enum when the
1361 * enum values range from 0 to @a count-1. If the last value in the
1362 * enum is a special "count" value, it can be passed as the count,
1363 * and the return value can be cast directly to the enum type.
1364 *
1365 * @code{.c}
1366 * typedef enum { APPLE , BANANA , ORANGE , COUNT} fruit_t;
1367 * const char* fruits[] = {"apple", "banana", "orange"};
1368 *
1369 * fruit_t fruit = (fruit_t)mpack_expect_enum(reader, fruits, COUNT);
1370 * @endcode
1371 *
1372 * See @ref docs/expect.md for more examples.
1373 *
1374 * The maximum string length is the size of the buffer (strings are read in-place.)
1375 *
1376 * @param reader The reader
1377 * @param strings An array of expected strings of length count
1378 * @param count The number of strings
1379 * @return The index of the matched string, or @a count in case of error
1380 */
1381size_t mpack_expect_enum(mpack_reader_t* reader, const char* strings[], size_t count);
1382
1383/**
1384 * Expects a string matching one of the strings in the given array
1385 * returning its array index, or @a count if no strings match.
1386 *
1387 * If the value is not a string, or it does not match any of the
1388 * given strings, @a count is returned and no error is flagged.
1389 *
1390 * If any error occurs or the reader is in an error state, @a count
1391 * is returned.
1392 *
1393 * This can be used to quickly parse a string into an enum when the
1394 * enum values range from 0 to @a count-1. If the last value in the
1395 * enum is a special "count" value, it can be passed as the count,
1396 * and the return value can be cast directly to the enum type.
1397 *
1398 * @code{.c}
1399 * typedef enum { APPLE , BANANA , ORANGE , COUNT} fruit_t;
1400 * const char* fruits[] = {"apple", "banana", "orange"};
1401 *
1402 * fruit_t fruit = (fruit_t)mpack_expect_enum_optional(reader, fruits, COUNT);
1403 * @endcode
1404 *
1405 * See @ref docs/expect.md for more examples.
1406 *
1407 * The maximum string length is the size of the buffer (strings are read in-place.)
1408 *
1409 * @param reader The reader
1410 * @param strings An array of expected strings of length count
1411 * @param count The number of strings
1412 *
1413 * @return The index of the matched string, or @a count if it does not
1414 * match or an error occurs
1415 */
1416size_t mpack_expect_enum_optional(mpack_reader_t* reader, const char* strings[], size_t count);
1417
1418/**
1419 * Expects an unsigned integer map key between 0 and count-1, marking it
1420 * as found in the given bool array and returning it.
1421 *
1422 * This is a helper for switching among int keys in a map. It is
1423 * typically used with an enum to define the key values. It should
1424 * be called in the expression of a switch() statement. See @ref
1425 * docs/expect.md for an example.
1426 *
1427 * The found array must be cleared before expecting the first key. If the
1428 * flag for a given key is already set when found (i.e. the map contains a
1429 * duplicate key), mpack_error_invalid is flagged.
1430 *
1431 * If the key is not a non-negative integer, or if the key is @a count or
1432 * larger, @a count is returned and no error is flagged. If you want an error
1433 * on unrecognized keys, flag an error in the default case in your switch;
1434 * otherwise you must call mpack_discard() to discard its content.
1435 *
1436 * @param reader The reader
1437 * @param found An array of bool flags of length count
1438 * @param count The number of values in the found array, and one more than the
1439 * maximum allowed key
1440 *
1441 * @see @ref docs/expect.md
1442 */
1443size_t mpack_expect_key_uint(mpack_reader_t* reader, bool found[], size_t count);
1444
1445/**
1446 * Expects a string map key matching one of the strings in the given key list,
1447 * marking it as found in the given bool array and returning its index.
1448 *
1449 * This is a helper for switching among string keys in a map. It is
1450 * typically used with an enum with names matching the strings in the
1451 * array to define the key indices. It should be called in the expression
1452 * of a switch() statement. See @ref docs/expect.md for an example.
1453 *
1454 * The found array must be cleared before expecting the first key. If the
1455 * flag for a given key is already set when found (i.e. the map contains a
1456 * duplicate key), mpack_error_invalid is flagged.
1457 *
1458 * If the key is unrecognized, count is returned and no error is flagged. If
1459 * you want an error on unrecognized keys, flag an error in the default case
1460 * in your switch; otherwise you must call mpack_discard() to discard its content.
1461 *
1462 * The maximum key length is the size of the buffer (keys are read in-place.)
1463 *
1464 * @param reader The reader
1465 * @param keys An array of expected string keys of length count
1466 * @param found An array of bool flags of length count
1467 * @param count The number of values in the keys and found arrays
1468 *
1469 * @see @ref docs/expect.md
1470 */
1471size_t mpack_expect_key_cstr(mpack_reader_t* reader, const char* keys[],
1472 bool found[], size_t count);
1473
1474/**
1475 * @}
1476 */
1477
1478/**
1479 * @}
1480 */
1481
1482#endif
1483
1484MPACK_EXTERN_C_END
1485MPACK_SILENCE_WARNINGS_END
1486
1487#endif
1488
1489
1490