Private contracts for the EPUB container and OPF consumers. More...

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

Include dependency graph for epub_xml_opf_internal.h:

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

Go to the source code of this file.

Functions
static bool	internal_font_type (const uint8_t *source, size_t source_len, priv_attr_t media)
	Recognise one supported embedded-font media type.
static void	internal_manifest_item (const uint8_t source, size_t source_len, const xml_event_t event, epub_book_t *book)
	Collect one manifest item and its derived resource roles.
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)
	Record metadata text based on its live parent marker.
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)
	Mark a metadata child frame for later text consumption.
static ra8_err_t	internal_opf_status (ra8_err_t err, uint16_t manifest_depth, uint16_t spine_depth)
	Preserve parser status while enforcing required OPF sections.
static ra8_err_t	internal_opf_first (const uint8_t source, size_t length, epub_book_t book, xml_span_t *out_spine_toc)
	Run the OPF metadata/manifest/cover/font/TOC-source pass.
static ra8_err_t	internal_collect_spine (const uint8_t source, size_t length, epub_book_t book)
	Collect exact unprefixed spine itemrefs in source order.
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)
	Resolve one manifest identifier across the uncapped source manifest.
static ra8_err_t	internal_opf_shape (const uint8_t source, size_t length, epub_xml_workspace_t workspace)
	Validate OPF structure and spine capacity before semantic mutation.

Detailed Description

Private contracts for the EPUB container and OPF consumers.

Declares the file-local helpers of epub_xml_shim.c; the helpers it shares with the table-of-contents pass stay in epub_xml_consumer_internal.h, which this header includes. [Ring 4 / EPUB] {World: NS}

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

Since: 0.1.0

Definition in file epub_xml_opf_internal.h.

Function Documentation

◆ internal_collect_spine()

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

static

Collect exact unprefixed spine itemrefs in source order.

Stores bounded encoded idref spans in the caller-owned workspace.

Parameters

[in]	source	Immutable OPF source.
[in]	length	Exact source extent.
[in,out]	book	EPUB book and scratch workspace.

Returns: Repository error code.

Return values

k_ra8_ok	Complete spine collected.
k_ra8_err_no_mem	Chapter-reference capacity was exceeded.

Precondition: Source passed XML and OPF-shape validation.; Book workspace is exclusive and writable.

Postcondition: Success records exact reference count and spans.; Failure leaves source unchanged; workspace scratch may be partial.

Note: Semantic chapter fields are not changed here.

Since: 0.1.0

◆ internal_font_type()

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

static

Recognise one supported embedded-font media type.

Performs exact byte comparisons against the fixed supported set.

Parameters

[in]	source	Immutable XML source.
[in]	source_len	Exact source extent.
[in]	media	Optional encoded media-type attribute.

Returns: True only for a supported exact media type.

Return values

false Attribute is absent, out of range, or unsupported.

Precondition: Present span lies within source_len.; Source remains readable for the call.

Postcondition: No input memory is modified.; Result is deterministic for the span.

Note: No MIME parameter parsing is performed.

Since: 0.1.0

Referenced by internal_manifest_item().

◆ 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

Collect one manifest item and its derived resource roles.

Updates bounded manifest/font/cover/nav fields using decoded prefixes.

Parameters

[in]	source	Immutable XML source.
[in]	source_len	Exact source extent.
[in]	event	Valid manifest item start.
[in,out]	book	EPUB semantic output.

Precondition: The document and event were fully validated.; book is writable and owns its workspace.

Postcondition: Resource fields reflect this item within fixed capacities.; Source bytes remain unchanged.

Note: Overflow beyond legacy manifest/font caps is ignored deterministically.

Since: 0.1.0

References RA8_INTERNAL.

◆ 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

Resolve one manifest identifier across the uncapped source manifest.

Compares decoded IDs and returns the matching encoded href span.

Parameters

[in]	source	Immutable OPF source.
[in]	length	Exact source extent.
[in,out]	workspace	Exclusive reader scratch.
[in]	wanted	Encoded identifier span.
[out]	out_href	Matching encoded href span.

Returns: Repository error code.

Return values

k_ra8_ok	Matching item found.
k_ra8_err_no_data	No item matched.

