mdl_service.c File Reference

ESP-IDF HTTP backend and synchronous CustomRpc hook for media chunks. More...

#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "esp_idf_mdl_compat_internal.h"
#include "ra8_attributes.h"
#include "ra8_c6link_mdl_msg.h"
#include "ra8_mdl_service.h"

Include dependency graph for mdl_service.c:

Go to the source code of this file.

Data Structures
struct	mdl_http_state
	Single retained ESP-IDF client and one serialized remote transfer. More...

Typedefs
typedef struct mdl_http_state	mdl_http_state_t
typedef uint32_t(*	mdl_component_abi_fn_t) (void)
	Return the first-party media component ABI marker.

Enumerations
enum	mdl_http_const_t : uint16_t {   k_mdl_http_timeout_ms = 15000U ,   k_mdl_http_status_min = 100U ,   k_mdl_http_status_max = 599U }
	Fixed HTTP policy values for the concrete ESP-IDF adapter. More...

Functions
uint32_t	ra8_mdl_service_component_abi (void)
	Return the linked first-party media component ABI version.
static void	internal_mdl_http_reset_job (mdl_http_state_t *state)
	Close one request while retaining the one-time client/hash objects.
static bool	internal_mdl_header_equal (const char *lhs, const char *rhs)
	Compare one HTTP header name without ASCII case sensitivity.
static ra8_err_t	internal_mdl_copy_field (char *destination, size_t capacity, const char *source)
	Copy one optional bounded HTTP field into retained storage.
static void	internal_mdl_select_response_header (mdl_http_state_t *state, const char *key, char **destination, size_t *capacity)
	Select retained storage for one response header.
static esp_err_t	internal_mdl_http_event (esp_http_client_event_t *event)
	Capture selected response headers from ESP-IDF events.
static ra8_err_t	internal_mdl_http_init (mdl_http_state_t *state)
	Create the retained ESP-IDF client and SHA context once.
static ra8_err_t	internal_mdl_http_set_header (mdl_http_state_t *state, const char *name, const char *value)
	Replace one optional retained request header.
static ra8_err_t	internal_mdl_http_apply_request (mdl_http_state_t *state, const ra8_mdl_request_t *request)
	Copy and apply the complete bounded request policy.
static ra8_err_t	internal_mdl_http_begin (void *ctx, const ra8_mdl_request_t *request)
	Validate and prepare one typed HTTPS-artifact job.
static ra8_err_t	internal_mdl_http_open (mdl_http_state_t *state)
	Open lazily so Start returns without waiting for network exchange.
static ra8_err_t	internal_mdl_http_finish (mdl_http_state_t *state, uint64_t *total_bytes, bool *complete, uint8_t sha256[k_ra8_mdl_sha256_bytes], ra8_mdl_http_response_t *response)
	Validate EOF and publish the terminal length and digest.
static ra8_err_t	internal_mdl_http_account_read (mdl_http_state_t *state, const uint8_t *out, int read, uint16_t *got, uint64_t *total_bytes)
	Account one successful nonzero body read into job state.
static ra8_err_t	internal_mdl_http_read (void *ctx, uint8_t *out, uint16_t cap, uint16_t *got, uint64_t *total_bytes, bool *complete, uint8_t sha256[k_ra8_mdl_sha256_bytes], ra8_mdl_http_response_t *response)
	Pull one bounded body span or verified terminal metadata.
static ra8_err_t	internal_mdl_http_cancel (void *ctx)
	Cancel the active HTTP job while retaining one-time objects.
static esp_err_t	internal_mdl_to_esp_status (ra8_err_t result)
	Translate a portable media-service result into ESP-IDF's error domain.
esp_err_t	esp_hosted_custom_rpc_sync_handler (uint32_t message_id, const uint8_t *request, size_t request_len, uint8_t *response, size_t response_cap, size_t *response_len)
	Strong implementation consumed by the pinned ESP-hosted patch.

