Point-to-Point Network Link

Connection-oriented link between independent processes (ADR-001). More...

Files
file	src/oal/netlink/sapi_netlink.c
	Network link service: validates parameters, then dispatches to the backend registered via sapi_netlink_register_backend() (ADR-005). See sapi_ipc.c for the pattern this follows.

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

Connection-oriented link between independent processes (ADR-001).

Typedef Documentation

sapi_netlink_handle_t

typedef struct sapi_netlink_impl_s* sapi_netlink_handle_t

Opaque handle to an established link, returned by sapi_netlink_open().

Definition at line 55 of file sapi_netlink.h.

Enumeration Type Documentation

sapi_netlink_role_t

enum sapi_netlink_role_t

Which side of the connection this link instance plays.

A TCP-style backend needs exactly one LISTEN side (binds, accepts one peer) and one CONNECT side (dials the listener) per link; which role a given process/role/site plays is an application-level decision (e.g. "site West listens, site East connects"), not something this service decides on its own.

Enumerator
SAPI_NETLINK_ROLE_LISTEN	Bind config->port and accept one peer.
SAPI_NETLINK_ROLE_CONNECT	Dial config->host:config->port.

Definition at line 66 of file sapi_netlink.h.

Function Documentation

sapi_netlink_open()

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.

Parameters

storage	Caller-owned storage for the handle's state. Must not be NULL.
config	Link configuration. Must not be NULL; config->message_size must be > 0; config->host must not be NULL for CONNECT.
out_handle	Receives the established link's handle. Must not be NULL.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM for a bad argument; SAPI_STATUS_TIMEOUT if the link is not established within config->connect_timeout_ms; SAPI_STATUS_NOT_INITIALIZED if no backend is registered (sapi_netlink_register_backend()); SAPI_STATUS_NOT_SUPPORTED if the registered backend does not implement open. REQ-OAL-NETLINK-010

Definition at line 45 of file sapi_netlink.c.

sapi_netlink_send()

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.

Parameters

handle	Link handle. Must not be NULL.
message	Message data to send. Must not be NULL.
message_size	Size of message in bytes; must be > 0.
timeout_ms	Maximum time to wait for the send to complete.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM; SAPI_STATUS_TIMEOUT if the send does not complete in time; SAPI_STATUS_HARDWARE_FAULT if the backend can positively confirm the peer is gone (e.g. a TCP disconnect, or an unreliable-transport backend's own best-effort signal - not guaranteed on every backend, see REQ-OAL-NETLINK-014); SAPI_STATUS_NOT_INITIALIZED/ SAPI_STATUS_NOT_SUPPORTED as in sapi_netlink_open(). REQ-OAL-NETLINK-011

Definition at line 73 of file sapi_netlink.c.

sapi_netlink_receive()

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.

Parameters

handle	Link handle. Must not be NULL.
out_message	Destination buffer. Must not be NULL.
buffer_size	Usable size of out_message in bytes; must be > 0.
timeout_ms	Maximum time to wait for a message to arrive.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM; SAPI_STATUS_TIMEOUT if no message arrives in time; SAPI_STATUS_HARDWARE_FAULT per sapi_netlink_send()'s own note above; SAPI_STATUS_DATA_CORRUPTION if a backend can detect the received message violated this link's wire contract (e.g. wrong length) but not necessarily its content (content integrity, if needed, is the caller's job - see REQ-OAL-NETLINK-014); SAPI_STATUS_NOT_INITIALIZED/ SAPI_STATUS_NOT_SUPPORTED as in sapi_netlink_open(). REQ-OAL-NETLINK-012

Definition at line 93 of file sapi_netlink.c.

sapi_netlink_close()

sapi_status_t sapi_netlink_close

(

sapi_netlink_handle_t

handle

)

Closes a link.

Parameters

handle

Handle to close. Must not be NULL. Invalid to use after this call.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM; SAPI_STATUS_NOT_INITIALIZED/ SAPI_STATUS_NOT_SUPPORTED as in sapi_netlink_open(). REQ-OAL-NETLINK-013

Definition at line 113 of file sapi_netlink.c.