ra8_c6link_mdl.h File Reference

Pull-based media download client over ESP-hosted CustomRpc. More...

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

Include dependency graph for ra8_c6link_mdl.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_session_t
	RA8-local state for one accepted remote artifact job. More...
struct	ra8_mdl_chunk_t
	One correlated bounded raw-byte response. More...

Functions
ra8_err_t	ra8_c6link_mdl_start (ra8_c6link_t *link, const char *url, mdl_format_t format, ra8_mdl_session_t *session)
	Start retrieval of one selected artifact and receive its job identifier.
ra8_err_t	ra8_c6link_mdl_start_request (ra8_c6link_t *link, const ra8_mdl_request_t *request, ra8_mdl_session_t *session)
	Start one typed request while preserving downloader HTTP policy.
ra8_err_t	ra8_c6link_mdl_next (ra8_c6link_t *link, ra8_mdl_session_t *session, uint16_t max_bytes, ra8_mdl_chunk_t *chunk)
	Pull the next bounded chunk while acknowledging the prior offset.
ra8_err_t	ra8_c6link_mdl_cancel (ra8_c6link_t *link, ra8_mdl_session_t *session)
	Cancel one active remote job and invalidate its local session.

Detailed Description

Pull-based media download client over ESP-hosted CustomRpc.

Tag

[Ring 4 / PAL] {World: NS}

The C6 owns HTTP fetching. The RA8 owns the destination path and file lifecycle: callers pull bounded chunks and write them through the RA8 filesystem. This keeps POSIX paths and storage handles off the co-processor wire and gives the existing single-outstanding-call c6link natural backpressure.

Copyright

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

Since

0.1.0

Definition in file ra8_c6link_mdl.h.

Function Documentation

ra8_c6link_mdl_cancel()

ra8_err_t ra8_c6link_mdl_cancel ( ra8_c6link_t * link, ra8_mdl_session_t * session )

nodiscard

Cancel one active remote job and invalidate its local session.

Sends the generated CancelRequest and validates the returned job id before changing local state.

Parameters

[in,out]	link	Already-open exclusively owned c6link.
[in,out]	session	Active job to cancel.

Returns

Cancellation status.

Return values

k_ra8_ok	Remote acknowledged cancellation and session is inactive.
k_ra8_err_null_ptr	A required pointer is null.
k_ra8_err_invalid_state	Session is not active.
k_ra8_err_invalid_size	Encoded request exceeds its static buffer.
k_ra8_err_protocol_error	Cancellation acknowledgement is incoherent.
k_ra8_err_timeout	C6 did not answer inside the RPC budget.

Precondition

session came from a successful ra8_c6link_mdl_start.

No other thread uses link concurrently.

Postcondition

Success leaves session inactive.

Failure preserves the session for retry or caller recovery.

Note

Not thread-safe; the c6link handle and session are single-owner.

Since

0.1.0

Definition at line 659 of file ra8_c6link_mdl.c.

References ra8_mdl_session_t::active, internal_mdl_call(), Ra8__Mdl__CancelRequest::job_id, ra8_mdl_session_t::job_id, k_mdl_take_cancelled, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_mdl_protocol_version, k_ra8_mdl_rpc_cancel, ra8_c6link::mdl_request, Ra8__Mdl__CancelRequest::protocol_version, ra8__mdl__cancel_request__get_packed_size(), RA8__MDL__CANCEL_REQUEST__INIT, and ra8__mdl__cancel_request__pack().

Referenced by internal_mdl_transfer_abort().

ra8_c6link_mdl_next()

ra8_err_t ra8_c6link_mdl_next ( ra8_c6link_t * link, ra8_mdl_session_t * session, uint16_t max_bytes, ra8_mdl_chunk_t * chunk )

nodiscard

Pull the next bounded chunk while acknowledging the prior offset.

Encodes the session's exact next sequence/offset contract and advances it only after a correlated protobuf response passes validation.

Parameters

[in,out]	link	Already-open exclusively owned c6link.
[in,out]	session	Active job correlation state.
[in]	max_bytes	Requested body-byte bound for this response.
[out]	chunk	Correlated response, including terminal metadata.

Returns

Pull status.

Return values

k_ra8_ok	A valid data or terminal response was decoded.
k_ra8_err_null_ptr	A required pointer is null.
k_ra8_err_invalid_state	Session is inactive or invalid.
k_ra8_err_invalid_size	Requested or encoded size exceeds a bound.
k_ra8_err_protocol_error	Job, sequence, offset, state, or fields are incoherent.
k_ra8_err_timeout	C6 did not answer inside the RPC budget.

Precondition

session came from a successful ra8_c6link_mdl_start.

max_bytes is non-zero and no larger than the negotiated maximum.

Postcondition

Success advances session correlation by exactly the returned data length.

A terminal response makes session inactive.

Note

Not thread-safe; the c6link handle and session are single-owner.

Since

0.1.0