Variables
static mdl_http_state_t	s_http
static ra8_mdl_service_t	s_service
static bool	s_initialised
static mdl_component_abi_fn_t volatile	s_component_abi = ra8_mdl_service_component_abi

Detailed Description

ESP-IDF HTTP backend and synchronous CustomRpc hook for media chunks.

Tag

[Ring 4 / PAL] {World: NS}

The portable service and caller-owned buffers are bounded. The concrete ESP-IDF adapter is deliberately fenced as a remaining allocator exception: esp_http_client_set_url/open and TLS reconnects can allocate from ESP-IDF heaps. Keeping one client handle avoids init/cleanup churn but does not make this adapter zero-heap after initialisation. Replace only this backend seam with a board-proven fixed-memory HTTPS mechanism.

Copyright

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

Definition in file mdl_service.c.

Typedef Documentation

mdl_component_abi_fn_t

typedef uint32_t(* mdl_component_abi_fn_t) (void)

Return the first-party media component ABI marker.

Returns

Stable component ABI version.

Return values

1	First version of the concrete media service component.

Precondition

The component object is strongly linked into the image.

The caller does not replace this symbol with the upstream weak hook.

Postcondition

No global or peripheral state is modified.

The return value is stable for the component build.

Note

Thread-safe and allocation-free.

Since

0.1.0

Definition at line 73 of file mdl_service.c.

mdl_http_state_t

typedef struct mdl_http_state mdl_http_state_t

Enumeration Type Documentation

mdl_http_const_t

enum mdl_http_const_t : uint16_t

Fixed HTTP policy values for the concrete ESP-IDF adapter.

Enumerator
k_mdl_http_timeout_ms	Default whole-request timeout.
k_mdl_http_status_min	Lowest valid terminal status.
k_mdl_http_status_max	Highest valid terminal status.

Definition at line 28 of file mdl_service.c.

Function Documentation

esp_hosted_custom_rpc_sync_handler()

esp_err_t esp_hosted_custom_rpc_sync_handler	(	uint32_t	message_id,
		const uint8_t *	request,
		size_t	request_len,
		uint8_t *	response,
		size_t	response_cap,
		size_t *	response_len )

Strong implementation consumed by the pinned ESP-hosted patch.

Handle one synchronous ESP-hosted CustomRpc media operation.

The hook runs on ESP-hosted's serialized control path. It returns a fully packed inner protobuf in caller-owned storage; the patched upstream handler immediately wraps those bytes in its generated CustomRpc response.

Parameters

[in]	message_id	Stable media RPC operation identifier.
[in]	request	Packed generated inner protobuf.
[in]	request_len	Valid request bytes.
[out]	response	Caller-owned inner response buffer.
[in]	response_cap	Capacity of response.
[out]	response_len	Packed response bytes.

Returns

ESP-hosted hook status.

Return values

ESP_OK	A valid inner response was produced.
ESP_FAIL	Component or one-time backend initialisation failed.
ESP_ERR_NOT_SUPPORTED	The operation is not owned by the media service.
ESP_ERR_INVALID_ARG	A request argument or pointer was invalid.
ESP_ERR_INVALID_STATE	The media service is busy or inactive.
ESP_ERR_INVALID_SIZE	A bounded request or response extent was rejected.
ESP_ERR_INVALID_RESPONSE	The inner protobuf or response was invalid.

Precondition

ESP-hosted invokes the hook on its serialized control path.

Request/response spans are valid and do not overlap.

Postcondition

Success sets response_len within response_cap.

Failure does not claim a successful CustomRpc response.

Note

Not thread-safe outside the serialized ESP-hosted control task.

Warning

The concrete ESP-IDF HTTP/TLS adapter remains a heap exception.

Since

0.1.0

Definition at line 759 of file mdl_service.c.

