epub_xml_shim.c File Reference

Strict bounded container/OPF/NCX/nav XML consumers. More...

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

Include dependency graph for epub_xml_shim.c:

Go to the source code of this file.

Enumerations
enum	priv_marker_t : uint16_t {   k_priv_mark_none = 0U ,   k_priv_mark_title = 1U ,   k_priv_mark_creator = 2U ,   k_priv_mark_language = 3U ,   k_priv_mark_identifier = 4U ,   k_priv_mark_identifier_match = 5U }
	Consumer markers stored in live reader frames. 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.
ra8_err_t	priv_epub_xml_parse_container (const uint8_t *xml_bytes, size_t xml_len, epub_container_result_t *out, epub_xml_workspace_t *workspace)
	Parse META-INF/container.xml and copy the rootfile path out.
static bool	internal_font_type (const uint8_t *source, size_t source_len, priv_attr_t media)
static void	internal_manifest_item (const uint8_t *source, size_t source_len, const xml_event_t *event, epub_book_t *book)
static void	internal_metadata_text (const uint8_t *source, size_t source_len, const xml_event_t *event, const xml_reader_t *reader, epub_book_t *book)
static void	internal_mark_metadata (const uint8_t *source, size_t source_len, const xml_event_t *event, xml_reader_t *reader, xml_span_t unique_id)
static ra8_err_t	internal_opf_status (ra8_err_t err, uint16_t manifest_depth, uint16_t spine_depth)
static void	internal_opf_metadata_child (const uint8_t *source, size_t length, const xml_event_t *event, xml_reader_t *reader, xml_span_t unique_id, epub_book_t *book)
	Record one direct metadata child of the OPF metadata element.
static void	internal_opf_first_event (const uint8_t *source, size_t length, const xml_event_t *event, xml_reader_t *reader, epub_book_t *book, uint16_t *metadata_depth, uint16_t *manifest_depth, uint16_t *spine_depth, xml_span_t *unique_id, xml_span_t *out_spine_toc)
	Classify one OPF start-tag event during the first parse pass.
static ra8_err_t	internal_opf_first (const uint8_t *source, size_t length, epub_book_t *book, xml_span_t *out_spine_toc)
static ra8_err_t	internal_collect_spine (const uint8_t *source, size_t length, epub_book_t *book)
static ra8_err_t	internal_manifest_lookup (const uint8_t *source, size_t length, epub_xml_workspace_t *workspace, xml_span_t wanted, xml_span_t *out_href)
static ra8_err_t	internal_opf_shape (const uint8_t *source, size_t length, epub_xml_workspace_t *workspace)
static ra8_err_t	internal_opf_resolve_refs (const uint8_t *xml_bytes, size_t xml_len, xml_span_t spine_toc, epub_book_t *book)
	Resolve chapter, cover, and TOC hrefs from cross-referenced ids.
ra8_err_t	priv_epub_xml_parse_opf (const uint8_t *xml_bytes, size_t xml_len, epub_book_t *book)
	Parse the OPF document into metadata, cover and spine.

Detailed Description

Strict bounded container/OPF/NCX/nav XML consumers.

Replays validated immutable XML through a caller-owned pull-reader workspace and commits EPUB metadata, spine, and TOC fields only after every syntax, shape, and fixed-capacity preflight succeeds.

[Ring 4 / EPUB] {World: NS}

Copyright

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

Definition in file epub_xml_shim.c.

Enumeration Type Documentation

priv_marker_t

enum priv_marker_t : uint16_t

Consumer markers stored in live reader frames.

Enumerator
k_priv_mark_none	Frame carries no metadata role.
k_priv_mark_title	Frame is a Dublin Core title.
k_priv_mark_creator	Frame is a Dublin Core creator.
k_priv_mark_language	Frame is a Dublin Core language.
k_priv_mark_identifier	Frame is a fallback identifier.
k_priv_mark_identifier_match	Frame matches the package identifier.

Definition at line 26 of file epub_xml_shim.c.

Function Documentation

internal_collect_spine()

ra8_err_t internal_collect_spine ( const uint8_t * source, size_t length, epub_book_t * book )

static

Definition at line 479 of file epub_xml_shim.c.

References k_epub_max_chapters, k_ra8_err_no_mem, k_ra8_ok, k_xml_event_none, k_xml_event_start, priv_attr_t::present, priv_epub_xml_attr(), priv_epub_xml_direct_child(), priv_epub_xml_frame_name(), priv_epub_xml_reader(), epub_xml_workspace_t::reference_count, epub_xml_workspace_t::references, priv_attr_t::span, xml_reader_next(), xml_span_equal(), xml_span_local_equal(), and epub_book_t::xml_workspace.

