mdl_export_internal.h File Reference

Module-private contracts shared by chapter export writers. More...

#include <stddef.h>
#include <stdint.h>
#include "mdl_export.h"
#include "mdl_export_io_internal.h"
#include "miniz.h"
#include "ra8_attributes.h"
#include "ra8_err.h"

Include dependency graph for mdl_export_internal.h:

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

Go to the source code of this file.

Data Structures
struct	mdl_external_cover_t
	Validated external cover details retained without owning storage. More...
struct	mdl_zip_block_t
	Metadata stored immediately before each bounded miniz allocation. More...
struct	mdl_zip_allocator_t
	Per-writer adapter from miniz callbacks to one caller workspace. More...

Enumerations
enum	mdl_export_limits_t : uint16_t {   k_max_pages = 2048 ,   k_name_max = 256 }
	Fixed bounds on the per-chapter page list. More...
enum	mdl_cover_bounds_t : uint8_t {   k_cover_ext_bytes = 8U ,   k_cover_mime_bytes = 32U ,   k_cover_entry_bytes = 32U }
	Fixed storage used to describe a validated external cover. More...

Functions
ra8_err_t	priv_mdl_export_validate_source_url (const char *url)
	Validate an optional bounded source-attribution URL.
bool	priv_mdl_export_snprintf_fit (int written, size_t cap)
	Report whether an snprintf result fit its destination.
void	priv_mdl_zip_workspace_bind (mz_zip_archive *zip, mdl_zip_allocator_t *alloc, mdl_export_workspace_t *ws)
	Bind a miniz archive to caller-owned bounded storage.
void	priv_mdl_zip_workspace_release (mdl_zip_allocator_t *alloc)
	Restore a workspace after a miniz writer ends.
ra8_err_t	priv_mdl_zip_workspace_error (const mdl_zip_allocator_t *alloc)
	Classify a miniz writer failure.
ra8_err_t	priv_mdl_export_prepare_cover (mdl_storage_t *storage, const mdl_export_meta_t *meta, const char names[][k_name_max], size_t count, mdl_external_cover_t *cover)
	Validate and canonicalize an external cover.
ra8_err_t	priv_mdl_export_cbz (mdl_storage_t *storage, const char *dir, char names[][k_name_max], size_t count, mdl_export_output_t *output, const mdl_export_meta_t *meta, mdl_export_workspace_t *ws)
	Write a CBZ into a caller-owned staged output.
ra8_err_t	priv_mdl_export_tar (mdl_storage_t *storage, const char *dir, char names[][k_name_max], size_t count, mdl_export_output_t *output, const mdl_export_meta_t *meta)
	Write an uncompressed CBT tar archive.
ra8_err_t	priv_mdl_export_tar_gzip (mdl_storage_t *storage, const char *dir, char names[][k_name_max], size_t count, mdl_export_output_t *output, const mdl_export_meta_t *meta, mdl_export_workspace_t *ws)
	Write a gzip-wrapped CBT archive.
ra8_err_t	priv_mdl_export_epub (mdl_storage_t *storage, const char *dir, char names[][k_name_max], size_t count, mdl_export_output_t *output, const mdl_export_meta_t *meta, mdl_export_workspace_t *ws)
	Write a fixed-layout EPUB3 archive.
ra8_err_t	priv_mdl_export_rabook (mdl_storage_t *storage, const char *directory, char names[][k_name_max], size_t count, const char *destination, const mdl_export_meta_t *meta, mdl_export_workspace_t *workspace)
	Compile one page directory into a strict chunked RABOOK artifact.
ra8_err_t	priv_mdl_export_jof (mdl_storage_t *storage, const char *dir, const char names[][k_name_max], size_t count, mdl_export_workspace_t *ws)
	Convert every page in a chapter directory to a sibling .jof atlas.

Detailed Description

Module-private contracts shared by chapter export writers.

Defines the bounded page table, miniz workspace adapter, canonical external-cover descriptor, and the cross-translation-unit writer seams. None of these declarations is part of the exporter-facing API.

[Ring 4 / Domain] {World: NS}

Copyright

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

Since

0.1.0

Definition in file mdl_export_internal.h.

Enumeration Type Documentation

mdl_cover_bounds_t

enum mdl_cover_bounds_t : uint8_t

Fixed storage used to describe a validated external cover.

