Unified Channel Factory

App-facing channel open/send/receive/close, transport hidden (ADR-022). More...

Data Structures
struct	sapi_safechannel_endpoint_t
	One remote endpoint to open internally - replaces a caller- supplied sapi_netlink_handle_t (ADR-022 section 2.2). More...
struct	sapi_safechannel_dual_config_t
	Configuration specific to SAPI_SAFECHANNEL_TYPE_DUAL_REDUNDANT. More...
struct	sapi_safechannel_vital_config_t
	Configuration specific to SAPI_SAFECHANNEL_TYPE_VITAL_VOTED. More...
struct	sapi_safechannel_config_t
	Configuration for sapi_safechannel_open(). More...
union	sapi_safechannel_config_t::[union].as
struct	sapi_safechannel_t
	Caller-owned storage for one sapi_safechannel_t instance. Every field is private - reach it only through the functions below. No dynamic allocation (REQ-SAFECHANNEL-002): sized to hold up to SAPI_SAFECHANNEL_MAX_LINKS opened netlink links plus whichever of sapi_dual_channel_t/sapi_channel_t is in use. More...
union	sapi_safechannel_t::[union].impl
struct	sapi_safechannel_t::[struct].impl.vital

Macros
#define	SAPI_SAFECHANNEL_MAX_LINKS   4U
	Maximum number of redundant endpoints one sapi_safechannel_t may be configured with, for either type. Fixed, not dynamic.

Enumerations
enum	sapi_safechannel_type_t { SAPI_SAFECHANNEL_TYPE_DUAL_REDUNDANT = 0 , SAPI_SAFECHANNEL_TYPE_VITAL_VOTED = 1 }
	Which underlying channel implementation a sapi_safechannel_t wraps. More...
enum	sapi_safechannel_link_status_t { SAPI_SAFECHANNEL_LINK_DOWN = 0 , SAPI_SAFECHANNEL_LINK_DEGRADED = 1 , SAPI_SAFECHANNEL_LINK_FULL = 2 }
	Aggregate link status, uniform across both wrapped types. More...

Functions
sapi_status_t	sapi_safechannel_open (sapi_safechannel_t *channel, const sapi_safechannel_config_t *config)
	Opens a channel: opens every configured endpoint via the registered sapi_netlink backend, then initializes the wrapped sapi_dual_channel_t or sapi_channel_t on top of the resulting links (ADR-022 section 2.2). Retries each endpoint's sapi_netlink_open() internally up to config's own connect_timeout_ms, matching the retry pattern every current hand-rolled caller already implemented itself.
sapi_status_t	sapi_safechannel_send (sapi_safechannel_t *channel, const uint8_t *payload, size_t payload_size)
	Sends payload on the underlying channel - broadcast-with-ACK- wait for DUAL_REDUNDANT (sapi_dual_channel_send()), atomic all-or-nothing broadcast to every registered channel for VITAL_VOTED (sapi_voter_send()).
sapi_status_t	sapi_safechannel_receive (sapi_safechannel_t *channel, uint8_t *out_payload, size_t max_size, sapi_duration_ms_t timeout_ms, size_t *out_size)
	Returns the most recent inbound payload, actively polling the underlying channel if nothing was already staged.
sapi_safechannel_link_status_t	sapi_safechannel_get_status (const sapi_safechannel_t *channel)
	Aggregate status across every configured endpoint - DOWN before the first send/receive.
sapi_status_t	sapi_safechannel_close (sapi_safechannel_t *channel)
	Closes every endpoint this instance opened and releases the wrapped channel. Safe to call on an already-closed/never-opened instance (no-op).

Detailed Description

App-facing channel open/send/receive/close, transport hidden (ADR-022).

Macro Definition Documentation

SAPI_SAFECHANNEL_MAX_LINKS

#define SAPI_SAFECHANNEL_MAX_LINKS   4U

Maximum number of redundant endpoints one sapi_safechannel_t may be configured with, for either type. Fixed, not dynamic.

Definition at line 57 of file sapi_safechannel.h.

Enumeration Type Documentation

sapi_safechannel_type_t

enum sapi_safechannel_type_t

Which underlying channel implementation a sapi_safechannel_t wraps.

Enumerator
SAPI_SAFECHANNEL_TYPE_DUAL_REDUNDANT	Wraps sapi_dual_channel_t: 1..N redundant links, always-send + bounded-ACK-wait delivery, EN 50159-framed (ADR-020).
SAPI_SAFECHANNEL_TYPE_VITAL_VOTED	Wraps a sapi_voter_t over N sapi_channel_t links: 2oo2/2oo3/NMR voting arbitration (ADR-025).

