CBZ backend: a streaming miniz ZIP reader that indexes page images. More...

#include <stddef.h>
#include <string.h>
#include "comic.h"
#include "comic_internal.h"
#include "epub_miniz_alloc.h"
#include "miniz.h"
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_decomp_limits.h"

Include dependency graph for comic_cbz.c:

Enumerations
enum	cbz_limits_t : uint16_t { k_cbz_name_max = 256U }
	Per-entry name scratch size for the central-directory walk. More...

Functions
static mz_zip_archive *	internal_zip (comic_t *c)
	The comic's inline mz_zip_archive view.
static size_t	internal_stream_read (void opaque, mz_uint64 file_ofs, void buf, size_t n)
	miniz user-read trampoline – forward to the comic's seek+read backing.
static ra8_err_t	internal_set_alloc (comic_t c, mz_zip_archive zip)
	Route miniz allocations through this comic's private bounded arena.
static ra8_err_t	internal_add_entry (comic_t c, mz_zip_archive zip, mz_uint i)
	Index one central-directory entry if it is a decodable page image.
ra8_err_t	priv_comic_cbz_open (comic_t *c)
	Open the CBZ (ZIP) backend: init the streaming miniz reader + page index.
ra8_err_t	priv_comic_cbz_extract (comic_t c, const comic_page_t p, uint8_t buf, size_t cap, size_t got)
	Extract one CBZ page's encoded image through the streaming ZIP reader.
ra8_err_t	priv_comic_cbz_close (comic_t *c)
	Tear down the CBZ backend's miniz reader.

Variables
static const char *const	s_tag_cbz = "comic_cbz"
	Log tag for CBZ-backend diagnostics.

Detailed Description

CBZ backend: a streaming miniz ZIP reader that indexes page images.

Tag: [Ring 4 / Domain] {World: NS}

The ZIP half of the comic facade. It drives miniz's user-read reader (mz_zip_reader_init) off the comic's seek+read backing – the same streaming path epub_open_streamed uses – so only the central directory and one entry at a time are ever fetched. priv_comic_cbz_open walks the central directory, filters entries to decodable page images (skipping directories, hidden files and AppleDouble forks), and appends each to the shared page index. priv_comic_cbz_extract inflates one page's encoded image (STORE or DEFLATE) on demand.

Miniz's central-directory and decompressor allocations always route through the comic object's caller-owned bounded arena. Host and target follow the same no-heap path, and simultaneously-open comics share no allocator state.

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

Since: Version 0.1.0

Definition in file comic_cbz.c.

Enumeration Type Documentation

◆ cbz_limits_t

enum cbz_limits_t : uint16_t

Per-entry name scratch size for the central-directory walk.

Since: Version 0.1.0

Enumerator

k_cbz_name_max

Longest entry name indexed (bytes, incl.

path).

Definition at line 53 of file comic_cbz.c.

Function Documentation

◆ internal_add_entry()

ra8_err_t internal_add_entry	(	comic_t *	c,
		mz_zip_archive *	zip,
		mz_uint	i )

static

Index one central-directory entry if it is a decodable page image.

Skips directories, non-image / hidden names, and unreadable entries; otherwise appends the entry (with its uncompressed image length and miniz index) to the shared page index.

Parameters

[in,out]	c	Comic accumulating its index.
[in]	zip	Initialised miniz reader.
[in]	i	Central-directory index.

Returns: ra8_err_t status (k_ra8_ok also for a skipped, non-page entry).

Return values

k_ra8_ok	Entry indexed or intentionally skipped.
k_ra8_err_invalid_size	Page index / name arena is full.

Precondition: zip was initialised; i is a valid entry index.; c has its buffers bound.

Postcondition: On k_ra8_ok either one page was added or nothing changed (a skip).; On error the index is unchanged.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 163 of file comic_cbz.c.

References k_cbz_name_max, k_ra8_ok, k_ra8_rar_method_store, priv_comic_is_page_name(), priv_comic_page_add(), ra8_decomp_check_declared(), ra8_decomp_limits_default(), and RA8_INTERNAL.