Enumerator
k_cover_ext_bytes	Canonical image extension buffer.
k_cover_mime_bytes	Canonical image MIME buffer.
k_cover_entry_bytes	Canonical archive member path.

Definition at line 34 of file mdl_export_internal.h.

mdl_export_limits_t

enum mdl_export_limits_t : uint16_t

Fixed bounds on the per-chapter page list.

Enumerator
k_max_pages	Maximum page entries per chapter.
k_name_max	Maximum entry-name bytes.

Definition at line 28 of file mdl_export_internal.h.

Function Documentation

priv_mdl_export_cbz()

ra8_err_t priv_mdl_export_cbz	(	mdl_storage_t *	storage,
		const char *	dir,
		char	names[][k_name_max],
		size_t	count,
		mdl_export_output_t *	output,
		const mdl_export_meta_t *	meta,
		mdl_export_workspace_t *	ws )

Write a CBZ into a caller-owned staged output.

Stores page and optional cover members and appends ComicInfo before finalizing the bounded ZIP writer.

Parameters

[in,out]	storage	Injected portable file reader.
[in]	dir	Chapter directory.
[in]	names	Sorted page-name rows.
[in]	count	Page count.
[in,out]	output	Active validated-publication output.
[in]	meta	Resolved metadata.
[in,out]	ws	Exclusive exporter workspace.

Returns

Writer status.

Return values

k_ra8_ok	A finalized CBZ was written.
k_ra8_err_invalid_size	A bound or workspace was exceeded.
k_ra8_err_validation_failed	An external cover was invalid.
k_ra8_fail	ZIP or file I/O failed.

Precondition

Paths and name rows are valid and stable.

output owns an active transaction and remains valid through finalization.

Postcondition

Success leaves one finalized CBZ.

Failure leaves transaction abort or publication to the caller.

Note

Not thread-safe for shared output or workspace.

Since

0.1.0

Write a CBZ into a caller-owned staged output.

Stores each page without recompression, inserts an external cover first when present, and finalizes only after ComicInfo succeeds.

Parameters

[in,out]	storage	Injected portable file reader.
[in]	dir	NUL-terminated chapter directory.
[in]	names	Sorted page-name rows.
[in]	count	Number of pages to archive.
[in,out]	output	Active validated-publication output.
[in]	meta	Metadata to embed, or NULL.
[in,out]	ws	Exclusive caller-owned workspace.

Returns

CBZ writer status.

Return values

k_ra8_ok	The ZIP central directory finalized successfully.
k_ra8_err_validation_failed	An external cover is invalid.
k_ra8_err_invalid_size	Metadata or a bounded name does not fit.
k_ra8_fail	ZIP creation, member writing, or finalization failed.

Precondition

Paths and name rows are valid and stable.

output owns an active transaction.

Postcondition

Success leaves a finalized CBZ with ComicInfo.

External cover paths are represented only by canonical member names.

Note

Not thread-safe for the same output or changing source files.

Since

0.1.0

Definition at line 458 of file mdl_export_zip.c.

References mdl_external_cover_t::entry, mdl_export_output_t::error, mdl_zip_allocator_t::exhausted, mdl_external_cover_t::external, internal_cbz_add_metadata(), internal_cbz_add_pages(), k_name_max, k_ra8_err_invalid_size, k_ra8_fail, k_ra8_ok, priv_mdl_export_prepare_cover(), priv_mdl_export_zip_add_file(), priv_mdl_export_zip_write(), priv_mdl_zip_workspace_bind(), priv_mdl_zip_workspace_error(), priv_mdl_zip_workspace_release(), RA8_PRIV, and mdl_external_cover_t::source.

Referenced by internal_export_dispatch().

priv_mdl_export_epub()

ra8_err_t priv_mdl_export_epub	(	mdl_storage_t *	storage,
		const char *	dir,
		char	names[][k_name_max],
		size_t	count,
		mdl_export_output_t *	output,
		const mdl_export_meta_t *	meta,
		mdl_export_workspace_t *	ws )

Write a fixed-layout EPUB3 archive.

Emits OCF roots, page XHTML, images, metadata, cover information, navigation, and the final ZIP directory from caller storage.

Parameters

