Macros
#define	SER_BIN_MAGIC "CXSB"
	Magic at the start of every document, followed by a version byte and a flags byte.

#define	SER_BIN_VERSION 1
	Format version this build writes. The reader rejects anything it does not know.

Enumerations
enum	SerBinHeaderFlagsEnum { SER_BinHdr_SelfDescribing = (1 << 0) , SER_BinHdr_StringDedup = (1 << 1) , SER_BinHdr_Refs = (1 << 2) }
	Header flag bits, recording how the body was encoded. More...

Functions
SerWriter *	serBinaryWriterCreate (StreamBuffer *sb, flags_t flags)

SerReader *	serBinaryReaderCreate (StreamBuffer *sb, flags_t flags)

Detailed Description

A compact, lossless binary format. It advertises SER_Cap_Bytes, SER_Cap_ExactInt, and SER_Cap_Sizes, so nothing is lost or approximated the way it can be with JSON.

Documents are written and read strictly front-to-back, which makes this format a good fit for a socket or pipe. It is not meant for reading a large file at random; use a different backend for that.

A few notes on the encoding, useful if you need to inspect or debug a document:

Little-endian, with varint-encoded lengths, counts, and dictionary ids.
Every value starts with a one-byte tag.
Member names, type names, and (unless SER_Bin_NoStringDedup is set) string values are deduplicated into a shared dictionary, so a repeated string only costs a few bytes after the first time it appears.

Compact mode (SER_Bin_Compact) makes documents smaller by dropping the tag byte on values whose type the schema already pins down (integers, reals, byte runs). The trade-off: a compact document can only be read back with the exact schema it was written with, and an unrecognized field is an error rather than something that can be skipped. Use the default, self-describing mode if documents need to keep reading after the schema changes.

The reader detects the mode from the document itself, so you don't need to know how a document was written in order to read it.

StreamBuffer *sb = sbufCreate(4096);
string out = 0;
sbufStrCRegisterPush(sb, &out);
 
SerWriter *w = serBinaryWriterCreate(sb, 0);
serWrite(w, MyStruct, val);
serWriterFinish(w);
serWriterDestroy(&w);
sbufFinish(&sb);

Enumeration Type Documentation

◆ SerBinHeaderFlagsEnum

enum SerBinHeaderFlagsEnum

Header flag bits, recording how the body was encoded.

Enumerator
SER_BinHdr_SelfDescribing	values carry tag bytes
SER_BinHdr_StringDedup	string values intern into the dictionary
SER_BinHdr_Refs	document may contain reference nodes

Definition at line 59 of file serbinary.h.

Function Documentation

◆ serBinaryReaderCreate()

SerReader * serBinaryReaderCreate	(	StreamBuffer *	sb,
		flags_t	flags
	)

Creates a reader that decodes binary from a stream buffer.

The document's header decides whether it is self-describing or compact and whether string values were interned; none of that has to be supplied here.

Parameters

sb	Stream buffer with a producer registered in pull mode. The reader registers as the consumer, taking a reference of its own; destroying it ends the consumer side and drops that reference, which spends the stream. The caller's own reference is untouched and still has to be released.
flags	SerFlagsEnum options

Returns: A new reader; destroy with serReaderDestroy()

Example:

StreamBuffer *sb = sbufCreate(4096);
sbufStrPRegisterPull(sb, doc);
 
SerReader *r = serBinaryReaderCreate(sb, 0);
MyStruct out;
structInit(MyStruct, &out);
serRead(r, MyStruct, &out);
serReaderDestroy(&r);
sbufFinish(&sb);

◆ serBinaryWriterCreate()

SerWriter * serBinaryWriterCreate	(	StreamBuffer *	sb,
		flags_t	flags
	)

Creates a writer that emits binary to a stream buffer.