References ESP_ERR_INVALID_ARG, ESP_ERR_NOT_SUPPORTED, ESP_FAIL, internal_mdl_http_begin(), internal_mdl_http_cancel(), internal_mdl_http_init(), internal_mdl_http_read(), internal_mdl_to_esp_status(), k_ra8_mdl_rpc_cancel, k_ra8_mdl_rpc_next, k_ra8_mdl_rpc_start, k_ra8_ok, ra8_mdl_service_dispatch(), ra8_mdl_service_init(), s_component_abi, s_http, s_initialised, and s_service.

internal_mdl_copy_field()

ra8_err_t internal_mdl_copy_field ( char * destination, size_t capacity, const char * source )

static

Copy one optional bounded HTTP field into retained storage.

Canonicalizes an absent value to empty, rejects line breaks, and retains one exact NUL-terminated value for the synchronous exchange.

Parameters

[out]	destination	Fixed-capacity destination.
[in]	capacity	Total destination capacity including NUL.
[in]	source	Optional NUL-terminated field value.

Returns

Copy status.

Return values

k_ra8_ok	The value or canonical empty string was copied.
k_ra8_err_invalid_arg	The value contains CR or LF.
k_ra8_err_invalid_size	The value does not fit.

Precondition

destination is writable for capacity bytes.

capacity is positive.

Postcondition

Success leaves destination NUL-terminated.

Failure leaves destination as an empty string.

Note

Null and empty inputs both represent an absent field.

Since

0.1.0

Definition at line 178 of file mdl_service.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, memcpy(), and strnlen().

Referenced by internal_mdl_http_apply_request(), and internal_mdl_http_event().

internal_mdl_header_equal()

bool internal_mdl_header_equal ( const char * lhs, const char * rhs )

static

Compare one HTTP header name without ASCII case sensitivity.

Folds only the ASCII uppercase range because HTTP field names are ASCII tokens and locale-dependent case conversion is forbidden here.

Parameters

[in]	lhs	Candidate response-header name.
[in]	rhs	Canonical response-header name.

Returns

Whether both NUL-terminated names are equal ignoring ASCII case.

Return values

true	The names are equal.
false	The names differ or lhs is null.

Precondition

rhs is non-null and NUL-terminated.

Non-null lhs is NUL-terminated.

Header names contain only ASCII octets.

Postcondition

No input or service state is modified.

The result is independent of the process locale.

Note

HTTP field names are case-insensitive.

Since

0.1.0

Definition at line 136 of file mdl_service.c.

References RA8_INTERNAL.

Referenced by internal_mdl_select_response_header().

internal_mdl_http_account_read()

ra8_err_t internal_mdl_http_account_read ( mdl_http_state_t * state, const uint8_t * out, int read, uint16_t * got, uint64_t * total_bytes )

static

Account one successful nonzero body read into job state.

Overflow-checks the running byte count against a 64-bit ceiling, enforces it against any advertised total, folds the bytes into the running SHA-256 digest, and reports the exact transfer.

Parameters

[in,out]	state	Prepared job state being accounted.
[in]	out	Body bytes just read, spanning read bytes.
[in]	read	Strictly positive byte count returned by the transport.
[out]	got	Exact body bytes returned.
[out]	total_bytes	Advertised or independently counted total.

Returns

Accounting status.

Return values

k_ra8_ok	The bytes were folded into state and reported.
k_ra8_err_invalid_size	Received-byte count overflowed.
k_ra8_err_protocol_error	The advertised total was exceeded.
k_ra8_fail	SHA digest processing failed.

Precondition

read is strictly positive.

out has at least read readable bytes.

Postcondition

Success advances state->received by exactly read.

Failure resets the job state before returning.

Note

Not thread-safe; service dispatch serializes calls.

Since

0.1.0

Definition at line 570 of file mdl_service.c.

References internal_mdl_http_reset_job(), k_ra8_err_invalid_size, k_ra8_err_protocol_error, k_ra8_fail, k_ra8_ok, mbedtls_sha256_update, RA8_INTERNAL, mdl_http_state::received, mdl_http_state::sha, mdl_http_state::total, and mdl_http_state::total_known.