Definition at line 60 of file sapi_safechannel.h.

sapi_safechannel_link_status_t

enum sapi_safechannel_link_status_t

Aggregate link status, uniform across both wrapped types.

Enumerator
SAPI_SAFECHANNEL_LINK_DOWN	No configured endpoint is usable.
SAPI_SAFECHANNEL_LINK_DEGRADED	Some, but not all, endpoints usable.
SAPI_SAFECHANNEL_LINK_FULL	Every configured endpoint usable.

Definition at line 71 of file sapi_safechannel.h.

Function Documentation

sapi_safechannel_open()

sapi_status_t sapi_safechannel_open	(	sapi_safechannel_t *	channel,
		const sapi_safechannel_config_t *	config )

Opens a channel: opens every configured endpoint via the registered sapi_netlink backend, then initializes the wrapped sapi_dual_channel_t or sapi_channel_t on top of the resulting links (ADR-022 section 2.2). Retries each endpoint's sapi_netlink_open() internally up to config's own connect_timeout_ms, matching the retry pattern every current hand-rolled caller already implemented itself.

Parameters

channel	Caller-owned storage to initialize. Must not be NULL.
config	Configuration. Must not be NULL; config->type selects which union member is read; that member's link_count must be in [1, its type's max] and every endpoints[0..link_count-1].host must not be NULL for a CONNECT-role endpoint.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM for a bad argument; SAPI_STATUS_TIMEOUT if any configured endpoint fails to establish within its connect_timeout_ms (every endpoint opened so far is closed again before returning - all-or-nothing); SAPI_STATUS_NOT_INITIALIZED if no sapi_netlink backend is registered.

Definition at line 208 of file sapi_safechannel.c.

sapi_safechannel_send()

sapi_status_t sapi_safechannel_send	(	sapi_safechannel_t *	channel,
		const uint8_t *	payload,
		size_t	payload_size )

Sends payload on the underlying channel - broadcast-with-ACK- wait for DUAL_REDUNDANT (sapi_dual_channel_send()), atomic all-or-nothing broadcast to every registered channel for VITAL_VOTED (sapi_voter_send()).

Parameters

channel	Opened channel. Must not be NULL.
payload	Payload to send. May be NULL only if payload_size is 0.
payload_size	Payload size in bytes; must be <= SAPI_DUAL_CHANNEL_MAX_PAYLOAD (DUAL_REDUNDANT) or the configured message_size (VITAL_VOTED).

Returns

SAPI_STATUS_OK; SAPI_STATUS_TIMEOUT; SAPI_STATUS_INVALID_PARAM; SAPI_STATUS_HARDWARE_FAULT (VITAL_VOTED disagreement/fault) - see sapi_dual_channel_send()/sapi_voter_send() for the exact per-type semantics.

Definition at line 236 of file sapi_safechannel.c.

sapi_safechannel_receive()

sapi_status_t sapi_safechannel_receive	(	sapi_safechannel_t *	channel,
		uint8_t *	out_payload,
		size_t	max_size,
		sapi_duration_ms_t	timeout_ms,
		size_t *	out_size )

Returns the most recent inbound payload, actively polling the underlying channel if nothing was already staged.

Parameters

channel	Opened channel. Must not be NULL.
out_payload	Destination buffer. Must not be NULL.
max_size	Usable size of out_payload; must be > 0.
timeout_ms	Maximum time to actively poll if nothing was already staged; 0 = check only what is already staged.
out_size	Receives the actual payload size. Must not be NULL.

Returns

SAPI_STATUS_OK; SAPI_STATUS_TIMEOUT if nothing arrived in time; SAPI_STATUS_INVALID_PARAM for a bad argument or an already-staged frame larger than max_size.

Definition at line 254 of file sapi_safechannel.c.

sapi_safechannel_get_status()

sapi_safechannel_link_status_t sapi_safechannel_get_status

(

const sapi_safechannel_t *

channel

)

Aggregate status across every configured endpoint - DOWN before the first send/receive.

Parameters

channel

Channel to query. May be NULL (returns DOWN, defensive default).

Returns

The current aggregate status.

Definition at line 283 of file sapi_safechannel.c.

sapi_safechannel_close()

sapi_status_t sapi_safechannel_close

(

sapi_safechannel_t *

channel

)

Closes every endpoint this instance opened and releases the wrapped channel. Safe to call on an already-closed/never-opened instance (no-op).

Parameters

channel

Channel to close. May be NULL (no-op).

Returns

SAPI_STATUS_OK.

Definition at line 320 of file sapi_safechannel.c.