epub_entry.h File Reference

Iterative, bounded-RAM ZIP-entry extraction for the EPUB reader (#231). More...

#include "epub.h"

Include dependency graph for epub_entry.h:

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

Go to the source code of this file.

Data Structures
struct	epub_entry_reader_t
	Forward streaming cursor over one ZIP entry – inflate in bounded RAM (#231). More...

Enumerations
enum	epub_entry_reader_layout_t : uint8_t { k_epub_entry_reader_reserved_bytes }
	Fixed-layout constants for epub_entry_reader_t. More...

Functions
ra8_err_t	epub_entry_open (epub_book_t *book, const char *path, epub_entry_reader_t *out_reader, uint64_t *out_size)
	Begin a bounded-RAM streaming extraction of one archive entry (#231).
ra8_err_t	epub_entry_read (epub_entry_reader_t *reader, uint8_t *buf, size_t cap, size_t *got)
	Pull the next chunk of a streaming entry into a bounded caller buffer (#231).
ra8_err_t	epub_entry_close (epub_entry_reader_t *reader)
	Tear down a streaming-entry cursor and release its inflate state (#231).
ra8_err_t	epub_entry_pread (epub_book_t *book, const char *path, uint64_t offset, uint8_t *buf, size_t len, size_t *got)
	Positioned read of a stored (uncompressed) archive entry – windowed random access in bounded RAM (#231).

Detailed Description

Iterative, bounded-RAM ZIP-entry extraction for the EPUB reader (#231).

Split out of epub.h so that header stays inside the 1000-line maintainability cap. This is the forward-streaming cursor over a single ZIP entry: epub_open() / epub_open_streamed() give you a book, and epub_entry_open() / _read() / _close() inflate one archive entry a bounded block at a time instead of materialising it whole (as epub_get_resource() does). epub_entry_pread() is the positioned read for stored (uncompressed) entries. The implementation lives in epub_entry.c.

This header depends on epub.h (for epub_book_t) and includes it, so the dependency is one-directional: epub.h does NOT include this header. A translation unit that needs the entry cursor includes this header directly (epub.h alone is not sufficient for the entry API).

[Ring 4 / EPUB] {World: NS}

See also

epub.h

Copyright

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

Since

0.1.0

Definition in file epub_entry.h.

Enumeration Type Documentation

epub_entry_reader_layout_t

enum epub_entry_reader_layout_t : uint8_t

Fixed-layout constants for epub_entry_reader_t.

Names the trailing padding that rounds the reader's single-byte done flag up to the struct's 8-byte alignment, so the layout carries no bare numeric literal.

Invariant

k_epub_entry_reader_reserved_bytes keeps done plus the padding at 8 bytes, matching the alignment of the leading 64-bit members.

See also

epub_entry_reader_t

Since

0.1.0

Enumerator
k_epub_entry_reader_reserved_bytes	Padding bytes after done; rounds the tail to 8-byte alignment.

Definition at line 59 of file epub_entry.h.

Function Documentation

epub_entry_close()

ra8_err_t epub_entry_close ( epub_entry_reader_t * reader )

nodiscard

Tear down a streaming-entry cursor and release its inflate state (#231).

Frees the miniz iterator (returning its LZ dictionary + read buffer to the allocator). If the entire entry had been read, the entry's CRC/size are verified as a corruption check; an early close (before EOF) is legal and simply releases resources. Idempotent on an already-closed cursor.

Parameters

[in,out]

reader

Cursor from epub_entry_open().

Returns

ra8_err_t

Return values

k_ra8_ok	Cursor closed and state released.
k_ra8_err_null_ptr	reader is NULL.
k_ra8_err_validation_failed	The fully-read entry failed CRC/size verification.

Precondition

reader is a cursor (open or already closed).

Postcondition

reader->iter == NULL on return.

No inflate state remains allocated for this cursor.

Note

Not thread-safe.

See also

epub_entry_open()

Since

0.1.0

Definition at line 392 of file epub_entry.c.

References epub_entry_reader_t::consumed, epub_entry_reader_t::iter, k_ra8_err_validation_failed, k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and epub_entry_reader_t::total.

epub_entry_open()

ra8_err_t epub_entry_open ( epub_book_t * book, const char * path, epub_entry_reader_t * out_reader, uint64_t * out_size )

nodiscard

Begin a bounded-RAM streaming extraction of one archive entry (#231).

Resolves path the same way epub_get_resource() does – first joined onto the OPF directory (book->opf_dir), then as a bare archive-rooted path – then starts a miniz extract-iterator over the located entry. No entry bytes are inflated yet; the caller pulls them with epub_entry_read(). The entry's uncompressed size is reported so the caller can size a progress bar or a tile grid without materialising the entry.

Parameters

[in]	book	Open book (in_use == 1, archive active).
[in]	path	Entry path, OPF-dir-relative or archive-rooted, NUL-terminated.
[out]	out_reader	Cursor to populate (zero-initialised by the caller).
[out]	out_size	Receives the entry's uncompressed size in bytes (may be NULL).

Returns

ra8_err_t

Return values

k_ra8_ok	Cursor open; read with epub_entry_read().
k_ra8_err_null_ptr	book, path, or out_reader is NULL.
k_ra8_err_not_initialized	Book not open / archive inactive.
k_ra8_err_not_found	No entry at path (prefixed or bare).
k_ra8_err_validation_failed	The iterator could not be started (corrupt entry).

Precondition

book->in_use == 1 and the archive is active.

out_reader points at writable, zero-initialised storage.

Postcondition

On success out_reader->iter != NULL and *out_size (if given) is the size.

On any error *out_reader is zeroed and no iterator leaks.

Note

Not thread-safe; the reader serialises archive access (one open cursor at a time).

See also

epub_entry_read()

epub_entry_close()

Since

0.1.0

Definition at line 331 of file epub_entry.c.

References epub_entry_reader_t::book, epub_entry_reader_t::done, epub_book_t::in_use, internal_open_iter(), epub_entry_reader_t::iter, k_ra8_err_not_initialized, k_ra8_ok, memset(), priv_epub_book_not_ready(), RA8_CHECK_NULL_PTR, s_tag, epub_entry_reader_t::total, and epub_book_t::zip_archive_active.

epub_entry_pread()

ra8_err_t epub_entry_pread ( epub_book_t * book, const char * path, uint64_t offset, uint8_t * buf, size_t len, size_t * got )

nodiscard

Positioned read of a stored (uncompressed) archive entry – windowed random access in bounded RAM (#231).

For an entry stored with no compression (ZIP method 0 – the natural choice for already-compressed pixel data or a display-native tile atlas), the uncompressed bytes lie contiguously in the archive, so any window [offset, offset+len) can be read directly off the backing without inflating from the start. This is the random-access primitive the tile source (epub_img_tiles) uses to page a single tile without holding the whole image. A short read at the entry's tail is reported via *got.

Deflated entries are rejected (k_ra8_err_not_supported): random access into a DEFLATE stream requires inflating from the start, which the forward cursor (epub_entry_read()) already provides.

Parameters

[in]	book	Open book (in_use == 1, archive active).
[in]	path	Entry path, OPF-dir-relative or archive-rooted, NUL-terminated.
[in]	offset	Byte offset into the entry's uncompressed data.
[out]	buf	Destination buffer (len writable bytes).
[in]	len	Bytes requested.
[out]	got	Bytes actually read (0 at/after the entry's end).

Returns

ra8_err_t

Return values

k_ra8_ok	Window read (possibly short at EOF; see *got).
k_ra8_err_null_ptr	book, path, buf, or got is NULL.
k_ra8_err_not_initialized	Book not open / archive inactive.
k_ra8_err_not_found	No entry at path (prefixed or bare).
k_ra8_err_not_supported	The entry is DEFLATE-compressed (use the cursor).
k_ra8_err_validation_failed	The local header could not be read / is corrupt.

Precondition

book->in_use == 1 and the archive is active.

buf holds len writable bytes.

Postcondition

On success *got <= len bytes are written to buf.

On any error *got == 0.

Note

Not thread-safe.

See also

epub_entry_read()

Since

0.1.0

Definition at line 446 of file epub_entry.c.

References epub_book_t::in_use, internal_backing_read(), internal_pread_null_ok(), internal_stored_data_offset(), k_ra8_err_not_initialized, k_ra8_err_validation_failed, k_ra8_ok, priv_epub_book_not_ready(), and epub_book_t::zip_archive_active.

epub_entry_read()

ra8_err_t epub_entry_read ( epub_entry_reader_t * reader, uint8_t * buf, size_t cap, size_t * got )

nodiscard

Pull the next chunk of a streaming entry into a bounded caller buffer (#231).

Inflates up to cap more bytes of the entry into buf. A short read (*got < cap) means end-of-entry has been reached; a subsequent call reports *got == 0. The caller reuses the same fixed buf across calls, so the high-water resident footprint is cap – constant regardless of how large the entry inflates to.

Parameters

[in]	reader	Cursor from epub_entry_open().
[out]	buf	Destination chunk buffer (cap writable bytes).
[in]	cap	Capacity of buf, bytes (> 0).
[out]	got	Bytes written this call (0 at end-of-entry).

Returns

ra8_err_t

Return values

k_ra8_ok	Chunk delivered (or clean EOF with *got == 0).
k_ra8_err_null_ptr	reader, buf, or got is NULL.
k_ra8_err_not_initialized	reader is closed / never opened.
k_ra8_err_invalid_size	cap == 0.
k_ra8_err_validation_failed	The compressed stream is corrupt (bad CRC / LZ).

Precondition

reader came from a successful epub_entry_open().

buf holds cap writable bytes.

Postcondition

On success reader->consumed advanced by *got.

*got == 0 iff the whole entry has now been delivered.

Note

Not thread-safe.

See also

epub_entry_open()

Since

0.1.0

Definition at line 360 of file epub_entry.c.

References epub_entry_reader_t::consumed, epub_entry_reader_t::done, epub_entry_reader_t::iter, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_err_validation_failed, k_ra8_ok, RA8_CHECK_NULL_PTR, s_tag, and epub_entry_reader_t::total.