Referenced by internal_mdl_http_read().

internal_mdl_http_apply_request()

ra8_err_t internal_mdl_http_apply_request ( mdl_http_state_t * state, const ra8_mdl_request_t * request )

static

Copy and apply the complete bounded request policy.

Retains every caller string, applies the resolved timeout, and replaces all optional headers before the HTTP request may open.

Parameters

[in,out]	state	Reset retained HTTP state.
[in]	request	Validated portable media request.

Returns

Policy configuration status.

Return values

k_ra8_ok	All strings and ESP-IDF settings were accepted.
k_ra8_err_invalid_arg	A field contains a forbidden line break.
k_ra8_err_invalid_size	A field exceeds its fixed capacity.
k_ra8_fail	ESP-IDF rejected timeout or header configuration.

Precondition

state owns a closed retained client.

request and its URL are non-null.

Postcondition

Success retains every request string through the HTTP exchange.

Failure leaves no request eligible to open.

Note

Zero timeout selects the adapter default.

Since

0.1.0

Definition at line 355 of file mdl_service.c.

References esp_http_client_set_timeout_ms, ESP_OK, mdl_http_state::http, ra8_mdl_request_t::http, mdl_http_state::if_modified_since, ra8_mdl_http_policy_t::if_modified_since, mdl_http_state::if_none_match, ra8_mdl_http_policy_t::if_none_match, internal_mdl_copy_field(), internal_mdl_http_set_header(), k_mdl_http_timeout_ms, k_ra8_fail, k_ra8_ok, RA8_INTERNAL, mdl_http_state::referer, ra8_mdl_http_policy_t::referer, ra8_mdl_http_policy_t::timeout_ms, mdl_http_state::url, ra8_mdl_request_t::url, mdl_http_state::user_agent, and ra8_mdl_http_policy_t::user_agent.

Referenced by internal_mdl_http_begin().

internal_mdl_http_begin()

ra8_err_t internal_mdl_http_begin ( void * ctx, const ra8_mdl_request_t * request )

static

Validate and prepare one typed HTTPS-artifact job.

Reuses retained client/hash objects and resets only per-job fields.

Parameters

[in,out]	ctx	Initialised mdl_http_state_t.
[in]	request	Complete typed HTTPS request and optional policy.

Returns

Begin status.

Return values

k_ra8_ok	Job state and SHA stream are ready.
k_ra8_err_invalid_arg	URL is not a non-empty HTTPS URL.
k_ra8_err_invalid_size	URL exceeds the fixed buffer.
k_ra8_fail	ESP-IDF URL setup or SHA setup failed.

Precondition

ctx completed internal_mdl_http_init.

No read callback executes concurrently.

Postcondition

Success leaves a closed client ready for lazy network open.

Failure leaves no active job.

Note

Not thread-safe; service dispatch serializes calls.

Warning

esp_http_client_set_url may allocate internally.

Since

0.1.0

Definition at line 418 of file mdl_service.c.

References esp_http_client_set_url, ESP_OK, mdl_http_state::format, ra8_mdl_request_t::format, mdl_http_state::hashing, mdl_http_state::http, internal_mdl_http_apply_request(), internal_mdl_http_reset_job(), k_mdl_format_rabook, k_ra8_err_invalid_arg, k_ra8_fail, k_ra8_ok, mbedtls_sha256_starts, RA8_INTERNAL, mdl_http_state::sha, strncmp(), mdl_http_state::url, and ra8_mdl_request_t::url.

Referenced by esp_hosted_custom_rpc_sync_handler().

internal_mdl_http_cancel()

ra8_err_t internal_mdl_http_cancel ( void * ctx )

static

Cancel the active HTTP job while retaining one-time objects.

Closes per-job state without destroying retained service objects.

Parameters

[in,out]

