ip.h File Reference

Layer 3 (Network) - a family-tagged IP address (IPv4 or IPv6) with RFC-faithful text parsing, canonical formatting, and scope classification. More...

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

Go to the source code of this file.

Classes
struct	DetIp
	A v4 or v6 address in network (big-endian) byte order. More...

Macros
#define	DET_IP_STR_MAX   46
	Longest text an det_ip_format can produce, including the NUL (RFC 5952 v4-mapped).

Enumerations
enum class	DetIpFamily : uint8_t { DET_IP_NONE = 0 , DET_IP_V4 = 4 , DET_IP_V6 = 6 }
	Address family tag. More...
enum class	DetIpScope : uint8_t {   DET_IP_SCOPE_UNSPECIFIED = 0 , DET_IP_SCOPE_LOOPBACK , DET_IP_SCOPE_LINK_LOCAL , DET_IP_SCOPE_PRIVATE ,   DET_IP_SCOPE_MULTICAST , DET_IP_SCOPE_GLOBAL }
	Address scope, in rough order of reachability (used for allow/deny policy + logging). More...

Functions
bool	det_ip_parse (const char *s, DetIp *out)
	Parse an IPv4 or IPv6 textual address (RFC 4291 §2.2) into out.
size_t	det_ip_format (const DetIp *ip, char *out, size_t cap)
	Format ip into out as its RFC 5952 canonical text.
DetIpScope	det_ip_classify (const DetIp *ip)
	Classify ip into a DetIpScope.
bool	det_ip_equal (const DetIp *a, const DetIp *b)
	True if a and b are the same family and address.
bool	det_ip_is_v4_mapped (const DetIp *ip)
	True if ip is an IPv4-mapped IPv6 address (::ffff:a.b.c.d, RFC 4291 §2.5.5.2).
DetIp	det_ip_from_v4_octets (uint8_t a, uint8_t b, uint8_t c, uint8_t d)
	Build a v4 DetIp from four octets (a.b.c.d).
DetIp	det_ip_from_v6_bytes (const uint8_t bytes[16])
	Build a v6 DetIp from 16 address bytes in network (big-endian) order.
uint32_t	det_ip_to_v4_be (const DetIp *ip)
	The v4 address as a big-endian (network-order) uint32 (a<<24 | b<<16 | c<<8 | d).
bool	det_ip_is_unspecified (const DetIp *ip)
	True if ip is empty (DetIpFamily::DET_IP_NONE) or the all-zero unspecified address (0.0.0.0 / ::).
bool	det_ip_prefix_match (const DetIp *addr, const DetIp *net, uint8_t prefix_len)
	CIDR containment: is addr inside the net / prefix_len block?

Detailed Description

Layer 3 (Network) - a family-tagged IP address (IPv4 or IPv6) with RFC-faithful text parsing, canonical formatting, and scope classification.

One representation for both address families so the rest of the stack can carry a peer address without caring whether it is v4 or v6. The address bytes are stored in network (big-endian, left-to-right) order: a v4 address uses bytes[0..3], a v6 address bytes[0..15].

Pure and host-testable - no lwIP, no Arduino, no heap, no stdlib parsing. The parser implements RFC 4291 §2.2 text forms (dotted-quad v4; v6 with :: zero-compression and the embedded-v4 ::ffff:a.b.c.d tail); the formatter emits the RFC 5952 canonical form (lower-case, no leading zeros, the longest zero run compressed to ::, v4-mapped shown as dotted). ESP32 dual-stack bring-up (enabling IPv6 on the netif) lives in the physical layer behind DETWS_ENABLE_IPV6; the TCP/UDP listeners already bind IPADDR_TYPE_ANY, so the server accepts v6 connections the moment the interface has a v6 address.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file ip.h.

Macro Definition Documentation

DET_IP_STR_MAX

#define DET_IP_STR_MAX   46

Longest text an det_ip_format can produce, including the NUL (RFC 5952 v4-mapped).

Definition at line 58 of file ip.h.

Enumeration Type Documentation

DetIpFamily

enum class DetIpFamily : uint8_t

strong

Address family tag.

Enumerator
DET_IP_NONE	empty / unparsed
DET_IP_V4	IPv4 (bytes[0..3])
DET_IP_V6	IPv6 (bytes[0..15])

Definition at line 32 of file ip.h.

DetIpScope

enum class DetIpScope : uint8_t

strong

Address scope, in rough order of reachability (used for allow/deny policy + logging).

