udp.h File Reference

Layer 4 (Transport) - connectionless UDP datagram service. More...

#include "ServerConfig.h"
#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Typedefs
typedef void(*	DetUdpHandler) (const uint8_t *data, size_t len, struct DetUdpPeer *peer, void *ctx)
	Datagram handler invoked for each received UDP packet.

Functions
bool	det_udp_listen (uint16_t port, DetUdpHandler handler, void *ctx)
	Bind a UDP port and route incoming datagrams to handler.
bool	det_udp_send (struct DetUdpPeer *peer, const uint8_t *data, size_t len)
	Send a datagram back to the peer captured during the handler call.
bool	det_udp_sendto (const char *dst_ip, uint16_t dst_port, const uint8_t *data, size_t len)
	Send a UDP datagram to an arbitrary destination (outbound client).
bool	det_udp_peer_addr (const struct DetUdpPeer *peer, char *ip_out, size_t ip_cap, uint16_t *port_out)
	Copy a received peer's source IPv4 address (dotted-quad) and port out.
bool	det_udp_listener_sendto (uint16_t listen_port, const char *dst_ip, uint16_t dst_port, const uint8_t *data, size_t len)
	Send a datagram from the listener bound on listen_port to an address.

Detailed Description

Layer 4 (Transport) - connectionless UDP datagram service.

The transport layer's UDP counterpart to the TCP connection pool (see tcp.h / listener.h). It owns all lwIP UDP plumbing (udp_pcb, pbuf); higher layers (application services such as SNMP and the captive portal's DNS responder) bind a port and exchange datagrams through this API without ever touching lwIP. This keeps the OSI layering honest: transport concerns stay in the transport layer.

Datagram delivery is callback-driven from the lwIP thread (no per-loop polling). The handler receives a contiguous payload and an opaque peer token valid only for the duration of the call; reply synchronously with det_udp_send(). On non-Arduino (host) builds the functions are no-op stubs so the services that use them stay host-compilable.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file udp.h.

Typedef Documentation

DetUdpHandler

typedef void(* DetUdpHandler) (const uint8_t *data, size_t len, struct DetUdpPeer *peer, void *ctx)

Datagram handler invoked for each received UDP packet.

Parameters

data	contiguous datagram payload (transport-owned scratch).
len	payload length in bytes.
peer	reply token (valid only during this call).
ctx	the opaque context passed to det_udp_listen().

Definition at line 49 of file udp.h.

Function Documentation

det_udp_listen()

bool det_udp_listen	(	uint16_t	port,
		DetUdpHandler	handler,
		void *	ctx
	)

Bind a UDP port and route incoming datagrams to handler.

Parameters

port	UDP port to bind (e.g. 161 for SNMP, 53 for captive DNS).
handler	callback for each datagram.
ctx	opaque pointer forwarded to handler.

Returns

true on success; false if no listener slot is free, the bind fails, or UDP is unavailable (host builds). ESP32 only; a host build returns false.

Definition at line 151 of file udp.cpp.

References DetUdpCall::base, UdpListener::ctx, DETWS_MAX_UDP_LISTENERS, UdpListener::handler, UdpCtx::listeners, DetUdpCall::op, UdpListener::pcb, DetUdpCall::port, DetUdpCall::result, DetUdpCall::slot, UDP_OP_LISTEN, and UdpListener::used.

det_udp_send()

bool det_udp_send	(	struct DetUdpPeer *	peer,
		const uint8_t *	data,
		size_t	len
	)

Send a datagram back to the peer captured during the handler call.

Parameters

peer	the token handed to the DetUdpHandler.
data	payload bytes.
len	payload length.

Returns

true if the datagram was queued for transmission.

Definition at line 178 of file udp.cpp.

References DetUdpPeer::addr, DetUdpCall::addr, DetUdpCall::base, DetUdpCall::data, UdpCtx::in_tcpip_thread, DetUdpCall::len, DetUdpCall::op, DetUdpPeer::pcb, DetUdpCall::pcb, DetUdpPeer::port, DetUdpCall::port, DetUdpCall::result, and UDP_OP_SEND.

det_udp_sendto()

bool det_udp_sendto	(	const char *	dst_ip,
		uint16_t	dst_port,
		const uint8_t *	data,
		size_t	len
	)

Send a UDP datagram to an arbitrary destination (outbound client).

Unlike det_udp_send() - which replies to the peer of a received datagram - this sends to a host given as a dotted-quad IPv4 string and port, using a single shared outbound PCB. Fire-and-forget; for clients such as the syslog sender. ESP32 only; a host build returns false.

Parameters

dst_ip	destination IPv4 address (e.g. "192.168.1.10").
dst_port	destination UDP port.
data	payload bytes.
len	payload length.

Returns

true if the datagram was queued; false on a bad address, allocation failure, or a host build.

Definition at line 196 of file udp.cpp.

References DetUdpCall::addr, DetUdpCall::base, DetUdpCall::data, UdpCtx::in_tcpip_thread, DetUdpCall::len, DetUdpCall::op, UdpCtx::out, DetUdpCall::port, DetUdpCall::result, and UDP_OP_SEND_OUT.

det_udp_peer_addr()

bool det_udp_peer_addr	(	const struct DetUdpPeer *	peer,
		char *	ip_out,
		size_t	ip_cap,
		uint16_t *	port_out
	)

Copy a received peer's source IPv4 address (dotted-quad) and port out.

The DetUdpPeer token is valid only inside the handler; a service that wants to message the peer later (e.g. CoAP Observe notifications) captures its address here and sends with det_udp_listener_sendto().

Returns

false on a host build or a too-small buffer.

Definition at line 224 of file udp.cpp.

References DetUdpPeer::addr, and DetUdpPeer::port.

det_udp_listener_sendto()

bool det_udp_listener_sendto	(	uint16_t	listen_port,
		const char *	dst_ip,
		uint16_t	dst_port,
		const uint8_t *	data,
		size_t	len
	)

Send a datagram from the listener bound on listen_port to an address.

Unlike det_udp_sendto() (a shared ephemeral source port), this uses the bound listener's PCB, so the datagram's source is listen_port - required when a peer matches replies by the server endpoint (CoAP Observe notifications come from :5683).

Returns

false if no listener is bound on listen_port.

Definition at line 234 of file udp.cpp.

References DetUdpCall::addr, DetUdpCall::base, DetUdpCall::data, DETWS_MAX_UDP_LISTENERS, UdpCtx::in_tcpip_thread, DetUdpCall::len, UdpCtx::listeners, DetUdpCall::op, UdpListener::pcb, DetUdpCall::pcb, DetUdpCall::port, DetUdpCall::result, UDP_OP_SEND, and UdpListener::used.