epub_xml_consumer_internal.h File Reference

Private contracts for streamed EPUB XML consumers. More...

#include <stddef.h>
#include <stdint.h>
#include "epub_xml_shim_internal.h"
#include "ra8_attributes.h"
#include "xml.h"

Include dependency graph for epub_xml_consumer_internal.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	priv_attr_t
	Optional attribute span. More...

Functions
void	priv_epub_xml_copy (const uint8_t *source, size_t source_len, xml_span_t span, char *destination, size_t capacity)
	Copy decoded text into a bounded EPUB field.
priv_attr_t	priv_epub_xml_attr (const uint8_t *source, size_t source_len, const xml_event_t *event, const char *name)
	Find an exact-name attribute on one start event.
bool	priv_epub_xml_attr_contains (const uint8_t *source, size_t source_len, priv_attr_t attribute, const char *needle)
	Test whether a decoded attribute contains an ASCII literal.
xml_span_t	priv_epub_xml_frame_name (const xml_reader_t *reader, uint16_t frame)
	Return one live reader-frame name span.
bool	priv_epub_xml_direct_child (uint16_t child, uint16_t parent)
	Test whether a depth is exactly one level below another.
bool	priv_epub_xml_ancestor_frame (uint16_t depth, uint16_t levels, uint16_t *out_frame)
	Resolve a bounded ancestor frame index.
uint16_t	priv_epub_xml_ancestor_marker (const xml_reader_t *reader, uint16_t depth, uint16_t levels)
	Return a checked ancestor consumer marker.
ra8_err_t	priv_epub_xml_reader (xml_reader_t *reader, const uint8_t *source, size_t length, epub_xml_workspace_t *workspace)
	Initialise another validated EPUB pull pass.
ra8_err_t	priv_epub_xml_find (const uint8_t *source, size_t length, epub_xml_workspace_t *workspace, const char *local, bool use_parent, uint32_t parent_offset, uint16_t parent_depth, xml_event_t *out)
	Find the first local-name element under an optional direct parent.

Detailed Description

Private contracts for streamed EPUB XML consumers.

Declares the helpers every consumer unit shares and their caller-owned workspace rules; definitions defer here so generated documentation has one authoritative block. Each unit's own file-local helpers are declared beside it, in epub_xml_opf_internal.h and epub_xml_toc_internal.h, so neither unit sees a static prototype it does not define. [Ring 4 / EPUB] {World: NS}

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file epub_xml_consumer_internal.h.

Function Documentation

priv_epub_xml_ancestor_frame()

bool priv_epub_xml_ancestor_frame	(	uint16_t	depth,
		uint16_t	levels,
		uint16_t *	out_frame )

Resolve a bounded ancestor frame index.

Subtracts one level at a time to avoid narrowing or underflow.

Parameters

[in]	depth	Current event depth.
[in]	levels	Ancestor distance.
[out]	out_frame	Resolved frame index.

Returns

True when the ancestor exists.

Return values

false

levels exceeds depth.

Precondition

out_frame is writable.

Depth and levels are reader-bounded values.

Postcondition

Success sets out_frame exactly.

Failure leaves out_frame unchanged.

Note

Pure and thread-safe.

Since

0.1.0

Definition at line 98 of file epub_xml_shim.c.

Referenced by internal_ancestor_name(), internal_ncx_event(), and priv_epub_xml_ancestor_marker().

priv_epub_xml_ancestor_marker()

uint16_t priv_epub_xml_ancestor_marker	(	const xml_reader_t *	reader,
		uint16_t	depth,
		uint16_t	levels )

Return a checked ancestor consumer marker.

Converts an invalid ancestor request to zero.

Parameters

[in]	reader	Active reader.
[in]	depth	Current event depth.
[in]	levels	Ancestor distance.

Returns

Stored consumer marker or zero.

Return values

0	Ancestor does not exist or carries no marker.

Precondition

Reader workspace contains live frames for depth.

Marker zero remains the unassigned sentinel.

Postcondition

Reader/workspace bytes are unchanged.

Return is bounded to uint16_t.

Note

Pure with respect to parser state.

Since

0.1.0

Definition at line 113 of file epub_xml_shim.c.

