sapi_safechannel.h File Reference

Unified, transport-hiding channel factory (ADR-022). More...

#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
#include "safeapi/redundancy/dual/sapi_dual_channel.h"
#include "safeapi/oal/netlink/sapi_netlink.h"
#include "safeapi/utils/status/sapi_status.h"
#include "safeapi/utils/types/sapi_types.h"
#include "safeapi/redundancy/channel_link/sapi_channel.h"
#include "safeapi/redundancy/voter/sapi_voter.h"

Include dependency graph for sapi_safechannel.h:

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

Go to the source code of this file.

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

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

Unified, transport-hiding channel factory (ADR-022).

The single entry point an application uses to open a communication channel: pick a sapi_safechannel_type_t, describe the remote endpoint(s) as host/port/role, and get back one handle with uniform open/send/receive/close/status operations - regardless of whether it is backed by a redundant-link sapi_dual_channel_t or a voting sapi_voter_t (over N sapi_channel_t links, ADR-025) underneath.

This header never requires the caller to include safeapi/netlink/sapi_netlink.h or safeapi/ipc/sapi_ipc.h, or to call sapi_netlink_open()/sapi_ipc_create() itself: sapi_safechannel_open() opens every configured endpoint internally via the already-registered sapi_netlink backend (ADR-005). Direct use of sapi_netlink/sapi_ipc is a backend-and-channel-layer-only concern from here on (ADR-022 section 2.3) - an application should not need those headers at all.

REQ-SAFECHANNEL-001: sapi_safechannel_open() shall open every configured endpoint itself; the caller shall never need to call sapi_netlink_open() or hold a sapi_netlink_handle_t. REQ-SAFECHANNEL-002: no dynamic allocation; all storage is caller-owned and fixed-size. REQ-SAFECHANNEL-003: sapi_safechannel_send()/_receive() behave identically to the caller regardless of config.type (uniform facade over sapi_dual_channel_t / sapi_channel_t).

Definition in file sapi_safechannel.h.