Referenced by priv_epub_xml_parse_opf().

internal_font_type()

bool internal_font_type ( const uint8_t * source, size_t source_len, priv_attr_t media )

static

Definition at line 212 of file epub_xml_shim.c.

References priv_attr_t::present, priv_attr_t::span, and xml_span_equal().

internal_manifest_item()

void internal_manifest_item ( const uint8_t * source, size_t source_len, const xml_event_t * event, epub_book_t * book )

static

Definition at line 227 of file epub_xml_shim.c.

References epub_book_t::cover_path, epub_book_t::embedded_font_count, epub_book_t::embedded_font_paths, epub_manifest_item_t::href, epub_manifest_item_t::id, internal_font_type(), k_epub_max_fonts, k_epub_max_manifest, k_epub_max_path_len, k_epub_toc_nav, epub_book_t::manifest, epub_book_t::manifest_count, epub_manifest_item_t::media_type, priv_attr_t::present, priv_epub_xml_attr(), priv_epub_xml_attr_contains(), priv_epub_xml_copy(), RA8_INTERNAL, priv_attr_t::span, epub_book_t::toc_kind, and epub_book_t::toc_path.

Referenced by internal_opf_first_event().

internal_manifest_lookup()

ra8_err_t internal_manifest_lookup ( const uint8_t * source, size_t length, epub_xml_workspace_t * workspace, xml_span_t wanted, xml_span_t * out_href )

static

Definition at line 519 of file epub_xml_shim.c.

References k_ra8_err_no_data, k_ra8_ok, k_xml_event_none, k_xml_event_start, priv_attr_t::present, priv_epub_xml_attr(), priv_epub_xml_direct_child(), priv_epub_xml_frame_name(), priv_epub_xml_reader(), RA8_INTERNAL, priv_attr_t::span, xml_decoded_equal(), xml_reader_next(), and xml_span_local_equal().

Referenced by internal_opf_resolve_refs().

internal_mark_metadata()

void internal_mark_metadata ( const uint8_t * source, size_t source_len, const xml_event_t * event, xml_reader_t * reader, xml_span_t unique_id )

static

Definition at line 298 of file epub_xml_shim.c.

References xml_frame_t::consumer, xml_workspace_t::frames, k_priv_mark_creator, k_priv_mark_identifier, k_priv_mark_identifier_match, k_priv_mark_language, k_priv_mark_none, k_priv_mark_title, xml_span_t::length, xml_event_t::name, priv_epub_xml_attr(), RA8_INTERNAL, xml_reader_t::workspace, xml_decoded_equal(), and xml_span_local_equal().

Referenced by internal_opf_metadata_child().

internal_metadata_text()

void internal_metadata_text ( const uint8_t * source, size_t source_len, const xml_event_t * event, const xml_reader_t * reader, epub_book_t * book )

static

Definition at line 270 of file epub_xml_shim.c.

References epub_book_t::author, xml_event_t::depth, epub_book_t::identifier, k_priv_mark_creator, k_priv_mark_identifier, k_priv_mark_identifier_match, k_priv_mark_language, k_priv_mark_title, epub_book_t::language, xml_event_t::markup, priv_epub_xml_ancestor_marker(), priv_epub_xml_copy(), RA8_INTERNAL, and epub_book_t::title.

Referenced by internal_opf_first().

internal_opf_first()

ra8_err_t internal_opf_first ( const uint8_t * source, size_t length, epub_book_t * book, xml_span_t * out_spine_toc )

static

Definition at line 438 of file epub_xml_shim.c.

References internal_metadata_text(), internal_opf_first_event(), internal_opf_status(), k_ra8_ok, k_xml_event_none, k_xml_event_start, k_xml_event_text, priv_epub_xml_reader(), RA8_INTERNAL, xml_reader_next(), and epub_book_t::xml_workspace.

Referenced by priv_epub_xml_parse_opf().

internal_opf_first_event()

void internal_opf_first_event ( const uint8_t * source, size_t length, const xml_event_t * event, xml_reader_t * reader, epub_book_t * book, uint16_t * metadata_depth, uint16_t * manifest_depth, uint16_t * spine_depth, xml_span_t * unique_id, xml_span_t * out_spine_toc )

static

Classify one OPF start-tag event during the first parse pass.

Records the package unique-identifier attribute at depth 0, remembers where <metadata>, <manifest>, and <spine> begin, and forwards a direct metadata or manifest-item child to its own handler.

Parameters

