Cross-TU seams between the comic facade and its CBZ / CBR backends. More...

#include <stddef.h>
#include <stdint.h>
#include "comic.h"
#include "ra8_attributes.h"
#include "ra8_err.h"

Include dependency graph for comic_internal.h:

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

Functions
bool	priv_comic_is_page_name (const char *name, uint16_t len)
	Whether an archive entry name is a decodable comic page image.
ra8_err_t	priv_comic_page_add (comic_t c, const char name, uint16_t name_len, uint64_t raw_size, uint8_t extractable, uint8_t method, uint32_t zip_index, uint64_t data_off, uint64_t pack_size)
	Append one image member to the resident page index.
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.
ra8_err_t	priv_comic_cbr_open (comic_t *c)
	Open the CBR (RAR) backend: walk the archive + build the page index.
ra8_err_t	priv_comic_cbr_extract (comic_t c, const comic_page_t p, uint8_t buf, size_t cap, size_t got)
	Extract one CBR page's encoded image (STORE copy or RAR5 decode).
ra8_err_t	priv_comic_cbt_open (comic_t *c)
	Open the CBT (tar) backend: walk the archive + build the page index.
ra8_err_t	priv_comic_cbt_extract (comic_t c, const comic_page_t p, uint8_t buf, size_t cap, size_t got)
	Extract one CBT page's encoded image (verbatim tar member copy).

Detailed Description

Cross-TU seams between the comic facade and its CBZ / CBR backends.

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

comic.c owns the public API, the shared page-index storage, the entry-name image filter, and the name-sort. Each container backend – comic_cbz.c (miniz ZIP) and comic_cbr.c (RAR via ra8_rar.h) – enumerates its image members by calling priv_comic_page_add and extracts one page through its own *_extract. This header is the internal contract between them; it is not part of the public comic.h surface.

Note: Not thread-safe; the single-threaded reader loop serialises access.

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

Definition in file comic_internal.h.

Function Documentation

◆ priv_comic_cbr_extract()

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

Extract one CBR page's encoded image (STORE copy or RAR5 decode).

Routes the page through ra8_rar_extract: a STORE member's literal bytes are streamed, a RAR5-compressed member is inflated by the decompressor into buf. A RAR4-compressed page (indexed non-extractable) is rejected.

Parameters