Referenced by priv_comic_cbz_open().

◆ internal_set_alloc()

ra8_err_t internal_set_alloc	(	comic_t *	c,
		mz_zip_archive *	zip )

static

Route miniz allocations through this comic's private bounded arena.

Both host and target use the same caller-owned workspace. This keeps allocator behaviour test-equivalent and permits independent live CBZ and EPUB objects.

Parameters

[in,out]	c	Comic object that owns the private miniz arena.
[in,out]	zip	Inline archive to configure (must be zeroed first).

Precondition: zip addresses the comic's zeroed inline storage.; Called before mz_zip_reader_init.

Returns: Arena initialisation status.

Return values

k_ra8_ok Allocator callbacks and opaque context were installed.

Postcondition: On success the archive uses c's private miniz workspace.; No I/O is performed.

Note: Not thread-safe; single-threaded init context.

Since: Version 0.1.0

Definition at line 130 of file comic_cbz.c.

References epub_miniz_workspace_t::bytes, epub_miniz_alloc(), epub_miniz_arena_init(), epub_miniz_free(), epub_miniz_realloc(), k_ra8_ok, comic_t::miniz_arena, comic_t::miniz_workspace, and RA8_INTERNAL.

Referenced by priv_comic_cbz_open().

◆ internal_stream_read()

size_t internal_stream_read	(	void *	opaque,
		mz_uint64	file_ofs,
		void *	buf,
		size_t	n )

static

miniz user-read trampoline – forward to the comic's seek+read backing.

Bound to mz_zip_archive::m_pRead; miniz clamps every request to the archive size, so this only defends a caller size shorter than the real archive (a short read aborts the miniz read).

Parameters

[in]	opaque	The comic's comic_stream_t (via m_pIO_opaque).
[in]	file_ofs	Absolute byte offset within the archive.
[out]	buf	Destination buffer (`n` writable bytes).
[in]	n	Bytes requested by miniz.

Returns: Bytes actually read (0 at/after EOF; < n aborts the read).

Return values

0	A NULL/invalid stream, an offset at/after EOF, or a backing read of 0.

Precondition: opaque is the comic's stream descriptor.; buf is writable for n bytes.

Postcondition: No state outside buf is modified.; At most min(n, size - file_ofs) bytes are requested.

Note: Not thread-safe; single-threaded reader context.

Since: Version 0.1.0

Definition at line 97 of file comic_cbz.c.

References comic_stream_t::ctx, comic_stream_t::read, and comic_stream_t::size.

Referenced by priv_comic_cbz_open().

◆ internal_zip()

mz_zip_archive * internal_zip ( comic_t * c )

static

The comic's inline mz_zip_archive view.

Parameters

[in] c Comic carrying the inline storage.

Returns: Typed pointer to the archive within c->zip_storage.

Precondition: c is non-NULL and its storage is aligned for mz_zip_archive.; The storage is zeroed before mz_zip_reader_init.

Postcondition: No state is modified (pure cast).; The result aliases c->zip_storage.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 68 of file comic_cbz.c.

References RA8_INTERNAL, and comic_t::zip_storage.

Referenced by priv_comic_cbz_close(), priv_comic_cbz_extract(), and priv_comic_cbz_open().

◆ priv_comic_cbz_close()

ra8_err_t priv_comic_cbz_close ( comic_t * c )

Tear down the CBZ backend's miniz reader.

Ends the miniz reader (freeing its central directory to the static pool) when one is active, and clears the active flag; a no-op otherwise.

Parameters

[in,out] c Comic whose CBZ reader is to be released.

Returns: ra8_err_t status.

Return values

k_ra8_ok Always; a non-active reader is a no-op.

Precondition: c is a valid comic (possibly already inactive).; c out-lives the call.

Postcondition: c->zip_active == 0.; The miniz central directory is freed to the static pool.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 264 of file comic_cbz.c.

References epub_miniz_arena_deinit(), internal_zip(), k_ra8_ok, comic_t::miniz_arena, RA8_CHECK_NULL_PTR, RA8_PRIV, s_tag_cbz, and comic_t::zip_active.

