sapi_netlink.h File Reference

OS Abstraction Layer - Point-to-point network link service. More...

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

Include dependency graph for sapi_netlink.h:

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

Go to the source code of this file.

Data Structures
struct	sapi_netlink_config_t
	Configuration for sapi_netlink_open(). More...

Typedefs
typedef struct sapi_netlink_impl_s *	sapi_netlink_handle_t
	Opaque handle to an established link, returned by sapi_netlink_open().

Enumerations
enum	sapi_netlink_role_t { SAPI_NETLINK_ROLE_LISTEN = 0 , SAPI_NETLINK_ROLE_CONNECT = 1 }
	Which side of the connection this link instance plays. More...

Functions
	SAFEAPI_DECLARE_STORAGE (sapi_netlink_storage_t, 64U)
	Caller-owned, fixed-size storage backing one sapi_netlink_handle_t.
sapi_status_t	sapi_netlink_open (sapi_netlink_storage_t *storage, const sapi_netlink_config_t *config, sapi_netlink_handle_t *out_handle)
	Establishes a point-to-point link: binds+accepts (LISTEN) or dials (CONNECT), per config->role.
sapi_status_t	sapi_netlink_send (sapi_netlink_handle_t handle, const void *message, size_t message_size, sapi_duration_ms_t timeout_ms)
	Sends one fixed-size message, blocking at most timeout_ms.
sapi_status_t	sapi_netlink_receive (sapi_netlink_handle_t handle, void *out_message, size_t buffer_size, sapi_duration_ms_t timeout_ms)
	Receives one fixed-size message, blocking at most timeout_ms.
sapi_status_t	sapi_netlink_close (sapi_netlink_handle_t handle)
	Closes a link.

Detailed Description

OS Abstraction Layer - Point-to-point network link service.

A sibling to sapi_ipc (ADR-001 section 4, service 5), not a replacement: sapi_ipc models a bounded local queue between two ends that already exist (e.g. a pipe created by one process for two of its own threads/tasks). sapi_netlink models a connection-oriented link between two independent processes - possibly on separate machines - that must first find each other (one side listens, the other connects) before any data can flow. Distinct connection-establishment semantics is why this is a new service instead of new fields bolted onto sapi_ipc_config_t (ADR-005's backend-agnostic config principle: a config struct should not carry fields that are meaningless for most backends of that service).

Framework ships the interface and validate-then-dispatch layer only; a concrete backend (e.g. POSIX TCP sockets) is integrator-supplied (ADR-005) and lives with the application that registers it - see safeAPIRBC2oo2's src/posix_backend/sapi_posix_backend_netlink.c for the reference POSIX/TCP implementation this header was designed alongside.

REQ-OAL-NETLINK-001: no dynamic allocation; caller supplies storage. REQ-OAL-NETLINK-002: sapi_netlink_open() shall never block longer than config->connect_timeout_ms. REQ-OAL-NETLINK-003: send/receive shall accept an explicit timeout and shall never block indefinitely by default. REQ-OAL-NETLINK-014: this service provides no message ordering, deduplication, or delivery guarantee of its own - a backend may be built on an unreliable transport (e.g. UDP). Any such guarantee is the caller's responsibility (see safeAPIFreamwork's sapi_dual_msgchannel/sapi_dual_channel for a reusable sequence+CRC+ACK layer, and ADR-027).

Definition in file sapi_netlink.h.