[in]	source	Complete OPF byte range being parsed.
[in]	length	Readable bytes at source.
[in]	event	Start-tag event being classified.
[in,out]	reader	Reader whose frame stack names enclosing elements.
[in,out]	book	Book whose XML workspace receives recorded values.
[in,out]	metadata_depth	Depth of <metadata>, or UINT16_MAX.
[in,out]	manifest_depth	Depth of <manifest>, or UINT16_MAX.
[in,out]	spine_depth	Depth of <spine>, or UINT16_MAX.
[in,out]	unique_id	Span naming the package unique-identifier.
[out]	out_spine_toc	Spine toc attribute span, set once seen.

Returns

Nothing.

Precondition

event->kind is k_xml_event_start.

book owns a live XML workspace.

Postcondition

At most one tracked depth, the unique-id span, the spine toc span, or a forwarded child handler's effects is updated.

A start tag matching no arm leaves every tracked depth, the unique-id span, and book byte-for-byte as they were.

Note

Extracted from internal_opf_first so both stay within the 60-line function cap; the vectors that cover it are unchanged.

Since

0.1.0

Definition at line 396 of file epub_xml_shim.c.

References xml_event_t::depth, internal_manifest_item(), internal_opf_metadata_child(), xml_event_t::name, priv_attr_t::present, priv_epub_xml_attr(), priv_epub_xml_direct_child(), priv_epub_xml_frame_name(), RA8_INTERNAL, priv_attr_t::span, and xml_span_local_equal().

Referenced by internal_opf_first().

internal_opf_metadata_child()

void internal_opf_metadata_child ( const uint8_t * source, size_t length, const xml_event_t * event, xml_reader_t * reader, xml_span_t unique_id, epub_book_t * book )

static

Record one direct metadata child of the OPF metadata element.

Marks the Dublin Core element, then captures the EPUB 2 legacy cover pointer carried by <meta name="cover" content="..."/>.

Parameters

[in]	source	Complete OPF byte range being parsed.
[in]	length	Readable bytes at source.
[in]	event	Start event for the metadata child.
[in,out]	reader	Reader whose frame stack names the enclosing element.
[in]	unique_id	Span naming the package unique-identifier attribute.
[in,out]	book	Book whose XML workspace receives the recorded values.

Returns

Nothing.

Precondition

event is a start event whose parent is the metadata element.

book owns a live XML workspace.

Postcondition

Recognised Dublin Core elements are marked in the workspace.

A legacy cover meta records its content span; nothing else is touched.

Note

Extracted from internal_opf_first so both stay within the 60-line function cap; the vectors that cover it are unchanged.

Since

0.1.0

Definition at line 352 of file epub_xml_shim.c.

References internal_mark_metadata(), epub_xml_workspace_t::legacy_cover_id, xml_event_t::name, priv_attr_t::present, priv_epub_xml_attr(), RA8_INTERNAL, priv_attr_t::span, xml_span_equal(), xml_span_local_equal(), and epub_book_t::xml_workspace.

Referenced by internal_opf_first_event().

internal_opf_resolve_refs()

ra8_err_t internal_opf_resolve_refs ( const uint8_t * xml_bytes, size_t xml_len, xml_span_t spine_toc, epub_book_t * book )

static

Resolve chapter, cover, and TOC hrefs from cross-referenced ids.

Looks up each spine reference internal_collect_spine already gathered against the manifest to fill in the ordered chapter path table, then resolves the legacy cover id and the spine toc= attribute the same way.

Parameters

[in]	xml_bytes	Complete OPF byte range.
[in]	xml_len	Readable bytes at xml_bytes.
[in]	spine_toc	Spine toc attribute span, or empty if absent.
[in,out]	book	Book whose chapter/cover/toc fields are filled in.

Returns

Canonical status.

Return values

k_ra8_ok	Every manifest lookup that mattered succeeded or was legitimately absent.
other	The first manifest-lookup failure that is not "no data".

Precondition

book's spine references were already collected.

book's xml_workspace names a live reader over xml_bytes.

Postcondition

book->chapter_paths holds one entry per resolved spine reference and book->chapter_count is their count.

book->cover_path and book->toc_path are filled when their source ids resolve; book->toc_kind may flip to the NCX kind.

Note

Extracted from priv_epub_xml_parse_opf so both stay within the 60-line function cap; the vectors that cover it are unchanged.

Since

0.1.0

Definition at line 624 of file epub_xml_shim.c.

References epub_book_t::chapter_count, epub_book_t::chapter_paths, epub_book_t::cover_path, internal_manifest_lookup(), k_epub_max_path_len, k_epub_toc_nav, k_epub_toc_ncx, k_ra8_err_no_data, k_ra8_ok, epub_xml_workspace_t::legacy_cover_id, xml_span_t::length, priv_epub_xml_copy(), RA8_INTERNAL, epub_xml_workspace_t::reference_count, epub_xml_workspace_t::references, epub_book_t::toc_kind, epub_book_t::toc_path, and epub_book_t::xml_workspace.

