Render the EPUB3 package document, navigation, and identifier. More...

#include <stdio.h>
#include <string.h>
#include "mdl_export.h"
#include "mdl_export_epub_internal.h"
#include "mdl_sanitize.h"
#include "miniz.h"
#include "ra8_attributes.h"

Include dependency graph for mdl_export_epub_meta.c:

Data Structures
struct	mdl_epub_meta_text_t
	Escaped and rendered EPUB publication metadata. More...

Enumerations
enum	mdl_epub_text_bounds_t : uint16_t { k_epub_creator_factor = 12U , k_epub_fragment_slack = 64U , k_epub_creator_slack = 128U , k_epub_uuid_byte_bits = 8U }
	Bounded EPUB text expansion sizes. More...
enum	mdl_uuid_hash_t : uint64_t { k_uuid_fnv_prime = 1099511628211ULL , k_uuid_seed_one = 0xCBF29CE484222325ULL , k_uuid_seed_two = 7809847782465536322ULL }
	FNV-1a values used to derive deterministic publication UUIDs. More...
enum	mdl_uuid_layout_t : uint8_t { k_uuid_separator = 0xFFU , k_uuid_byte_count = 16U , k_uuid_half_bytes = 8U , k_uuid_top_shift = 56U , k_uuid_version_byte = 6U , k_uuid_version_mask = 0x0FU , k_uuid_version_five = 0x50U , k_uuid_variant_byte = 8U , k_uuid_variant_mask = 0x3FU , k_uuid_variant_rfc4122 = 0x80U , k_uuid_node_offset = 10U , k_uuid_last_byte = 15U }
	RFC 4122 UUID byte layout, masks, and version/variant bits. More...

Functions
static uint64_t	internal_uuid_hash_text (uint64_t hash, const char *text)
	Mix one NUL-terminated metadata field into a UUID hash.
static void	internal_generate_uuid (char out, size_t cap, const mdl_export_meta_t meta)
	Derive a stable RFC-4122-shaped identifier from canonical metadata.
static void	internal_epub_prepare_creators (const mdl_export_meta_t meta, mdl_epub_meta_text_t text)
	Render the EPUB creator fragments with their original fallback.
static ra8_err_t	internal_epub_prepare_optional (const mdl_export_meta_t meta, mdl_epub_meta_text_t text)
	Render optional EPUB description and source fragments.
static ra8_err_t	internal_epub_prepare_text (const mdl_export_meta_t meta, mdl_epub_meta_text_t text)
	Prepare all escaped EPUB metadata text.
static ra8_err_t	internal_epub_render_meta (mz_zip_archive zip, const char mani, const char spine, const char nav, size_t page_count, const mdl_epub_meta_text_t text, char opf, size_t opf_cap, char *navdoc, size_t nav_cap)
	Render and append prepared EPUB package documents.
ra8_err_t	priv_mdl_epub_add_meta (mz_zip_archive zip, const char mani, const char spine, const char nav, size_t page_count, const mdl_export_meta_t meta, char opf, size_t opf_buf_cap, char *navdoc, size_t nav_buf_cap)
	Build EPUB package metadata and finalize the archive.

Detailed Description

Render the EPUB3 package document, navigation, and identifier.

Derives one deterministic RFC 4122 publication identifier, escapes the Dublin Core metadata text, and renders the bounded OPF plus navigation documents that finalize a staged EPUB archive.

[Ring 4 / Domain] {World: NS}

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

Since: 0.1.0

Definition in file mdl_export_epub_meta.c.

Enumeration Type Documentation

◆ mdl_epub_text_bounds_t

enum mdl_epub_text_bounds_t : uint16_t

Bounded EPUB text expansion sizes.

Enumerator
k_epub_creator_factor	Writer plus artist expansion factor.
k_epub_fragment_slack	Fixed bytes around an XML fragment.
k_epub_creator_slack	Fixed bytes around all creators.
k_epub_uuid_byte_bits	Bits consumed per UUID hash byte.

Definition at line 25 of file mdl_export_epub_meta.c.

◆ mdl_uuid_hash_t

enum mdl_uuid_hash_t : uint64_t

FNV-1a values used to derive deterministic publication UUIDs.

