udp.h

Go to the documentation of this file.

// ProtoCore v1.0.16 - Copyright (C) 2026 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
// SPDX-License-Identifier: AGPL-3.0-or-later
 
/**
 * @file udp.h
 * @brief Layer 4 (Transport), connectionless: the two sides of UDP, joined.
 *
 * One module with two halves. The listener binds a port, receives on it, and answers from it; the
 * client sends from an ephemeral port and receives nothing. They are the same datagram service seen
 * from either end, so they sit together and a caller reaches whichever it needs through @ref Udp
 * rather than knowing two modules.
 *
 * Both halves own their stack plumbing (`udp_pcb`, `pbuf`) and hand out framed rings instead, so no
 * stack type reaches a layer above this one.
 *
 * Every send here takes a `protocore_ip`, never a name or its text. A caller that starts from either turns
 * it into an address once, where it enters, and keeps that: resolving a name or parsing a string
 * per datagram puts that work on the send path of every call.
 *
 * Each half is reached through its own handle: ::UdpListener and ::UdpClient. The halves are pointers
 * rather than values because a table in one translation unit is not a constant expression in
 * another, so a by-value member could not be initialized from here.
 *
 * @author  Douglas Quigg (dstroy0)
 * @date    2026
 */
 
#ifndef PROTOCORE_UDP_H
#define PROTOCORE_UDP_H
 
#include "protocore_config.h" // the entry point: the enable gate below, and the widths
 
#if PROTOCORE_ENABLE_UDP
 
#include "network_drivers/transport/udp/client/client.h" // UdpClientNs: the sending half
#include "network_drivers/transport/udp/server/server.h" // UdpListenerNs: the receiving half
 
PROTOCORE_BEGIN_DECLS
 
/**
 * @brief The datagram service.
 *
 * @var UdpNs::listener  bound ports: receiving, replying, and sending from the bound endpoint
 * @var UdpNs::client    an ephemeral source port: sending only
 */
typedef struct
{
    UdpListenerNs *const listener;
    UdpClientNs *const client;
} UdpNs;
 
/** @brief The one symbol this module exports. */
extern UdpNs Udp;
 
PROTOCORE_END_DECLS
 
#endif // PROTOCORE_ENABLE_UDP
 
#endif // PROTOCORE_UDP_H