Writing CBOR#
Overview#
When an underlying stream type object is available, such as a file handle or an in-memory appendable buffer, simply pass a suitable minicbor_write_fn
to the minicbor_write_*()
functions.
Note
The minicbor_write_*()
do not write the contents of any bytestring / string values. The contents of these values should be written directly by the user.
#include <minicbor.h>
static void stream_write(stream_type *Stream, unsigned char *Bytes, int Size) {
...
}
void example_write() {
stream_type *Stream = ...;
minicbor_write_indef_array(Stream, stream, write);
minicbor_write_string(Stream, stream_write, strlen("Hello world!"));
stream_write(Stream, "Hello world!", strlen("Hello world!"));
minicbor_write_integer(Stream, stream_write, 100);
minicbor_write_float4(Stream, stream_write, 1.2);
minicbor_write_break(Stream, stream_write);
}
Presizing a CBOR output before writing#
If a contiguous output buffer is required, then the required CBOR buffer size can be calculated by calling the minicbor_write_*()
functions twice.
For the first pass, use a
minicbor_write_fn
that takes a pointer to asize_t
and simply increments the value with the value ofSize
. For example:static void calculate_size(size_t *Required, unsigned char *Bytes, int Size) { *Required += Size; }
The user is responsible for incrementing
Total
with the content sizes of any bytestrings or strings.Then allocate a buffer (e.g. using
malloc()
) and use aminicbor_write_fn
that actual writes the data to the end of the buffer. For example:static void write_bytes(unsigned char **Tail, unsigned char *Bytes, int Size) { memcpy(*Tail, Bytes, Size); *Tail += Size; }
Defines#
-
CBOR_SIMPLE_FALSE
Simple false value.
-
CBOR_SIMPLE_TRUE
Simple true value.
-
CBOR_SIMPLE_NULL
Simple null value.
-
CBOR_SIMPLE_UNDEF
Simple undefined value.
Types#
-
typedef void (*minicbor_write_fn)(void *UserData, const void *Bytes, unsigned Size)#
Minicbor write callback type.
- Param UserData
Pointer passed to
minicbor_write_*()
functions.- Param Bytes
Bytes to write.
- Param Size
Number of bytes.
Functions#
-
void minicbor_write_integer(void *UserData, minicbor_write_fn WriteFn, int64_t Number)#
Write a signed integer. Will automatically write a positive or negative integer with the smallest possible width.
-
void minicbor_write_positive(void *UserData, minicbor_write_fn WriteFn, uint64_t Number)#
Write a positive integer with the smallest width.
-
void minicbor_write_negative(void *UserData, minicbor_write_fn WriteFn, uint64_t Number)#
Write a negative integer with the smallest width. Here Number is the exact value to write into the stream. This means if
X
is the desired negative value to write, thenNumber
should be1 - X
or~X
(the one’s complement). This is to allow the full range of negative numbers to be written.
-
void minicbor_write_bytes(void *UserData, minicbor_write_fn WriteFn, unsigned Size)#
Write the leading bytes of a definite bytestring with
Size
bytes. The actual bytes should be written directly by the application.
-
void minicbor_write_indef_bytes(void *UserData, minicbor_write_fn WriteFn)#
Write the leading bytes of an indefinite bytestring. The chunks should be written using
minicbor_write_bytes()
followed by the bytes themselves. Finally,minicbor_write_break()
should be used to end the indefinite bytestring.
-
void minicbor_write_string(void *UserData, minicbor_write_fn WriteFn, unsigned Size)#
Write the leading bytes of a definite string with
Size
bytes. The actual string should be written directly by the application.
-
void minicbor_write_indef_string(void *UserData, minicbor_write_fn WriteFn)#
Write the leading bytes of an indefinite string. The chunks should be written using
minicbor_write_string()
followed by the strings themselves. Finally,minicbor_write_break()
should be used to end the indefinite string.
-
void minicbor_write_array(void *UserData, minicbor_write_fn WriteFn, unsigned Size)#
Write the leading bytes of a definite array with
Size
elements. The elements themselves should be written with the appropriateminicbor_write_*()
functions.
-
void minicbor_write_indef_array(void *UserData, minicbor_write_fn WriteFn)#
Write the leading bytes of an indefinite array. The elements themselves should be written with the appropriate
minicbor_write_*()
functions. Finally,minicbor_write_break()
should be used to ende the indefinite array.
-
void minicbor_write_map(void *UserData, minicbor_write_fn WriteFn, unsigned Size)#
Write the leading bytes of a definite map with
Size
key-value pairs. The keys and values themselves should be written with the appropriateminicbor_write_*()
functions.
-
void minicbor_write_indef_map(void *UserData, minicbor_write_fn WriteFn)#
Write the leading bytes of an indefinite map. The keys and values themselves should be written with the appropriate
minicbor_write_*()
functions. Finally,minicbor_write_break()
should be used to ende the indefinite map.
-
void minicbor_write_float2(void *UserData, minicbor_write_fn WriteFn, double Number)#
Write a floating point number in half precision.
-
void minicbor_write_float4(void *UserData, minicbor_write_fn WriteFn, double Number)#
Write a floating point number in single precision.
-
void minicbor_write_float8(void *UserData, minicbor_write_fn WriteFn, double Number)#
Write a floating point number in double precision.
-
void minicbor_write_simple(void *UserData, minicbor_write_fn WriteFn, unsigned char Simple)#
Write a simple value.
-
void minicbor_write_break(void *UserData, minicbor_write_fn WriteFn)#
Write a break (to end an indefinite bytestring, string, array or map).
-
void minicbor_write_tag(void *UserData, minicbor_write_fn WriteFn, uint64t Tag)#
Write a tag sequence which will apply to the next value written.