Cross-Layer Data Buffer

Caller-owned, bounds-checked view over static storage (ADR-002). More...

Files
file	src/utils/buffer/sapi_buffer.c
	Implementation of the cross-layer data buffer abstraction (ADR-002).

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

Caller-owned, bounds-checked view over static storage (ADR-002).

Function Documentation

sapi_buffer_init()

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.

Parameters

buf	Buffer view to initialize. Must not be NULL.
storage	Caller-owned backing storage. Must not be NULL and must remain valid for the lifetime of buf.
capacity	Usable size of storage in bytes. Must be > 0.

Returns

SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM if buf or storage is NULL, or capacity is 0. REQ-COMMON-BUF-010

Definition at line 9 of file sapi_buffer.c.

sapi_buffer_clear()

sapi_status_t sapi_buffer_clear

(

sapi_buffer_t *

buf

)

Resets length to 0; capacity and data are unchanged.

Parameters

buf	Buffer to clear. Must not be NULL and must satisfy sapi_buffer_is_valid().

Returns

SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM otherwise. REQ-COMMON-BUF-011

Definition at line 21 of file sapi_buffer.c.

sapi_buffer_set_length()

sapi_status_t sapi_buffer_set_length	(	sapi_buffer_t *	buf,
		size_t	length )

Marks length bytes of already-written storage as valid.

Parameters

buf	Buffer to update. Must not be NULL.
length	New valid length in bytes.

Returns

SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM if buf is NULL; SAPI_STATUS_RESOURCE_EXHAUSTED if length > buf->capacity. REQ-COMMON-BUF-012

Definition at line 31 of file sapi_buffer.c.

sapi_buffer_copy_in()

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.

Parameters

buf	Destination buffer. Must not be NULL.
src	Source data to copy in. Must not be NULL.
src_len	Number of bytes to copy from src.

Returns

SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM if buf or src is NULL; SAPI_STATUS_RESOURCE_EXHAUSTED if src_len exceeds buf->capacity (buf is left unmodified in that case). REQ-COMMON-BUF-013

Definition at line 45 of file sapi_buffer.c.

sapi_buffer_copy_out()

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.

Parameters

buf	Source buffer. Must not be NULL.
dest	Destination to copy into. Must not be NULL.
dest_capacity	Usable size of dest in bytes.
out_copied	Receives the number of bytes actually copied (== buf->length on success; 0 on failure). Must not be NULL.

Returns

SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM if any pointer argument is NULL; SAPI_STATUS_RESOURCE_EXHAUSTED if buf->length exceeds dest_capacity. REQ-COMMON-BUF-014

Definition at line 63 of file sapi_buffer.c.

sapi_buffer_as_const()

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.

Parameters

buf	Source buffer. Must not be NULL.
out_view	Receives the read-only view. Must not be NULL.

Returns

SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM if buf or out_view is NULL; SAPI_STATUS_INTERNAL_ERROR if buf's own length/capacity invariant is violated (defensive check). REQ-COMMON-BUF-015

Definition at line 85 of file sapi_buffer.c.

sapi_buffer_is_valid()

bool sapi_buffer_is_valid

(

const sapi_buffer_t *

buf

)

Defensive validity check: non-null data and length <= capacity.

Parameters

buf	Buffer to check; NULL is a valid input (returns false).

Returns

true if buf is non-NULL, buf->data is non-NULL, and buf->length <= buf->capacity; false otherwise. REQ-COMMON-BUF-016

Definition at line 100 of file sapi_buffer.c.

sapi_buffer_write_u16_le()

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.

Parameters

buf	Destination buffer. Must not be NULL.
value	Value to encode and append.

Returns

SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM if buf is NULL; SAPI_STATUS_RESOURCE_EXHAUSTED if 2 bytes will not fit before buf->capacity. REQ-COMMON-BUF-020

Definition at line 170 of file sapi_buffer.c.

sapi_buffer_write_u16_be()

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().

Parameters

buf	Destination buffer. Must not be NULL.
value	Value to encode and append.

