#include <UsefulBuf.h>

Detailed Description

UsefulInputBuf is the counterpart to UsefulOutBuf. It is for parsing data received. Initialize it with the data from the network. Then use the functions like UsefulInputBuf_GetBytes() to get data chunks of various types. A position cursor is maintained internally.

As long as the functions here are used, there will never be any reference off the end of the given buffer (except UsefulInputBuf_SetBufferLength()). This is true even if they are called incorrectly, an attempt is made to seek off the end of the buffer or such. This makes it easier to write safe and correct code. For example, the QCBOR decoder implementation is safer and easier to review through its use of UsefulInputBuf.

UsefulInputBuf maintains an internal error state. The intended use is fetching data chunks without any error checks until the end. If there was any error, such as an attempt to fetch data off the end, the error state is entered and no further data will be returned. In the error state the UsefulInputBuf_GetXxxx() functions return 0, or NULL or NULLUsefulBufC. As long as null is not dereferenced, the error check can be put off until the end, simplifying the calling code.

The integer and float parsing expects network byte order (big endian). Network byte order is what is used by TCP/IP, CBOR and most internet protocols.

Lots of inline functions are used to keep code size down. The optimizer, particularly with the -Os or -O3, also reduces code size a lot. The only non-inline code is UsefulInputBuf_GetBytes(). It is less than 100 bytes so use of UsefulInputBuf doesn't add much code for all the messy hard-to-get right issues with parsing binary protocols in C that it solves.

The parse context size is:

64-bit machine: 16 + 8 + 2 + 1 (+ 5 bytes padding to align) = 32 bytes
32-bit machine: 8 + 4 + 2 + 1 (+ 1 byte padding to align) = 16 bytes

The documentation for this struct was generated from the following file:

/Users/lgl/Code/QCBOR/dev/inc/qcbor/UsefulBuf.h