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 core MPack Tag Reader.
26 */
27
28#ifndef MPACK_READER_H
29#define MPACK_READER_H 1
30
31#include "mpack-common.h"
32
33MPACK_SILENCE_WARNINGS_BEGIN
34MPACK_EXTERN_C_BEGIN
35
36#if MPACK_READER
37
38#if MPACK_READ_TRACKING
39struct mpack_track_t;
40#endif
41
42// The denominator to determine whether a read is a small
43// fraction of the buffer size.
44#define MPACK_READER_SMALL_FRACTION_DENOMINATOR 32
45
46/**
47 * @defgroup reader Reader API
48 *
49 * The MPack Reader API contains functions for imperatively reading dynamically
50 * typed data from a MessagePack stream.
51 *
52 * See @ref docs/reader.md for examples.
53 *
54 * @note If you are not writing code for an embedded device (or otherwise do
55 * not need maximum performance with minimal memory usage), you should not use
56 * this. You probably want to use the @link node Node API@endlink instead.
57 *
58 * This forms the basis of the @link expect Expect API@endlink, which can be
59 * used to interpret the stream of elements in expected types and value ranges.
60 *
61 * @{
62 */
63
64/**
65 * @def MPACK_READER_MINIMUM_BUFFER_SIZE
66 *
67 * The minimum buffer size for a reader with a fill function.
68 */
69#define MPACK_READER_MINIMUM_BUFFER_SIZE 32
70
71/**
72 * A buffered MessagePack decoder.
73 *
74 * The decoder wraps an existing buffer and, optionally, a fill function.
75 * This allows efficiently decoding data from existing memory buffers, files,
76 * streams, etc.
77 *
78 * All read operations are synchronous; they will block until the
79 * requested data is fully read, or an error occurs.
80 *
81 * This structure is opaque; its fields should not be accessed outside
82 * of MPack.
83 */
84typedef struct mpack_reader_t mpack_reader_t;
85
86/**
87 * The MPack reader's fill function. It should fill the buffer with at
88 * least one byte and at most the given @c count, returning the number
89 * of bytes written to the buffer.
90 *
91 * In case of error, it should flag an appropriate error on the reader
92 * (usually @ref mpack_error_io), or simply return zero. If zero is
93 * returned, mpack_error_io is raised.
94 *
95 * @note When reading from a stream, you should only copy and return
96 * the bytes that are immediately available. It is always safe to return
97 * less than the requested count as long as some non-zero number of bytes
98 * are read; if more bytes are needed, the read function will simply be
99 * called again.
100 *
101 * @see mpack_reader_context()
102 */
103typedef size_t (*mpack_reader_fill_t)(mpack_reader_t* reader, char* buffer, size_t count);
104
105/**
106 * The MPack reader's skip function. It should discard the given number
107 * of bytes from the source (for example by seeking forward.)
108 *
109 * In case of error, it should flag an appropriate error on the reader.
110 *
111 * @see mpack_reader_context()
112 */
113typedef void (*mpack_reader_skip_t)(mpack_reader_t* reader, size_t count);
114
115/**
116 * An error handler function to be called when an error is flagged on
117 * the reader.
118 *
119 * The error handler will only be called once on the first error flagged;
120 * any subsequent reads and errors are ignored, and the reader is
121 * permanently in that error state.
122 *
123 * MPack is safe against non-local jumps out of error handler callbacks.
124 * This means you are allowed to longjmp or throw an exception (in C++,
125 * Objective-C, or with SEH) out of this callback.
126 *
127 * Bear in mind when using longjmp that local non-volatile variables that
128 * have changed are undefined when setjmp() returns, so you can't put the
129 * reader on the stack in the same activation frame as the setjmp without
130 * declaring it volatile.
131 *
132 * You must still eventually destroy the reader. It is not destroyed
133 * automatically when an error is flagged. It is safe to destroy the
134 * reader within this error callback, but you will either need to perform
135 * a non-local jump, or store something in your context to identify
136 * that the reader is destroyed since any future accesses to it cause
137 * undefined behavior.
138 */
139typedef void (*mpack_reader_error_t)(mpack_reader_t* reader, mpack_error_t error);
140
141/**
142 * A teardown function to be called when the reader is destroyed.
143 */
144typedef void (*mpack_reader_teardown_t)(mpack_reader_t* reader);
145
146/* Hide internals from documentation */
147/** @cond */
148
149struct mpack_reader_t {
150 void* context; /* Context for reader callbacks */
151 mpack_reader_fill_t fill; /* Function to read bytes into the buffer */
152 mpack_reader_error_t error_fn; /* Function to call on error */
153 mpack_reader_teardown_t teardown; /* Function to teardown the context on destroy */
154 mpack_reader_skip_t skip; /* Function to skip bytes from the source */
155
156 char* buffer; /* Writeable byte buffer */
157 size_t size; /* Size of the buffer */
158
159 const char* data; /* Current data pointer (in the buffer, if it is used) */
160 const char* end; /* The end of available data (in the buffer, if it is used) */
161
162 mpack_error_t error; /* Error state */
163
164 #if MPACK_READ_TRACKING
165 mpack_track_t track; /* Stack of map/array/str/bin/ext reads */
166 #endif
167};
168
169/** @endcond */
170
171/**
172 * @name Lifecycle Functions
173 * @{
174 */
175
176/**
177 * Initializes an MPack reader with the given buffer. The reader does
178 * not assume ownership of the buffer, but the buffer must be writeable
179 * if a fill function will be used to refill it.
180 *
181 * @param reader The MPack reader.
182 * @param buffer The buffer with which to read MessagePack data.
183 * @param size The size of the buffer.
184 * @param count The number of bytes already in the buffer.
185 */
186void mpack_reader_init(mpack_reader_t* reader, char* buffer, size_t size, size_t count);
187
188/**
189 * Initializes an MPack reader directly into an error state. Use this if you
190 * are writing a wrapper to mpack_reader_init() which can fail its setup.
191 */
192void mpack_reader_init_error(mpack_reader_t* reader, mpack_error_t error);
193
194/**
195 * Initializes an MPack reader to parse a pre-loaded contiguous chunk of data. The
196 * reader does not assume ownership of the data.
197 *
198 * @param reader The MPack reader.
199 * @param data The data to parse.
200 * @param count The number of bytes pointed to by data.
201 */
202void mpack_reader_init_data(mpack_reader_t* reader, const char* data, size_t count);
203
204#if MPACK_STDIO
205/**
206 * Initializes an MPack reader that reads from a file.
207 *
208 * The file will be automatically opened and closed by the reader.
209 */
210void mpack_reader_init_filename(mpack_reader_t* reader, const char* filename);
211
212/**
213 * Deprecated.
214 *
215 * \deprecated Renamed to mpack_reader_init_filename().
216 */
217MPACK_INLINE void mpack_reader_init_file(mpack_reader_t* reader, const char* filename) {
218 mpack_reader_init_filename(reader, filename);
219}
220
221/**
222 * Initializes an MPack reader that reads from a libc FILE. This can be used to
223 * read from stdin, or from a file opened separately.
224 *
225 * @param reader The MPack reader.
226 * @param stdfile The FILE.
227 * @param close_when_done If true, fclose() will be called on the FILE when it
228 * is no longer needed. If false, the file will not be closed when
229 * reading is done.
230 *
231 * @warning The reader is buffered. It will read data in advance of parsing it,
232 * and it may read more data than it parsed. See mpack_reader_remaining() to
233 * access the extra data.
234 */
235void mpack_reader_init_stdfile(mpack_reader_t* reader, FILE* stdfile, bool close_when_done);
236#endif
237
238/**
239 * @def mpack_reader_init_stack(reader)
240 * @hideinitializer
241 *
242 * Initializes an MPack reader using stack space as a buffer. A fill function
243 * should be added to the reader to fill the buffer.
244 *
245 * @see mpack_reader_set_fill
246 */
247
248/** @cond */
249#define mpack_reader_init_stack_line_ex(line, reader) \
250 char mpack_buf_##line[MPACK_STACK_SIZE]; \
251 mpack_reader_init((reader), mpack_buf_##line, sizeof(mpack_buf_##line), 0)
252
253#define mpack_reader_init_stack_line(line, reader) \
254 mpack_reader_init_stack_line_ex(line, reader)
255/** @endcond */
256
257#define mpack_reader_init_stack(reader) \
258 mpack_reader_init_stack_line(__LINE__, (reader))
259
260/**
261 * Cleans up the MPack reader, ensuring that all compound elements
262 * have been completely read. Returns the final error state of the
263 * reader.
264 *
265 * This will assert in tracking mode if the reader is not in an error
266 * state and has any incomplete reads. If you want to cancel reading
267 * in the middle of a document, you need to flag an error on the reader
268 * before destroying it (such as mpack_error_data).
269 *
270 * @see mpack_read_tag()
271 * @see mpack_reader_flag_error()
272 * @see mpack_error_data
273 */
274mpack_error_t mpack_reader_destroy(mpack_reader_t* reader);
275
276/**
277 * @}
278 */
279
280/**
281 * @name Callbacks
282 * @{
283 */
284
285/**
286 * Sets the custom pointer to pass to the reader callbacks, such as fill
287 * or teardown.
288 *
289 * @param reader The MPack reader.
290 * @param context User data to pass to the reader callbacks.
291 *
292 * @see mpack_reader_context()
293 */
294MPACK_INLINE void mpack_reader_set_context(mpack_reader_t* reader, void* context) {
295 reader->context = context;
296}
297
298/**
299 * Returns the custom context for reader callbacks.
300 *
301 * @see mpack_reader_set_context
302 * @see mpack_reader_set_fill
303 * @see mpack_reader_set_skip
304 */
305MPACK_INLINE void* mpack_reader_context(mpack_reader_t* reader) {
306 return reader->context;
307}
308
309/**
310 * Sets the fill function to refill the data buffer when it runs out of data.
311 *
312 * If no fill function is used, truncated MessagePack data results in
313 * mpack_error_invalid (since the buffer is assumed to contain a
314 * complete MessagePack object.)
315 *
316 * If a fill function is used, truncated MessagePack data usually
317 * results in mpack_error_io (since the fill function fails to get
318 * the missing data.)
319 *
320 * This should normally be used with mpack_reader_set_context() to register
321 * a custom pointer to pass to the fill function.
322 *
323 * @param reader The MPack reader.
324 * @param fill The function to fetch additional data into the buffer.
325 */
326void mpack_reader_set_fill(mpack_reader_t* reader, mpack_reader_fill_t fill);
327
328/**
329 * Sets the skip function to discard bytes from the source stream.
330 *
331 * It's not necessary to implement this function. If the stream is not
332 * seekable, don't set a skip callback. The reader will fall back to
333 * using the fill function instead.
334 *
335 * This should normally be used with mpack_reader_set_context() to register
336 * a custom pointer to pass to the skip function.
337 *
338 * The skip function is ignored in size-optimized builds to reduce code
339 * size. Data will be skipped with the fill function when necessary.
340 *
341 * @param reader The MPack reader.
342 * @param skip The function to discard bytes from the source stream.
343 */
344void mpack_reader_set_skip(mpack_reader_t* reader, mpack_reader_skip_t skip);
345
346/**
347 * Sets the error function to call when an error is flagged on the reader.
348 *
349 * This should normally be used with mpack_reader_set_context() to register
350 * a custom pointer to pass to the error function.
351 *
352 * See the definition of mpack_reader_error_t for more information about
353 * what you can do from an error callback.
354 *
355 * @see mpack_reader_error_t
356 * @param reader The MPack reader.
357 * @param error_fn The function to call when an error is flagged on the reader.
358 */
359MPACK_INLINE void mpack_reader_set_error_handler(mpack_reader_t* reader, mpack_reader_error_t error_fn) {
360 reader->error_fn = error_fn;
361}
362
363/**
364 * Sets the teardown function to call when the reader is destroyed.
365 *
366 * This should normally be used with mpack_reader_set_context() to register
367 * a custom pointer to pass to the teardown function.
368 *
369 * @param reader The MPack reader.
370 * @param teardown The function to call when the reader is destroyed.
371 */
372MPACK_INLINE void mpack_reader_set_teardown(mpack_reader_t* reader, mpack_reader_teardown_t teardown) {
373 reader->teardown = teardown;
374}
375
376/**
377 * @}
378 */
379
380/**
381 * @name Core Reader Functions
382 * @{
383 */
384
385/**
386 * Queries the error state of the MPack reader.
387 *
388 * If a reader is in an error state, you should discard all data since the
389 * last time the error flag was checked. The error flag cannot be cleared.
390 */
391MPACK_INLINE mpack_error_t mpack_reader_error(mpack_reader_t* reader) {
392 return reader->error;
393}
394
395/**
396 * Places the reader in the given error state, calling the error callback if one
397 * is set.
398 *
399 * This allows you to externally flag errors, for example if you are validating
400 * data as you read it.
401 *
402 * If the reader is already in an error state, this call is ignored and no
403 * error callback is called.
404 */
405void mpack_reader_flag_error(mpack_reader_t* reader, mpack_error_t error);
406
407/**
408 * Places the reader in the given error state if the given error is not mpack_ok,
409 * returning the resulting error state of the reader.
410 *
411 * This allows you to externally flag errors, for example if you are validating
412 * data as you read it.
413 *
414 * If the given error is mpack_ok or if the reader is already in an error state,
415 * this call is ignored and the actual error state of the reader is returned.
416 */
417MPACK_INLINE mpack_error_t mpack_reader_flag_if_error(mpack_reader_t* reader, mpack_error_t error) {
418 if (error != mpack_ok)
419 mpack_reader_flag_error(reader, error);
420 return mpack_reader_error(reader);
421}
422
423/**
424 * Returns bytes left in the reader's buffer.
425 *
426 * If you are done reading MessagePack data but there is other interesting data
427 * following it, the reader may have buffered too much data. The number of bytes
428 * remaining in the buffer and a pointer to the position of those bytes can be
429 * queried here.
430 *
431 * If you know the length of the MPack chunk beforehand, it's better to instead
432 * have your fill function limit the data it reads so that the reader does not
433 * have extra data. In this case you can simply check that this returns zero.
434 *
435 * Returns 0 if the reader is in an error state.
436 *
437 * @param reader The MPack reader from which to query remaining data.
438 * @param data [out] A pointer to the remaining data, or NULL.
439 * @return The number of bytes remaining in the buffer.
440 */
441size_t mpack_reader_remaining(mpack_reader_t* reader, const char** data);
442
443/**
444 * Reads a MessagePack object header (an MPack tag.)
445 *
446 * If an error occurs, the reader is placed in an error state and a
447 * nil tag is returned. If the reader is already in an error state,
448 * a nil tag is returned.
449 *
450 * If the type is compound (i.e. is a map, array, string, binary or
451 * extension type), additional reads are required to get the contained
452 * data, and the corresponding done function must be called when done.
453 *
454 * @note Maps in JSON are unordered, so it is recommended not to expect
455 * a specific ordering for your map values in case your data is converted
456 * to/from JSON.
457 *
458 * @see mpack_read_bytes()
459 * @see mpack_done_array()
460 * @see mpack_done_map()
461 * @see mpack_done_str()
462 * @see mpack_done_bin()
463 * @see mpack_done_ext()
464 */
465mpack_tag_t mpack_read_tag(mpack_reader_t* reader);
466
467/**
468 * Parses the next MessagePack object header (an MPack tag) without
469 * advancing the reader.
470 *
471 * If an error occurs, the reader is placed in an error state and a
472 * nil tag is returned. If the reader is already in an error state,
473 * a nil tag is returned.
474 *
475 * @note Maps in JSON are unordered, so it is recommended not to expect
476 * a specific ordering for your map values in case your data is converted
477 * to/from JSON.
478 *
479 * @see mpack_read_tag()
480 * @see mpack_discard()
481 */
482mpack_tag_t mpack_peek_tag(mpack_reader_t* reader);
483
484/**
485 * @}
486 */
487
488/**
489 * @name String and Data Functions
490 * @{
491 */
492
493/**
494 * Skips bytes from the underlying stream. This is used only to
495 * skip the contents of a string, binary blob or extension object.
496 */
497void mpack_skip_bytes(mpack_reader_t* reader, size_t count);
498
499/**
500 * Reads bytes from a string, binary blob or extension object, copying
501 * them into the given buffer.
502 *
503 * A str, bin or ext must have been opened by a call to mpack_read_tag()
504 * which yielded one of these types, or by a call to an expect function
505 * such as mpack_expect_str() or mpack_expect_bin().
506 *
507 * If an error occurs, the buffer contents are undefined.
508 *
509 * This can be called multiple times for a single str, bin or ext
510 * to read the data in chunks. The total data read must add up
511 * to the size of the object.
512 *
513 * @param reader The MPack reader
514 * @param p The buffer in which to copy the bytes
515 * @param count The number of bytes to read
516 */
517void mpack_read_bytes(mpack_reader_t* reader, char* p, size_t count);
518
519/**
520 * Reads bytes from a string, ensures that the string is valid UTF-8,
521 * and copies the bytes into the given buffer.
522 *
523 * A string must have been opened by a call to mpack_read_tag() which
524 * yielded a string, or by a call to an expect function such as
525 * mpack_expect_str().
526 *
527 * The given byte count must match the complete size of the string as
528 * returned by the tag or expect function. You must ensure that the
529 * buffer fits the data.
530 *
531 * This does not accept any UTF-8 variant such as Modified UTF-8, CESU-8 or
532 * WTF-8. Only pure UTF-8 is allowed.
533 *
534 * If an error occurs, the buffer contents are undefined.
535 *
536 * Unlike mpack_read_bytes(), this cannot be used to read the data in
537 * chunks (since this might split a character's UTF-8 bytes, and the
538 * reader does not keep track of the UTF-8 decoding state between reads.)
539 *
540 * @throws mpack_error_type if the string contains invalid UTF-8.
541 */
542void mpack_read_utf8(mpack_reader_t* reader, char* p, size_t byte_count);
543
544/**
545 * Reads bytes from a string, ensures that the string contains no NUL
546 * bytes, copies the bytes into the given buffer and adds a null-terminator.
547 *
548 * A string must have been opened by a call to mpack_read_tag() which
549 * yielded a string, or by a call to an expect function such as
550 * mpack_expect_str().
551 *
552 * The given byte count must match the size of the string as returned
553 * by the tag or expect function. The string will only be copied if
554 * the buffer is large enough to store it.
555 *
556 * If an error occurs, the buffer will contain an empty string.
557 *
558 * @note If you know the object will be a string before reading it,
559 * it is highly recommended to use mpack_expect_cstr() instead.
560 * Alternatively you could use mpack_peek_tag() and call
561 * mpack_expect_cstr() if it's a string.
562 *
563 * @throws mpack_error_too_big if the string plus null-terminator is larger than the given buffer size
564 * @throws mpack_error_type if the string contains a null byte.
565 *
566 * @see mpack_peek_tag()
567 * @see mpack_expect_cstr()
568 * @see mpack_expect_utf8_cstr()
569 */
570void mpack_read_cstr(mpack_reader_t* reader, char* buf, size_t buffer_size, size_t byte_count);
571
572/**
573 * Reads bytes from a string, ensures that the string is valid UTF-8
574 * with no NUL bytes, copies the bytes into the given buffer and adds a
575 * null-terminator.
576 *
577 * A string must have been opened by a call to mpack_read_tag() which
578 * yielded a string, or by a call to an expect function such as
579 * mpack_expect_str().
580 *
581 * The given byte count must match the size of the string as returned
582 * by the tag or expect function. The string will only be copied if
583 * the buffer is large enough to store it.
584 *
585 * This does not accept any UTF-8 variant such as Modified UTF-8, CESU-8 or
586 * WTF-8. Only pure UTF-8 is allowed, but without the NUL character, since
587 * it cannot be represented in a null-terminated string.
588 *
589 * If an error occurs, the buffer will contain an empty string.
590 *
591 * @note If you know the object will be a string before reading it,
592 * it is highly recommended to use mpack_expect_utf8_cstr() instead.
593 * Alternatively you could use mpack_peek_tag() and call
594 * mpack_expect_utf8_cstr() if it's a string.
595 *
596 * @throws mpack_error_too_big if the string plus null-terminator is larger than the given buffer size
597 * @throws mpack_error_type if the string contains invalid UTF-8 or a null byte.
598 *
599 * @see mpack_peek_tag()
600 * @see mpack_expect_utf8_cstr()
601 */
602void mpack_read_utf8_cstr(mpack_reader_t* reader, char* buf, size_t buffer_size, size_t byte_count);
603
604#ifdef MPACK_MALLOC
605/** @cond */
606// This can optionally add a null-terminator, but it does not check
607// whether the data contains null bytes. This must be done separately
608// in a cstring read function (possibly as part of a UTF-8 check.)
609char* mpack_read_bytes_alloc_impl(mpack_reader_t* reader, size_t count, bool null_terminated);
610/** @endcond */
611
612/**
613 * Reads bytes from a string, binary blob or extension object, allocating
614 * storage for them and returning the allocated pointer.
615 *
616 * The allocated string must be freed with MPACK_FREE() (or simply free()
617 * if MPack's allocator hasn't been customized.)
618 *
619 * Returns NULL if any error occurs, or if count is zero.
620 */
621MPACK_INLINE char* mpack_read_bytes_alloc(mpack_reader_t* reader, size_t count) {
622 return mpack_read_bytes_alloc_impl(reader, count, false);
623}
624#endif
625
626/**
627 * Reads bytes from a string, binary blob or extension object in-place in
628 * the buffer. This can be used to avoid copying the data.
629 *
630 * A str, bin or ext must have been opened by a call to mpack_read_tag()
631 * which yielded one of these types, or by a call to an expect function
632 * such as mpack_expect_str() or mpack_expect_bin().
633 *
634 * If the bytes are from a string, the string is not null-terminated! Use
635 * mpack_read_cstr() to copy the string into a buffer and add a null-terminator.
636 *
637 * The returned pointer is invalidated on the next read, or when the buffer
638 * is destroyed.
639 *
640 * The reader will move data around in the buffer if needed to ensure that
641 * the pointer can always be returned, so this should only be used if
642 * count is very small compared to the buffer size. If you need to check
643 * whether a small size is reasonable (for example you intend to handle small and
644 * large sizes differently), you can call mpack_should_read_bytes_inplace().
645 *
646 * This can be called multiple times for a single str, bin or ext
647 * to read the data in chunks. The total data read must add up
648 * to the size of the object.
649 *
650 * NULL is returned if the reader is in an error state.
651 *
652 * @throws mpack_error_too_big if the requested size is larger than the buffer size
653 *
654 * @see mpack_should_read_bytes_inplace()
655 */
656const char* mpack_read_bytes_inplace(mpack_reader_t* reader, size_t count);
657
658/**
659 * Reads bytes from a string in-place in the buffer and ensures they are
660 * valid UTF-8. This can be used to avoid copying the data.
661 *
662 * A string must have been opened by a call to mpack_read_tag() which
663 * yielded a string, or by a call to an expect function such as
664 * mpack_expect_str().
665 *
666 * The string is not null-terminated! Use mpack_read_utf8_cstr() to
667 * copy the string into a buffer and add a null-terminator.
668 *
669 * The returned pointer is invalidated on the next read, or when the buffer
670 * is destroyed.
671 *
672 * The reader will move data around in the buffer if needed to ensure that
673 * the pointer can always be returned, so this should only be used if
674 * count is very small compared to the buffer size. If you need to check
675 * whether a small size is reasonable (for example you intend to handle small and
676 * large sizes differently), you can call mpack_should_read_bytes_inplace().
677 *
678 * This does not accept any UTF-8 variant such as Modified UTF-8, CESU-8 or
679 * WTF-8. Only pure UTF-8 is allowed.
680 *
681 * Unlike mpack_read_bytes_inplace(), this cannot be used to read the data in
682 * chunks (since this might split a character's UTF-8 bytes, and the
683 * reader does not keep track of the UTF-8 decoding state between reads.)
684 *
685 * NULL is returned if the reader is in an error state.
686 *
687 * @throws mpack_error_type if the string contains invalid UTF-8
688 * @throws mpack_error_too_big if the requested size is larger than the buffer size
689 *
690 * @see mpack_should_read_bytes_inplace()
691 */
692const char* mpack_read_utf8_inplace(mpack_reader_t* reader, size_t count);
693
694/**
695 * Returns true if it's a good idea to read the given number of bytes
696 * in-place.
697 *
698 * If the read will be larger than some small fraction of the buffer size,
699 * this will return false to avoid shuffling too much data back and forth
700 * in the buffer.
701 *
702 * Use this if you're expecting arbitrary size data, and you want to read
703 * in-place for the best performance when possible but will fall back to
704 * a normal read if the data is too large.
705 *
706 * @see mpack_read_bytes_inplace()
707 */
708MPACK_INLINE bool mpack_should_read_bytes_inplace(mpack_reader_t* reader, size_t count) {
709 return (reader->size == 0 || count <= reader->size / MPACK_READER_SMALL_FRACTION_DENOMINATOR);
710}
711
712#if MPACK_EXTENSIONS
713/**
714 * Reads a timestamp contained in an ext object of the given size, closing the
715 * ext type.
716 *
717 * An ext object of exttype @ref MPACK_EXTTYPE_TIMESTAMP must have been opened
718 * by a call to e.g. mpack_read_tag() or mpack_expect_ext().
719 *
720 * You must NOT call mpack_done_ext() after calling this. A timestamp ext
721 * object can only contain a single timestamp value, so this calls
722 * mpack_done_ext() automatically.
723 *
724 * @note This requires @ref MPACK_EXTENSIONS.
725 *
726 * @throws mpack_error_invalid if the size is not one of the supported
727 * timestamp sizes, or if the nanoseconds are out of range.
728 */
729mpack_timestamp_t mpack_read_timestamp(mpack_reader_t* reader, size_t size);
730#endif
731
732/**
733 * @}
734 */
735
736/**
737 * @name Core Reader Functions
738 * @{
739 */
740
741#if MPACK_READ_TRACKING
742/**
743 * Finishes reading the given type.
744 *
745 * This will track reads to ensure that the correct number of elements
746 * or bytes are read.
747 */
748void mpack_done_type(mpack_reader_t* reader, mpack_type_t type);
749#else
750MPACK_INLINE void mpack_done_type(mpack_reader_t* reader, mpack_type_t type) {
751 MPACK_UNUSED(reader);
752 MPACK_UNUSED(type);
753}
754#endif
755
756/**
757 * Finishes reading an array.
758 *
759 * This will track reads to ensure that the correct number of elements are read.
760 */
761MPACK_INLINE void mpack_done_array(mpack_reader_t* reader) {
762 mpack_done_type(reader, mpack_type_array);
763}
764
765/**
766 * @fn mpack_done_map(mpack_reader_t* reader)
767 *
768 * Finishes reading a map.
769 *
770 * This will track reads to ensure that the correct number of elements are read.
771 */
772MPACK_INLINE void mpack_done_map(mpack_reader_t* reader) {
773 mpack_done_type(reader, mpack_type_map);
774}
775
776/**
777 * @fn mpack_done_str(mpack_reader_t* reader)
778 *
779 * Finishes reading a string.
780 *
781 * This will track reads to ensure that the correct number of bytes are read.
782 */
783MPACK_INLINE void mpack_done_str(mpack_reader_t* reader) {
784 mpack_done_type(reader, mpack_type_str);
785}
786
787/**
788 * @fn mpack_done_bin(mpack_reader_t* reader)
789 *
790 * Finishes reading a binary data blob.
791 *
792 * This will track reads to ensure that the correct number of bytes are read.
793 */
794MPACK_INLINE void mpack_done_bin(mpack_reader_t* reader) {
795 mpack_done_type(reader, mpack_type_bin);
796}
797
798#if MPACK_EXTENSIONS
799/**
800 * @fn mpack_done_ext(mpack_reader_t* reader)
801 *
802 * Finishes reading an extended type binary data blob.
803 *
804 * This will track reads to ensure that the correct number of bytes are read.
805 *
806 * @note This requires @ref MPACK_EXTENSIONS.
807 */
808MPACK_INLINE void mpack_done_ext(mpack_reader_t* reader) {
809 mpack_done_type(reader, mpack_type_ext);
810}
811#endif
812
813/**
814 * Reads and discards the next object. This will read and discard all
815 * contained data as well if it is a compound type.
816 */
817void mpack_discard(mpack_reader_t* reader);
818
819/**
820 * @}
821 */
822
823/** @cond */
824
825#if MPACK_DEBUG && MPACK_STDIO
826/**
827 * @name Debugging Functions
828 * @{
829 */
830/*
831 * Converts a blob of MessagePack to a pseudo-JSON string for debugging
832 * purposes, placing the result in the given buffer with a null-terminator.
833 *
834 * If the buffer does not have enough space, the result will be truncated (but
835 * it is guaranteed to be null-terminated.)
836 *
837 * This is only available in debug mode, and only if stdio is available (since
838 * it uses snprintf().) It's strictly for debugging purposes.
839 */
840void mpack_print_data_to_buffer(const char* data, size_t data_size, char* buffer, size_t buffer_size);
841
842/*
843 * Converts a node to pseudo-JSON for debugging purposes, calling the given
844 * callback as many times as is necessary to output the character data.
845 *
846 * No null-terminator or trailing newline will be written.
847 *
848 * This is only available in debug mode, and only if stdio is available (since
849 * it uses snprintf().) It's strictly for debugging purposes.
850 */
851void mpack_print_data_to_callback(const char* data, size_t size, mpack_print_callback_t callback, void* context);
852
853/*
854 * Converts a blob of MessagePack to pseudo-JSON for debugging purposes
855 * and pretty-prints it to the given file.
856 */
857void mpack_print_data_to_file(const char* data, size_t len, FILE* file);
858
859/*
860 * Converts a blob of MessagePack to pseudo-JSON for debugging purposes
861 * and pretty-prints it to stdout.
862 */
863MPACK_INLINE void mpack_print_data_to_stdout(const char* data, size_t len) {
864 mpack_print_data_to_file(data, len, stdout);
865}
866
867/*
868 * Converts the MessagePack contained in the given `FILE*` to pseudo-JSON for
869 * debugging purposes, calling the given callback as many times as is necessary
870 * to output the character data.
871 */
872void mpack_print_stdfile_to_callback(FILE* file, mpack_print_callback_t callback, void* context);
873
874/*
875 * Deprecated.
876 *
877 * \deprecated Renamed to mpack_print_data_to_stdout().
878 */
879MPACK_INLINE void mpack_print(const char* data, size_t len) {
880 mpack_print_data_to_stdout(data, len);
881}
882
883/**
884 * @}
885 */
886#endif
887
888/** @endcond */
889
890/**
891 * @}
892 */
893
894
895
896#if MPACK_INTERNAL
897
898bool mpack_reader_ensure_straddle(mpack_reader_t* reader, size_t count);
899
900/*
901 * Ensures there are at least @c count bytes left in the
902 * data, raising an error and returning false if more
903 * data cannot be made available.
904 */
905MPACK_INLINE bool mpack_reader_ensure(mpack_reader_t* reader, size_t count) {
906 mpack_assert(count != 0, "cannot ensure zero bytes!");
907 mpack_assert(reader->error == mpack_ok, "reader cannot be in an error state!");
908
909 if (count <= (size_t)(reader->end - reader->data))
910 return true;
911 return mpack_reader_ensure_straddle(reader, count);
912}
913
914void mpack_read_native_straddle(mpack_reader_t* reader, char* p, size_t count);
915
916// Reads count bytes into p, deferring to mpack_read_native_straddle() if more
917// bytes are needed than are available in the buffer.
918MPACK_INLINE void mpack_read_native(mpack_reader_t* reader, char* p, size_t count) {
919 mpack_assert(count == 0 || p != NULL, "data pointer for %i bytes is NULL", (int)count);
920
921 if (count > (size_t)(reader->end - reader->data)) {
922 mpack_read_native_straddle(reader, p, count);
923 } else {
924 mpack_memcpy(p, reader->data, count);
925 reader->data += count;
926 }
927}
928
929#if MPACK_READ_TRACKING
930#define MPACK_READER_TRACK(reader, error_expr) \
931 (((reader)->error == mpack_ok) ? mpack_reader_flag_if_error((reader), (error_expr)) : (reader)->error)
932#else
933#define MPACK_READER_TRACK(reader, error_expr) (MPACK_UNUSED(reader), mpack_ok)
934#endif
935
936MPACK_INLINE mpack_error_t mpack_reader_track_element(mpack_reader_t* reader) {
937 return MPACK_READER_TRACK(reader, mpack_track_element(&reader->track, true));
938}
939
940MPACK_INLINE mpack_error_t mpack_reader_track_peek_element(mpack_reader_t* reader) {
941 return MPACK_READER_TRACK(reader, mpack_track_peek_element(&reader->track, true));
942}
943
944MPACK_INLINE mpack_error_t mpack_reader_track_bytes(mpack_reader_t* reader, size_t count) {
945 MPACK_UNUSED(count);
946 return MPACK_READER_TRACK(reader, mpack_track_bytes(&reader->track, true, count));
947}
948
949MPACK_INLINE mpack_error_t mpack_reader_track_str_bytes_all(mpack_reader_t* reader, size_t count) {
950 MPACK_UNUSED(count);
951 return MPACK_READER_TRACK(reader, mpack_track_str_bytes_all(&reader->track, true, count));
952}
953
954#endif
955
956
957
958#endif
959
960MPACK_EXTERN_C_END
961MPACK_SILENCE_WARNINGS_END
962
963#endif
964
965