ra8_c6link_mdl_transfer.h File Reference

Transactional RA8-side coordinator for C6 media byte streams. More...

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

Include dependency graph for ra8_c6link_mdl_transfer.h:

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

Go to the source code of this file.

Data Structures
struct	ra8_mdl_storage_iface
	Transactional destination seam for one downloaded object. More...
struct	ra8_mdl_sha256_iface
	Streaming SHA-256 seam with caller-owned fixed storage. More...
struct	ra8_mdl_transfer_config
	Fixed policy and injected mechanisms for one transfer. More...
struct	ra8_mdl_transfer_result
	Verified result published by a completed transfer. More...

Typedefs
typedef struct ra8_mdl_storage_iface	ra8_mdl_storage_iface_t
typedef struct ra8_mdl_sha256_iface	ra8_mdl_sha256_iface_t
typedef bool(*	ra8_mdl_cancel_requested_fn) (void *ctx)
	Query whether the caller requests cooperative cancellation.
typedef struct ra8_mdl_transfer_config	ra8_mdl_transfer_config_t
typedef struct ra8_mdl_transfer_result	ra8_mdl_transfer_result_t

Enumerations
enum	ra8_mdl_transfer_limit_t : uint64_t { k_ra8_mdl_transfer_bytes_max = UINT64_C(67108864) }
	Absolute transfer policy limits independent of caller chunk geometry. More...

Functions
ra8_err_t	ra8_c6link_mdl_transfer (ra8_c6link_t *link, const char *url, const char *destination, const ra8_mdl_transfer_config_t *config, ra8_mdl_transfer_result_t *result)
	Fetch, verify, and atomically publish one remote byte stream.

Detailed Description

Transactional RA8-side coordinator for C6 media byte streams.

Tag

[Ring 4 / PAL] {World: NS}

This module composes an already-open ra8_c6link_t with caller-owned storage and SHA-256 implementations. The selected format is carried across the wire and correlated by the response; the RA8 owns the destination, verifies the digest and artifact independently, and publishes the temporary object atomically. Every buffer and context is caller-owned, and the transfer loop is bounded by max_chunks.

Copyright

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

Since

0.1.0

Definition in file ra8_c6link_mdl_transfer.h.

Typedef Documentation

ra8_mdl_cancel_requested_fn

typedef bool(* ra8_mdl_cancel_requested_fn) (void *ctx)

Query whether the caller requests cooperative cancellation.

Called before each remote pull. Returning true causes remote cancellation followed by unconditional local transaction abort.

Parameters

[in]

ctx

Caller-owned cancellation context.

Returns

Whether cancellation is requested.

Return values

true	Stop before pulling another chunk.
false	Continue the transfer.

Precondition

ctx remains valid for the transfer duration.

The callback does not mutate the c6link handle.

Postcondition

No coordinator-owned state is modified directly.

A true result is observed before another storage write.

Note

Called synchronously; thread safety belongs to the implementation.

Since

0.1.0

Definition at line 130 of file ra8_c6link_mdl_transfer.h.

ra8_mdl_sha256_iface_t

typedef struct ra8_mdl_sha256_iface ra8_mdl_sha256_iface_t

ra8_mdl_storage_iface_t

typedef struct ra8_mdl_storage_iface ra8_mdl_storage_iface_t

ra8_mdl_transfer_config_t

typedef struct ra8_mdl_transfer_config ra8_mdl_transfer_config_t

ra8_mdl_transfer_result_t

typedef struct ra8_mdl_transfer_result ra8_mdl_transfer_result_t

Enumeration Type Documentation

ra8_mdl_transfer_limit_t

enum ra8_mdl_transfer_limit_t : uint64_t

Absolute transfer policy limits independent of caller chunk geometry.

Enumerator
k_ra8_mdl_transfer_bytes_max	Maximum one-object byte budget.

Definition at line 30 of file ra8_c6link_mdl_transfer.h.

Function Documentation

ra8_c6link_mdl_transfer()

ra8_err_t ra8_c6link_mdl_transfer ( ra8_c6link_t * link, const char * url, const char * destination, const ra8_mdl_transfer_config_t * config, ra8_mdl_transfer_result_t * result )

nodiscard

Fetch, verify, and atomically publish one remote byte stream.

Starts a typed artifact transfer on an already-open c6link, pulls ordered bounded chunks, hashes exactly the bytes accepted by storage, compares the local digest with the C6 terminal digest, invokes the optional artifact validator against the private object, then commits. SHA equality proves transport integrity but does not prove .rabook identity: callers claiming any non-loose format must supply storage.validate. After a successful storage begin, every non-success path calls abort; an active remote session is also cancelled on local failure or cancellation.

Parameters

[in,out]	link	Already-open, exclusively owned c6link handle.
[in]	url	NUL-terminated source URL accepted by the C6 HTTPS backend.
[in]	destination	RA8-local destination understood only by storage.
[in]	config	Complete fixed-size storage, hash, cancellation, and bound policy.
[out]	result	Verified committed byte count and digest.

Returns

Canonical transfer status.

Return values

k_ra8_ok	Object verified and atomically committed.
k_ra8_err_null_ptr	Required pointer or injected function is null.
k_ra8_err_invalid_arg	Configuration or URL is invalid.
k_ra8_err_invalid_size	Chunk bound, response length, or byte count is invalid.
k_ra8_err_protocol_error	Remote state or ordering is incoherent.
k_ra8_err_checksum_mismatch	Local and remote SHA-256 digests differ.
k_ra8_err_cancelled	Caller requested cancellation or remote cancelled.
k_ra8_err_timeout	max_chunks was exhausted before completion.
k_ra8_fail	Injected storage, hash, or transport mechanism failed.

Precondition

ra8_c6link_open completed successfully for link.

No other thread uses link or any injected context concurrently.

Postcondition

Success leaves exactly one committed destination and no temporary state.

Failure leaves no committed destination and calls storage abort exactly once.

Note

Not thread-safe; c6link and injected contexts require exclusive ownership.

Warning

commit must provide the atomic publication guarantee; this module cannot synthesize it.

See also

ra8_c6link_mdl_start

Since

0.1.0

Definition at line 286 of file ra8_c6link_mdl_transfer.c.

References ra8_mdl_session_t::active, ra8_mdl_transfer_config::cancel_ctx, ra8_mdl_transfer_config::cancel_requested, ra8_mdl_transfer_config::chunk_bytes, internal_mdl_transfer_abort(), internal_mdl_transfer_begin(), internal_mdl_transfer_commit(), internal_mdl_transfer_store(), k_ra8_err_cancelled, k_ra8_err_timeout, k_ra8_mdl_state_cancelled, k_ra8_mdl_state_complete, k_ra8_mdl_state_downloading, k_ra8_ok, ra8_mdl_transfer_config::max_chunks, ra8_c6link_mdl_next(), mdl_transfer_state_t::session, ra8_mdl_chunk_t::state, and mdl_transfer_state_t::storage_active.

Referenced by internal_c6_get(), internal_transfer_and_consume(), and priv_media_download_image_run().