[in,out]	storage	Injected portable file reader.
[in]	dir	Chapter directory.
[in]	names	Sorted page-name rows.
[in]	count	Page count.
[in,out]	output	Active validated-publication output.
[in]	meta	Resolved metadata.
[in,out]	ws	Exclusive exporter workspace.

Returns

Writer status.

Return values

k_ra8_ok	A finalized EPUB was written.
k_ra8_err_invalid_size	A text or workspace bound was exceeded.
k_ra8_err_validation_failed	An external cover was invalid.
k_ra8_fail	ZIP, formatting, or file I/O failed.

Precondition

Paths and rows are valid and stable.

Workspace bytes and output remain live through writer teardown.

Postcondition

The ZIP writer is ended on every initialized path.

Success includes OPF and navigation members.

Note

Not thread-safe for shared output or workspace.

Since

0.1.0

Write a fixed-layout EPUB3 archive.

Carves all XML accumulators from caller storage, adds OCF roots, canonical cover, page members, metadata, and finalizes the staged archive.

Parameters

[in,out]	storage	Injected portable file reader.
[in]	dir	Chapter directory.
[in]	names	Sorted page-name rows.
[in]	count	Number of page rows.
[in,out]	output	Active validated-publication output.
[in]	meta	Metadata to encode, or NULL.
[in,out]	ws	Exclusive caller-owned workspace.

Returns

EPUB writer status.

Return values

k_ra8_ok	A complete finalized EPUB was written.
k_ra8_err_invalid_size	Workspace or metadata bounds were exceeded.
k_ra8_err_validation_failed	External cover validation failed.
k_ra8_fail	ZIP, XHTML, or metadata writing failed.

Precondition

Paths and rows are valid, stable, and NUL-terminated.

ws is exclusive and owns writable arena storage.

Postcondition

The ZIP writer is ended on every initialized path.

Success includes required mimetype, container, OPF, and navigation members.

Note

Not thread-safe for shared output or workspace.

Since

0.1.0

Definition at line 584 of file mdl_export_epub.c.

References internal_epub_add_external_cover(), internal_epub_add_page(), internal_epub_carve_workspace(), internal_epub_finish_writer(), internal_epub_page_meta(), k_epub_base_bytes, k_epub_per_page_bytes, k_name_max, k_ra8_fail, k_ra8_ok, priv_mdl_epub_add_meta(), priv_mdl_epub_add_str(), priv_mdl_export_prepare_cover(), priv_mdl_export_zip_write(), priv_mdl_zip_workspace_bind(), priv_mdl_zip_workspace_error(), RA8_PRIV, and s_epub_container_xml.

Referenced by internal_export_dispatch(), and internal_write_temp_epub().

priv_mdl_export_jof()

ra8_err_t priv_mdl_export_jof	(	mdl_storage_t *	storage,
		const char *	dir,
		const char	names[][k_name_max],
		size_t	count,
		mdl_export_workspace_t *	ws )

Convert every page in a chapter directory to a sibling .jof atlas.

Transcodes each listed page in place: page.jpg becomes page.jof beside it, leaving the source file untouched. Each page is produced through the firmware's own jof producer, so a container this tool writes is byte-identical to one the board would produce from the same source, and the full-width band geometry is the shape longstrip scrolls.

Stops at the first page that fails and reports that page's error, so a partially converted directory is always explained by a non-ok return rather than discovered later; pages already written before the failure remain.

Parameters

[in,out]	storage	Injected portable storage and transaction provider.
[in]	dir	Chapter directory holding the page files.
[in]	names	Page file names, count entries of at most k_name_max bytes each, in the order they should be converted.
[in]	count	Number of valid entries in names.
[in,out]	ws	Exclusive caller-owned exporter workspace.

Returns

Result code.

Return values

k_ra8_ok	Every page was transcoded.
k_ra8_err_not_supported	A page is in no format the producer decodes.
k_ra8_err_invalid_size	A page's geometry admits no work arena.
k_ra8_fail	A page could not be read, or its output could not be opened or written.

Precondition

storage is initialized and exclusive to this export.

dir names an existing, readable directory.

names holds count readable entries.

Postcondition

On k_ra8_ok a .jof sibling exists for every entry in names.

On failure, earlier committed pages remain visible; the failed page and every later page preserve their prior destinations.

Note

Not thread-safe for a shared workspace or destination directory.

See also

mdl_export_chapter_ws()

