Private bounded RABOOK export contracts for the media downloader. More...

#include <stddef.h>
#include <stdint.h>
#include "epub.h"
#include "mdl_export_internal.h"
#include "mdl_export_io_internal.h"

Include dependency graph for mdl_export_rabook_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_rabook_epub_source_t
	Open portable EPUB stream retained during one compile. More...
struct	mdl_rabook_flat_source_t
	Resident flat RABOOK1 source for the chunked container writer. More...

Functions
ra8_err_t	priv_mdl_rabook_temp_begin (mdl_export_output_t output, mdl_storage_t storage, const char directory, const char destination, char *path, size_t capacity)
	Reserve one collision-free temporary EPUB publication path.
ra8_err_t	priv_mdl_rabook_epub_open (mdl_rabook_epub_source_t source, mdl_storage_t storage, const char *path)
	Open one validated temporary EPUB as a portable random-read stream.
ra8_err_t	priv_mdl_rabook_epub_close (mdl_rabook_epub_source_t *source)
	Close one temporary EPUB stream.
size_t	priv_mdl_rabook_epub_read (void opaque, uint64_t offset, void destination, size_t length)
	Serve one exact random EPUB read to the streamed reader.
ra8_err_t	priv_mdl_rabook_flat_read (void opaque, uint32_t offset, uint8_t destination, uint32_t requested, uint32_t *out_read)
	Serve one exact flat-blob read to the RBKC writer.

Detailed Description

Private bounded RABOOK export contracts for the media downloader.

Separates portable temporary-EPUB I/O from the fixed-profile EPUB-to-RABOOK compiler and validated RBKC publication coordinator.

[Ring 4 / Domain] {World: NS}

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

Since: 0.1.0

Definition in file mdl_export_rabook_internal.h.

Function Documentation

◆ priv_mdl_rabook_epub_close()

ra8_err_t priv_mdl_rabook_epub_close ( mdl_rabook_epub_source_t * source )

Close one temporary EPUB stream.

Delegates to the injected file adapter and clears retained state only after the close operation succeeds.

Parameters

[in,out] source Open source state.

Returns: Portable close status.

Return values

k_ra8_ok	The file closed and state was cleared.
other	The portable close operation failed.

Precondition: source is non-NULL and owns an open file.; No EPUB reader continues to borrow the source callback.

Postcondition: Success clears the complete source state.; Failure remains visible and the state is not claimed reusable.

Note: Not thread-safe for a shared source.

Since: 0.1.0

Definition at line 148 of file mdl_export_rabook_io.c.

References mdl_rabook_epub_source_t::file, fw_fs_close(), fw_fs_file_t::is_open, k_ra8_err_invalid_arg, k_ra8_ok, and RA8_PRIV.

Referenced by internal_close_compile_sources().

◆ priv_mdl_rabook_epub_open()

ra8_err_t priv_mdl_rabook_epub_open	(	mdl_rabook_epub_source_t *	source,
		mdl_storage_t *	storage,
		const char *	path )

Open one validated temporary EPUB as a portable random-read stream.

Stats and opens one regular file, retaining its exact immutable extent for the callback lifetime.

Parameters

[out]	source	Caller-owned stream state.
[in,out]	storage	Exclusive portable storage binding.
[in]	path	Canonical temporary EPUB path.

Returns: File metadata/open status.

Return values

k_ra8_ok	A nonempty regular file is open with a stable extent.
k_ra8_err_invalid_arg	The node is nonregular or an argument is invalid.

Precondition: Pointers are non-NULL and source owns no open file.; No concurrent writer mutates path.

Postcondition: Success initializes the complete source state.; Failure leaves source clear and owns no file.

Note: The storage file workspace is borrowed until close.

Since: 0.1.0

Definition at line 108 of file mdl_export_rabook_io.c.

References fw_fs_stat_t::exists, mdl_rabook_epub_source_t::file, mdl_storage_t::file_workspace, mdl_storage_t::file_workspace_bytes, mdl_storage_t::fs, fw_fs_close(), fw_fs_file_size(), fw_fs_open(), fw_fs_stat(), fw_fs_file_t::is_open, k_fw_fs_node_file, k_fw_fs_open_read, k_ra8_err_invalid_arg, k_ra8_err_protocol_error, k_ra8_ok, fw_fs_t::names, RA8_PRIV, fw_fs_stat_t::size_bytes, mdl_rabook_epub_source_t::size_bytes, fw_fs_t::streams, and fw_fs_stat_t::type.

Referenced by internal_compile_temp().

◆ priv_mdl_rabook_epub_read()

size_t priv_mdl_rabook_epub_read	(	void *	opaque,
		uint64_t	offset,
		void *	destination,
		size_t	length )