ctx

Initialised mdl_http_state_t.

Returns

Cancellation status.

Return values

k_ra8_ok

Local job state was reset.

Precondition

ctx is non-null and exclusively owned.

One-time client initialisation succeeded.

Postcondition

No active response or SHA operation remains.

Retained objects are ready for a later Start.

Note

Not thread-safe; service dispatch serializes calls.

Since

0.1.0

Definition at line 667 of file mdl_service.c.

References internal_mdl_http_reset_job(), k_ra8_ok, and RA8_INTERNAL.

Referenced by esp_hosted_custom_rpc_sync_handler().

internal_mdl_http_event()

esp_err_t internal_mdl_http_event ( esp_http_client_event_t * event )

static

Capture selected response headers from ESP-IDF events.

Filters the event stream to header events and records the first bounded-copy failure so the later read path fails closed.

Parameters

[in,out]

event

ESP-IDF event record.

Returns

ESP-IDF callback status.

Return values

ESP_OK	The event was ignored or captured safely.
ESP_FAIL	A selected header was malformed or oversized.

Precondition

event is non-null when called by ESP-IDF.

event->user_data points to the retained backend state.

Postcondition

Selected valid headers are copied into bounded retained storage.

The first selected-header failure is retained for portable reporting.

Note

Body data is consumed synchronously through esp_http_client_read.

Since

0.1.0

Definition at line 251 of file mdl_service.c.

References ESP_FAIL, ESP_OK, esp_http_client_event_t::event_id, mdl_http_state::header_error, esp_http_client_event_t::header_key, esp_http_client_event_t::header_value, HTTP_EVENT_ON_HEADER, internal_mdl_copy_field(), internal_mdl_select_response_header(), k_ra8_ok, RA8_INTERNAL, and esp_http_client_event_t::user_data.

Referenced by internal_mdl_http_init().

internal_mdl_http_finish()

ra8_err_t internal_mdl_http_finish ( mdl_http_state_t * state, uint64_t * total_bytes, bool * complete, uint8_t sha256[k_ra8_mdl_sha256_bytes], ra8_mdl_http_response_t * response )

static

Validate EOF and publish the terminal length and digest.

Rejects truncated or length-mismatched responses, finalizes SHA, derives an unknown total from counted bytes, and closes job state.

Parameters

[in,out]	state	Open response and active hash state.
[out]	total_bytes	Advertised or independently counted final length.
[out]	complete	Receives true only for verified terminal success.
[out]	sha256	Complete-body digest destination.
[out]	response	Final status and selected response headers.

Returns

Terminal response status.

Return values

k_ra8_ok	Terminal metadata and digest were published.
k_ra8_err_protocol_error	HTTP completeness or length is incoherent.
k_ra8_fail	SHA finalization failed.

Precondition

Output pointers are non-null and state owns an open response.

Every returned body byte was counted and hashed exactly once.

Postcondition

Success closes job state after publishing terminal outputs.

Failure closes job state without claiming completion.

Note

Close-delimited responses publish their independently counted length.

Since

0.1.0

Definition at line 518 of file mdl_service.c.

References esp_http_client_is_complete_data_received, mdl_http_state::http, internal_mdl_http_reset_job(), k_ra8_err_protocol_error, k_ra8_fail, k_ra8_mdl_sha256_bytes, k_ra8_ok, mbedtls_sha256_finish, RA8_INTERNAL, mdl_http_state::received, mdl_http_state::response, mdl_http_state::sha, mdl_http_state::total, and mdl_http_state::total_known.

Referenced by internal_mdl_http_read().

internal_mdl_http_init()

ra8_err_t internal_mdl_http_init ( mdl_http_state_t * state )

static

Create the retained ESP-IDF client and SHA context once.

This is the sole direct call to esp_http_client_init in the component. Upstream still allocates internally during URL changes and TLS.

Parameters

[in,out]

state

Zero-initialised backend state.

Returns