Since

0.1.0

Definition at line 415 of file mdl_export_jof.c.

References internal_jof_one(), k_fw_fs_path_cap, k_name_max, k_ra8_err_invalid_size, k_ra8_ok, memcpy(), priv_mdl_export_path_join(), priv_mdl_export_snprintf_fit(), RA8_PRIV, strrchr(), and mdl_export_workspace::used.

Referenced by mdl_export_chapter_meta_ws().

priv_mdl_export_prepare_cover()

ra8_err_t priv_mdl_export_prepare_cover	(	mdl_storage_t *	storage,
		const mdl_export_meta_t *	meta,
		const char	names[][k_name_max],
		size_t	count,
		mdl_external_cover_t *	cover )

Validate and canonicalize an external cover.

Leaves in-chapter covers alone and maps a validated external image to a type-derived canonical member path.

Parameters

[in,out]	storage	Injected portable file reader.
[in]	meta	Metadata carrying the cover path, or NULL.
[in]	names	Sorted chapter page names.
[in]	count	Readable page-name rows.
[out]	cover	Canonical cover descriptor.

Returns

Cover classification status.

Return values

k_ra8_ok	No external cover is needed or one is valid.
k_ra8_err_invalid_arg	The fixed path is unterminated.
k_ra8_err_invalid_size	The canonical path does not fit.
k_ra8_err_validation_failed	The source is not a valid image.

Precondition

names and cover are valid for the declared bounds.

meta is NULL or stable for the call.

Postcondition

Success initializes cover completely.

Host paths never become archive member names.

Note

Not thread-safe against cover replacement.

Since

0.1.0

Validate and canonicalize an external cover.

Recognizes an in-chapter page by exact name; otherwise requires a stable regular image file, sniffs its bytes, and hides the trusted host path behind cover/cover.<actual-type>.

Parameters

[in,out]	storage	Injected portable file reader.
[in]	meta	Metadata carrying the trusted cover path, or NULL.
[in]	names	Sorted chapter page rows.
[in]	count	Number of readable rows.
[out]	cover	Canonical external-cover descriptor.

Returns

Cover classification status.

Return values

k_ra8_ok	No external cover is needed or one was validated.
k_ra8_err_invalid_arg	The fixed path lacks a terminating NUL.
k_ra8_err_invalid_size	The canonical member path does not fit.
k_ra8_err_validation_failed	The source is absent, nonregular, or not an image.

Precondition

cover and names are valid for count rows.

meta is NULL or exclusively stable for the call.

Postcondition

Success fully initializes cover.

An external source path is never copied into an archive member name.

Note

Not thread-safe against concurrent replacement of the cover file.

Since

0.1.0

Definition at line 305 of file mdl_export_zip.c.

References mdl_export_meta_t::cover_path, mdl_external_cover_t::entry, fw_fs_stat_t::exists, mdl_external_cover_t::external, mdl_storage_t::fs, fw_fs_stat(), k_cover_ext_bytes, k_fw_fs_node_file, k_name_max, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_validation_failed, k_ra8_ok, mdl_urlname_sniff_file(), memset(), mdl_external_cover_t::mime, fw_fs_t::names, priv_mdl_export_snprintf_fit(), RA8_PRIV, fw_fs_stat_t::size_bytes, mdl_external_cover_t::source, strcmp(), strnlen(), and fw_fs_stat_t::type.

Referenced by priv_mdl_export_cbz(), and priv_mdl_export_epub().

priv_mdl_export_rabook()

ra8_err_t priv_mdl_export_rabook	(	mdl_storage_t *	storage,
		const char *	directory,
		char	names[][k_name_max],
		size_t	count,
		const char *	destination,
		const mdl_export_meta_t *	meta,
		mdl_export_workspace_t *	workspace )

Compile one page directory into a strict chunked RABOOK artifact.

Produces a private fixed-layout EPUB with the production writer, compiles it through the firmware RABOOK1 pipeline, wraps the flat blob as independent RBKC chunks, and validates the complete staged artifact before atomic publication.

Parameters

[in,out]	storage	Injected portable storage and transaction provider.
[in]	directory	Canonical chapter directory.
[in]	names	Sorted page-name rows.
[in]	count	Page count within the fixed RABOOK profile.
[in]	destination	Canonical final .rabook path.
[in]	meta	Resolved metadata to embed.
[in,out]	workspace	Exclusive caller-owned export/compiler workspace.