References xml_frame_t::consumer, xml_workspace_t::frames, priv_epub_xml_ancestor_frame(), and xml_reader_t::workspace.

Referenced by internal_metadata_text(), and internal_nav_event().

priv_epub_xml_attr()

priv_attr_t priv_epub_xml_attr	(	const uint8_t *	source,
		size_t	source_len,
		const xml_event_t *	event,
		const char *	name )

Find an exact-name attribute on one start event.

Traverses source order and returns an optional source-aliasing span.

Parameters

[in]	source	Immutable XML source.
[in]	source_len	Exact source extent.
[in]	event	Valid start event.
[in]	name	NUL-terminated exact QName.

Returns

Optional attribute span.

Return values

present

Attribute matched.

Precondition

Event spans lie within source_len.

Source and name remain readable for the call.

Postcondition

No input memory is modified.

Absent result carries an empty span.

Note

Fail-closed if attribute replay is inconsistent.

Since

0.1.0

Definition at line 45 of file epub_xml_shim.c.

References k_ra8_ok, xml_attribute_t::name, xml_attribute_t::value, xml_attr_begin(), xml_attr_next(), and xml_span_equal().

Referenced by internal_collect_spine(), internal_manifest_item(), internal_manifest_lookup(), internal_mark_metadata(), internal_nav_event_start(), internal_ncx_event(), internal_opf_first_event(), internal_opf_metadata_child(), internal_opf_shape(), internal_select_nav(), and priv_epub_xml_parse_container().

priv_epub_xml_attr_contains()

bool priv_epub_xml_attr_contains	(	const uint8_t *	source,
		size_t	source_len,
		priv_attr_t	attribute,
		const char *	needle )

Test whether a decoded attribute contains an ASCII literal.

Decodes into the fixed EPUB path bound before substring search.

Parameters

[in]	source	Immutable XML source.
[in]	source_len	Exact source extent.
[in]	attribute	Optional encoded attribute.
[in]	needle	NUL-terminated search literal.

Returns

True only when the complete decoded value contains needle.

Return values

false

Attribute is absent, oversized, invalid, or does not contain it.

Precondition

Present span lies within source_len.

needle remains readable for the call.

Postcondition

No input memory is modified.

Temporary decoded bytes do not escape the call.

Note

Search semantics intentionally preserve the legacy substring policy.

Since

0.1.0

Definition at line 67 of file epub_xml_shim.c.

References k_epub_max_path_len, k_ra8_ok, priv_attr_t::present, priv_attr_t::span, strstr(), and xml_decode().

Referenced by internal_manifest_item(), and internal_select_nav().

priv_epub_xml_copy()

void priv_epub_xml_copy	(	const uint8_t *	source,
		size_t	source_len,
		xml_span_t	span,
		char *	destination,
		size_t	capacity )

Copy decoded text into a bounded EPUB field.

Truncates only at a complete entity/codepoint, matching legacy fields.

Parameters

[in]	source	Immutable XML source.
[in]	source_len	Exact source extent.
[in]	span	Encoded source-relative span.
[out]	destination	Bounded NUL-terminated output.
[in]	capacity	Writable capacity including NUL.

Precondition

span lies within source_len validated bytes.

Destination does not overlap source and has nonzero capacity.

Postcondition

Destination is NUL-terminated with a maximal complete prefix.

Source bytes remain unchanged.

Note

Decode cannot fail after document validation.

Since

0.1.0

Definition at line 35 of file epub_xml_shim.c.

References xml_decode_prefix().

Referenced by internal_manifest_item(), internal_metadata_text(), internal_nav_event(), internal_nav_event_start(), internal_ncx_event(), internal_opf_resolve_refs(), and priv_epub_xml_parse_container().

priv_epub_xml_direct_child()

bool priv_epub_xml_direct_child	(	uint16_t	child,
		uint16_t	parent )

Test whether a depth is exactly one level below another.

Guards UINT16_MAX before incrementing the parent depth.

Parameters

[in]	child	Candidate child depth.
[in]	parent	Candidate parent depth.

Returns

True only for an exact direct-child relationship.

Return values

false

Parent is sentinel or depths are not adjacent.

Precondition

Depth values use the XML reader coordinate system.

UINT16_MAX denotes no active parent.

Postcondition

No memory is modified.