Referenced by comic_close(), and priv_comic_cbz_open().

◆ priv_comic_cbz_extract()

ra8_err_t priv_comic_cbz_extract	(	comic_t *	c,
		const comic_page_t *	p,
		uint8_t *	buf,
		size_t	cap,
		size_t *	got )

Extract one CBZ page's encoded image through the streaming ZIP reader.

Inflates the ZIP member named by p->zip_index (STORE or DEFLATE) on demand through miniz, into the caller buffer – one page of I/O.

Parameters

[in]	c	Comic with an active CBZ reader.
[in]	p	Page-index entry (its zip_index selects the ZIP member).
[out]	buf	Destination for the encoded image bytes.
[in]	cap	Capacity of `buf`; must be >= p->raw_size.
[out]	got	Receives the bytes written.

Returns: ra8_err_t status.

Return values

k_ra8_ok	Page inflated into `buf`.
k_ra8_err_no_mem	`cap` is smaller than p->raw_size.
k_ra8_err_validation_failed	miniz could not extract the member.

Precondition: c->zip_active == 1; p came from this comic's index.; buf holds cap writable bytes.

Postcondition: On k_ra8_ok, *got == p->raw_size.; On any error *got == 0.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 243 of file comic_cbz.c.

References internal_zip(), k_ra8_err_invalid_state, k_ra8_err_no_mem, k_ra8_err_validation_failed, k_ra8_ok, RA8_CHECK_NULL_PTR, comic_page_t::raw_size, s_tag_cbz, comic_t::zip_active, and comic_page_t::zip_index.

Referenced by comic_page_read().

◆ priv_comic_cbz_open()

ra8_err_t priv_comic_cbz_open ( comic_t * c )

Open the CBZ (ZIP) backend: init the streaming miniz reader + page index.

Binds miniz's user-read ZIP reader to the comic's seek+read backing, walks the central directory, and appends each image entry via priv_comic_page_add. On firmware, miniz allocations route through the epub_miniz_alloc static pool (no heap).

Parameters

[in,out] c Comic with backing + buffers bound, kind == cbz.

Returns: ra8_err_t status.

Return values

k_ra8_ok	Central directory walked; index populated.
k_ra8_err_validation_failed	miniz could not open the ZIP.
k_ra8_err_invalid_size	The page index / name arena was too small.

Precondition: c->read / c->size / c->pages / c->names are bound.; c->stream is available for the miniz I/O opaque pointer.

Postcondition: On k_ra8_ok, c->zip_active == 1 and the index holds every image entry.; On any error the miniz reader is torn down.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 204 of file comic_cbz.c.

References comic_stream_t::ctx, epub_miniz_arena_deinit(), internal_add_entry(), internal_set_alloc(), internal_stream_read(), internal_zip(), k_ra8_err_decomp_entries, k_ra8_err_validation_failed, k_ra8_ok, ra8_decomp_limits_t::max_entries, memset(), comic_t::miniz_arena, priv_comic_cbz_close(), RA8_CHECK_NULL_PTR, ra8_decomp_limits_default(), ra8_decomp_zip_entry_preflight(), RA8_PRIV, comic_stream_t::read, s_tag_cbz, comic_t::size, comic_t::stream, and comic_t::zip_active.

Referenced by internal_open_detect().

Variable Documentation

◆ s_tag_cbz

const char* const s_tag_cbz = "comic_cbz"

static

Log tag for CBZ-backend diagnostics.

Definition at line 39 of file comic_cbz.c.

Referenced by priv_comic_cbz_close(), priv_comic_cbz_extract(), and priv_comic_cbz_open().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ cbz_limits_t

Function Documentation

◆ internal_add_entry()

◆ internal_set_alloc()

◆ internal_stream_read()

◆ internal_zip()

◆ priv_comic_cbz_close()

◆ priv_comic_cbz_extract()

◆ priv_comic_cbz_open()

Variable Documentation

◆ s_tag_cbz