zxsd typed bindings

Read and write generated typed XML structures. More...

Data Structures
struct	zxsd_bind_field
	Generated descriptor for one member of a bound structure. More...
struct	zxsd_bind_type
	Generated descriptor for a bound structure. More...
struct	zxsd_bind_namespace_t
	Namespace prefix declared on the root element when writing. More...
struct	zxsd_bind_root_t
	Generated descriptor for a bound global element. More...
struct	zxsd_bind_arena_t
	Caller-owned bump allocator used when reading a document. More...
struct	zxsd_bind_path_step_t
	One generation-time-resolved element step; prefixes are not identities. More...
struct	zxsd_bind_selection_t
	Immutable selection emitted by zxsdc --stream-bind. More...
struct	zxsd_bind_stream_frame_t
	Internal binding frame, exposed only for static allocation. More...
struct	zxsd_bind_stream_t
	Single-pass validating typed reader with caller-owned, reusable storage. More...
struct	zxsd_bind_runtime_config_t
	Binding-specific layout stamp; initialize with ZXSD_BIND_RUNTIME_CONFIG_INIT. More...

Macros
#define	ZXSD_BIND_NO_OFFSET   ((size_t)(-1))
	Offset value marking an absent presence or count member.
#define	ZXSD_BIND_RUNTIME_CONFIG_INIT
	Initialize a binding stamp using the application's headers and compile definitions.

Typedefs
typedef struct zxsd_bind_field	zxsd_bind_field_t
	Generated descriptor for one member of a bound structure.
typedef struct zxsd_bind_type	zxsd_bind_type_t
	Generated descriptor for a bound structure.
typedef const zxsd_schema_t *(*	zxsd_bind_schema_fn) (void)
	Access a generated schema descriptor.
typedef int(*	zxsd_bind_sink_fn) (void *context, const char *data, size_t length)
	Output callback used by zxsd_bind_write.
typedef zxsd_bind_action_t(*	zxsd_bind_item_fn) (void *user_data, const void *object)
	Receive one complete, locally validated selected subtree.

Enumerations
enum	zxsd_bind_kind_t {   ZXSD_BIND_STRING = 0 , ZXSD_BIND_BOOLEAN , ZXSD_BIND_INT8 , ZXSD_BIND_UINT8 ,   ZXSD_BIND_INT16 , ZXSD_BIND_UINT16 , ZXSD_BIND_INT32 , ZXSD_BIND_UINT32 ,   ZXSD_BIND_INT64 , ZXSD_BIND_UINT64 , ZXSD_BIND_ENUM , ZXSD_BIND_COMPLEX }
	C representation of one bound value. More...
enum	zxsd_bind_role_t { ZXSD_BIND_ATTRIBUTE = 0 , ZXSD_BIND_ELEMENT , ZXSD_BIND_CONTENT }
	XML item carrying a bound value. More...
enum	zxsd_bind_storage_t { ZXSD_BIND_INLINE = 0 , ZXSD_BIND_POINTER , ZXSD_BIND_ARRAY }
	Storage layout of a bound member inside its structure. More...
enum	zxsd_bind_action_t { ZXSD_BIND_CONTINUE = 0 , ZXSD_BIND_VALIDATE_ONLY , ZXSD_BIND_CALLBACK_ERROR }
	Next action after one locally validated, typed subtree has been delivered. More...

Functions
void	zxsd_bind_arena_init (zxsd_bind_arena_t *arena, void *storage, size_t capacity)
	Initialize a reading arena over caller-provided storage.
void	ZXSD_BINDING_ABI_GUARD (void)
	Link-time binding ABI guard used by generated code; no side effects.
zxsd_result_t	zxsd_bind_check_runtime (const zxsd_bind_runtime_config_t *expected)
	Check core configuration and binding layout sizes before using bindings.
zxsd_result_t	zxsd_bind_stream_init (zxsd_bind_stream_t *reader, const zxsd_bind_selection_t *selection, void *object, zxsd_bind_arena_t *arena, zxsd_bind_item_fn callback, void *user_data, const zxsd_allocator_t *allocator)
	Initialize a single-pass selected-subtree binding reader.
zxsd_result_t	zxsd_bind_stream_feed (zxsd_bind_stream_t *reader, const void *data, size_t length)
	Consume arbitrary raw XML bytes without retaining the fragment.
zxsd_result_t	zxsd_bind_stream_finish (zxsd_bind_stream_t *reader)
	Finish parsing and validate document-wide constraints.
void	zxsd_bind_stream_dispose (zxsd_bind_stream_t *reader)
	Release identity scratch, clear output, and restore the borrowed arena.
zxsd_result_t	zxsd_bind_read (const zxsd_bind_root_t *root, const char *xml, void *object, zxsd_bind_arena_t *arena)
	Validate a document and fill a bound structure from it.