Returns

Writer, compiler, validator, or publication status.

Return values

k_ra8_ok	One strict RBKC artifact was published.
k_ra8_err_invalid_size	A page/profile/workspace bound was exceeded.
k_ra8_err_validation_failed	An intermediate or final artifact failed validation.

Precondition

All pointers and page rows are valid and stable for the complete call.

ws is exclusively mutable and no competing writer owns the destination.

Postcondition

Success publishes exactly one reader-openable RABOOK artifact.

Failure removes private intermediates and preserves any prior destination.

Note

Not thread-safe for shared storage, destination, or workspace.

Since

0.1.0

Definition at line 475 of file mdl_export_rabook.c.

References mdl_storage_t::fs, fw_fs_unlink(), internal_compile_temp(), internal_emit_container(), internal_write_temp_epub(), k_fw_fs_path_cap, k_name_max, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, k_rabook_page_cap, fw_fs_t::names, and RA8_PRIV.

Referenced by mdl_export_chapter_meta_ws().

priv_mdl_export_snprintf_fit()

bool priv_mdl_export_snprintf_fit	(	int	written,
		size_t	cap )

Report whether an snprintf result fit its destination.

Rejects encoding errors and values that consumed the NUL position.

Parameters

[in]	written	Return value from snprintf.
[in]	cap	Destination capacity passed to snprintf.

Returns

Whether formatting completed without truncation.

Return values

true	The complete result fit.
false	Formatting failed or truncated.

Precondition

cap matches the formatted destination.

written is the unmodified formatting result.

Postcondition

No state is modified.

A true result permits use of the formatted string.

Note

Thread-safe and side-effect free.

Since

0.1.0

Report whether an snprintf result fit its destination.

Rejects encoding errors and results equal to capacity because the terminating NUL would not fit.

Parameters

[in]	written	Return value produced by snprintf.
[in]	cap	Destination capacity passed to snprintf.

Returns

Whether formatting completed without truncation.

Return values

true	written is nonnegative and below cap.
false	Formatting failed or truncated.

Precondition

cap matches the formatted destination.

written is the unmodified snprintf result.

Postcondition

No state is modified.

A true result permits safe use of the destination string.

Note

Thread-safe: this is a pure predicate.

Since

0.1.0

Definition at line 90 of file mdl_export_meta.c.

References RA8_PRIV.

Referenced by internal_epub_add_external_cover(), internal_epub_add_page(), internal_epub_append_frags(), internal_epub_prepare_optional(), internal_epub_render_meta(), internal_epub_write_page_xhtml(), internal_render_comicinfo(), mdl_export_build_comicinfo_pages(), priv_mdl_export_jof(), and priv_mdl_export_prepare_cover().

priv_mdl_export_tar()

ra8_err_t priv_mdl_export_tar	(	mdl_storage_t *	storage,
		const char *	dir,
		char	names[][k_name_max],
		size_t	count,
		mdl_export_output_t *	output,
		const mdl_export_meta_t *	meta )

Write an uncompressed CBT tar archive.

Streams page members and ComicInfo through deterministic ustar records without retaining the whole archive.

Parameters

[in,out]	storage	Injected portable file reader.
[in]	dir	Chapter directory.
[in]	names	Sorted page-name rows.
[in]	count	Page count.
[in,out]	output	Active validated-publication output.
[in]	meta	Resolved metadata.

Returns

Writer status.

Return values

k_ra8_ok	A complete CBT was written.
k_ra8_err_invalid_size	A ustar or metadata bound was exceeded.
k_ra8_fail	File I/O failed.

Precondition

Paths and rows are valid and stable.

output owns an active transaction.

Postcondition

Every opened source stream is closed.

Success includes the complete ustar trailer.

Note

Not thread-safe for the same output.

Since

0.1.0

Definition at line 425 of file mdl_export_tar.c.

References internal_build_tar(), internal_direct_sink(), k_name_max, and RA8_PRIV.

Referenced by internal_export_dispatch().

priv_mdl_export_tar_gzip()

ra8_err_t priv_mdl_export_tar_gzip	(	mdl_storage_t *	storage,
		const char *	dir,
		char	names[][k_name_max],
		size_t	count,
		mdl_export_output_t *	output,
		const mdl_export_meta_t *	meta,
		mdl_export_workspace_t *	ws )

