Media service dispatch contract for the ESP32-C6 integration. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_err.h"
#include "ra8_mdl_http.h"
#include "ra8_mdl_protocol.h"

Include dependency graph for ra8_c6link_mdl_msg.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_service_backend
	Bounded typed-artifact source seam implemented by the C6 port. More...
struct	ra8_mdl_decode_arena
	Linear allocator storage the generated decoder draws one dispatch from. More...
struct	ra8_mdl_service
	Caller-owned one-job portable service state. More...

Typedefs
typedef ra8_err_t(*	ra8_mdl_service_dispatch_fn) (void ctx, uint32_t operation, const uint8_t request, size_t request_len, uint8_t response, size_t response_cap, size_t response_len)
	Dispatch one generated inner media request into caller-owned storage.
typedef struct ra8_mdl_service_backend	ra8_mdl_service_backend_t
typedef struct ra8_mdl_decode_arena	ra8_mdl_decode_arena_t
typedef struct ra8_mdl_service	ra8_mdl_service_t

Enumerations
enum	ra8_mdl_decode_arena_limit_t : uint16_t { k_ra8_mdl_decode_arena_bytes , k_ra8_mdl_decode_align = 8U }
	Bounded protobuf decode storage one dispatch may consume. More...

Functions
ra8_err_t	ra8_mdl_service_init (ra8_mdl_service_t service, const ra8_mdl_service_backend_t backend)
	Initialise portable service state with a complete backend seam.
ra8_err_t	ra8_mdl_service_dispatch (void ctx, uint32_t operation, const uint8_t request, size_t request_len, uint8_t response, size_t response_cap, size_t response_len)
	Dispatch Start, Next, or Cancel generated protobuf payloads.

Detailed Description

Media service dispatch contract for the ESP32-C6 integration.

Tag: [Ring 4 / PAL] {World: NS}

Wire messages are generated from ra8_media_download.proto; this header intentionally defines no packed C wire structs.

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

Definition in file ra8_c6link_mdl_msg.h.

Typedef Documentation

◆ ra8_mdl_decode_arena_t

typedef struct ra8_mdl_decode_arena ra8_mdl_decode_arena_t

◆ ra8_mdl_service_backend_t

typedef struct ra8_mdl_service_backend ra8_mdl_service_backend_t

◆ ra8_mdl_service_dispatch_fn

typedef ra8_err_t(* ra8_mdl_service_dispatch_fn) (void *ctx, uint32_t operation, const uint8_t *request, size_t request_len, uint8_t *response, size_t response_cap, size_t *response_len)

Dispatch one generated inner media request into caller-owned storage.

The implementation decodes with a bounded arena and returns one packed generated response without retaining either byte span.

Parameters

[in]	ctx	Service context selected by the RPC integration.
[in]	operation	One ra8_mdl_rpc_id_t value.
[in]	request	Packed protobuf request bytes.
[in]	request_len	Valid bytes at `request`.
[out]	response	Caller-owned packed-response buffer.
[in]	response_cap	Capacity of `response`.
[out]	response_len	Packed bytes written on success.

Returns: Dispatch status.

Return values

k_ra8_ok	A valid response was packed.
k_ra8_err_null_ptr	A required pointer is null.
k_ra8_err_invalid_arg	The operation or decoded fields are invalid.
k_ra8_err_invalid_size	A request or response exceeds a fixed bound.
k_ra8_err_protocol_error	Job correlation or state is incoherent.

Precondition: The request and response spans do not overlap.; ctx remains exclusively owned for the complete call.

Postcondition: Success sets response_len within response_cap.; Failure sets response_len to zero after pointer validation.

Note: Synchronous and not thread-safe for a shared service context.

Since: 0.1.0

Definition at line 51 of file ra8_c6link_mdl_msg.h.

◆ ra8_mdl_service_t

typedef struct ra8_mdl_service ra8_mdl_service_t

Enumeration Type Documentation

◆ ra8_mdl_decode_arena_limit_t

enum ra8_mdl_decode_arena_limit_t : uint16_t

Bounded protobuf decode storage one dispatch may consume.