zxsd_result_t	zxsd_bind_read_with_allocator (const zxsd_bind_root_t *root, const char *xml, void *object, zxsd_bind_arena_t *arena, const zxsd_allocator_t *allocator)
	Read like zxsd_bind_read, validating with a scratch allocator.
zxsd_result_t	zxsd_bind_write (const zxsd_bind_root_t *root, const void *object, zxsd_bind_sink_fn sink, void *context, zxsd_stream_t *validator)
	Serialize a bound structure as an XML document.
zxsd_result_t	zxsd_bind_write_buffer (const zxsd_bind_root_t *root, const void *object, char *buffer, size_t capacity, size_t *length)
	Serialize a bound structure into a buffer and validate the result.
zxsd_result_t	zxsd_bind_write_buffer_with_allocator (const zxsd_bind_root_t *root, const void *object, char *buffer, size_t capacity, size_t *length, const zxsd_allocator_t *allocator)
	Write like zxsd_bind_write_buffer, validating with a scratch allocator.

Detailed Description

Read and write generated typed XML structures.

Macro Definition Documentation

ZXSD_BIND_NO_OFFSET

#define ZXSD_BIND_NO_OFFSET   ((size_t)(-1))

Offset value marking an absent presence or count member.

Definition at line 43 of file zxsd_bind.h.

ZXSD_BIND_RUNTIME_CONFIG_INIT

#define ZXSD_BIND_RUNTIME_CONFIG_INIT

Value:

    {                                                                                          \
        ZXSD_RUNTIME_CONFIG_INIT, ZXSD_BINDING_ABI_VERSION,                                \
        {                                                                                  \
            sizeof(zxsd_bind_field_t), sizeof(zxsd_bind_type_t),                       \
                sizeof(zxsd_bind_root_t), sizeof(zxsd_bind_arena_t),               \
                sizeof(zxsd_bind_stream_t), sizeof(zxsd_bind_stream_frame_t)       \
        }                                                                                  \
    }

Initialize a binding stamp using the application's headers and compile definitions.

Definition at line 243 of file zxsd_bind.h.

Typedef Documentation

zxsd_bind_item_fn

typedef zxsd_bind_action_t(* zxsd_bind_item_fn) (void *user_data, const void *object)

Receive one complete, locally validated selected subtree.

The object and all arena pointers are valid only during the callback. Copy needed values into application storage. Delivery is provisional: later XML or document-wide identity validation can still fail at finish. Do not feed, finish, dispose, or reset the reader/arena from this callback.

Parameters

[in]	user_data	Application context.
[in]	object	Value of the selected generated type.

Returns

Whether to continue, validate only, or report a callback error.

Definition at line 209 of file zxsd_bind.h.

zxsd_bind_schema_fn

typedef const zxsd_schema_t *(* zxsd_bind_schema_fn) (void)

Access a generated schema descriptor.

Returns

Generated immutable schema descriptor.

Definition at line 125 of file zxsd_bind.h.

zxsd_bind_sink_fn

typedef int(* zxsd_bind_sink_fn) (void *context, const char *data, size_t length)

Output callback used by zxsd_bind_write.

Parameters

[in]	context	Caller context passed to zxsd_bind_write.
[in]	data	UTF-8 bytes to append. They are not NUL-terminated.
[in]	length	Number of bytes in data.

Return values

0	The bytes were accepted.
nonzero	Output failed; writing stops with ZXSD_ERR_OUTPUT.

Definition at line 162 of file zxsd_bind.h.

Enumeration Type Documentation

zxsd_bind_action_t

enum zxsd_bind_action_t

Next action after one locally validated, typed subtree has been delivered.

Enumerator
ZXSD_BIND_CONTINUE	Materialize the next occurrence with the same arena.
ZXSD_BIND_VALIDATE_ONLY	Stop materializing, but validate the remaining document.
ZXSD_BIND_CALLBACK_ERROR	Reject delivery with ZXSD_ERR_OUTPUT.

Definition at line 174 of file zxsd_bind.h.

zxsd_bind_kind_t

enum zxsd_bind_kind_t

C representation of one bound value.

Enumerator
ZXSD_BIND_STRING	const char * NUL-terminated UTF-8 text.
ZXSD_BIND_BOOLEAN	bool.
ZXSD_BIND_INT8	int8_t, from xs:byte.
ZXSD_BIND_UINT8	uint8_t, from xs:unsignedByte.
ZXSD_BIND_INT16	int16_t, from xs:short.
ZXSD_BIND_UINT16	uint16_t, from xs:unsignedShort.
ZXSD_BIND_INT32	int32_t, from xs:int.
ZXSD_BIND_UINT32	uint32_t, from xs:unsignedInt.
ZXSD_BIND_INT64	int64_t, from xs:long.
ZXSD_BIND_UINT64	uint64_t, from xs:unsignedLong.
ZXSD_BIND_ENUM	Generated C enumeration indexing a value table.
ZXSD_BIND_COMPLEX	Generated structure described by zxsd_bind_type_t.

