udp_api.h File Reference

Freestanding C11 interface for the UDP socket module (udp-threads example). More...

#include <stdint.h>
#include <stdbool.h>
#include "juno/status.h"
#include "juno/module.h"
#include "juno/types.h"

Include dependency graph for udp_api.h:

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

Go to the source code of this file.

Data Structures
struct	UDP_THREAD_MSG_TAG
	Fixed-size UDP datagram message transferred between sender and receiver. More...
struct	JUNO_UDP_CFG_TAG
	Configuration passed to JunoUdp_LinuxInit to open and configure a UDP socket. More...
struct	JUNO_UDP_API_TAG
	Vtable defining the UDP socket module interface. More...

Typedefs
typedef struct JUNO_UDP_API_TAG	JUNO_UDP_API_T
	Forward declaration of the UDP vtable (API) type.
typedef struct JUNO_UDP_ROOT_TAG	JUNO_UDP_ROOT_T
	Forward declaration of the UDP module root type.
typedef struct JUNO_UDP_LINUX_TAG	JUNO_UDP_LINUX_T
	Forward declaration of the Linux derivation type.
typedef union JUNO_UDP_TAG	JUNO_UDP_T
	Forward declaration of the UDP module union type.
typedef struct UDP_THREAD_MSG_TAG	UDP_THREAD_MSG_T
	Fixed-size UDP datagram message transferred between sender and receiver.
typedef struct JUNO_UDP_CFG_TAG	JUNO_UDP_CFG_T
	Configuration passed to JunoUdp_LinuxInit to open and configure a UDP socket.

Functions
struct JUNO_UDP_ROOT_TAG	JUNO_MODULE_ROOT (JUNO_UDP_API_T, JUNO_MODULE_EMPTY)
	UDP module root; the primary instance type used throughout the API.
JUNO_STATUS_T	JunoUdp_Init (JUNO_UDP_ROOT_T *ptRoot, const JUNO_UDP_API_T *ptApi, JUNO_FAILURE_HANDLER_T pfcnFailureHandler, void *pvFailureUserData)
	Type-safe polymorphic handle for a UDP module instance.

Detailed Description

Freestanding C11 interface for the UDP socket module (udp-threads example).

This header defines the freestanding-compatible public interface for the UDP socket module used by the udp-threads example. It follows the LibJuno vtable/dependency-injection module pattern:

• Interface layer (this header): no POSIX or OS-specific includes; may be compiled with -nostdlib -ffreestanding.
• Platform layer (udp_linux.h / linux_udp_impl.cpp): the only translation unit that includes POSIX socket headers. It provides g_junoUdpLinuxApi and JunoUdp_LinuxInit.

All memory is caller-owned and injected. The module allocates nothing.

Typical usage (Linux):

#include "udp_linux.h"
 
static JUNO_UDP_T tUdp = {0};
 
JUNO_UDP_CFG_T tCfg = { "127.0.0.1", 5000, false };
JunoUdp_LinuxInit(&tUdp, &tCfg, NULL, NULL);  // wires vtable + opens socket
 
UDP_THREAD_MSG_T tMsg = {0};
tUdp.tRoot.ptApi->Send(&tUdp.tRoot, &tMsg);
tUdp.tRoot.ptApi->Free(&tUdp.tRoot);           // closes socket

Typedef Documentation

JUNO_UDP_API_T

typedef struct JUNO_UDP_API_TAG JUNO_UDP_API_T

Forward declaration of the UDP vtable (API) type.

JUNO_UDP_CFG_T

typedef struct JUNO_UDP_CFG_TAG JUNO_UDP_CFG_T

Configuration passed to JunoUdp_LinuxInit to open and configure a UDP socket.

The caller allocates this struct; it need only remain valid for the duration of the JunoUdp_LinuxInit call. No pointer from this struct is retained by the module after the call returns.

The bIsReceiver field selects the socket role:

• true — implementation calls bind() for incoming datagrams (receiver).
• false — implementation calls connect() to associate with the remote address and port (sender).

JUNO_UDP_LINUX_T

typedef struct JUNO_UDP_LINUX_TAG JUNO_UDP_LINUX_T

Forward declaration of the Linux derivation type.

JUNO_UDP_ROOT_T

typedef struct JUNO_UDP_ROOT_TAG JUNO_UDP_ROOT_T

Forward declaration of the UDP module root type.

JUNO_UDP_T

typedef union JUNO_UDP_TAG JUNO_UDP_T

Forward declaration of the UDP module union type.

The complete definition requires JUNO_UDP_LINUX_T to be complete (POSIX types). Include udp_linux.h to obtain the full definition.

