Zero-heap streaming writer for the chunked RBKC .rabook container. More...

#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for ra8_rabook_container.h:

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

Data Structures
struct	ra8_rabook_container_workspace_t
	Caller-owned transient storage for one RBKC write. More...

Typedefs
typedef ra8_err_t(*	ra8_rabook_flat_read_fn) (void ctx, uint32_t offset, uint8_t dst, uint32_t requested, uint32_t *out_read)
	Read a bounded range from the flat RABOOK1 source.
typedef ra8_err_t(*	ra8_rabook_write_at_fn) (void ctx, uint64_t offset, const uint8_t src, uint32_t requested, uint32_t *out_written)
	Write a bounded range at an absolute staging-destination offset.

Functions
ra8_err_t	ra8_rabook_container_write (ra8_rabook_flat_read_fn read, void read_ctx, uint32_t flat_len, uint32_t chunk_bytes, ra8_rabook_write_at_fn write_at, void write_ctx, ra8_rabook_container_workspace_t ws, uint64_t out_len)
	Stream one flat RABOOK1 blob into a chunked RBKC staging object.

Detailed Description

Zero-heap streaming writer for the chunked RBKC .rabook container.

Wraps a flat RABOOK1 blob in the random-access RBKC container used by the reader. Input and output are callback-driven, so the same producer works over POSIX files, fw_if_fs, RA8 VFS volumes, RAM, or RPC-backed storage. Each flat chunk is read into caller storage, compressed as one independent RFC 1950 stream, and written to a caller-owned staging destination. No heap, global workspace, filesystem API, or device knowledge is present here.

[Ring 4 / EPUB Compiler] {World: NS}

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

Since: 0.1.0

Definition in file ra8_rabook_container.h.

Typedef Documentation

◆ ra8_rabook_flat_read_fn

typedef ra8_err_t(* ra8_rabook_flat_read_fn) (void *ctx, uint32_t offset, uint8_t *dst, uint32_t requested, uint32_t *out_read)

Read a bounded range from the flat RABOOK1 source.

Parameters

[in,out]	ctx	Caller-owned source context.
[in]	offset	Absolute byte offset in the flat blob.
[out]	dst	Destination spanning `requested` writable bytes.
[in]	requested	Exact requested byte count.
[out]	out_read	Actual bytes copied, never greater than `requested`.

Returns: Backend status; non-ok values are propagated.

Precondition: All pointers are non-NULL and the requested range is in the declared blob.

Postcondition: The container writer rejects a successful short read.

Since: 0.1.0

Definition at line 41 of file ra8_rabook_container.h.

◆ ra8_rabook_write_at_fn

typedef ra8_err_t(* ra8_rabook_write_at_fn) (void *ctx, uint64_t offset, const uint8_t *src, uint32_t requested, uint32_t *out_written)

Write a bounded range at an absolute staging-destination offset.

Parameters

[in,out]	ctx	Caller-owned destination context.
[in]	offset	Absolute byte offset in the RBKC staging object.
[in]	src	Source spanning `requested` readable bytes.
[in]	requested	Exact requested byte count.
[out]	out_written	Actual bytes stored, never greater than `requested`.

Returns: Backend status; non-ok values are propagated.

Precondition: All pointers are non-NULL and the destination supports bounded random writes.

Postcondition: The container writer rejects a successful short write.

Since: 0.1.0

Definition at line 59 of file ra8_rabook_container.h.

Function Documentation

◆ ra8_rabook_container_write()

ra8_err_t ra8_rabook_container_write	(	ra8_rabook_flat_read_fn	read,
		void *	read_ctx,
		uint32_t	flat_len,
		uint32_t	chunk_bytes,
		ra8_rabook_write_at_fn	write_at,
		void *	write_ctx,
		ra8_rabook_container_workspace_t *	ws,
		uint64_t *	out_len )

nodiscard

Stream one flat RABOOK1 blob into a chunked RBKC staging object.

Writes the fixed little-endian header, reserves the complete offset table, then reads and zlib-compresses each independent flat chunk. The table is back-filled only after all streams succeed. The caller must target a private staging object and validate it before atomic publication; this function deliberately owns neither filenames nor commit policy.

Parameters

[in]	read	Source read callback.
[in,out]	read_ctx	Context passed to `read`.
[in]	flat_len	Exact nonzero flat RABOOK1 length.
[in]	chunk_bytes	Inflated bytes per independently compressed chunk.
[in]	write_at	Random-write callback for the staging destination.
[in,out]	write_ctx	Context passed to `write_at`.
[in,out]	ws	Exclusive caller-owned workspace.
[out]	out_len	Final RBKC byte length.

Returns: Container write status.

Return values

k_ra8_ok	Complete RBKC bytes were written and `out_len` was set.
k_ra8_err_null_ptr	A required pointer or workspace member was NULL.
k_ra8_err_invalid_arg	`flat_len` or `chunk_bytes` was zero.
k_ra8_err_invalid_size	A workspace/table bound was insufficient, an offset overflowed, or a callback was short.
k_ra8_err_no_mem	The compressed-chunk destination was too small.

Returns: Any other source, destination, or compressor error is propagated.

Precondition: ws storage is non-overlapping and exclusively owned for the call.; read serves every byte in [0, flat_len) repeatably.; write_at targets a private staging object and supports back-filling.

Postcondition: On success the output conforms to book_container_t.; On failure out_len is zero and the caller must abort its staging object.; No dynamically allocated memory or global mutable state is used.

Note: Not thread-safe with respect to the supplied callbacks or workspace.

Since: 0.1.0

Definition at line 389 of file ra8_rabook_container.c.

References internal_validate(), internal_write_chunks(), internal_write_prefix(), internal_write_table(), k_book_container_entry_len, k_book_container_header_len, k_ra8_err_invalid_size, k_ra8_ok, and ra8_rabook_container_workspace_t::offsets.

Referenced by internal_emit_container(), and priv_media_download_format_rabook().

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ ra8_rabook_flat_read_fn

◆ ra8_rabook_write_at_fn

Function Documentation

◆ ra8_rabook_container_write()