Referenced by priv_epub_xml_parse_opf().

internal_opf_shape()

ra8_err_t internal_opf_shape ( const uint8_t * source, size_t length, epub_xml_workspace_t * workspace )

static

Definition at line 559 of file epub_xml_shim.c.

References k_epub_max_chapters, k_ra8_err_no_mem, k_ra8_err_validation_failed, k_ra8_ok, k_xml_event_none, k_xml_event_start, priv_epub_xml_attr(), priv_epub_xml_direct_child(), priv_epub_xml_reader(), xml_reader_next(), xml_span_equal(), and xml_span_local_equal().

Referenced by priv_epub_xml_parse_opf().

internal_opf_status()

ra8_err_t internal_opf_status ( ra8_err_t err, uint16_t manifest_depth, uint16_t spine_depth )

static

Definition at line 325 of file epub_xml_shim.c.

References k_ra8_err_validation_failed, and k_ra8_ok.

Referenced by internal_opf_first().

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_parse_container()

ra8_err_t priv_epub_xml_parse_container	(	const uint8_t *	xml_bytes,
		size_t	xml_len,
		epub_container_result_t *	out,
		epub_xml_workspace_t *	workspace )

Parse META-INF/container.xml and copy the rootfile path out.

Reads the <rootfiles>/<rootfile full-path=...> attribute of the first rootfile entry. The complete immutable document is validated before out changes. Decoded paths longer than the fixed result field are truncated at a complete XML entity or UTF-8 sequence, matching the legacy bounded-field contract.

Parameters

[in]	xml_bytes	Container document bytes. Not NUL-terminated.
[in]	xml_len	Exact readable extent of xml_bytes in bytes.
[out]	out	Receives the rootfile path.
[in,out]	workspace	Exclusive caller-owned XML scratch workspace.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Rootfile path copied into out.
k_ra8_err_null_ptr	xml_bytes or out was NULL.
k_ra8_err_invalid_size	xml_len is zero.
k_ra8_err_validation_failed	The document is malformed or no usable rootfile path exists.

Precondition

xml_bytes is readable for xml_len bytes.

out and workspace point at writable non-overlapping storage.

Postcondition

On success out->opf_path is NUL-terminated; on failure out is unchanged. Workspace bytes are scratch and unspecified on return.

The function performs no dynamic allocation and never changes the source.

Note

Thread-safe for distinct outputs and workspaces.

See also

priv_epub_xml_parse_opf()

Since

0.1.0

Definition at line 168 of file epub_xml_shim.c.

References xml_event_t::depth, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_err_validation_failed, k_ra8_ok, xml_span_t::length, xml_event_t::markup, xml_span_t::offset, epub_container_result_t::opf_path, priv_attr_t::present, priv_epub_xml_attr(), priv_epub_xml_copy(), priv_epub_xml_find(), epub_xml_workspace_t::reader, priv_attr_t::span, and xml_validate().

Referenced by internal_parse_archive().

priv_epub_xml_parse_opf()

ra8_err_t priv_epub_xml_parse_opf	(	const uint8_t *	xml_bytes,
		size_t	xml_len,
		epub_book_t *	book )

Parse the OPF document into metadata, cover and spine.

The complete document, required OPF shape, and spine capacity are checked before semantic fields change. On success chapter_count, chapter paths, metadata, manifest resources, cover, fonts, and TOC source are written from the OPF <metadata>, <manifest> and <spine> sections.

Parameters

[in]	xml_bytes	OPF document bytes. Not NUL-terminated.
[in]	xml_len	Exact readable extent of xml_bytes in bytes.
[in,out]	book	Book record to fill in.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Metadata, spine and cover recorded.
k_ra8_err_null_ptr	xml_bytes or book was NULL.
k_ra8_err_invalid_size	xml_len is zero.
k_ra8_err_validation_failed	The XML or required OPF shape is invalid.
k_ra8_err_no_mem	The spine exceeds the fixed chapter capacity.

Precondition

xml_bytes is readable for xml_len bytes.

book points at writable storage and its embedded XML workspace is not used by another live parse.

Postcondition

On documented input/shape/capacity failure, externally visible book fields are unchanged; embedded workspace scratch is unspecified.

The function performs no dynamic allocation and never changes the source.

Note

Thread-safe for distinct books.

See also

priv_epub_xml_parse_ncx()

Since

0.1.0

Definition at line 677 of file epub_xml_shim.c.

References internal_collect_spine(), internal_opf_first(), internal_opf_resolve_refs(), internal_opf_shape(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, epub_xml_workspace_t::reader, xml_validate(), and epub_book_t::xml_workspace.

Referenced by internal_parse_archive().

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().