[in]	c	Comic with a bound CBR walker.
[in]	p	Page-index entry (its data_off / raw_size / rar_method).
[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	Member copied / decoded into `buf`.
k_ra8_err_not_supported	The page is a RAR4-compressed member.
k_ra8_err_no_mem	`cap` is smaller than p->raw_size.
k_ra8_err_invalid_size	A STORE member overruns the archive / short read.
k_ra8_err_validation_failed	A malformed / truncated compressed stream.

Precondition: p came from this comic's CBR 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 150 of file comic_cbr.c.

References comic_page_t::data_off, ra8_rar_entry_t::data_off, comic_page_t::extractable, ra8_rar_entry_t::is_dir, ra8_rar_entry_t::is_file, k_ra8_err_invalid_state, k_ra8_err_not_supported, k_ra8_rar_ver_none, ra8_rar_entry_t::method, comic_page_t::pack_size, ra8_rar_entry_t::pack_size, RA8_CHECK_NULL_PTR, ra8_rar_extract(), comic_t::rar, comic_t::rar5_state, comic_page_t::rar_method, comic_page_t::raw_size, s_tag_cbr, ra8_rar_entry_t::unp_size, and ra8_rar_t::version.

Referenced by comic_page_read().

◆ priv_comic_cbr_open()

ra8_err_t priv_comic_cbr_open ( comic_t * c )

Open the CBR (RAR) backend: walk the archive + build the page index.

Iterates the RAR block chain (ra8_rar_next) from c->rar.first_off, appending each image file member via priv_comic_page_add. STORE and (on a RAR5 archive) compressed members are indexed extractable == 1; only a RAR4-compressed member (legacy codec, unsupported) gets extractable == 0.

Parameters

[in,out] c Comic with c->rar bound by ra8_rar_open, kind == cbr.

Returns: ra8_err_t status.

Return values

k_ra8_ok	Archive walked; index populated.
k_ra8_err_invalid_size	The page index / name arena was too small.
k_ra8_err_*	A RAR-walk error.

Precondition: c->rar was bound by ra8_rar_open; buffers are bound.; c->size is the archive length.

Postcondition: On k_ra8_ok, the index holds every image member in archive order.; On any error the index is left partially filled (caller discards c).

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 111 of file comic_cbr.c.

References ra8_rar_t::first_off, internal_add_member(), k_cbr_max_blocks, k_cbr_name_max, k_ra8_err_invalid_state, k_ra8_ok, k_ra8_rar_ver_none, ra8_decomp_budget_t::limits, ra8_rar_entry_t::name_len, ra8_rar_entry_t::next_off, RA8_CHECK_NULL_PTR, ra8_decomp_budget_charge_entry(), ra8_decomp_limits_default(), RA8_PRIV, ra8_rar_next(), comic_t::rar, s_tag_cbr, ra8_rar_t::size, and ra8_rar_t::version.

Referenced by internal_open_detect().

◆ priv_comic_cbt_extract()

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

Extract one CBT page's encoded image (verbatim tar member copy).

Streams the member's literal bytes through unarch_tar_read, which re-validates the (potentially forged) entry bounds against the archive before any copy.

Parameters

[in]	c	Comic with a bound CBT walker.
[in]	p	Page-index entry (its data_off / raw_size).
[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	Member copied into `buf`.
k_ra8_err_no_mem	`cap` is smaller than p->raw_size.
k_ra8_err_invalid_size	The member overruns the archive / short read.

Precondition: p came from this comic's CBT 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 116 of file comic_cbt.c.

References comic_page_t::data_off, unarch_tar_entry_t::data_off, unarch_tar_entry_t::is_file, k_ra8_err_invalid_state, unarch_tar_t::live, RA8_CHECK_NULL_PTR, comic_page_t::raw_size, s_tag_cbt, unarch_tar_entry_t::size, comic_t::tar, and unarch_tar_read().

Referenced by comic_page_read().

◆ priv_comic_cbt_open()

ra8_err_t priv_comic_cbt_open ( comic_t * c )

Open the CBT (tar) backend: walk the archive + build the page index.

Iterates the tar member chain (unarch_tar_next) from offset 0, appending each image file member via priv_comic_page_add. tar stores members verbatim, so every indexed page is extractable == 1 with pack_size == raw_size. The walk (and each member's declared size) is charged against the walker's embedded decompression budget.

Parameters

[in,out] c Comic with c->tar bound by unarch_tar_open, kind == cbt.

Returns: ra8_err_t status.

Return values

k_ra8_ok	Archive walked; index populated.
k_ra8_err_invalid_size	The page index / name arena was too small.
k_ra8_err_decomp_*	The walk breached the decompression policy.
k_ra8_err_*	A tar-walk error (malformed header, ...).

Precondition: c->tar was bound by unarch_tar_open; buffers are bound.; c->size is the archive length.

Postcondition: On k_ra8_ok, the index holds every image member in archive order.; On any error the index is left partially filled (caller discards c).

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 87 of file comic_cbt.c.

References internal_add_member(), k_cbt_max_members, k_cbt_name_max, k_ra8_err_invalid_state, k_ra8_err_not_found, k_ra8_err_validation_failed, k_ra8_ok, unarch_tar_t::live, unarch_tar_entry_t::name_len, unarch_tar_entry_t::next_off, RA8_CHECK_NULL_PTR, RA8_PRIV, s_tag_cbt, comic_t::tar, and unarch_tar_next().

Referenced by internal_open_detect().

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

◆ priv_comic_is_page_name()

bool priv_comic_is_page_name	(	const char *	name,
		uint16_t	len )

Whether an archive entry name is a decodable comic page image.

A page qualifies when its base name is not a dotfile (skips hidden entries and macOS __MACOSX/._* AppleDouble resource forks) and it ends in an image extension the on-device decoder (stb_image) handles: .jpg, .jpeg, .png, .gif, .bmp (case-insensitive). Both / and \\ are treated as path separators for the base-name test.

Parameters

[in]	name	Entry name bytes (not NUL-terminated; `len` is authoritative).
[in]	len	Length of `name` in bytes.

Returns: Whether name is a page image to index.

Return values

true	`name` is a decodable, non-hidden page image.
false	`name` is hidden, a resource fork, or not a decodable image.

Precondition: name addresses at least len readable bytes (or len is 0).; len is the true entry-name length.

Postcondition: No state is modified (pure read).; The result depends only on name / len.

Note: Thread-safe: pure read.

Since: Version 0.1.0

Definition at line 152 of file comic.c.

References internal_is_image_ext(), and RA8_PRIV.

Referenced by internal_add_entry(), internal_add_member(), and internal_add_member().

◆ priv_comic_page_add()

ra8_err_t priv_comic_page_add	(	comic_t *	c,
		const char *	name,
		uint16_t	name_len,
		uint64_t	raw_size,
		uint8_t	extractable,
		uint8_t	method,
		uint32_t	zip_index,
		uint64_t	data_off,
		uint64_t	pack_size )

Append one image member to the resident page index.

Copies name into the comic's name arena and fills the next comic_page_t slot with the backend bookkeeping. Rejects an index or arena overflow so no page is silently dropped.

Parameters

[in,out]	c	Comic accumulating its page index.
[in]	name	Entry name bytes.
[in]	name_len	Length of `name` in bytes.
[in]	raw_size	Encoded image length in bytes.
[in]	extractable	1 if this reader can decode the page, else 0.
[in]	method	CBR ra8_rar_method_t (0 = store); 0 for CBZ.
[in]	zip_index	CBZ miniz central-directory index (0 for CBR).
[in]	data_off	CBR member data-area offset (0 for CBZ).
[in]	pack_size	CBR packed size (0 for CBZ).

Returns: ra8_err_t status.

Return values

k_ra8_ok	Page appended.
k_ra8_err_invalid_size	Page index or name arena is full.

Precondition: c has its pages / names buffers bound.; name addresses name_len readable bytes.

Postcondition: On k_ra8_ok, c->page_count and c->names_len advanced by one entry.; On any error the index and arena are unchanged.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 177 of file comic.c.

References comic_page_t::data_off, comic_page_t::extractable, k_ra8_err_invalid_size, k_ra8_ok, memcpy(), comic_page_t::name_len, comic_page_t::name_off, comic_t::names, comic_t::names_cap, comic_t::names_len, comic_page_t::pack_size, comic_t::page_cap, comic_t::page_count, comic_t::pages, RA8_CHECK_NULL_PTR, RA8_PRIV, comic_page_t::rar_method, comic_page_t::raw_size, s_tag_comic, and comic_page_t::zip_index.

Referenced by internal_add_entry(), internal_add_member(), and internal_add_member().

Functions

Detailed Description

Function Documentation

◆ priv_comic_cbr_extract()

◆ priv_comic_cbr_open()

◆ priv_comic_cbt_extract()

◆ priv_comic_cbt_open()

◆ priv_comic_cbz_close()

◆ priv_comic_cbz_extract()

◆ priv_comic_cbz_open()

◆ priv_comic_is_page_name()

◆ priv_comic_page_add()