Write a gzip-wrapped CBT archive.

Streams deterministic ustar records directly through caller-arena DEFLATE into the active output; no intermediate archive exists.

Parameters

[in,out]	storage	Injected portable file reader.
[in]	dir	Chapter directory.
[in]	names	Sorted page-name rows.
[in]	count	Page count.
[in,out]	output	Active validated-publication output.
[in]	meta	Resolved metadata.
[in,out]	ws	Exclusive exporter workspace.

Returns

Writer status.

Return values

k_ra8_ok	A complete gzip stream was written.
k_ra8_err_invalid_size	A bound or workspace was exceeded.
k_ra8_fail	File or compression I/O failed.

Precondition

Paths and rows are valid and stable.

Workspace bytes remain live throughout the call.

Postcondition

No intermediate file is created.

Success includes the gzip checksum trailer.

Note

Not thread-safe for shared output or workspace.

Since

0.1.0

Definition at line 436 of file mdl_export_tar.c.

References internal_gzip_sink_t::crc, internal_gzip_sink_t::error, internal_build_tar(), internal_gzip_put(), internal_gzip_sink(), internal_put_u32le(), k_gzip_deflate, k_gzip_header_bytes, k_gzip_id1, k_gzip_id2, k_gzip_os_unknown, k_gzip_u32_bytes, k_name_max, k_ra8_err_invalid_size, k_ra8_fail, k_ra8_ok, mdl_export_workspace_take(), priv_mdl_export_output_write(), RA8_PRIV, and internal_gzip_sink_t::size.

Referenced by internal_export_dispatch().

priv_mdl_export_validate_source_url()

ra8_err_t priv_mdl_export_validate_source_url

(

const char *

url

)

Validate an optional bounded source-attribution URL.

Accepts empty fields or complete absolute HTTP(S) URLs and rejects whitespace, control bytes, invalid authority, and unterminated storage.

Parameters

[in]

url

Fixed-capacity source URL field.

Returns

Source field validation status.

Return values

k_ra8_ok	The field is empty or valid.
k_ra8_err_invalid_size	The field is not NUL-terminated.
k_ra8_err_invalid_arg	The nonempty URL is invalid.

Precondition

url addresses k_mdl_meta_url_max readable bytes.

The caller treats every non-ok result as a metadata failure.

Postcondition

The URL is unchanged.

No filesystem or network access occurs.

Note

Thread-safe and allocation-free.

Since

0.1.0

Requires complete NUL termination, an HTTP(S) scheme, a nonempty authority, and no whitespace/control bytes while permitting XML metacharacters that the container emitters escape later.

Parameters

[in]

url

Fixed-capacity source URL field.

Returns

Source field validation status.

Return values

k_ra8_ok	The field is empty or a valid absolute HTTP(S) URL.
k_ra8_err_invalid_size	The fixed field lacks a terminating NUL.
k_ra8_err_invalid_arg	The nonempty URL has an invalid scheme, authority, whitespace, or control byte.

Precondition

url points to at least k_mdl_meta_url_max readable bytes.

The caller treats every non-ok result as a hard metadata failure.

Postcondition

url is not modified.

No allocation, network access, or filesystem access occurs.

Note

Thread-safe and allocation-free.

Since

0.1.0

Definition at line 54 of file mdl_export_meta.c.

References k_mdl_meta_url_max, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, mdl_url_host(), mdl_url_scheme_allowed(), RA8_PRIV, and strnlen().

Referenced by internal_apply_semantic_key(), internal_parse_xml_semantics(), internal_resolve_export_metadata(), mdl_export_build_comicinfo_pages(), and priv_mdl_epub_add_meta().

priv_mdl_zip_workspace_bind()

void priv_mdl_zip_workspace_bind	(	mz_zip_archive *	zip,
		mdl_zip_allocator_t *	alloc,
		mdl_export_workspace_t *	ws )

Bind a miniz archive to caller-owned bounded storage.

Installs the module allocator callbacks and records the workspace cursor that writer teardown must restore.

Parameters

[out]	zip	Zeroed archive descriptor receiving callbacks.
[out]	alloc	Writer-lifetime allocator adapter.
[in,out]	ws	Exclusive initialized exporter workspace.

