sapi_buffer.h File Reference

Cross-layer data buffer abstraction (ADR-002). More...

#include "safeapi/utils/status/sapi_status.h"
#include "safeapi/utils/types/sapi_types.h"

Include dependency graph for sapi_buffer.h:

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

Go to the source code of this file.

Data Structures
struct	sapi_buffer_t
	Mutable, bounds-tracked view over caller-owned storage. More...
struct	sapi_const_buffer_t
	Read-only view of a buffer's currently valid bytes. Grants no write access to the underlying storage. More...

Functions
sapi_status_t	sapi_buffer_init (sapi_buffer_t *buf, void *storage, size_t capacity)
	Binds a buffer view to caller-owned storage. Initial length is 0.
sapi_status_t	sapi_buffer_clear (sapi_buffer_t *buf)
	Resets length to 0; capacity and data are unchanged.
sapi_status_t	sapi_buffer_set_length (sapi_buffer_t *buf, size_t length)
	Marks length bytes of already-written storage as valid.
sapi_status_t	sapi_buffer_copy_in (sapi_buffer_t *buf, const void *src, size_t src_len)
	Bounds-checked copy of external data into the buffer; sets length.
sapi_status_t	sapi_buffer_copy_out (const sapi_buffer_t *buf, void *dest, size_t dest_capacity, size_t *out_copied)
	Bounds-checked copy of the buffer's valid bytes to an external destination.
sapi_status_t	sapi_buffer_as_const (const sapi_buffer_t *buf, sapi_const_buffer_t *out_view)
	Produces a read-only view of the buffer's current valid bytes. The view is only valid as long as the source buffer's storage is.
bool	sapi_buffer_is_valid (const sapi_buffer_t *buf)
	Defensive validity check: non-null data and length <= capacity.
sapi_status_t	sapi_buffer_write_u16_le (sapi_buffer_t *buf, uint16_t value)
	Appends a little-endian uint16_t at buf's current length.
sapi_status_t	sapi_buffer_write_u16_be (sapi_buffer_t *buf, uint16_t value)
	Appends a big-endian uint16_t. See sapi_buffer_write_u16_le().
sapi_status_t	sapi_buffer_write_u32_le (sapi_buffer_t *buf, uint32_t value)
	Appends a little-endian uint32_t at buf's current length.
sapi_status_t	sapi_buffer_write_u32_be (sapi_buffer_t *buf, uint32_t value)
	Appends a big-endian uint32_t. See sapi_buffer_write_u32_le().
sapi_status_t	sapi_buffer_write_u64_le (sapi_buffer_t *buf, uint64_t value)
	Appends a little-endian uint64_t at buf's current length.
sapi_status_t	sapi_buffer_write_u64_be (sapi_buffer_t *buf, uint64_t value)
	Appends a big-endian uint64_t. See sapi_buffer_write_u64_le().
sapi_status_t	sapi_buffer_read_u16_le (const sapi_buffer_t *buf, size_t offset, uint16_t *out_value)
	Reads a little-endian uint16_t at the given offset.
sapi_status_t	sapi_buffer_read_u16_be (const sapi_buffer_t *buf, size_t offset, uint16_t *out_value)
	Reads a big-endian uint16_t. See sapi_buffer_read_u16_le().
sapi_status_t	sapi_buffer_read_u32_le (const sapi_buffer_t *buf, size_t offset, uint32_t *out_value)
	Reads a little-endian uint32_t at the given offset.
sapi_status_t	sapi_buffer_read_u32_be (const sapi_buffer_t *buf, size_t offset, uint32_t *out_value)
	Reads a big-endian uint32_t. See sapi_buffer_read_u32_le().
sapi_status_t	sapi_buffer_read_u64_le (const sapi_buffer_t *buf, size_t offset, uint64_t *out_value)
	Reads a little-endian uint64_t at the given offset.
sapi_status_t	sapi_buffer_read_u64_be (const sapi_buffer_t *buf, size_t offset, uint64_t *out_value)
	Reads a big-endian uint64_t. See sapi_buffer_read_u64_le().

Detailed Description

Cross-layer data buffer abstraction (ADR-002).

sapi_buffer_t is a lightweight, caller-owned VIEW over static storage - it never allocates and never frees memory. Every operation is bounds-checked against the declared capacity.

REQ-COMMON-BUF-001: no dynamic allocation; the caller owns the backing storage (e.g. a static or stack-scoped byte array) for the lifetime of the buffer view. REQ-COMMON-BUF-002: every copy operation shall be bounds-checked and shall never write past the declared capacity.

Definition in file sapi_buffer.h.