Definition at line 624 of file ra8_c6link_mdl.c.

References Ra8__Mdl__NextRequest::acknowledged_offset, ra8_mdl_session_t::active, internal_mdl_call(), Ra8__Mdl__NextRequest::job_id, ra8_mdl_session_t::job_id, k_mdl_take_chunk, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_mdl_chunk_data_max, k_ra8_mdl_protocol_version, k_ra8_mdl_rpc_next, Ra8__Mdl__NextRequest::max_bytes, ra8_mdl_session_t::max_chunk_bytes, ra8_c6link::mdl_request, ra8_mdl_session_t::next_offset, Ra8__Mdl__NextRequest::protocol_version, ra8__mdl__next_request__get_packed_size(), RA8__MDL__NEXT_REQUEST__INIT, and ra8__mdl__next_request__pack().

Referenced by ra8_c6link_mdl_transfer().

ra8_c6link_mdl_start()

ra8_err_t ra8_c6link_mdl_start ( ra8_c6link_t * link, const char * url, mdl_format_t format, ra8_mdl_session_t * session )

nodiscard

Start retrieval of one selected artifact and receive its job identifier.

Encodes a generated protobuf StartRequest with the exact artifact identity. loose selects an untyped source body; other values require the returned bytes to be that format and must be validated before publication.

Parameters

[in,out]	link	Already-open exclusively owned c6link.
[in]	url	NUL-terminated HTTPS source URL below k_ra8_mdl_url_max.
[in]	format	Artifact identity requested from the C6 backend.
[out]	session	Accepted job correlation state.

Returns

Start status.

Return values

k_ra8_ok	Remote job accepted.
k_ra8_err_null_ptr	A required pointer is null.
k_ra8_err_invalid_arg	URL or format is invalid.
k_ra8_err_invalid_size	URL or encoded request exceeds its bound.
k_ra8_err_protocol_error	Remote response is malformed.
k_ra8_err_timeout	C6 did not answer inside the RPC budget.

Precondition

ra8_c6link_open completed successfully for link.

No other thread uses link concurrently.

Postcondition

Success produces an active non-zero job in session.

Failure leaves session inactive and zeroed after argument validation.

Note

Not thread-safe; the c6link handle is single-owner.

Since

0.1.0

Definition at line 615 of file ra8_c6link_mdl.c.

References ra8_c6link_mdl_start_request().

ra8_c6link_mdl_start_request()

ra8_err_t ra8_c6link_mdl_start_request ( ra8_c6link_t * link, const ra8_mdl_request_t * request, ra8_mdl_session_t * session )

nodiscard

Start one typed request while preserving downloader HTTP policy.

This is the protocol-v3 entry point used by the portable network adapter. It validates every bounded header locally before encoding it. ra8_c6link_mdl_start is the empty-policy convenience wrapper.

Parameters

[in,out]	link	Already-open exclusively owned c6link.
[in]	request	Complete typed HTTPS request and optional headers.
[out]	session	Accepted job correlation state.

Returns

Start status.

Return values

k_ra8_ok	Remote job accepted.
k_ra8_err_null_ptr	A required pointer is null.
k_ra8_err_invalid_arg	URL, format, timeout, or header is invalid.
k_ra8_err_invalid_size	A bounded string or request encoding is too large.
k_ra8_err_protocol_error	Remote response is malformed.

Precondition

ra8_c6link_open completed successfully for link.

No other thread uses link concurrently.

Postcondition

Success produces an active non-zero job in session.

Failure leaves session inactive after pointer validation.

Note

Not thread-safe; the c6link handle is single-owner.

Since

0.1.0

Definition at line 575 of file ra8_c6link_mdl.c.

References Ra8__Mdl__StartRequest::format, ra8_mdl_request_t::format, ra8_mdl_request_t::http, mdl_http_headers_t::if_modified_since, Ra8__Mdl__StartRequest::if_modified_since, mdl_http_headers_t::if_none_match, Ra8__Mdl__StartRequest::if_none_match, internal_mdl_call(), internal_mdl_stage_headers(), internal_mdl_start_request_valid(), k_mdl_take_accepted, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_mdl_protocol_version, k_ra8_mdl_rpc_start, k_ra8_mdl_url_max, k_ra8_ok, ra8_c6link::mdl_request, memcpy(), Ra8__Mdl__StartRequest::protocol_version, ra8__mdl__start_request__get_packed_size(), ra8__mdl__start_request__init(), ra8__mdl__start_request__pack(), mdl_http_headers_t::referer, Ra8__Mdl__StartRequest::referer, Ra8__Mdl__StartRequest::timeout_ms, ra8_mdl_http_policy_t::timeout_ms, Ra8__Mdl__StartRequest::url, ra8_mdl_request_t::url, mdl_http_headers_t::user_agent, and Ra8__Mdl__StartRequest::user_agent.

Referenced by internal_mdl_transfer_begin(), and ra8_c6link_mdl_start().