epub_xml_shim_internal.h File Reference

Library-private contract for the bounded EPUB XML parser. More...

#include <stddef.h>
#include <stdint.h>
#include "epub.h"
#include "ra8_attributes.h"
#include "ra8_err.h"

Include dependency graph for epub_xml_shim_internal.h:

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

Go to the source code of this file.

Data Structures
struct	epub_container_result_t
	Out-parameter struct returned by priv_epub_xml_parse_container(). More...

Functions
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.
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.
ra8_err_t	priv_epub_xml_parse_ncx (const uint8_t *xml_bytes, size_t xml_len, epub_book_t *book)
	Parse an EPUB 2 NCX document into book->toc.
ra8_err_t	priv_epub_xml_parse_nav (const uint8_t *xml_bytes, size_t xml_len, epub_book_t *book)
	Parse an EPUB 3 nav document into book->toc.

Detailed Description

Library-private contract for the bounded EPUB XML parser.

Tag

[Ring 3 / LIB] {World: NS}

epub_xml_shim.c implements four strict streamed entry points that epub_open.c calls. Those four functions and the container-result struct they share used to be restated by hand in the shim, in epub_open.c and in three test translation units – five copies of one contract, none of which the compiler could check against another. This header is the single copy.

Everything declared here is library-private: production callers outside apps/shared_libs/epub go through epub_open().

Copyright

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

Definition in file epub_xml_shim_internal.h.

Function Documentation

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

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

Parse an EPUB 3 nav document into book->toc.

Locates the <nav epub:type="toc"> element, falling back to the first <nav>, then walks its <ol>/<li> tree. Each <li> contributes one entry (<a> text becomes the title, <a href> the href) and nested <ol> elements increase the entry depth.

Parameters

[in]	xml_bytes	Nav document bytes. Not NUL-terminated.
[in]	xml_len	Exact readable extent of xml_bytes in bytes.
[in,out]	book	Book record whose toc / toc_count are set.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Table of contents 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 is malformed or has no usable nav.
k_ra8_err_no_mem	The nav tree exceeds the fixed TOC capacity.

Precondition

xml_bytes is readable for xml_len bytes.

priv_epub_xml_parse_opf() has already run for book.

Postcondition

On success book->toc[0..toc_count) is replaced. On failure existing TOC 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 379 of file epub_xml_toc.c.

References internal_nav_event(), internal_nav_has_list(), internal_select_nav(), internal_toc_capacity(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_err_validation_failed, k_ra8_ok, k_xml_event_none, priv_epub_xml_reader(), epub_xml_workspace_t::reader, priv_nav_ctx_t::saw_ol, epub_book_t::toc_count, xml_reader_next(), xml_validate(), and epub_book_t::xml_workspace.

Referenced by internal_load_toc().

priv_epub_xml_parse_ncx()

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

Parse an EPUB 2 NCX document into book->toc.

Walks <navMap> depth-first. Each <navPoint> contributes one entry (<navLabel><text> becomes the title, <content src> the href) and nested <navPoint> elements increase the entry depth.

Parameters

[in]	xml_bytes	NCX document bytes. Not NUL-terminated.
[in]	xml_len	Exact readable extent of xml_bytes in bytes.
[in,out]	book	Book record whose toc / toc_count are set.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Table of contents 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 is malformed or has no nav map.
k_ra8_err_no_mem	The nav map exceeds the fixed TOC capacity.

Precondition

xml_bytes is readable for xml_len bytes.

priv_epub_xml_parse_opf() has already run for book.

Postcondition

On success book->toc[0..toc_count) is replaced. On failure existing TOC 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_nav()

Since

0.1.0

Definition at line 176 of file epub_xml_toc.c.

References internal_ncx_event(), internal_toc_capacity(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, k_xml_event_none, priv_epub_xml_find(), priv_epub_xml_reader(), epub_xml_workspace_t::reader, epub_book_t::toc_count, xml_reader_next(), xml_validate(), and epub_book_t::xml_workspace.

Referenced by internal_load_toc().

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