Enumerator
k_uuid_fnv_prime	FNV-1a 64-bit prime.
k_uuid_seed_one	Primary FNV offset basis.
k_uuid_seed_two	Independent second seed.

Definition at line 33 of file mdl_export_epub_meta.c.

◆ mdl_uuid_layout_t

enum mdl_uuid_layout_t : uint8_t

RFC 4122 UUID byte layout, masks, and version/variant bits.

Enumerator
k_uuid_separator	Separator mixed between hash fields.
k_uuid_byte_count	Bytes in an RFC 4122 UUID.
k_uuid_half_bytes	Bytes contributed by each hash.
k_uuid_top_shift	Shift selecting the top hash byte.
k_uuid_version_byte	UUID version field byte index.
k_uuid_version_mask	Mask retaining non-version bits.
k_uuid_version_five	RFC 4122 version-five field bits.
k_uuid_variant_byte	UUID variant field byte index.
k_uuid_variant_mask	Mask retaining non-variant bits.
k_uuid_variant_rfc4122	RFC 4122 variant field bits.
k_uuid_node_offset	First byte of the UUID node field.
k_uuid_last_byte	Final UUID byte index.

Definition at line 40 of file mdl_export_epub_meta.c.

Function Documentation

◆ internal_epub_prepare_creators()

void internal_epub_prepare_creators	(	const mdl_export_meta_t *	meta,
		mdl_epub_meta_text_t *	text )

static

Render the EPUB creator fragments with their original fallback.

Builds epub prepare creators within caller-owned bounded workspace and reports capacity, encoding, or I/O failure without transferring workspace ownership.

Parameters

[in]	meta	Resolved export metadata.
[out]	text	Prepared EPUB text storage.

Precondition: Both pointers are non-NULL.; Supplied capacities cover their referenced bounded buffers.

Postcondition: text contains at least one creator fragment.; Result status and outputs describe one completed synchronous attempt.

Note: Thread-safe across distinct objects.

Since: 0.1.0

Definition at line 171 of file mdl_export_epub_meta.c.

References mdl_export_meta_t::artist, mdl_epub_meta_text_t::creators, k_epub_fragment_slack, k_mdl_meta_name_max, mdl_xml_escape(), priv_mdl_epub_str_cat(), RA8_INTERNAL, and mdl_export_meta_t::writer.

Referenced by internal_epub_prepare_text().

◆ internal_epub_prepare_optional()

ra8_err_t internal_epub_prepare_optional	(	const mdl_export_meta_t *	meta,
		mdl_epub_meta_text_t *	text )

static

Render optional EPUB description and source fragments.

Builds epub prepare optional within caller-owned bounded workspace and reports capacity, encoding, or I/O failure without transferring workspace ownership.

Parameters

[in]	meta	Resolved and URL-validated metadata.
[out]	text	Prepared EPUB text storage.

Returns: Optional-fragment status.

Return values

k_ra8_ok	Every present optional value fit.
k_ra8_err_invalid_size	Escaped source storage was insufficient.

Precondition: Both pointers are non-NULL.; Supplied capacities cover their referenced bounded buffers.

Postcondition: Absent fields leave empty fragments.; Result status and outputs describe one completed synchronous attempt.

Note: Thread-safe across distinct objects.

Since: 0.1.0

Definition at line 211 of file mdl_export_epub_meta.c.

References mdl_epub_meta_text_t::description, k_mdl_meta_summary_max, k_mdl_meta_url_max, k_ra8_err_invalid_size, k_ra8_ok, mdl_xml_escape(), priv_mdl_export_snprintf_fit(), RA8_INTERNAL, mdl_epub_meta_text_t::source, mdl_export_meta_t::source_url, and mdl_export_meta_t::summary.

Referenced by internal_epub_prepare_text().

◆ internal_epub_prepare_text()

ra8_err_t internal_epub_prepare_text	(	const mdl_export_meta_t *	meta,
		mdl_epub_meta_text_t *	text )

static

Prepare all escaped EPUB metadata text.

Builds epub prepare text within caller-owned bounded workspace and reports capacity, encoding, or I/O failure without transferring workspace ownership.

Parameters

[in]	meta	Resolved and URL-validated metadata.
[out]	text	Prepared EPUB text storage.

Returns: Text-preparation status.

Return values