Definition at line 46 of file zxsd_bind.h.

zxsd_bind_role_t

enum zxsd_bind_role_t

XML item carrying a bound value.

Enumerator
ZXSD_BIND_ATTRIBUTE	Attribute of the enclosing element.
ZXSD_BIND_ELEMENT	Child element.
ZXSD_BIND_CONTENT	Character content of a simpleContent element.

Definition at line 62 of file zxsd_bind.h.

zxsd_bind_storage_t

enum zxsd_bind_storage_t

Storage layout of a bound member inside its structure.

Enumerator
ZXSD_BIND_INLINE	The value is stored in the member itself. Optional scalars use a bool presence member; optional strings use NULL for absence.
ZXSD_BIND_POINTER	The member is a const pointer to one item; NULL means absent.
ZXSD_BIND_ARRAY	The member is a const pointer to items with a size_t count member.

Definition at line 69 of file zxsd_bind.h.

Function Documentation

zxsd_bind_arena_init()

void zxsd_bind_arena_init	(	zxsd_bind_arena_t *	arena,
		void *	storage,
		size_t	capacity
	)

Initialize a reading arena over caller-provided storage.

Parameters

[out]	arena	Arena to initialize.
[in]	storage	First byte of the storage, or NULL when capacity is zero.
[in]	capacity	Number of usable bytes in storage.

zxsd_bind_check_runtime()

zxsd_result_t zxsd_bind_check_runtime

(

const zxsd_bind_runtime_config_t *

expected

)

Check core configuration and binding layout sizes before using bindings.

Parameters

[in]

expected

Application stamp using ZXSD_BIND_RUNTIME_CONFIG_INIT.

Return values

ZXSD_OK	All recorded epochs, limits, and sizes match.
ZXSD_ERR_ARGUMENT	The stamp is NULL.
ZXSD_ERR_INCOMPATIBLE_ABI	Core or binding configuration differs.

Returns

A structured result. The toolchain requirements of zxsd_check_runtime apply.

zxsd_bind_read()

zxsd_result_t zxsd_bind_read	(	const zxsd_bind_root_t *	root,
		const char *	xml,
		void *	object,
		zxsd_bind_arena_t *	arena
	)

Validate a document and fill a bound structure from it.

The document is first validated with the root schema descriptor, so the result is either a complete structure for a valid document or an error. On failure the structure is zeroed and the arena is restored to its previous usage.

Parameters

[in]	root	Generated root binding.
[in]	xml	NUL-terminated XML document.
[out]	object	Structure of type root->type to fill.
[in,out]	arena	Arena receiving strings, arrays and optional structures.

Return values

ZXSD_OK	The structure was filled.
ZXSD_ERR_ARGUMENT	An argument is invalid.
ZXSD_ERR_RESOURCE_LIMIT	The arena is too small.
ZXSD_ERR_UNSUPPORTED	The valid document uses an xsi:type substitution or xsi:nil that the binding cannot represent.

Returns

Any validation result produced by zxsd_validate otherwise.

zxsd_bind_read_with_allocator()

zxsd_result_t zxsd_bind_read_with_allocator	(	const zxsd_bind_root_t *	root,
		const char *	xml,
		void *	object,
		zxsd_bind_arena_t *	arena,
		const zxsd_allocator_t *	allocator
	)

Read like zxsd_bind_read, validating with a scratch allocator.

The allocator is used only by identity-constraint validation, exactly as in zxsd_validate_with_allocator. Pass NULL for zero-heap operation.

Parameters

[in]	root	Generated root binding.
[in]	xml	NUL-terminated XML document.
[out]	object	Structure of type root->type to fill.
[in,out]	arena	Arena receiving strings, arrays and optional structures.
[in]	allocator	Scratch allocator, or NULL.

Returns

A structured binding or validation result.

zxsd_bind_stream_dispose()

void zxsd_bind_stream_dispose

(

zxsd_bind_stream_t *

reader

)

Release identity scratch, clear output, and restore the borrowed arena.

Parameters

[in,out]

reader

Initialized reader, or NULL.

zxsd_bind_stream_feed()

zxsd_result_t zxsd_bind_stream_feed	(	zxsd_bind_stream_t *	reader,
		const void *	data,
		size_t	length
	)

Consume arbitrary raw XML bytes without retaining the fragment.

Parameters

[in,out]	reader	Initialized reader.
[in]	data	Bytes to consume, or NULL for zero length.
[in]	length	Byte count.