Serve one exact random EPUB read to the streamed reader.

Bounds the request against the retained extent, seeks explicitly, and latches any short read or excessive callback count.

Parameters

[in,out]	opaque	Bound mdl_rabook_epub_source_t.
[in]	offset	Absolute archive byte offset.
[out]	destination	Writable destination.
[in]	length	Exact requested byte count.

Returns: length on complete success, otherwise zero.

Return values

0	The request was invalid, out of range, short, or faulted.
other	The exact positive `length` requested by the reader.

Precondition: Pointer arguments are non-NULL and the file remains open.; destination spans length writable bytes.

Postcondition: Success initializes every requested destination byte.; Failure latches the first canonical error in the source state.

Note: The callback is serialized by the EPUB reader.

Since: 0.1.0

Definition at line 160 of file mdl_export_rabook_io.c.

References mdl_rabook_epub_source_t::calls, mdl_rabook_epub_source_t::error, mdl_rabook_epub_source_t::file, fw_fs_read(), fw_fs_seek(), fw_fs_file_t::is_open, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_err_out_of_range, k_ra8_ok, k_rabook_read_calls, RA8_PRIV, and mdl_rabook_epub_source_t::size_bytes.

Referenced by internal_compile_temp().

◆ priv_mdl_rabook_flat_read()

ra8_err_t priv_mdl_rabook_flat_read	(	void *	opaque,
		uint32_t	offset,
		uint8_t *	destination,
		uint32_t	requested,
		uint32_t *	out_read )

Serve one exact flat-blob read to the RBKC writer.

Validates offset arithmetic before copying the requested resident span and reporting its exact transferred count.

Parameters

[in]	opaque	Bound mdl_rabook_flat_source_t.
[in]	offset	Flat blob byte offset.
[out]	destination	Writable destination.
[in]	requested	Exact requested byte count.
[out]	out_read	Exact copied count on success.

Returns: Range or copy status.

Return values

k_ra8_ok	The complete requested range was copied.
k_ra8_err_out_of_range	The range exceeds the flat blob.

Precondition: All pointers are non-NULL and spans match their declared extents.; The flat blob remains immutable for the call.

Postcondition: Success initializes the complete destination range.; Failure sets out_read to zero.

Note: Thread-safe for immutable distinct destinations.

Since: 0.1.0

Definition at line 197 of file mdl_export_rabook_io.c.

References mdl_rabook_flat_source_t::bytes, k_ra8_err_invalid_arg, k_ra8_err_out_of_range, k_ra8_ok, memcpy(), RA8_PRIV, and mdl_rabook_flat_source_t::size_bytes.

Referenced by internal_emit_container().

◆ priv_mdl_rabook_temp_begin()

ra8_err_t priv_mdl_rabook_temp_begin	(	mdl_export_output_t *	output,
		mdl_storage_t *	storage,
		const char *	directory,
		const char *	destination,
		char *	path,
		size_t	capacity )

Reserve one collision-free temporary EPUB publication path.

Hashes the final destination into bounded 8.3-compatible sibling names and uses create-new transactions so no prior file is replaced.

Parameters

[out]	output	Active create-new EPUB output on success.
[in,out]	storage	Exclusive portable storage binding.
[in]	directory	Canonical directory that will contain the temporary file.
[in]	destination	Final RABOOK path used only as a deterministic salt.
[out]	path	Destination for the chosen canonical temporary path.
[in]	capacity	Writable bytes at `path`.

Returns: Path construction or transaction-open status.

Return values

k_ra8_ok	One private EPUB stage is active.
k_ra8_err_exists	Every bounded candidate already exists.
k_ra8_err_invalid_size	The temporary path cannot fit.

Precondition: Pointers are non-NULL and strings are NUL-terminated.; output is inactive and storage is exclusively owned.

Postcondition: Success initializes path and one active output transaction.; Failure changes no named file and leaves output inactive.

Note: At most sixteen candidate names are attempted.

Since: 0.1.0

Definition at line 77 of file mdl_export_rabook_io.c.

References internal_temp_leaf(), internal_temp_seed(), k_mdl_format_epub, k_ra8_err_exists, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, k_rabook_temp_attempts, k_rabook_value_mask, priv_mdl_export_output_begin_new(), priv_mdl_export_path_join(), and RA8_PRIV.

Referenced by internal_write_temp_epub().

Data Structures

Functions

Detailed Description

Function Documentation

◆ priv_mdl_rabook_epub_close()

◆ priv_mdl_rabook_epub_open()

◆ priv_mdl_rabook_epub_read()

◆ priv_mdl_rabook_flat_read()

◆ priv_mdl_rabook_temp_begin()