Readers

Data Structures
struct	SerReaderOps

Macros
#define	serReaderCaps(r)   ((r)->caps)
#define	serReaderCan(r, capname)   (((r)->caps & SER_Cap_##capname) != 0)
#define	serRead(r, type, pval)   _serRead(r, stExt(type), stArgPtr(type, pval))

Typedefs
typedef struct SerReaderOps	SerReaderOps

Functions
SerReader *	_serReaderAlloc (size_t size, const SerReaderOps *ops, flags_t caps, flags_t flags)
void	serReaderDestroy (SerReader **r)
void	serReaderAddResolver (SerReader *r, SerTypeResolver fn, void *user)
bool	serReaderResolve (SerResolved *out, SerReader *r, strref name)
bool	serReaderFail (SerReader *r, int32 code, strref msg)

Detailed Description

Macro Definition Documentation

serRead

#define serRead	(		r,
			type,
			pval
	)		_serRead(r, stExt(type), stArgPtr(type, pval))

bool serRead(SerReader *r, type, pvalue)

Reads a value back from the given backend. The counterpart to serWrite().

Safe to call whether the destination already holds a value or is freshly zeroed – any existing value is destroyed before the new one is read in.

Parameters

r	Backend to read from
type	Type name of the destination
pval	Pointer to the destination

Returns

true on success; on failure the error is left in r->err

Example:

int32 n = 0;
serRead(r, int32, &n);

Definition at line 192 of file serreader.h.

serReaderCan

#define serReaderCan	(		r,
			capname
	)		(((r)->caps & SER_Cap_##capname) != 0)

bool serReaderCan(SerReader *r, capname)

Tests one capability of a reader.

Parameters

r	Reader to query
capname	Capability name without the SER_Cap_ prefix, e.g. Skip

Definition at line 122 of file serreader.h.

serReaderCaps

#define serReaderCaps

(

r

)

((r)->caps)

flags_t serReaderCaps(SerReader *r)

The capabilities this reader's backend advertises.

Definition at line 114 of file serreader.h.

Typedef Documentation

SerReaderOps

typedef struct SerReaderOps SerReaderOps

A serialization format, defined as a set of operations for reading each kind of value.

The traverser asks for whatever should come next according to the schema, and the backend checks and consumes it. peek is only needed when the next value's type isn't already known (a dynamic slot, an optional member); skip is for fields the schema doesn't recognize.

Function Documentation

_serReaderAlloc()

SerReader * _serReaderAlloc	(	size_t	size,
		const SerReaderOps *	ops,
		flags_t	caps,
		flags_t	flags
	)

Allocates a reader of the given total size and fills in the generic header.

Parameters

size	Total size of the backend's private struct, whose first member must be a SerReader
ops	The backend's vtable
caps	Capabilities this backend advertises
flags	Per-document options

Returns

A zero-filled reader; never NULL

serReaderAddResolver()

void serReaderAddResolver	(	SerReader *	r,
		SerTypeResolver	fn,
		void *	user
	)

Adds a type resolver to this reader.

There is no global mutable type registry: resolution is explicit and per-reader, so the meaning of a stream never depends on what happened to be linked into the process. Resolvers are consulted in registration order, first match wins, and cx's own built-in resolver for its structural type names runs last.

Parameters

r	Reader to register with
fn	Resolver function
user	Opaque value passed back to the resolver

Example:

serReaderAddResolver(r, myStructSetResolver, (void*)&MyStructs_structset);

serReaderDestroy()

void serReaderDestroy

(

SerReader **

r

)

Releases the reader and sets the handle to NULL.

Readers have no finish step; nothing is buffered on the way in.

Parameters

r	Pointer to the reader handle; set to NULL on return

serReaderFail()

bool serReaderFail	(	SerReader *	r,
		int32	code,
		strref	msg
	)

Records an error against a reader and aborts the traversal.

Parameters

r	Reader to fail
code	SerErrorCodeEnum
msg	Human-readable description; copied

Returns

always false, so a failing op can return serReaderFail(...)

serReaderResolve()

bool serReaderResolve	(	SerResolved *	out,
		SerReader *	r,
		strref	name
	)

Resolves a wire type name through this reader's resolvers, then cx's built-in table.

Parameters

out	Receives the resolved type
r	Reader whose resolver list to consult
name	Wire type name

Returns

true if the name was recognized