media_download_format_internal.h File Reference

Private source-image to RBKC formatter for the media app. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_err.h"
#include "ra8_rabook_comic.h"
#include "ra8_rabook_container.h"

Include dependency graph for media_download_format_internal.h:

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

Go to the source code of this file.

Data Structures
struct	media_download_format_config_t
	Immutable policy for one fetched-image conversion. More...
struct	media_download_format_workspace_t
	Complete caller-owned storage for image-to-RBKC conversion. More...
struct	media_download_memory_t
	Mutable bounds for one formatter-owned in-memory spool. More...

Functions
ra8_err_t	priv_media_download_memory_write_at (media_download_memory_t *memory, uint64_t offset, const uint8_t *source, uint32_t requested, uint32_t *written)
	Write one exact span at an absolute private-spool offset.
ra8_err_t	priv_media_download_memory_read (void *context, uint32_t offset, uint8_t *destination, uint32_t requested, uint32_t *out_read)
	Read one exact initialized range from a private spool.
ra8_err_t	priv_media_download_format_rabook (const uint8_t *source, size_t source_size, const media_download_format_config_t *config, media_download_format_workspace_t *workspace, uint64_t *packed_size)
	Format one encoded source image as a reader-native .rabook.

Detailed Description

Private source-image to RBKC formatter for the media app.

Declares the caller-workspace contract that lets the RA8 normalize one fetched image into a reader-native RABOOK1 book and wrap it as the chunked RBKC .rabook artifact saved by the application.

Copyright

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

Since

0.1.0

Definition in file media_download_format_internal.h.

Function Documentation

priv_media_download_format_rabook()

ra8_err_t priv_media_download_format_rabook ( const uint8_t * source, size_t source_size, const media_download_format_config_t * config, media_download_format_workspace_t * workspace, uint64_t * packed_size )

nodiscard

Format one encoded source image as a reader-native .rabook.

Parameters

[in]	source	Complete encoded JPEG, PNG, GIF, BMP, or WebP bytes.
[in]	source_size	Exact encoded byte count.
[in]	config	Page, book, raster, and chunk policy.
[in,out]	workspace	Exclusive caller-owned conversion storage.
[out]	packed_size	Exact RBKC artifact byte count.

Returns

Conversion status.

Return values

k_ra8_ok	A complete RBKC artifact occupies workspace->packed.
k_ra8_err_null_ptr	A required pointer or workspace span is NULL.
k_ra8_err_invalid_size	A capacity, source, or callback extent failed.

Returns

Raster, builder, compressor, and validation statuses propagate.

Precondition

Workspace spans are live, writable, and mutually non-overlapping.

source is disjoint from every mutable workspace span.

Postcondition

Success initializes exactly packed_size bytes of packed storage.

Failure sets packed_size to zero and publishes no external object.

Note

The caller must strictly validate before transactionally publishing.

Since

0.1.0

Definition at line 234 of file media_download_format.c.

References media_download_format_config_t::chunk_bytes, media_download_format_workspace_t::comic, media_download_format_workspace_t::container, media_download_format_workspace_t::flat, media_download_format_workspace_t::flat_cap, media_download_format_workspace_t::image, media_download_format_workspace_t::image_cap, internal_flat_append(), internal_image_write(), internal_packed_write(), internal_validate_format_request(), k_ra8_err_validation_failed, k_ra8_ok, media_download_memory_t::length, media_download_format_config_t::max_image_edge, media_download_format_config_t::metadata, media_download_format_workspace_t::packed, media_download_format_workspace_t::packed_cap, media_download_format_config_t::page_id, media_download_format_config_t::pixel_format, priv_media_download_memory_read(), RA8_PRIV, ra8_rabook_comic_add_page(), ra8_rabook_comic_finish(), ra8_rabook_comic_init(), and ra8_rabook_container_write().

Referenced by internal_format().

priv_media_download_memory_read()

ra8_err_t priv_media_download_memory_read ( void * context, uint32_t offset, uint8_t * destination, uint32_t requested, uint32_t * out_read )

nodiscard

Read one exact initialized range from a private spool.

Parameters

[in]	context	Bound media_download_memory_t source.
[in]	offset	Absolute source offset.
[out]	destination	Writable destination span.
[in]	requested	Exact byte count.
[out]	out_read	Copied byte count.

Returns

Memory-read status.

Return values

k_ra8_ok	The complete range was copied.
k_ra8_err_null_ptr	A required pointer was NULL.
k_ra8_err_invalid_size	The requested range exceeded initialized bytes.

Precondition

Context and destination remain live for the call.

Destination does not overlap the selected source range.

Postcondition

Success reports requested and initializes the destination range.

Failure reports zero when out_read is available and preserves source state.

Note

Private formatter seam exposed only to same-module tests.

Since

0.1.0

Definition at line 53 of file media_download_format.c.

References media_download_memory_t::bytes, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, media_download_memory_t::length, memcpy(), and RA8_PRIV.

Referenced by priv_media_download_format_rabook().

priv_media_download_memory_write_at()

ra8_err_t priv_media_download_memory_write_at ( media_download_memory_t * memory, uint64_t offset, const uint8_t * source, uint32_t requested, uint32_t * written )

nodiscard

Write one exact span at an absolute private-spool offset.

Parameters

[in,out]	memory	Destination spool.
[in]	offset	Absolute destination offset.
[in]	source	Complete source span.
[in]	requested	Exact byte count.
[out]	written	Accepted byte count.

Returns

Memory-write status.

Return values

k_ra8_ok	The complete span was copied.
k_ra8_err_null_ptr	A required pointer was NULL.
k_ra8_err_invalid_size	The requested range exceeded capacity.

Precondition

Non-NULL pointers span their declared extents.

Source and destination ranges do not overlap.

Postcondition

Success reports requested and extends length monotonically.

Failure reports zero when written is available and preserves length.

Note

Private formatter seam exposed only to same-module tests.

Since

0.1.0

Definition at line 20 of file media_download_format.c.

References media_download_memory_t::bytes, media_download_memory_t::capacity, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, media_download_memory_t::length, memcpy(), and RA8_PRIV.

Referenced by internal_flat_append(), internal_image_write(), and internal_packed_write().