Initialisation status.

Return values

k_ra8_ok	Retained objects are ready.
k_ra8_err_no_mem	ESP-IDF could not create the client handle.

Precondition

state is non-null and not yet initialised.

The serialized RPC task exclusively owns state.

Postcondition

Success retains the HTTP/SHA objects for later dispatch.

Failure leaves the portable backend unregistered.

Note

Not thread-safe; called once before portable service initialisation.

Warning

This concrete adapter remains an ESP-IDF heap exception.

Since

0.1.0

Definition at line 290 of file mdl_service.c.

References esp_crt_bundle_attach, esp_http_client_init, mdl_http_state::http, internal_mdl_http_event(), k_mdl_http_timeout_ms, k_ra8_err_no_mem, k_ra8_mdl_chunk_data_max, k_ra8_ok, mbedtls_sha256_init, RA8_INTERNAL, and mdl_http_state::sha.

Referenced by esp_hosted_custom_rpc_sync_handler().

internal_mdl_http_open()

ra8_err_t internal_mdl_http_open ( mdl_http_state_t * state )

static

Open lazily so Start returns without waiting for network exchange.

Records the actual final status and bounded selected headers so the portable downloader, rather than this transport, owns HTTP semantics.

Parameters

[in,out]

state

Prepared job state.

Returns

Open status.

Return values

k_ra8_ok	Headers describe a syntactically valid HTTP response.
k_ra8_fail	ESP-IDF failed to open the HTTPS connection.
k_ra8_err_protocol_error	HTTP status is outside 100..599.
k_ra8_err_invalid_size	A selected response header is oversized.

Precondition

state completed internal_mdl_http_begin successfully.

No concurrent request uses the retained client.

Postcondition

Success marks the response opened and records advertised length.

Failure does not publish body bytes.

Note

Not thread-safe; service dispatch serializes calls.

Warning

TLS connection/reconnection may allocate internally.

Since

0.1.0

Definition at line 472 of file mdl_service.c.

References esp_http_client_fetch_headers, esp_http_client_get_status_code, esp_http_client_open, ESP_OK, mdl_http_state::header_error, mdl_http_state::http, k_mdl_http_status_max, k_mdl_http_status_min, k_ra8_err_protocol_error, k_ra8_fail, k_ra8_ok, mdl_http_state::opened, RA8_INTERNAL, mdl_http_state::response, ra8_mdl_http_response_t::status, mdl_http_state::total, and mdl_http_state::total_known.

Referenced by internal_mdl_http_read().

internal_mdl_http_read()

ra8_err_t internal_mdl_http_read ( void * ctx, uint8_t * out, uint16_t cap, uint16_t * got, uint64_t * total_bytes, bool * complete, uint8_t sha256[k_ra8_mdl_sha256_bytes], ra8_mdl_http_response_t * response )

static

Pull one bounded body span or verified terminal metadata.

Counts and hashes every returned byte and rejects truncated bodies.

Parameters

[in,out]	ctx	Prepared mdl_http_state_t.
[out]	out	Caller-owned body-byte buffer.
[in]	cap	Capacity of out.
[out]	got	Exact body bytes returned.
[out]	total_bytes	Advertised or independently counted total.
[out]	complete	Whether this response is terminal.
[out]	sha256	Complete-body digest when terminal.
[out]	response	Final status and selected headers when terminal.

Returns

Read status.

Return values

k_ra8_ok	Data or one verified terminal record is available.
k_ra8_err_protocol_error	HTTP status/body completion is incoherent.
k_ra8_err_invalid_size	Received-byte count overflowed.
k_ra8_fail	ESP-IDF or SHA processing failed.

Precondition

Every output pointer is non-null and cap is bounded by the protocol.

internal_mdl_http_begin succeeded for this job.

Postcondition

A data response advances received by exactly got.

Terminal success closes job state after digest finalisation.

Note

Not thread-safe; service dispatch serializes calls.