Returns

Same status contract as sapi_buffer_write_u16_le(). REQ-COMMON-BUF-021

Definition at line 178 of file sapi_buffer.c.

sapi_buffer_write_u32_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.

Parameters

buf	Destination buffer. Must not be NULL.
value	Value to encode and append.

Returns

SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM if buf is NULL; SAPI_STATUS_RESOURCE_EXHAUSTED if 4 bytes will not fit before buf->capacity. REQ-COMMON-BUF-022

Definition at line 186 of file sapi_buffer.c.

sapi_buffer_write_u32_be()

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().

Parameters

buf	Destination buffer. Must not be NULL.
value	Value to encode and append.

Returns

Same status contract as sapi_buffer_write_u32_le(). REQ-COMMON-BUF-023

Definition at line 196 of file sapi_buffer.c.

sapi_buffer_write_u64_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.

Parameters

buf	Destination buffer. Must not be NULL.
value	Value to encode and append.

Returns

SAPI_STATUS_OK on success; SAPI_STATUS_INVALID_PARAM if buf is NULL; SAPI_STATUS_RESOURCE_EXHAUSTED if 8 bytes will not fit before buf->capacity. REQ-COMMON-BUF-024

Definition at line 206 of file sapi_buffer.c.

sapi_buffer_write_u64_be()

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().

Parameters

buf	Destination buffer. Must not be NULL.
value	Value to encode and append.

Returns

Same status contract as sapi_buffer_write_u64_le(). REQ-COMMON-BUF-025

Definition at line 217 of file sapi_buffer.c.

sapi_buffer_read_u16_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.

Parameters

buf	Source buffer. Must not be NULL.
offset	Byte offset within buf's valid bytes to read from.
out_value	Receives the decoded value. Must not be NULL.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM for a NULL pointer; SAPI_STATUS_RESOURCE_EXHAUSTED if offset+2 exceeds buf->length. REQ-COMMON-BUF-026

Definition at line 229 of file sapi_buffer.c.

sapi_buffer_read_u16_be()

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().

Parameters

buf	Source buffer. Must not be NULL.
offset	Byte offset within buf's valid bytes to read from.
out_value	Receives the decoded value. Must not be NULL.

Returns

Same status contract as sapi_buffer_read_u16_le(). REQ-COMMON-BUF-027

Definition at line 249 of file sapi_buffer.c.

sapi_buffer_read_u32_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.

Parameters

buf	Source buffer. Must not be NULL.
offset	Byte offset within buf's valid bytes to read from.
out_value	Receives the decoded value. Must not be NULL.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM for a NULL pointer; SAPI_STATUS_RESOURCE_EXHAUSTED if offset+4 exceeds buf->length. REQ-COMMON-BUF-028

Definition at line 269 of file sapi_buffer.c.

sapi_buffer_read_u32_be()

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().

Parameters

buf	Source buffer. Must not be NULL.
offset	Byte offset within buf's valid bytes to read from.
out_value	Receives the decoded value. Must not be NULL.

Returns

Same status contract as sapi_buffer_read_u32_le(). REQ-COMMON-BUF-029

Definition at line 290 of file sapi_buffer.c.

sapi_buffer_read_u64_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.

Parameters

buf	Source buffer. Must not be NULL.
offset	Byte offset within buf's valid bytes to read from.
out_value	Receives the decoded value. Must not be NULL.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM for a NULL pointer; SAPI_STATUS_RESOURCE_EXHAUSTED if offset+8 exceeds buf->length. REQ-COMMON-BUF-030

Definition at line 311 of file sapi_buffer.c.

sapi_buffer_read_u64_be()

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().

Parameters

buf	Source buffer. Must not be NULL.
offset	Byte offset within buf's valid bytes to read from.
out_value	Receives the decoded value. Must not be NULL.

Returns

Same status contract as sapi_buffer_read_u64_le(). REQ-COMMON-BUF-031

Definition at line 335 of file sapi_buffer.c.