k_ra8_ok	Required and optional fields fit.
k_ra8_err_invalid_size	Escaped bounded storage was insufficient.

Precondition: Both pointers are non-NULL.; Supplied capacities cover their referenced bounded buffers.

Postcondition: Success initializes every field of text.; Result status and outputs describe one completed synchronous attempt.

Note: Thread-safe across distinct objects.

Since: 0.1.0

Definition at line 253 of file mdl_export_epub_meta.c.

References mdl_export_meta_t::chapter_title, mdl_epub_meta_text_t::identifier, mdl_export_meta_t::identifier, internal_epub_prepare_creators(), internal_epub_prepare_optional(), internal_generate_uuid(), k_mdl_meta_id_max, k_mdl_read_rtl, k_ra8_err_invalid_size, mdl_epub_meta_text_t::language, mdl_export_meta_t::language, mdl_xml_escape(), mdl_epub_meta_text_t::modified, mdl_export_meta_t::modified, mdl_epub_meta_text_t::progression, RA8_INTERNAL, mdl_export_meta_t::reading_direction, mdl_export_meta_t::series_title, and mdl_epub_meta_text_t::title.

Referenced by priv_mdl_epub_add_meta().

◆ internal_epub_render_meta()

ra8_err_t internal_epub_render_meta	(	mz_zip_archive *	zip,
		const char *	mani,
		const char *	spine,
		const char *	nav,
		size_t	page_count,
		const mdl_epub_meta_text_t *	text,
		char *	opf,
		size_t	opf_cap,
		char *	navdoc,
		size_t	nav_cap )

static

Render and append prepared EPUB package documents.

Builds epub render meta within caller-owned bounded workspace and reports capacity, encoding, or I/O failure without transferring workspace ownership.

Parameters

[in,out]	zip	Initialized EPUB writer.
[in]	mani	Manifest fragments.
[in]	spine	Spine fragments.
[in]	nav	Navigation fragments.
[in]	page_count	Logical page count.
[in]	text	Prepared metadata text.
[out]	opf	OPF workspace.
[in]	opf_cap	OPF workspace capacity.
[out]	navdoc	Navigation workspace.
[in]	nav_cap	Navigation workspace capacity.

Returns: Document/finalization status.

Return values

k_ra8_ok	Documents were added and archive finalized.
k_ra8_err_invalid_size	Required workspace was insufficient.
k_ra8_fail	Rendering, member addition, or finalization failed.

Precondition: All pointers are non-NULL and input strings are NUL-terminated.; Supplied capacities cover their referenced bounded buffers.

Postcondition: Success finalizes the EPUB central directory.; Result status and outputs describe one completed synchronous attempt.

Note: Not thread-safe for a shared writer or buffers.

Since: 0.1.0

Definition at line 307 of file mdl_export_epub_meta.c.

References mdl_epub_meta_text_t::creators, mdl_epub_meta_text_t::description, mdl_epub_meta_text_t::identifier, k_epub_base_bytes, k_ra8_err_invalid_size, k_ra8_fail, k_ra8_ok, mdl_epub_meta_text_t::language, mdl_epub_meta_text_t::modified, priv_mdl_epub_add_str(), priv_mdl_export_snprintf_fit(), mdl_epub_meta_text_t::progression, RA8_INTERNAL, mdl_epub_meta_text_t::source, strlen(), and mdl_epub_meta_text_t::title.

Referenced by priv_mdl_epub_add_meta().

◆ internal_generate_uuid()

void internal_generate_uuid	(	char *	out,
		size_t	cap,
		const mdl_export_meta_t *	meta )

static

Derive a stable RFC-4122-shaped identifier from canonical metadata.

Hashes canonical fields in both directions and sets version-five and RFC variant bits before formatting a URN into caller storage.

Parameters

[out]	out	Destination UUID string buffer.
[in]	cap	Writable capacity of `out`.
[in]	meta	Metadata to hash, or NULL for defaults.

Precondition: out is non-NULL and addresses cap writable bytes.; meta is NULL or contains bounded NUL-terminated fields.

Postcondition: out contains a deterministic NUL-terminated UUID URN when capacity permits.; Input metadata remains unchanged.

Note: Thread-safe across distinct output buffers.

Since: 0.1.0