Sized for the largest legal Start request: a maximum URL plus every bounded HTTP header, plus the generated decoder's per-message overhead.

Since: 0.1.0

Enumerator
k_ra8_mdl_decode_arena_bytes	Per-dispatch arena size.
k_ra8_mdl_decode_align	Alignment every arena span is issued on.

Definition at line 90 of file ra8_c6link_mdl_msg.h.

Function Documentation

◆ ra8_mdl_service_dispatch()

ra8_err_t ra8_mdl_service_dispatch	(	void *	ctx,
		uint32_t	operation,
		const uint8_t *	request,
		size_t	request_len,
		uint8_t *	response,
		size_t	response_cap,
		size_t *	response_len )

nodiscard

Dispatch Start, Next, or Cancel generated protobuf payloads.

Decodes into the service-owned bounded arena, validates job correlation, and packs exactly one response into caller-owned storage.

Parameters

[in,out]	ctx	Initialised ra8_mdl_service_t.
[in]	operation	One ra8_mdl_rpc_id_t value.
[in]	request	Packed generated request bytes.
[in]	request_len	Valid request bytes.
[out]	response	Caller-owned response bytes.
[in]	response_cap	Capacity of `response`.
[out]	response_len	Packed response length.

Returns: Dispatch status.

Return values

k_ra8_ok	A response was packed successfully.
k_ra8_err_null_ptr	A required pointer is null.
k_ra8_err_invalid_arg	Operation or request fields are invalid.
k_ra8_err_invalid_state	A Start arrived while another job is active.
k_ra8_err_invalid_size	A fixed request/response bound was exceeded.
k_ra8_err_protocol_error	Job, sequence, or offset did not correlate.

Precondition: ra8_mdl_service_init succeeded for ctx.; No concurrent call uses ctx or its backend.

Postcondition: Success sets response_len no larger than response_cap.; Failure sets response_len to zero after pointer validation.

Note: Synchronous and single-owner.

Since: 0.1.0

Definition at line 715 of file ra8_c6link_mdl_service.c.

References ra8_mdl_service::arena, internal_mdl_decode_alloc(), internal_mdl_decode_free(), internal_mdl_dispatch_cancel(), internal_mdl_dispatch_next(), internal_mdl_dispatch_start(), k_ra8_err_not_supported, k_ra8_err_null_ptr, k_ra8_mdl_rpc_cancel, k_ra8_mdl_rpc_next, and k_ra8_mdl_rpc_start.

Referenced by esp_hosted_custom_rpc_sync_handler().

◆ ra8_mdl_service_init()

ra8_err_t ra8_mdl_service_init	(	ra8_mdl_service_t *	service,
		const ra8_mdl_service_backend_t *	backend )

nodiscard

Initialise portable service state with a complete backend seam.

Copies the callback table and resets all job correlation fields.

Parameters

[out]	service	Caller-owned service state.
[in]	backend	Complete backend callback table and context.

Returns: Initialisation status.

Return values

k_ra8_ok	Service is ready to dispatch.
k_ra8_err_null_ptr	A pointer, callback, or backend context is null.

Precondition: No request is executing against service.; backend and its context remain valid for the service lifetime.

Postcondition: Success leaves the service inactive and ready for Start.; Failure does not invoke a backend callback.

Note: Not thread-safe with concurrent dispatch on the same service.

Since: 0.1.0

Definition at line 705 of file ra8_c6link_mdl_service.c.

References ra8_mdl_service_backend::begin, ra8_mdl_service_backend::cancel, k_ra8_err_null_ptr, k_ra8_ok, and ra8_mdl_service_backend::read.

Referenced by esp_hosted_custom_rpc_sync_handler().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ra8_mdl_decode_arena_t

◆ ra8_mdl_service_backend_t

◆ ra8_mdl_service_dispatch_fn

◆ ra8_mdl_service_t

Enumeration Type Documentation

◆ ra8_mdl_decode_arena_limit_t

Function Documentation

◆ ra8_mdl_service_dispatch()

◆ ra8_mdl_service_init()