Returns

The first sticky parser, validation, conversion, or capacity error, or success.

zxsd_bind_stream_finish()

zxsd_result_t zxsd_bind_stream_finish

(

zxsd_bind_stream_t *

reader

)

Finish parsing and validate document-wide constraints.

Parameters

[in,out]

reader

Initialized reader.

Returns

The final document result; earlier callbacks alone do not imply success.

zxsd_bind_stream_init()

zxsd_result_t zxsd_bind_stream_init	(	zxsd_bind_stream_t *	reader,
		const zxsd_bind_selection_t *	selection,
		void *	object,
		zxsd_bind_arena_t *	arena,
		zxsd_bind_item_fn	callback,
		void *	user_data,
		const zxsd_allocator_t *	allocator
	)

Initialize a single-pass selected-subtree binding reader.

The complete document is validated once. Unselected content consumes no binding arena. Arrays grow in the explicit arena; exhaustion is an error, never truncation. The arena returns to its initial mark after every callback. All storage and descriptors must remain alive through dispose. Generated wrappers provide a typed object and callback interface to this function.

Parameters

[out]	reader	Reader to initialize.
[in]	selection	Generated absolute-path selection.
[out]	object	Structure of type selection->type, reused for each delivery.
[in,out]	arena	Storage for strings, arrays, and optional structures.
[in]	callback	Delivery callback.
[in]	user_data	Application context.
[in]	allocator	Identity scratch allocator, or NULL for zero-heap validation.

Returns

A structured initialization result.

zxsd_bind_write()

zxsd_result_t zxsd_bind_write	(	const zxsd_bind_root_t *	root,
		const void *	object,
		zxsd_bind_sink_fn	sink,
		void *	context,
		zxsd_stream_t *	validator
	)

Serialize a bound structure as an XML document.

Structural rules expressed by the C representation are checked while writing: required strings and nested structures must be present and array counts must respect occurrence bounds. Facets, choices and identity constraints are enforced by validation.

Parameters

[in]	root	Generated root binding.
[in]	object	Structure of type root->type to serialize.
[in]	sink	Output callback.
[in]	context	Opaque context passed to sink.
[in,out]	validator	Optional streaming validator initialized for root->schema(), or NULL. When present, every written item is also validated and the first validation error stops writing.

Return values

ZXSD_OK	The document was written and, if requested, validated.
ZXSD_ERR_ARGUMENT	An argument or array pointer is invalid.
ZXSD_ERR_MISSING_ELEMENT	A required string or structure is NULL.
ZXSD_ERR_MISSING_ATTRIBUTE	A required attribute string is NULL.
ZXSD_ERR_OCCURRENCE	An array count violates its occurrence bounds.
ZXSD_ERR_INVALID_VALUE	A string is not XML text or an enumeration is out of range.
ZXSD_ERR_EXCESSIVE_NESTING	Structures nest deeper than ZXSD_MAX_DEPTH.
ZXSD_ERR_OUTPUT	sink reported a failure.

Returns

Any streaming validation result otherwise.

zxsd_bind_write_buffer()

zxsd_result_t zxsd_bind_write_buffer	(	const zxsd_bind_root_t *	root,
		const void *	object,
		char *	buffer,
		size_t	capacity,
		size_t *	length
	)

Serialize a bound structure into a buffer and validate the result.

The output is NUL-terminated whenever it fits. It is then validated with zxsd_validate, which also checks identity constraints.

Parameters

[in]	root	Generated root binding.
[in]	object	Structure of type root->type to serialize.
[out]	buffer	Destination buffer.
[in]	capacity	Size of buffer, including the terminating NUL.
[out]	length	Optional output receiving the document length without NUL.

Return values

ZXSD_OK	The document was written and is valid.
ZXSD_ERR_OUTPUT	buffer is too small.

Returns

Any result of zxsd_bind_write or zxsd_validate otherwise.

zxsd_bind_write_buffer_with_allocator()

zxsd_result_t zxsd_bind_write_buffer_with_allocator	(	const zxsd_bind_root_t *	root,
		const void *	object,
		char *	buffer,
		size_t	capacity,
		size_t *	length,
		const zxsd_allocator_t *	allocator
	)

Write like zxsd_bind_write_buffer, validating with a scratch allocator.

The allocator is used only by identity-constraint validation, exactly as in zxsd_validate_with_allocator. Pass NULL for zero-heap operation.

Parameters

[in]	root	Generated root binding.
[in]	object	Structure of type root->type to serialize.
[out]	buffer	Destination buffer.
[in]	capacity	Size of buffer, including the terminating NUL.
[out]	length	Optional output receiving the document length without NUL.
[in]	allocator	Scratch allocator, or NULL.

Returns

A structured binding or validation result.