ra8_fs -> epub bridge: open a .epub straight off a filesystem. More...

#include <stddef.h>
#include "epub.h"
#include "ra8_err.h"
#include "ra8_fs.h"

Include dependency graph for epub_fs.h:

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

Data Structures
struct	epub_stream_fs_ctx_t
	Backing state for a streamed ra8_fs EPUB open (#151). More...

Functions
ra8_err_t	epub_open_streamed_fs (ra8_fs_mount_t mount, const char path, epub_stream_fs_ctx_t io, epub_book_t out_book)
	Stream-open an EPUB directly off a mounted ra8_fs volume, no residency (#151).
ra8_err_t	epub_close_streamed_fs (epub_stream_fs_ctx_t io, epub_book_t book)
	Close a book opened by epub_open_streamed_fs() and its source file.

Detailed Description

ra8_fs -> epub bridge: open a .epub straight off a filesystem.

Tag: [Ring 4 / EPUB] {World: S}

The target-side adapter that opens a book living on a mounted ra8_fs volume (FAT12/16/32 over an SD card via ra8_sdmmc_spi, or any other ra8_fs_backend_t) by STREAMING it (#151/#230): epub_open_streamed_fs() hands epub_open_streamed() a seek+read backing over the open file, so only the ZIP tail and one entry at a time are ever resident – no whole-file buffer, no book-size ceiling below the ra8_fs 4 GiB offset limit, and no heap (NASA Rule 3). The retired whole-file epub_open_fs() bridge was deleted with #230 when its last consumer moved onto this streamed path.

Keeping the bridge in its own translation unit (and behind __has_include("ra8_fs.h")) means the pure epub core stays free of any ra8_fs dependency for hosts/apps that only use the in-memory media path.

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

Definition in file epub_fs.h.

Function Documentation

◆ epub_close_streamed_fs()

ra8_err_t epub_close_streamed_fs	(	epub_stream_fs_ctx_t *	io,
		epub_book_t *	book )

nodiscard

Close a book opened by epub_open_streamed_fs() and its source file.

Tears down the miniz reader (via epub_close()) and closes the open source file held in io. Safe to call once after a successful open; after a failed open the file is already closed (io->file == NULL) and only the book is reset.

Parameters

[in,out]	io	Stream context from epub_open_streamed_fs(). Non-NULL.
[in,out]	book	Book opened by epub_open_streamed_fs(). Non-NULL.

Returns: ra8_err_t The result of epub_close(book).

Return values

k_ra8_ok	Book closed and file released.
k_ra8_err_null_ptr	`io` or `book` is NULL.
other	Propagated from epub_close().

Precondition: io and book came from the same epub_open_streamed_fs() call.

Postcondition: io->file == NULL on return.; book->in_use == 0 on k_ra8_ok.

See also: epub_open_streamed_fs()

Since: 0.1.0

Referenced by etoc_check_bad(), etoc_read_toc(), and sh_sd_close_epub().

◆ epub_open_streamed_fs()

ra8_err_t epub_open_streamed_fs	(	ra8_fs_mount_t *	mount,
		const char *	path,
		epub_stream_fs_ctx_t *	io,
		epub_book_t *	out_book )

nodiscard

Stream-open an EPUB directly off a mounted ra8_fs volume, no residency (#151).

Opens path for reading and hands epub_open_streamed() a seek+read backing over the open file instead of reading the whole book into RAM (#151): only the ZIP tail and one entry at a time are ever read from the card, so an arbitrarily large book (bounded by ra8_fs's 32-bit file offsets, i.e. < 4 GiB) opens inside a small fixed RAM budget. The file stays open in io until epub_close_streamed_fs().

Parameters

[in]	mount	Mounted volume handle from ra8_fs_mount(). Non-NULL.
[in]	path	.epub path on the volume. Non-NULL.
[out]	io	Caller-owned stream context; receives the open file. Must out-live `out_book`. Non-NULL.
[out]	out_book	Receives the opened book on success. Non-NULL.

Returns: ra8_err_t outcome.

Return values

k_ra8_ok	Book opened; streams from the card on demand.
k_ra8_err_null_ptr	Any pointer argument is NULL.
other	Propagated from ra8_fs_open or epub_open_streamed.

Precondition: mount is a live mount; path names a .epub; io out-lives out_book.

Postcondition: On k_ra8_ok, *out_book is open and io->file is the open source file.; On any error the file is closed and io->file == NULL.

Note: Not thread-safe vs. concurrent use of the same mount. The file is read on every chapter/cover/resource access, not once up front.

See also: epub_open_streamed(); epub_close_streamed_fs()

Since: 0.1.0

Referenced by eoh_parse_or_halt(), etoc_check_bad(), etoc_read_toc(), and sh_sd_open_epub().

Data Structures

Functions

Detailed Description

Function Documentation

◆ epub_close_streamed_fs()

◆ epub_open_streamed_fs()