Private bounded EPUB3 writer contracts for the media downloader. More...

#include <stddef.h>
#include <stdint.h>
#include "mdl_export_internal.h"
#include "miniz.h"

Include dependency graph for mdl_export_epub_internal.h:

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

Enumerations
enum	mdl_epub_size_t : uint32_t { k_epub_name_esc_max = 1536U , k_epub_frag_max = 2048U , k_epub_xhtml_max = 2048U , k_epub_entry_max = 320U , k_epub_base_bytes = 4096U , k_epub_per_page_bytes = 2048U , k_epub_workspace_cap = k_epub_base_bytes + (k_max_pages * k_epub_per_page_bytes) }
	EPUB string-buffer sizing (grows with the page count). More...

Functions
bool	priv_mdl_epub_str_cat (char dst, size_t cap, const char text)
	Append text to NUL-terminated dst; report whether it fully fit.
bool	priv_mdl_epub_add_str (mz_zip_archive zip, const char name, const char *body)
	Add an in-memory string as a stored ZIP entry.
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

Private bounded EPUB3 writer contracts for the media downloader.

Separates fixed-layout page and ZIP assembly from the package metadata writer, and fixes the bounded XML accumulator sizing that both translation units budget against.

[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_internal.h.

Enumeration Type Documentation

◆ mdl_epub_size_t

enum mdl_epub_size_t : uint32_t

EPUB string-buffer sizing (grows with the page count).

Sized for the WORST case, not the typical page_NNN.jpg: a page filename may be up to k_name_max bytes and, XML-escaped, expand 6x (a name of all "). That escaped name is embedded once in the page's manifest fragment and once in its xhtml document, so both the fragment buffer and the per-page accumulator budget must exceed the fixed template text plus k_epub_name_esc_max. Undersizing here does not truncate silently – priv_mdl_epub_str_cat and priv_mdl_export_snprintf_fit report it and the export fails – but correct sizing is what lets a legitimate long-name chapter package rather than error.

Enumerator
k_epub_name_esc_max	XML-escaped page name (k_name_max * 6).
k_epub_frag_max	One manifest fragment (fixed + escaped name).
k_epub_xhtml_max	One page's xhtml document (embeds the name).
k_epub_entry_max	A zip entry path ("OEBPS/images/" + name).
k_epub_base_bytes	Fixed opf/nav overhead.
k_epub_per_page_bytes	Per-page opf/nav accumulator growth.
k_epub_workspace_cap	Maximum bounded XML accumulator bytes.

Definition at line 35 of file mdl_export_epub_internal.h.

Function Documentation

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

◆ priv_mdl_epub_add_str()

bool priv_mdl_epub_add_str	(	mz_zip_archive *	zip,
		const char *	name,
		const char *	body )

Add an in-memory string as a stored ZIP entry.

Passes the complete string length to miniz without compression.

Parameters

[in,out]	zip	Initialized ZIP writer.
[in]	name	Safe NUL-terminated member name.
[in]	body	NUL-terminated member body.

Returns: Whether miniz accepted the complete member.

Return values

true	The entry was added.
false	The ZIP writer rejected it.

Precondition: All pointers are non-NULL and strings are NUL-terminated.; zip remains initialized for writing.

Postcondition: Success adds exactly one stored member.; Input strings remain unchanged.

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

Since: 0.1.0

Definition at line 179 of file mdl_export_epub.c.

References k_ra8_ok, priv_mdl_export_zip_add_memory(), RA8_PRIV, and strlen().

Referenced by internal_epub_render_meta(), internal_epub_write_page_xhtml(), and priv_mdl_export_epub().

◆ priv_mdl_epub_str_cat()

bool priv_mdl_epub_str_cat	(	char *	dst,
		size_t	cap,
		const char *	text )

Append text to NUL-terminated dst; report whether it fully fit.

Never truncates: if the append (plus its NUL) would not fit in cap it leaves dst unchanged and returns false, so the caller can fail loudly rather than emit a manifest cut off mid-element.

Returns: true when the whole of text was appended, false if it would overrun.

Parameters

[in,out]	dst	Existing NUL-terminated accumulator.
[in]	cap	Total writable capacity of `dst`.
[in]	text	NUL-terminated text to append.

Return values

true	The complete text and terminator fit.
false	Capacity is insufficient and `dst` is unchanged.

Precondition: dst and text are non-NULL and do not overlap.; dst is NUL-terminated within cap.

Postcondition: Success appends the complete source string.; Failure preserves the original destination.

Note: Thread-safe across distinct accumulators.

Since: 0.1.0

Definition at line 168 of file mdl_export_epub.c.

References memcpy(), RA8_PRIV, and strlen().

Referenced by internal_epub_add_external_cover(), internal_epub_append_frags(), and internal_epub_prepare_creators().

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ mdl_epub_size_t

Function Documentation

◆ priv_mdl_epub_add_meta()

◆ priv_mdl_epub_add_str()

◆ priv_mdl_epub_str_cat()