UDP_THREAD_MSG_T

typedef struct UDP_THREAD_MSG_TAG UDP_THREAD_MSG_T

Fixed-size UDP datagram message transferred between sender and receiver.

Every Send and Receive call transfers exactly one UDP_THREAD_MSG_T as an atomic datagram (sizeof(UDP_THREAD_MSG_T) = 76 bytes). The fixed, compile-time-known size ensures datagrams are never truncated and no partial reads or writes are possible at the message boundary.

The arr prefix on arrPayload denotes a fixed-size static array field (an extension to the project Hungarian notation convention).

Function Documentation

JUNO_MODULE_ROOT()

struct JUNO_UDP_ROOT_TAG JUNO_MODULE_ROOT	(	JUNO_UDP_API_T	,
		JUNO_MODULE_EMPTY
	)

UDP module root; the primary instance type used throughout the API.

Defined via JUNO_MODULE_ROOT with JUNO_MODULE_EMPTY — the root carries no OS-specific fields. Platform-specific state (socket fd, address) lives exclusively in the derivation (JUNO_UDP_LINUX_T in udp_linux.h).

JUNO_MODULE_ROOT injects three mandatory members:

• ptApi — vtable pointer wired by the platform init function.
• _pfcnFailureHandler — diagnostic callback; invoked before any error return.
• _pvFailureUserData — opaque pointer passed to the failure handler.

The caller allocates (stack or static) the enclosing JUNO_UDP_T union and owns its storage. Its lifetime must exceed that of all API calls made on it.

JunoUdp_Init()

JUNO_STATUS_T JunoUdp_Init	(	JUNO_UDP_ROOT_T *	ptRoot,
		const JUNO_UDP_API_T *	ptApi,
		JUNO_FAILURE_HANDLER_T	pfcnFailureHandler,
		void *	pvFailureUserData
	)

Type-safe polymorphic handle for a UDP module instance.

The complete union definition (which embeds JUNO_UDP_LINUX_T) is provided in udp_linux.h, where the POSIX derivation type is complete. Freestanding translation units that only hold a JUNO_UDP_ROOT_T * need not include udp_linux.h; only the composition root and platform TUs that allocate a JUNO_UDP_T instance need the full definition.

#include "udp_linux.h"
static JUNO_UDP_T tUdp = {0};
JunoUdp_LinuxInit(&tUdp, &tCfg, NULL, NULL);
tUdp.tRoot.ptApi->Send(&tUdp.tRoot, &tMsg);
tUdp.tRoot.ptApi->Free(&tUdp.tRoot);

Initialise a UDP module root with a concrete vtable and failure handler.

Wires ptApi into ptRoot->ptApi and stores the failure handler and user data. Does NOT open any OS resource (use the platform init function for that). Must be called before any vtable operation when using a custom vtable (e.g., a test double). Platform callers should prefer JunoUdp_LinuxInit (declared in udp_linux.h), which calls this internally then opens the socket.

Initialisation sequence:

1. Guard ptRoot (returns JUNO_STATUS_NULLPTR_ERROR if NULL).
2. Guard ptApi (returns JUNO_STATUS_NULLPTR_ERROR if NULL).
3. Wire vtable, failure handler, user data.
4. Return JUNO_STATUS_SUCCESS.

Parameters

ptRoot	Caller-owned root storage; must be non-NULL.
ptApi	Vtable (Linux implementation or test double); must be non-NULL.
pfcnFailureHandler	Diagnostic callback invoked before any error return; may be NULL.
pvFailureUserData	Opaque user data pointer threaded to the failure handler; may be NULL.

Returns

JUNO_STATUS_SUCCESS on success; JUNO_STATUS_NULLPTR_ERROR if any required pointer is NULL.

Type-safe polymorphic handle for a UDP module instance.

Wires ptApi into ptRoot->ptApi and stores the optional failure handler and user data. Must be called before any vtable operation on the root. Platform-specific socket state (fd, address) is owned by the derivation (JUNO_UDP_LINUX_T) and initialised in JunoUdp_LinuxInit.

Parameters

ptRoot	Caller-owned root storage; must be non-NULL.
ptApi	Vtable (Linux implementation or test double); must be non-NULL.
pfcnFailureHandler	Diagnostic callback invoked before any error return; may be NULL.
pvFailureUserData	Opaque user data pointer threaded to the failure handler; may be NULL.

Returns

JUNO_STATUS_SUCCESS on success; JUNO_STATUS_NULLPTR_ERROR if ptRoot or ptApi is NULL.