Since

0.1.0

Definition at line 620 of file mdl_service.c.

References esp_http_client_read, mdl_http_state::http, internal_mdl_http_account_read(), internal_mdl_http_finish(), internal_mdl_http_open(), internal_mdl_http_reset_job(), k_ra8_fail, k_ra8_mdl_sha256_bytes, k_ra8_ok, and RA8_INTERNAL.

Referenced by esp_hosted_custom_rpc_sync_handler().

internal_mdl_http_reset_job()

void internal_mdl_http_reset_job ( mdl_http_state_t * state )

static

Close one request while retaining the one-time client/hash objects.

Clears job metadata but deliberately does not call HTTP cleanup or SHA free between Start operations.

Parameters

[in,out]

state

Retained backend state.

Precondition

state is non-null and has completed one-time initialisation.

The serialized RPC task exclusively owns state.

Postcondition

No active HTTP response or SHA operation remains.

The client and SHA objects remain initialised for a later Start.

Note

Not thread-safe; the ESP-hosted control path serializes access.

Warning

ESP-IDF close/reconnect internals may still release/allocate heap.

Since

0.1.0

Definition at line 98 of file mdl_service.c.

References esp_http_client_close, mdl_http_state::format, mdl_http_state::hashing, mdl_http_state::header_error, mdl_http_state::http, mdl_http_state::if_modified_since, mdl_http_state::if_none_match, k_mdl_format_invalid, k_ra8_ok, mdl_http_state::opened, RA8_INTERNAL, mdl_http_state::received, mdl_http_state::referer, mdl_http_state::response, mdl_http_state::total, mdl_http_state::total_known, mdl_http_state::url, and mdl_http_state::user_agent.

Referenced by internal_mdl_http_account_read(), internal_mdl_http_begin(), internal_mdl_http_cancel(), internal_mdl_http_finish(), and internal_mdl_http_read().

internal_mdl_http_set_header()

ra8_err_t internal_mdl_http_set_header ( mdl_http_state_t * state, const char * name, const char * value )

static

Replace one optional retained request header.

Clears prior client state first, then installs the new value only when the portable request selected a nonempty header.

Parameters

[in,out]	state	Retained HTTP state.
[in]	name	Canonical request-header name.
[in]	value	Bounded retained value, or empty to omit.

Returns

Header configuration status.

Return values

k_ra8_ok	The next request has the selected header policy.
k_ra8_fail	ESP-IDF rejected a nonempty header value.

Precondition

All pointers are non-null and strings are NUL-terminated.

No request is open on the retained client.

Postcondition

Success installs value or leaves name absent.

Failure does not authorize the next request.

Note

Deleting an already-absent header is intentionally idempotent.

Since

0.1.0

Definition at line 328 of file mdl_service.c.

References esp_http_client_delete_header, esp_http_client_set_header, ESP_OK, mdl_http_state::http, k_ra8_fail, and k_ra8_ok.

Referenced by internal_mdl_http_apply_request().

internal_mdl_select_response_header()

void internal_mdl_select_response_header ( mdl_http_state_t * state, const char * key, char ** destination, size_t * capacity )

static

Select retained storage for one response header.

Maps the four protocol-selected field names to their fixed arrays while leaving all other response headers intentionally ignored.

Parameters

[in,out]	state	Active HTTP state.
[in]	key	NUL-terminated response-header name.
[out]	destination	Selected destination, or null for an ignored header.
[out]	capacity	Selected destination capacity.

Precondition

All pointers are non-null and key is NUL-terminated.

state owns initialized response storage.

Postcondition

Known names select exactly one bounded response field.

Unknown names produce a null destination and zero capacity.

Note

Matching is ASCII case-insensitive.

Since

0.1.0

Definition at line 212 of file mdl_service.c.

