Module-private bounded source-key streaming contracts. More...

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

Include dependency graph for rabook_import_internal.h:

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

Typedefs
typedef ra8_err_t(*	rabook_import_read_fn) (void ctx, uint8_t buf, uint32_t requested, uint32_t *out_read)
	Exact sequential-reader seam used by the source-key CRC pass.

Functions
ra8_err_t	priv_rabook_import_crc_stream (rabook_import_read_fn read_fn, void read_ctx, uint64_t expected_size, uint8_t buf, uint32_t cap, uint32_t max_reads, uint32_t out_size, uint32_t out_crc)
	Compute one exact bounded source CRC through an injected reader.
ra8_err_t	rabook_import_crc_stream_test (rabook_import_read_fn read_fn, void read_ctx, uint64_t expected_size, uint8_t buf, uint32_t cap, uint32_t max_reads, uint32_t out_size, uint32_t out_crc)
	Exercise the bounded source-key CRC contract from focused tests.

Detailed Description

Module-private bounded source-key streaming contracts.

Declares the exact sequential-read seam shared by the RABOOK importer and its focused tests. The contract consumes a stable source-size snapshot, confirms EOF within a bounded callback budget, and publishes CRC and size only after the complete stream has been accepted.

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

Since: Version 0.1.0

Definition in file rabook_import_internal.h.

Typedef Documentation

◆ rabook_import_read_fn

typedef ra8_err_t(* rabook_import_read_fn) (void *ctx, uint8_t *buf, uint32_t requested, uint32_t *out_read)

Exact sequential-reader seam used by the source-key CRC pass.

Definition at line 23 of file rabook_import_internal.h.

Function Documentation

◆ priv_rabook_import_crc_stream()

ra8_err_t priv_rabook_import_crc_stream	(	rabook_import_read_fn	read_fn,
		void *	read_ctx,
		uint64_t	expected_size,
		uint8_t *	buf,
		uint32_t	cap,
		uint32_t	max_reads,
		uint32_t *	out_size,
		uint32_t *	out_crc )

Compute one exact bounded source CRC through an injected reader.

Consumes the immutable size in fixed-capacity chunks, rejects short or oversized callback results, and requires one final exact EOF read before publishing either source-key output.

Parameters

[in]	read_fn	Sequential read callback.
[in,out]	read_ctx	Opaque callback context.
[in]	expected_size	Immutable source-size snapshot.
[out]	buf	Caller-owned transfer buffer.
[in]	cap	Transfer-buffer capacity.
[in]	max_reads	Maximum data-bearing callback calls.
[out]	out_size	Published exact size on success only.
[out]	out_crc	Published CRC-32/ISO-HDLC on success only.

Returns: Exact-stream validation status.

Return values

k_ra8_ok	The size snapshot was consumed and EOF confirmed.
k_ra8_err_invalid_size	Geometry, callback count, or read length was invalid.
k_ra8_err_*	Callback failure, returned verbatim.

Precondition: Pointer arguments are non-NULL; buf holds cap bytes.; expected_size is stable and representable by the published uint32_t size.

Postcondition: Success publishes both outputs; failure leaves both unchanged.; Success confirms one additional callback returned exact EOF.

Note: Not thread-safe unless the injected reader serializes its context.

Since: Version 0.1.0

Definition at line 196 of file rabook_import.c.

References internal_crc_stream_read_chunk(), internal_crc_stream_validate_args(), k_crc32_seed, k_ra8_err_invalid_size, k_ra8_ok, and RA8_PRIV.

Referenced by internal_crc_stream(), and rabook_import_crc_stream_test().

◆ rabook_import_crc_stream_test()

ra8_err_t rabook_import_crc_stream_test	(	rabook_import_read_fn	read_fn,
		void *	read_ctx,
		uint64_t	expected_size,
		uint8_t *	buf,
		uint32_t	cap,
		uint32_t	max_reads,
		uint32_t *	out_size,
		uint32_t *	out_crc )

Exercise the bounded source-key CRC contract from focused tests.

Forwards every argument unchanged to the module-private production implementation so fault-vector tests cover the exact shipped loop.

Parameters

[in]	read_fn	Sequential read callback.
[in,out]	read_ctx	Opaque callback context.
[in]	expected_size	Immutable source-size snapshot.
[out]	buf	Caller-owned transfer buffer.
[in]	cap	Transfer-buffer capacity.
[in]	max_reads	Maximum data-bearing callback calls.
[out]	out_size	Published exact size on success only.
[out]	out_crc	Published CRC-32/ISO-HDLC on success only.

Returns: Exact-stream validation status from the production helper.

Return values

k_ra8_ok	The size snapshot was consumed and EOF confirmed.
k_ra8_err_invalid_size	Geometry, count, or callback length was invalid.
k_ra8_err_*	An injected callback error, returned verbatim.

Precondition: Pointer arguments are non-NULL and buf holds cap bytes.; max_reads bounds every possible data-bearing callback.

Postcondition: Success publishes both result objects.; Failure leaves both output objects unchanged.

Note: Test helper; thread safety follows the injected reader context.

Since: Version 0.1.0

Definition at line 241 of file rabook_import.c.

References priv_rabook_import_crc_stream(), and RA8_TEST_HELPER.