Enumerator
DET_IP_SCOPE_UNSPECIFIED	0.0.0.0 / ::
DET_IP_SCOPE_LOOPBACK	127.0.0.0/8 / ::1
DET_IP_SCOPE_LINK_LOCAL	169.254.0.0/16 / fe80::/10
DET_IP_SCOPE_PRIVATE	RFC1918 (10/8, 172.16/12, 192.168/16) / ULA fc00::/7.
DET_IP_SCOPE_MULTICAST	224.0.0.0/4 / ff00::/8
DET_IP_SCOPE_GLOBAL	globally routable unicast

Definition at line 40 of file ip.h.

Function Documentation

det_ip_parse()

bool det_ip_parse	(	const char *	s,
		DetIp *	out
	)

Parse an IPv4 or IPv6 textual address (RFC 4291 §2.2) into out.

Returns

true on success (out->family set to DetIpFamily::DET_IP_V4/V6), false if s is malformed.

Definition at line 350 of file ip.cpp.

References DetIp::bytes, DET_IP_V4, DET_IP_V6, and DetIp::family.

Referenced by listener_ip_allow_add_cidr().

det_ip_format()

size_t det_ip_format	(	const DetIp *	ip,
		char *	out,
		size_t	cap
	)

Format ip into out as its RFC 5952 canonical text.

Returns

the length written (excluding the NUL), or 0 if ip is empty or cap is too small (need up to DET_IP_STR_MAX).

Definition at line 388 of file ip.cpp.

References DetIp::bytes, det_ip_is_v4_mapped(), DET_IP_STR_MAX, DET_IP_V4, DET_IP_V6, and DetIp::family.

det_ip_classify()

DetIpScope det_ip_classify

(

const DetIp *

ip

)

Classify ip into a DetIpScope.

Definition at line 448 of file ip.cpp.

References DetIp::bytes, DET_IP_SCOPE_UNSPECIFIED, DET_IP_V4, DET_IP_V6, and DetIp::family.

det_ip_equal()

bool det_ip_equal	(	const DetIp *	a,
		const DetIp *	b
	)

True if a and b are the same family and address.

Definition at line 459 of file ip.cpp.

References DetIp::bytes, DET_IP_V4, DET_IP_V6, and DetIp::family.

Referenced by listener_accept_allowed_ip().

det_ip_is_v4_mapped()

bool det_ip_is_v4_mapped

(

const DetIp *

ip

)

True if ip is an IPv4-mapped IPv6 address (::ffff:a.b.c.d, RFC 4291 §2.5.5.2).

Definition at line 443 of file ip.cpp.

References DetIp::bytes, DET_IP_V6, and DetIp::family.

Referenced by det_ip_format(), and det_ip_to_v4_be().

det_ip_from_v4_octets()

DetIp det_ip_from_v4_octets	(	uint8_t	a,
		uint8_t	b,
		uint8_t	c,
		uint8_t	d
	)

Build a v4 DetIp from four octets (a.b.c.d).

Definition at line 473 of file ip.cpp.

References DetIp::bytes, DET_IP_V4, and DetIp::family.

Referenced by det_lwip_to_detip().

det_ip_from_v6_bytes()

DetIp det_ip_from_v6_bytes

(

const uint8_t

bytes[16]

)

Build a v6 DetIp from 16 address bytes in network (big-endian) order.

Definition at line 485 of file ip.cpp.

References DetIp::bytes, DET_IP_V6, and DetIp::family.

Referenced by det_lwip_to_detip().

det_ip_to_v4_be()

uint32_t det_ip_to_v4_be

(

const DetIp *

ip

)

The v4 address as a big-endian (network-order) uint32 (a<<24 | b<<16 | c<<8 | d).

Returns

0 if ip is not a v4 (or v4-mapped) address.

Definition at line 493 of file ip.cpp.

References DetIp::bytes, det_ip_is_v4_mapped(), DET_IP_V4, and DetIp::family.

det_ip_is_unspecified()

bool det_ip_is_unspecified

(

const DetIp *

ip

)

True if ip is empty (DetIpFamily::DET_IP_NONE) or the all-zero unspecified address (0.0.0.0 / ::).

Definition at line 505 of file ip.cpp.

References DetIp::bytes, DET_IP_NONE, DET_IP_V4, and DetIp::family.

Referenced by listener_accept_allowed_ip().

det_ip_prefix_match()

bool det_ip_prefix_match	(	const DetIp *	addr,
		const DetIp *	net,
		uint8_t	prefix_len
	)

CIDR containment: is addr inside the net / prefix_len block?

The two must be the same family. prefix_len is 0..32 for v4, 0..128 for v6; the top prefix_len bits of the address bytes must match net (a prefix of 0 matches everything). This is the standard v4/v6 allowlist match.

Returns

true if addr is covered; false on a family mismatch or an out-of-range prefix.

Definition at line 516 of file ip.cpp.

References DetIp::bytes, DET_IP_V4, DET_IP_V6, and DetIp::family.

Referenced by listener_ip_allowed().