Precondition

Every pointer is non-NULL.

Workspace bytes remain live until release.

Postcondition

No default miniz allocator remains installed.

alloc records the initial workspace cursor.

Note

Not thread-safe for a shared workspace.

Since

0.1.0

Bind a miniz archive to caller-owned bounded storage.

Records the current workspace floor and installs allocation, release, and resize callbacks before miniz initialization.

Parameters

[out]	zip	Archive descriptor to initialize.
[out]	alloc	Callback adapter with writer lifetime.
[in,out]	ws	Exclusive initialized exporter workspace.

Precondition

All pointer arguments are non-NULL.

ws owns live writable storage through writer teardown.

Postcondition

zip has no default miniz allocator callback.

alloc records the cursor restored by priv_mdl_zip_workspace_release.

Note

Not thread-safe for a shared workspace.

Since

0.1.0

Definition at line 232 of file mdl_export_zip.c.

References internal_zip_workspace_alloc(), internal_zip_workspace_free(), internal_zip_workspace_realloc(), memset(), RA8_PRIV, and mdl_export_workspace::used.

Referenced by priv_mdl_export_cbz(), and priv_mdl_export_epub().

priv_mdl_zip_workspace_error()

ra8_err_t priv_mdl_zip_workspace_error

(

const mdl_zip_allocator_t *

alloc

)

Classify a miniz writer failure.

Distinguishes caller-arena exhaustion from other ZIP failures.

Parameters

[in]

alloc

Active allocator adapter, or NULL.

Returns

Export status matching the allocator state.

Return values

k_ra8_err_invalid_size	Bounded storage was exhausted.
k_ra8_fail	No exhaustion was recorded.

Precondition

alloc is NULL or remains live.

A writer failure occurred before this call.

Postcondition

Allocator state is unchanged.

Equal state produces an equal result.

Note

Thread-safe across distinct immutable adapters.

Since

0.1.0

Classify a miniz writer failure.

Distinguishes an arena callback refusal from ordinary ZIP I/O or format failures so callers can size their explicit workspace.

Parameters

[in]

alloc

Active callback adapter, or NULL.

Returns

Exporter error matching the recorded allocator state.

Return values

k_ra8_err_invalid_size	Bounded callback capacity was exhausted.
k_ra8_fail	No allocator exhaustion was recorded.

Precondition

alloc is NULL or remains alive through result classification.

The writer has reported a failure before this helper is called.

Postcondition

No workspace counter or block is modified.

Identical allocator state produces an identical result.

Note

Thread-safe for immutable distinct adapters.

Since

0.1.0

Definition at line 278 of file mdl_export_zip.c.

References mdl_zip_allocator_t::exhausted, k_ra8_err_invalid_size, k_ra8_fail, and RA8_PRIV.

Referenced by internal_cbz_add_metadata(), priv_mdl_export_cbz(), and priv_mdl_export_epub().

priv_mdl_zip_workspace_release()

void priv_mdl_zip_workspace_release

(

mdl_zip_allocator_t *

alloc

)

Restore a workspace after a miniz writer ends.

Releases every transient archive block in one cursor operation while retaining the measured high-water mark.

Parameters

[in,out]

alloc

Active adapter, or NULL.

Precondition

alloc is NULL or its writer has ended.

Its workspace is not concurrently accessed.

Postcondition

A valid workspace cursor equals the saved floor.

High-water accounting is preserved.

Note

Not thread-safe for a shared workspace.

Since

0.1.0

Restore a workspace after a miniz writer ends.

Restores the bump cursor to its pre-writer floor after miniz has ended, making transient writer storage reusable by later phases.

Parameters

[in,out]

alloc

Active callback adapter, or NULL.

Precondition

alloc is NULL or its writer has ended or failed initialization.

The associated workspace is not concurrently accessed.

Postcondition

A valid workspace cursor equals the saved floor.

high_water retains the largest observed allocation edge.

Note

Not thread-safe for a shared workspace.

Since

0.1.0

Definition at line 256 of file mdl_export_zip.c.

References mdl_zip_allocator_t::floor, RA8_PRIV, mdl_export_workspace::used, and mdl_zip_allocator_t::ws.

Referenced by internal_epub_finish_writer(), and priv_mdl_export_cbz().