References ra8_mdl_http_response_t::content_type, ra8_mdl_http_response_t::etag, internal_mdl_header_equal(), ra8_mdl_http_response_t::last_modified, RA8_INTERNAL, mdl_http_state::response, and ra8_mdl_http_response_t::retry_after.

Referenced by internal_mdl_http_event().

internal_mdl_to_esp_status()

esp_err_t internal_mdl_to_esp_status ( ra8_err_t result )

static

Translate a portable media-service result into ESP-IDF's error domain.

Uses an explicit semantic mapping so equal numeric values in the unrelated RA8 and ESP-IDF enumerations cannot change meaning.

Parameters

[in]

result

Portable media-service result.

Returns

Equivalent ESP-IDF status for the outer CustomRpc response.

Return values

ESP_OK	Portable dispatch produced a complete inner response.
ESP_ERR_NO_MEM	The bounded decode arena was exhausted.
ESP_ERR_INVALID_ARG	A pointer or argument was invalid.
ESP_ERR_INVALID_STATE	The media service was busy or in the wrong state.
ESP_ERR_INVALID_SIZE	A request or response extent was invalid.
ESP_ERR_NOT_FOUND	A requested object was absent.
ESP_ERR_TIMEOUT	The operation exceeded its bounded work budget.
ESP_ERR_INVALID_RESPONSE	Protocol or structural validation failed.
ESP_ERR_INVALID_CRC	A digest comparison failed.
ESP_FAIL	No more specific ESP-IDF status represents result.

Precondition

result is a value returned by the portable media service.

Unknown operation identifiers are rejected before this mapping.

Postcondition

No service, HTTP, SHA, or response state is modified.

ESP_ERR_NOT_SUPPORTED is never returned for a recognized media operation.

Note

Keeping first-refusal separate prevents backend failures from invoking ESP-hosted's unrelated legacy CustomRpc fallback.

Since

0.1.0

Definition at line 699 of file mdl_service.c.

References ESP_ERR_INVALID_ARG, ESP_ERR_INVALID_CRC, ESP_ERR_INVALID_RESPONSE, ESP_ERR_INVALID_SIZE, ESP_ERR_INVALID_STATE, ESP_ERR_NO_MEM, ESP_ERR_NOT_FOUND, ESP_ERR_TIMEOUT, ESP_FAIL, ESP_OK, k_ra8_err_busy, k_ra8_err_checksum_mismatch, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_err_no_mem, k_ra8_err_not_found, k_ra8_err_null_ptr, k_ra8_err_protocol_error, k_ra8_err_timeout, k_ra8_err_validation_failed, k_ra8_ok, and RA8_INTERNAL.

Referenced by esp_hosted_custom_rpc_sync_handler().

ra8_mdl_service_component_abi()

uint32_t ra8_mdl_service_component_abi

(

void

)

Return the linked first-party media component ABI version.

The post-link build assertion requires this exact strong symbol.

Returns

Stable positive ABI version checked by the component itself.

Return values

1	First version of the concrete media service component.

Precondition

The first-party component object is strongly linked into the image.

The upstream weak fallback has not replaced this component.

Postcondition

No global or peripheral state is modified.

Repeated calls return the same version for one image.

Note

Thread-safe and allocation-free.

Since

0.1.0

Definition at line 75 of file mdl_service.c.

Variable Documentation

s_component_abi

mdl_component_abi_fn_t volatile s_component_abi = ra8_mdl_service_component_abi

static

Definition at line 83 of file mdl_service.c.

Referenced by esp_hosted_custom_rpc_sync_handler().

s_http

mdl_http_state_t s_http

static

Definition at line 58 of file mdl_service.c.

Referenced by esp_hosted_custom_rpc_sync_handler().

s_initialised

bool s_initialised

static

Definition at line 60 of file mdl_service.c.

Referenced by esp_hosted_custom_rpc_sync_handler().

s_service

ra8_mdl_service_t s_service

static

Definition at line 59 of file mdl_service.c.

Referenced by esp_hosted_custom_rpc_sync_handler().