Precondition: Source passed complete validation and spans share its coordinates.; Output/workspace are writable and source remains live.

Postcondition: Success fills a bounded source-aliasing href span.; Failure leaves source unchanged and output unspecified.

Note: Workspace is scratch on return.

Since: 0.1.0

References RA8_INTERNAL.

◆ 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

Mark a metadata child frame for later text consumption.

Distinguishes the package unique identifier from fallback identifiers.

Parameters

[in]	source	Immutable XML source.
[in]	source_len	Exact source extent.
[in]	event	Valid metadata-child start event.
[in,out]	reader	Reader whose frame receives the marker.
[in]	unique_id	Encoded package identifier reference.

Precondition: Event/frame spans lie within the same validated source.; Event is non-self-closing and its frame is live.

Postcondition: The event frame carries exactly one metadata marker.; Source bytes remain unchanged.

Note: Marker zero means no metadata role.

Since: 0.1.0

References RA8_INTERNAL.

◆ 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

Record metadata text based on its live parent marker.

Copies the first applicable title/creator/language/identifier field.

Parameters

[in]	source	Immutable XML source.
[in]	source_len	Exact source extent.
[in]	event	Valid text event.
[in]	reader	Reader whose live frames carry markers.
[in,out]	book	EPUB semantic output.

Precondition: Event/frames come from the same validated source.; book is writable and distinct from source.

Postcondition: A matching metadata field receives a decoded bounded prefix.; Nonmatching events leave semantic fields unchanged.

Note: Source bytes are never modified.

Since: 0.1.0

References RA8_INTERNAL.

◆ 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

Run the OPF metadata/manifest/cover/font/TOC-source pass.

Consumes only the already-validated and capacity-preflighted document.

Parameters

[in]	source	Immutable OPF source.
[in]	length	Exact source extent.
[in,out]	book	EPUB semantic output and reader workspace.
[out]	out_spine_toc	Encoded spine TOC identifier span.

Returns: Repository error code.

Return values

k_ra8_ok	Required sections consumed.
k_ra8_err_validation_failed	Required shape replay failed.

Precondition: internal_opf_shape succeeded on this source/book workspace.; Output storage is writable and source remains live.

Postcondition: Success updates bounded semantic fields and output span.; Source bytes remain unchanged on every result.

Note: Public caller owns failure atomicity through preflight.

Since: 0.1.0

References RA8_INTERNAL.

◆ internal_opf_shape()

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

static

Validate OPF structure and spine capacity before semantic mutation.

Requires direct manifest/spine sections and counts resolving itemrefs.

Parameters

[in]	source	Immutable OPF source.
[in]	length	Exact source extent.
[in,out]	workspace	Exclusive reader scratch.

Returns: Repository error code.

Return values

k_ra8_ok	Shape and fixed chapter capacity fit.
k_ra8_err_no_mem	Spine reference capacity was exceeded.

Precondition: Source already passed complete XML validation.; Workspace is exclusive and writable.

Postcondition: Success proves later semantic passes cannot hit chapter capacity.; Source remains unchanged; workspace is scratch.

Note: This pass provides OPF failure atomicity.

Since: 0.1.0

◆ internal_opf_status()

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

static

Preserve parser status while enforcing required OPF sections.

Converts a successful pass missing manifest/spine to validation failure.

Parameters

[in]	err	Existing parser status.
[in]	manifest_depth	Manifest depth or UINT16_MAX sentinel.
[in]	spine_depth	Spine depth or UINT16_MAX sentinel.

Returns: Original or derived repository error.

Return values

k_ra8_err_validation_failed Required section was absent.

Precondition: Sentinel semantics are shared by the OPF pass.; err is a repository error code.

Postcondition: Non-success input status is preserved exactly.; No memory is modified.

Note: Pure and thread-safe.

Since: 0.1.0

Functions

Detailed Description

Function Documentation

◆ internal_collect_spine()

◆ internal_font_type()

◆ internal_manifest_item()

◆ internal_manifest_lookup()

◆ internal_mark_metadata()

◆ internal_metadata_text()

◆ internal_opf_first()

◆ internal_opf_shape()

◆ internal_opf_status()