Arithmetic does not wrap.

Note

Pure and thread-safe.

Since

0.1.0

Definition at line 89 of file epub_xml_shim.c.

Referenced by internal_collect_spine(), internal_manifest_lookup(), internal_nav_event_start(), internal_nav_has_list(), internal_opf_first_event(), internal_opf_shape(), internal_toc_capacity(), and priv_epub_xml_find().

priv_epub_xml_find()

ra8_err_t priv_epub_xml_find	(	const uint8_t *	source,
		size_t	length,
		epub_xml_workspace_t *	workspace,
		const char *	local,
		bool	use_parent,
		uint32_t	parent_offset,
		uint16_t	parent_depth,
		xml_event_t *	out )

Find the first local-name element under an optional direct parent.

Replays the validated source without retaining a DOM.

Parameters

[in]	source	Immutable XML source.
[in]	length	Exact source extent.
[in,out]	workspace	Exclusive reader scratch.
[in]	local	NUL-terminated local-name literal.
[in]	use_parent	Require the parent coordinates when true.
[in]	parent_offset	Parent start-markup offset.
[in]	parent_depth	Parent absolute depth.
[out]	out	Matching start event.

Returns

Repository error code.

Return values

k_ra8_ok	Matching element found.
k_ra8_err_validation_failed	Match absent or replay failed.

Precondition

Source passed complete validation.

Output/workspace are writable and source stays live.

Postcondition

Success fills a bounded source-aliasing event.

Failure leaves source unchanged and output unspecified.

Note

Workspace is scratch on return.

Since

0.1.0

Definition at line 129 of file epub_xml_shim.c.

References k_ra8_err_validation_failed, k_ra8_ok, k_xml_event_end, k_xml_event_none, k_xml_event_start, priv_epub_xml_direct_child(), priv_epub_xml_reader(), xml_reader_next(), and xml_span_local_equal().

Referenced by priv_epub_xml_parse_container(), and priv_epub_xml_parse_ncx().

priv_epub_xml_frame_name()

xml_span_t priv_epub_xml_frame_name	(	const xml_reader_t *	reader,
		uint16_t	frame )

Return one live reader-frame name span.

Reconstructs the source-relative span retained for close validation.

Parameters

[in]	reader	Active reader.
[in]	frame	Live frame index.

Returns

Source-relative element-name span.

Return values

span	Coordinates stored in the selected frame.

Precondition

reader and its workspace are valid.

frame is below the live stack size.

Postcondition

Reader/workspace bytes are unchanged.

Returned span continues to alias the reader source.

Note

Pure with respect to parser state.

Since

0.1.0

Definition at line 83 of file epub_xml_shim.c.

References xml_workspace_t::frames, xml_frame_t::name_length, xml_frame_t::name_offset, and xml_reader_t::workspace.

Referenced by internal_ancestor_depth(), internal_ancestor_name(), internal_collect_spine(), internal_manifest_lookup(), and internal_opf_first_event().

priv_epub_xml_reader()

ra8_err_t priv_epub_xml_reader	(	xml_reader_t *	reader,
		const uint8_t *	source,
		size_t	length,
		epub_xml_workspace_t *	workspace )

Initialise another validated EPUB pull pass.

Binds the shared reader stack within the caller-owned EPUB workspace.

Parameters

[out]	reader	Reader state to initialise.
[in]	source	Immutable complete XML source.
[in]	length	Exact source extent.
[in,out]	workspace	Exclusive EPUB XML scratch.

Returns

Repository error code.

Return values

k_ra8_ok	Reader initialised.
k_ra8_err_invalid_size	Source extent is invalid.

Precondition

All pointers are non-NULL.

Workspace is not shared with a live pass.

Postcondition

Success positions reader before its first event.

Source bytes remain unchanged.

Note

Caller already validated the same document.

Since

0.1.0

Definition at line 121 of file epub_xml_shim.c.

References epub_xml_workspace_t::reader, and xml_reader_init().

Referenced by internal_collect_spine(), internal_manifest_lookup(), internal_nav_has_list(), internal_opf_first(), internal_opf_shape(), internal_select_nav(), internal_toc_capacity(), priv_epub_xml_find(), priv_epub_xml_parse_nav(), and priv_epub_xml_parse_ncx().