Definition at line 96 of file mdl_export_epub_meta.c.

References mdl_export_meta_t::artist, mdl_export_meta_t::chapter_title, mdl_export_meta_t::cover_path, internal_uuid_hash_text(), k_epub_uuid_byte_bits, k_uuid_byte_count, k_uuid_half_bytes, k_uuid_last_byte, k_uuid_node_offset, k_uuid_seed_one, k_uuid_seed_two, k_uuid_top_shift, k_uuid_variant_byte, k_uuid_variant_mask, k_uuid_variant_rfc4122, k_uuid_version_byte, k_uuid_version_five, k_uuid_version_mask, mdl_export_meta_t::language, mdl_meta_init(), mdl_export_meta_t::series_title, mdl_export_meta_t::source_url, and mdl_export_meta_t::writer.

Referenced by internal_epub_prepare_text().

◆ internal_uuid_hash_text()

uint64_t internal_uuid_hash_text	(	uint64_t	hash,
		const char *	text )

static

Mix one NUL-terminated metadata field into a UUID hash.

Applies 64-bit FNV-1a and a separator byte so adjacent fields cannot collapse into the same concatenated hash stream.

Parameters

[in]	hash	Incoming hash state.
[in]	text	NUL-terminated metadata field.

Returns: Updated hash state after the field and separator.

Return values

uint64_t Deterministic updated FNV state.

Precondition: text is non-NULL and NUL-terminated.; hash is the state for all preceding canonical fields.

Postcondition: text is not modified.; Equal input states and text produce equal output.

Note: Thread-safe: this is a pure hash helper.

Since: 0.1.0

Definition at line 70 of file mdl_export_epub_meta.c.

References k_uuid_fnv_prime, k_uuid_separator, and RA8_INTERNAL.

Referenced by internal_generate_uuid().

◆ priv_mdl_epub_add_meta()

ra8_err_t priv_mdl_epub_add_meta	(	mz_zip_archive *	zip,
		const char *	mani,
		const char *	spine,
		const char *	nav,
		size_t	page_count,
		const mdl_export_meta_t *	meta,
		char *	opf,
		size_t	opf_buf_cap,
		char *	navdoc,
		size_t	nav_buf_cap )

Build EPUB package metadata and finalize the archive.

Escapes deterministic metadata, composes bounded OPF/navigation documents, adds them to the ZIP, and writes the central directory.

Parameters

[in,out]	zip	Initialized EPUB ZIP writer.
[in]	mani	Complete manifest fragments.
[in]	spine	Complete spine fragments.
[in]	nav	Complete navigation fragments.
[in]	page_count	Logical reading-order page count.
[in]	meta	Metadata to encode, or NULL.
[out]	opf	Caller workspace for content.opf.
[in]	opf_buf_cap	Capacity of `opf`.
[out]	navdoc	Caller workspace for nav.xhtml.
[in]	nav_buf_cap	Capacity of `navdoc`.

Returns: Metadata/finalization status.

Return values

k_ra8_ok	Both documents were added and ZIP finalized.
k_ra8_err_invalid_size	Required bounded XML storage is insufficient.
k_ra8_fail	Formatting, member addition, or finalization failed.

Precondition: All document strings are NUL-terminated and pointers are non-NULL.; Output buffers are distinct and zip is initialized.

Postcondition: Success leaves a finalized EPUB central directory.; Failure is explicit and the caller owns temp cleanup.

Note: Not thread-safe for a shared ZIP writer or buffers.

Since: 0.1.0

Definition at line 367 of file mdl_export_epub_meta.c.

References internal_epub_prepare_text(), internal_epub_render_meta(), k_ra8_ok, mdl_meta_init(), priv_mdl_export_validate_source_url(), RA8_PRIV, and mdl_export_meta_t::source_url.

Referenced by priv_mdl_export_epub().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ mdl_epub_text_bounds_t

◆ mdl_uuid_hash_t

◆ mdl_uuid_layout_t

Function Documentation

◆ internal_epub_prepare_creators()

◆ internal_epub_prepare_optional()

◆ internal_epub_prepare_text()

◆ internal_epub_render_meta()

◆ internal_generate_uuid()

◆ internal_uuid_hash_text()

◆ priv_mdl_epub_add_meta()