Core IP layer definitions, structures, and functions for IPv4/IPv6 networking. More...

Topics
	IPADDR4 Class

	IPADDR6 Class

Classes
struct	_IpHeaderIPv4
	IP Header Structure (IPv4) More...

struct	IPPKT
	Internal IPv4 Header Representation. More...

struct	UDPPKT
	Internal UDP Packet Header Structure. More...

struct	PsudeoHeader
	UDP/TCP IPv4 Pseudo-header Structure (bits 0 through 95 of the pseudo-header) More...

Macros
#define	ICMP_PING_DATA_SIZE (32)
	Default data payload size for ICMP echo request and reply packets (32 bytes)

Typedefs
typedef struct _IpHeaderIPv4	IpHeaderIPv4
	IP Header Structure (IPv4)

typedef void	FragmentProcessFunction(PoolPtr pp)
	User-defined function pointer type for processing fragmented IP packets.

typedef void	PromisciousPacketFunc(PoolPtr pp)
	User-defined function pointer type for processing promiscuous packets.

Functions
void	IpProcessEthernetPacket (PoolPtr poolPtr, uint16_t packetSizeInBytes)
	Process an Ethernet packet for IP layer handling.

uint16_t	GetSum (puint16_t addr, uint16_t count)
	Calculate Internet checksum for the specified data.

uint16_t	GetSum20 (puint32_t addr)
	Calculate Internet checksum for exactly 20 bytes of data.

uint16_t	GetSumHdr (PsudeoHeader &hdr, puint16_t addr, uint16_t count)
	Calculate Internet checksum using a pseudo-header.

BOOL	IsMyIp4 (IPADDR4 ip, int ifc=-1)
	Check if the specified IPv4 address belongs to this device.

IPADDR4	GetSrcIp4 (IPADDR4 dst)
	Get the appropriate source IPv4 address for reaching a destination.

IPADDR4	GetSrcIpwIf4 (int ifn, const IPADDR4 dst)
	Get the source IPv4 address for a specific interface and destination.

BOOL	IsMyIp6 (const IPADDR &ip, int ifc=-1)
	Check if the specified IPv6 address belongs to this device.

BOOL	IsMyIp (const IPADDR &ip, int ifc=-1)
	Generic function to check if IP address belongs to this device (uses IPv6 when available)

IPADDR	GetSrcIp6 (const IPADDR &dst)
	Get the appropriate source IPv6 address for reaching a destination.

IPADDR	GetSrcIp (const IPADDR &dst)
	Generic function to get source IP address for reaching a destination (IPv6 version).

IPADDR	GetSrcIp6wIf (int ifn, const IPADDR &dst)
	Get the source IPv6 address for a specific interface and destination.

IPADDR	GetSrcIpwIf (int ifn, const IPADDR &dst)
	Generic function to get source IP address for an interface (IPv6 version).

void	SendICMPError (PoolPtr pBadPacket, uint8_t type, uint8_t code)
	Send an ICMP error message in response to a bad packet.

void	FixHeaderAndSend (PoolPtr p, PIPPKT pIp)
	Complete IP header fields and send packet on primary interface.

void	FixHeaderAndSendViaInterface (PoolPtr p, PIPPKT pIp, int Interface)
	Complete IP header fields and send packet via specified interface.

void	InitializeStack ()
	Initialize the IP protocol stack.

void	ShowIPBuffer (PoolPtr rp)
	Display the contents of a network buffer for diagnostic purposes.

int	Ping4 (IPADDR4 to, uint16_t id, uint16_t seq, uint16_t maxwaitticks)
	Send a "ping" packet and wait the specified timeout for a response.

int	Ping4ViaInterface (IPADDR4 to, uint16_t id, uint16_t seq, uint16_t wait, int interface)
	Send a "ping" packet via a specific network interface and wait for a response.

int	Ping6 (const IPADDR &to, uint16_t id, uint16_t seq, uint16_t maxwaitticks, int size=32)
	Send an IPv6 "ping" packet and wait the specified timeout for a response.

int	Ping6ViaInterface (const IPADDR &to, uint16_t id, uint16_t seq, uint16_t wait, int interface, int size=32)
	Send an IPv6 "ping" packet via a specific network interface.

int	Ping (const IPADDR &to, uint16_t id, uint16_t seq, uint16_t maxwaitticks, int size=32)
	Generic ping function that uses IPv6 when IPv6 is enabled.

int	PingViaInterface (const IPADDR &to, uint16_t id, uint16_t seq, uint16_t wait, int interface, int size=32)
	Generic ping via interface function that uses IPv6 when IPv6 is enabled.

BOOL	IsLocal4 (IPADDR4 ip, int ifc)
	Check if an IPv4 address is on the local network segment.

int	GetProperInterface4 (IPADDR4 dst)
	Get the appropriate interface number for reaching a destination.

int	AddInterface (IPADDR4 addr, IPADDR4 mask, IPADDR4 gateway, int root_if=0)
	Add a new network interface with the specified configuration.

int	GetMultiHomeInterface (IPADDR4 ipa, int norgif)
	Get the multi-home interface for a specific IP address.

int	GetLocalIPInterface4 (IPADDR4 ipa)
	Get the local interface number for a specific IPv4 address.

int	GetLocalIPInterface6 (const IPADDR &ipa)
	Get the local interface number for a specific IPv6 address.

int	GetLocalIPInterface (const IPADDR &ipa)
	Generic function to get local interface for an IP address (IPv6 version).

uint16_t	GetEphemeralPort ()
	Generate a random ephemeral port number.

Variables
FragmentProcessFunction *	pFragFunc
	Global function pointer for fragment processing callback.

PromisciousPacketFunc *	pPromisciousPacketFunc
	Global function pointer for promiscuous packet processing callback.

TaskPacketFunc *	pTaskPacketFunc
	Global function pointer for UDP task packet processing callback.

Global Configuration Variables
These global variables control various IP stack behaviors and can be modified by the application to customize network behavior.
uint8_t	bTTL_Default
	Default Time To Live (hop count) for outgoing IP packets. Typical value is 64 or 128.

uint16_t	wArpLifetime
	ARP cache entry lifetime in seconds. Entries older than this are refreshed. Typical value is 300-1200 seconds.

BOOL	bQuietStart
	When TRUE, suppresses startup messages during network initialization. Set before calling init().

Get Packet Functions
These inline functions provide convenient access to packet structures at various layers of the network stack. They handle the pointer arithmetic needed to locate specific headers within network buffer pool buffers. WARNING: If you use these functions on an uninitialized buffer you will get bogus values for the pointer as the header length field in the IP packet is not yet set up! Always ensure packets are properly initialized before using these accessor functions.
PIPPKT	GetIpPkt (PoolPtr p)
	Get IP packet pointer from network buffer pool buffer.

PIPPKT	GetIpPkt (PEFRAME pFrame)
	Get IP packet pointer from pointer to Ethernet frame.

PIPPKT	GetIpPkt (PVLEFRAME pFrame)
	Get IP packet pointer from pointer to VLAN-tagged Ethernet frame.

PUDPPKT	GetUdpPkt (PIPPKT pIp)
	Get UDP packet pointer from IP packet pointer.

IP Version
Uncomment for debugging IP layer operations
#define	IP_VERSION_MASK (0xF0)
	Mask for extracting IP version from version/header length byte.

#define	IP_VERSION_IPv4 (0x40)
	IPv4 version identifier (value 4 in upper nibble)

#define	IP_VERSION_IPv6 (0x60)
	IPv6 version identifier (value 6 in upper nibble)

Header Length
#define	IP_HEADER_LENGTH_MASK (0x0F)
	Mask for extracting header length from version/header length byte.

#define	IP_HEADER_LENGTH_NO_OPTIONS (0x05)
	Header length value when no IP options present (5 32-bit words = 20 bytes)

Flags and Fragment Offset
#define	IP_FLAGS_MASK (0xE000)
	Mask for extracting IP flags (upper 3 bits of flags/fragment field)

#define	IP_FRAGMENT_OFFSET_MASK (0x1FFF)
	Mask for extracting fragment offset (lower 13 bits of flags/fragment field)

IP Protocol Numbers
These are IANA-assigned protocol numbers that identify the next-level protocol encapsulated in the IP packet.
#define	IP_PROTOCOL_ICMP (0x01)
	Internet Control Message Protocol.

#define	IP_PROTOCOL_IGMP (0x02)
	Internet Group Management Protocol.

#define	IP_PROTOCOL_INTERNET (0x04)
	IP-in-IP encapsulation (deprecated)

#define	IP_PROTOCOL_TCP (0x06)
	Transmission Control Protocol.

#define	IP_PROTOCOL_UDP (0x11)
	User Datagram Protocol (value 17 decimal)

ICMP Message Types and Codes
Internet Control Message Protocol (ICMP) types and codes used for network diagnostics and error reporting. See RFC 792 for details.
#define	ICMP_TYPE_ECHO_REPLY (0)
	Echo Reply message (response to ping)

#define	ICMP_CODE_ECHO_REPLY (0)
	Code for Echo Reply (always 0)

#define	ICMP_TYPE_DEST_UNREACHABLE (3)
	Destination Unreachable error message.

#define	ICMP_CODE_PORT_UNREACHABLE (3)
	Port Unreachable code within Destination Unreachable.

#define	ICMP_TYPE_SOURCE_QUENCH (4)
	Source Quench message (deprecated, for flow control)

#define	ICMP_CODE_SOURCE_QUENCH (0)
	Code for Source Quench (always 0)

#define	ICMP_TYPE_REDIRECT_MESSAGE (5)
	Redirect message (routing optimization)

#define	ICMP_TYPE_ECHO_REQUEST (8)
	Echo Request message (ping)

#define	ICMP_CODE_ECHO_REQUEST (0)
	Code for Echo Request (always 0)

Well-Known Port Numbers
IANA-assigned well-known port numbers for common network services. These ports are reserved for specific protocols and services.
#define	IANA_ECHO_PORT (7)
	Echo protocol port.

#define	IANA_DISCARD_PORT (9)
	Discard protocol port (null service)

#define	IANA_SSH_PORT (22)
	Secure Shell (SSH) protocol port.

#define	IANA_TELNET_PORT (23)
	Telnet protocol port.

#define	IANA_NETBIOS_NAME_SERVICE_PORT (137)
	NetBIOS Name Service port.

Detailed Description

Core IP layer definitions, structures, and functions for IPv4/IPv6 networking.

#include< ip.h>

This module provides comprehensive support for IP networking including:

Packet structure definitions for IP, UDP, and ICMP
Address resolution and routing functions
Ping/ICMP echo request functionality
Packet checksum calculation
Multi-homing and multiple interface support
Promiscuous mode and packet filtering callbacks
Fragment processing support

Typedef Documentation

◆ FragmentProcessFunction

typedef void FragmentProcessFunction(PoolPtr pp)

#include <ip.h>

User-defined function pointer type for processing fragmented IP packets.

This callback function is called only for IP packets that have the fragmentation flag set in the IP header. Applications can implement this function to handle packet fragmentation and reassembly according to their specific requirements.

Typical implementations would:

Store fragments until all pieces arrive
Reassemble complete datagrams
Handle fragment timeout and cleanup
Free the buffer when done processing

Parameters

pp	Packet pointer from network buffer pool containing the fragmented packet

Note: The callback function is responsible for properly handling and freeing the buffer.; This function is only called for packets with fragmentation flags set.; Fragment reassembly is not provided by default - must be implemented by application.

See also: pFragFunc

◆ IpHeaderIPv4

typedef struct _IpHeaderIPv4 IpHeaderIPv4

#include <ip.h>

IP Header Structure (IPv4)

Standard IPv4 packet header as defined in IETF RFC 791 (September 1981) and MIL-STD-1777. This structure represents the 20-byte minimum IP header. IP options, if present, follow this structure and are indicated by a header length value greater than 5.

All multi-byte fields are in network byte order (big-endian) and use the beuint types for automatic endianness handling.

Note: The structure is packed to ensure proper alignment with network packet data.; Standard header is 20 bytes when no options are present (header length = 5).; Maximum header size is 60 bytes (header length = 15) when options are included.

See also: IPPKT for the internal representation used within NetBurner stack

◆ PromisciousPacketFunc

typedef void PromisciousPacketFunc(PoolPtr pp)

#include <ip.h>

User-defined function pointer type for processing promiscuous packets.

This callback function is called for packets that fail the "IP address == my address" test. This enables applications to receive and process packets not specifically addressed to this device, useful for:

Network monitoring and packet capture
Bridge or router implementations
Protocol analyzers
IDS/IPS systems
Custom routing logic

Parameters

pp	Packet pointer from network buffer pool containing the promiscuous packet

Warning: This function MUST free the buffers it receives using FreeBuffer() or equivalent. Failure to free buffers will result in buffer pool exhaustion and network failure.

Note: This callback is only invoked for packets not addressed to this device's IP address.; Ethernet interface must be set to promiscuous mode to receive these packets.

See also: pPromisciousPacketFunc

Function Documentation

◆ AddInterface()

int AddInterface	(	IPADDR4	addr,
		IPADDR4	mask,
		IPADDR4	gateway,
		int	root_if )

inline

#include <ip.h>

Add a new network interface with the specified configuration.

Dynamically adds a new network interface to the system with the specified IP address, subnet mask, gateway, and root interface configuration. This is used in multi-homed systems to configure additional network interfaces at runtime.

Typical uses:

Adding secondary IP addresses to an interface (IP aliasing)
Configuring Auto-IP link-local addresses
Setting up virtual interfaces
Dynamic network reconfiguration

Parameters

addr	IP address for the new interface
mask	Subnet mask for the new interface
gateway	Gateway IP address for the new interface (0.0.0.0 for none)
root_if	Root interface number this interface is associated with (physical interface)

Returns: Interface number of the newly added interface (>=0), or negative value on error

Note: Only available when MULTIHOME or AUTOIP is defined.; Used for dynamic interface configuration in multi-homed systems.; The root_if parameter specifies which physical interface this logical interface uses.

// Add a secondary IP address to interface 0
IPADDR4 secondary = AsciiToIp4("192.168.1.100");
IPADDR4 mask = AsciiToIp4("255.255.255.0");
IPADDR4 gw = AsciiToIp4("192.168.1.1");
int new_if = AddInterface(secondary, mask, gw, 0);
if (new_if >= 0) {
    iprintf("Added interface %d\r\n", new_if);
}

Add a new network interface with the specified configuration.

Parameters

addr	IP address of new interface
mask	IP mask
gateway	IP gateway
root_if	Optional root physical interface number. If not specified the default is 0, for Ethernt 0.

Returns: Interface number of newly created interface

◆ FixHeaderAndSend()

void FixHeaderAndSend	(	PoolPtr	p,
		PIPPKT	pIp )

#include <ip.h>

Complete IP header fields and send packet on primary interface.

Fills in remaining IP header fields (checksum, fragmentation info, etc.) and transmits the packet via the primary network interface. This function handles the final steps of IP packet transmission including:

Calculating and setting the header checksum
Setting the Time To Live (TTL) field if not already set
Handling fragmentation if necessary
Forwarding to the data link layer

Parameters

p	Network buffer pool pointer containing the packet
pIp	Pointer to IP header within the packet

Note: The IP header should be mostly complete before calling this function.; Source and destination addresses must be set before calling.; This function calculates and fills in header checksum and other final fields.

See also: FixHeaderAndSendViaInterface()

◆ FixHeaderAndSendViaInterface()

void FixHeaderAndSendViaInterface	(	PoolPtr	p,
		PIPPKT	pIp,
		int	Interface )

#include <ip.h>

Complete IP header fields and send packet via specified interface.

Similar to FixHeaderAndSend(), but allows specification of which network interface to use for transmission. This is useful in multi-homed systems where you need explicit control over the egress interface.

Parameters

p	Network buffer pool pointer containing the packet
pIp	Pointer to IP header within the packet
Interface	Interface number to use for transmission (0-based)

Note: Allows control over which interface transmits the packet.; Useful for routing and multi-homed configurations.; Interface number must be valid or packet will be dropped.

See also: FixHeaderAndSend()

◆ GetEphemeralPort()

uint16_t GetEphemeralPort ( )

#include <ip.h>

Generate a random ephemeral port number.

Returns a random port number suitable for use as a local port in client connections. The port number is selected from the ephemeral (dynamic) port range and avoids well-known ports (0-1023) and registered ports (1024-49151).

Ephemeral ports are temporary ports used by the client side of a connection. Each call returns a different random port number to avoid conflicts with other active connections.

Returns: Random ephemeral port number (typically in range 49152-65535 per RFC 6335)

Note: Used internally for automatic local port assignment in client connections.; Avoids conflicts with well-known and registered port numbers.; Each call returns a different random port number.; The random selection reduces the likelihood of port exhaustion and security issues.

// Get an ephemeral port for a client connection
uint16_t local_port = GetEphemeralPort();
int fd = connect(server_ip, server_port, local_port, timeout);

◆ GetIpPkt() [1/3]

PIPPKT GetIpPkt ( PEFRAME pFrame )

inline

#include <ip.h>

Get IP packet pointer from pointer to Ethernet frame.

Returns a pointer to the IP header located immediately after the Ethernet header.

Parameters

pFrame Pointer to Ethernet frame structure

Returns: Pointer to IP header within the frame

◆ GetIpPkt() [2/3]

PIPPKT GetIpPkt ( PoolPtr p )

inline

#include <ip.h>

Get IP packet pointer from network buffer pool buffer.

Calculates the location of the IP header within a network buffer by adding the Ethernet header size (14 bytes) to the buffer's data pointer.

Parameters

p	Network buffer pool pointer

Returns: Pointer to IP header, or NULL if p is NULL

◆ GetIpPkt() [3/3]

PIPPKT GetIpPkt ( PVLEFRAME pFrame )

inline

#include <ip.h>

Get IP packet pointer from pointer to VLAN-tagged Ethernet frame.

Returns a pointer to the IP header located after the VLAN Ethernet header.

Parameters

pFrame Pointer to VLAN Ethernet frame structure

Returns: Pointer to IP header within the frame

◆ GetLocalIPInterface()

int GetLocalIPInterface ( const IPADDR & ipa )

inline

#include <ip.h>

Generic function to get local interface for an IP address (IPv6 version).

This inline function provides a generic interface that automatically uses the IPv6 version when IPv6 support is compiled in.

Parameters

ipa	IP address to look up

Returns: Interface number associated with the address

See also: GetLocalIPInterface6(), GetLocalIPInterface4()

◆ GetLocalIPInterface4()

int GetLocalIPInterface4 ( IPADDR4 ipa )

#include <ip.h>

Get the local interface number for a specific IPv4 address.

Determines which local interface is associated with the specified IPv4 address. Searches all interfaces (physical and virtual) to find the one with the matching address.

Parameters

ipa	IPv4 address to look up

Returns: Interface number associated with the address, or -1 if not found

Note: Only available when MULTIHOME or AUTOIP is defined.; Returns -1 if the address is not assigned to any interface.

◆ GetLocalIPInterface6()

int GetLocalIPInterface6 ( const IPADDR & ipa )

#include <ip.h>

Get the local interface number for a specific IPv6 address.

Determines which local interface is associated with the specified IPv6 address. Checks both link-local and global IPv6 addresses on all interfaces.

Parameters

ipa	IPv6 address to look up

Returns: Interface number associated with the address, or -1 if not found

Note: Only available when MULTIHOME or AUTOIP is defined and IPv6 is enabled.; Important for determining interface for link-local addresses.

◆ GetMultiHomeInterface()

int GetMultiHomeInterface	(	IPADDR4	ipa,
		int	norgif )

#include <ip.h>

Get the multi-home interface for a specific IP address.

Finds the appropriate interface number for the specified IP address in a multi-homed system configuration. This searches through all configured interfaces (including virtual interfaces) to find a match.

Parameters

ipa	IP address to look up
norgif	Original interface number (for fallback if address not found)

Returns: Interface number for the specified IP address, or norgif if not found

Note: Only available when MULTIHOME or AUTOIP is defined.; Returns norgif if the address is not assigned to any interface.

◆ GetProperInterface4()

int GetProperInterface4 ( IPADDR4 dst )

#include <ip.h>

Get the appropriate interface number for reaching a destination.

Performs routing table lookup to determine which interface should be used to reach the specified IPv4 destination address. This considers:

Direct network connections (local subnets)
Default gateway routes
Static routes if configured
Interface priorities

Parameters

dst	Destination IPv4 address

Returns: Interface number that should be used to reach the destination

Note: Returns the interface number based on routing table configuration.; Used internally for automatic interface selection.; Returns primary interface if no specific route found.

IPADDR4 remote = AsciiToIp4("8.8.8.8");
int ifnum = GetProperInterface4(remote);
iprintf("Use interface %d to reach %s\r\n", ifnum, "8.8.8.8");

◆ GetSrcIp()

IPADDR GetSrcIp ( const IPADDR & dst )

inline

#include <ip.h>

Generic function to get source IP address for reaching a destination (IPv6 version).

This inline function provides a generic interface that automatically uses the IPv6 version when IPv6 support is compiled in.

Parameters

dst	Destination IP address

Returns: Local IP address that should be used as source for packets to dst

See also: GetSrcIp6(), GetSrcIp4()

◆ GetSrcIp4()

IPADDR4 GetSrcIp4 ( IPADDR4 dst )

#include <ip.h>

Get the appropriate source IPv4 address for reaching a destination.

Determines which local IPv4 address should be used as the source address when sending packets to the specified destination. This performs routing table lookup and interface selection based on the destination address.

Parameters

dst	Destination IPv4 address

Returns: Local IPv4 address that should be used as source for packets to dst

Note: Returns the IP address of the interface that would be used to reach dst.; Considers routing table and interface configuration.; Essential for multi-homed systems to select correct source address.

See also: GetSrcIp(), GetSrcIpwIf4(), GetSrcIp6()

◆ GetSrcIp6()

IPADDR GetSrcIp6 ( const IPADDR & dst )

#include <ip.h>

Get the appropriate source IPv6 address for reaching a destination.

Determines which local IPv6 address should be used as the source address when sending packets to the specified destination. This performs routing table lookup and interface selection.

Parameters

dst	Destination IPv6 address

Returns: Local IPv6 address that should be used as source for packets to dst

Note: Selects appropriate address scope (link-local vs global) based on destination.

See also: GetSrcIp(), GetSrcIp4(), GetSrcIp6wIf()

◆ GetSrcIp6wIf()

IPADDR GetSrcIp6wIf	(	int	ifn,
		const IPADDR &	dst )

#include <ip.h>

Get the source IPv6 address for a specific interface and destination.

Returns the IPv6 address that should be used as the source address when sending packets to the specified destination via the specified interface.

Parameters

ifn	Interface number to use
dst	Destination IPv6 address

Returns: Local IPv6 address of the specified interface

Note: Forces use of specified interface, bypassing routing table.

See also: GetSrcIp6(), GetSrcIpwIf(), GetSrcIpwIf4()

◆ GetSrcIpwIf()

IPADDR GetSrcIpwIf	(	int	ifn,
		const IPADDR &	dst )

inline

#include <ip.h>

Generic function to get source IP address for an interface (IPv6 version).

This inline function provides a generic interface that automatically uses the IPv6 version when IPv6 support is compiled in.

Parameters

ifn	Interface number to use
dst	Destination IP address

Returns: Local IP address of the specified interface

See also: GetSrcIp6wIf(), GetSrcIpwIf4()

◆ GetSrcIpwIf4()

IPADDR4 GetSrcIpwIf4	(	int	ifn,
		const IPADDR4	dst )

#include <ip.h>

Get the source IPv4 address for a specific interface and destination.

Returns the IPv4 address that should be used as the source address when sending packets to the specified destination via the specified interface. This bypasses routing table lookup and uses the specified interface directly.

Parameters

ifn	Interface number to use
dst	Destination IPv4 address

Returns: Local IPv4 address of the specified interface

Note: Forces use of the specified interface regardless of routing table.; Returns the IP address assigned to the specified interface.; The dst parameter may be used for interface-specific address selection.

See also: GetSrcIp4(), GetSrcIpwIf(), GetSrcIp6wIf()

◆ GetSum()

uint16_t GetSum	(	puint16_t	addr,
		uint16_t	count )

#include <ip.h>

Calculate Internet checksum for the specified data.

Computes the standard Internet checksum (RFC 1071) over the specified data. This is the standard checksum algorithm used in IP, TCP, UDP, and ICMP headers.

The algorithm sums all 16-bit words using one's complement arithmetic, then returns the one's complement of the sum.

Parameters

addr	Pointer to data to checksum (must be 16-bit aligned)
count	Number of bytes to include in checksum (should be even)

Returns: 16-bit Internet checksum value

Note: Data should be 16-bit aligned for optimal performance.; If count is odd, the last byte is padded with zero.; This is the general-purpose checksum function for variable-length data.

See also: GetSum20(), GetSumHdr()

◆ GetSum20()

uint16_t GetSum20 ( puint32_t addr )

#include <ip.h>

Calculate Internet checksum for exactly 20 bytes of data.

Optimized checksum calculation for exactly 20 bytes (5 32-bit words), which is the standard size of an IP header without options. This function is significantly faster than GetSum() for this common case.

Parameters

addr	Pointer to 20 bytes of data to checksum (must be 32-bit aligned)

Returns: 16-bit Internet checksum value

Note: This is an optimized version for the common case of IP header checksums.; Data must be 32-bit aligned for correct operation.; Use GetSum() if you need to checksum a different amount of data.

See also: GetSum(), GetSumHdr()

◆ GetSumHdr()

uint16_t GetSumHdr	(	PsudeoHeader &	hdr,
		puint16_t	addr,
		uint16_t	count )

#include <ip.h>

Calculate Internet checksum using a pseudo-header.

Computes the Internet checksum over a pseudo-header followed by data. This is used for TCP and UDP checksum calculation, which includes a pseudo-header containing source/destination IP addresses and protocol information.

The pseudo-header protects against misrouted packets but is not actually transmitted on the wire.

Parameters

hdr	Reference to pseudo-header structure (UDP/TCP pseudo-header)
addr	Pointer to data to checksum following the pseudo-header
count	Number of bytes in the data portion

Returns: 16-bit Internet checksum value including pseudo-header and data

Note: The pseudo-header is not transmitted, but is included in checksum calculation.; Used for TCP and UDP checksum computation per RFC specifications.; Provides protection against packets delivered to wrong IP address or protocol.

See also: GetSum(), GetSum20(), PsudeoHeader

◆ GetUdpPkt()

PUDPPKT GetUdpPkt ( PIPPKT pIp )

inline

#include <ip.h>

Get UDP packet pointer from IP packet pointer.

Calculates the location of the UDP header by skipping past the IP header. This function accounts for variable-length IP headers (with or without options) by examining the header length field.

Parameters

pIp	Pointer to IP header

Returns: Pointer to UDP header, or NULL if pIp is NULL

Note: If the IP header length is exactly 5 (no options), uses fast path.; Otherwise calculates offset based on header length field.

◆ InitializeStack()

void InitializeStack ( )

#include <ip.h>

Initialize the IP protocol stack.

Initializes the IP layer and underlying network infrastructure. This function should be called once during system startup, before the application calls init() or configures network interfaces.

This function:

Initializes the IP layer data structures
Sets up the routing table
Prepares the network interface framework
Allocates necessary system resources

Note: Should be called once and only once before UserMain resets its priority.; The default settings use the configuration record settings.; This provides the network infrastructure for additional network interfaces.; In most applications, this is called automatically by init().

◆ IpProcessEthernetPacket()

void IpProcessEthernetPacket	(	PoolPtr	poolPtr,
		uint16_t	packetSizeInBytes )

#include <ip.h>

Process an Ethernet packet for IP layer handling.

This internal function is called by the Ethernet layer to insert received packets into the IP processing pipeline. It handles the transition from Ethernet frame processing to IP packet processing.

Parameters

poolPtr	Pointer to network buffer pool buffer containing the packet
packetSizeInBytes	Total size of the packet in bytes

Note: This is an internal function typically called by the Ethernet driver.; Applications should not normally call this function directly.

◆ IsLocal4()

BOOL IsLocal4	(	IPADDR4	ip,
		int	ifc )

#include <ip.h>

Check if an IPv4 address is on the local network segment.

Determines if the specified IPv4 address is on the same network segment as the specified interface by comparing network portions of the addresses using the interface's subnet mask. This is useful for:

Routing decisions (local vs gateway)
ARP vs routing determination
Network topology validation

Parameters

ip	IPv4 address to check
ifc	Interface number to check against

Returns: TRUE if the address is on the local network segment, FALSE otherwise

Note: Uses the interface's subnet mask to determine network boundaries.; Returns FALSE if the interface number is invalid.

IPADDR4 target = AsciiToIp4("192.168.1.100");
if (IsLocal4(target, 0)) {
    iprintf("Address is on local network - use ARP\r\n");
} else {
    iprintf("Address is remote - use gateway\r\n");
}

◆ IsMyIp4()

BOOL IsMyIp4	(	IPADDR4	ip,
		int	ifc = -1 )

#include <ip.h>

Check if the specified IPv4 address belongs to this device.

Determines whether the given IPv4 address is assigned to any interface on this device. Optionally checks only a specific interface.

Parameters

ip	IPv4 address to check
ifc	Interface number to check (default: -1 for all interfaces)

Returns: TRUE if the address belongs to this device, FALSE otherwise

Note: When ifc is -1, all interfaces are checked.; When ifc is specified, only that interface is checked.; Useful for determining if a packet is addressed to this device.

See also: IsMyIp(), IsMyIp6()

◆ IsMyIp6()

BOOL IsMyIp6	(	const IPADDR &	ip,
		int	ifc = -1 )

#include <ip.h>

Check if the specified IPv6 address belongs to this device.

Determines whether the given IPv6 address is assigned to any interface on this device. Optionally checks only a specific interface.

Parameters

ip	IPv6 address to check
ifc	Interface number to check (default: -1 for all interfaces)

Returns: TRUE if the address belongs to this device, FALSE otherwise

Note: When ifc is -1, all interfaces are checked.; Checks both link-local and global IPv6 addresses.

See also: IsMyIp(), IsMyIp4()

◆ Ping()

int Ping	(	const IPADDR &	to,
		uint16_t	id,
		uint16_t	seq,
		uint16_t	maxwaitticks,
		int	size = 32 )

inline

#include <ip.h>

Generic ping function that uses IPv6 when IPv6 is enabled.

This inline function provides a generic ping interface that automatically uses the appropriate IPv6 ping function when IPv6 support is compiled in.

Parameters

to	Destination IP address to ping
id	ICMP identifier field
seq	ICMP sequence number field
maxwaitticks	Maximum wait time in system time ticks
size	Size of ping data payload in bytes (default: 32)

Returns: Same as Ping6()

See also: Ping6(), Ping4()

◆ Ping4()

int Ping4	(	IPADDR4	to,
		uint16_t	id,
		uint16_t	seq,
		uint16_t	maxwaitticks )

#include <ip.h>

Send a "ping" packet and wait the specified timeout for a response.

Sends an ICMP echo request packet to the specified destination address and waits for an echo reply. The ping uses the primary network interface (usually Ethernet). For interface selection, use Ping4ViaInterface().

The ping packet contains 32 bytes of ASCII data (starting with 'a' (0x61) through 0xFF) and expects an echo reply with the same data. This follows the standard ICMP echo request/reply protocol defined in RFC 792.

Parameters

to	Destination IPv4 address to ping
id	ICMP identifier field (typically process ID or sequence)
seq	ICMP sequence number field (typically increments per ping)
maxwaitticks	Maximum wait time in system time ticks. Use TICKS_PER_SECOND macro for conversion (e.g., TICKS_PER_SECOND * 5 for 5 seconds)

Returns: >=0 Number of ticks elapsed waiting for the response (successful ping) - use this for RTT -1 Timeout occurred - no response received within maxwaitticks -2 Error other than timeout occurred (e.g., network unreachable, invalid parameters)

// Ping Google DNS with a 3 second timeout
IPADDR4 google_dns = AsciiToIp4("8.8.8.8");
int result = Ping4(google_dns, 0x1234, 1, TICKS_PER_SECOND * 3);
if (result >= 0) {
    iprintf("Ping successful, RTT: %d ticks (%d ms)\r\n", 
            result, result * 1000 / TICKS_PER_SECOND);
} else if (result == -1) {
    iprintf("Ping timeout - host unreachable or not responding\r\n");
} else {
    iprintf("Ping error\r\n");
}

See also: Ping4ViaInterface(), Ping(), PingViaInterface()

◆ Ping4ViaInterface()

int Ping4ViaInterface	(	IPADDR4	to,
		uint16_t	id,
		uint16_t	seq,
		uint16_t	wait,
		int	interface )

#include <ip.h>

Send a "ping" packet via a specific network interface and wait for a response.

Similar to Ping4(), but allows selection of a specific network interface for sending the ICMP echo request. This is useful in multi-homed systems where you need to control which interface is used for the ping, such as:

Testing specific network paths
Verifying interface connectivity
Routing diagnostics
Multi-WAN configurations

Parameters

to	Destination IPv4 address to ping
id	ICMP identifier field (typically process ID)
seq	ICMP sequence number field
wait	Maximum wait time in system time ticks
interface	Network interface number to use for sending the ping (0-based)

Returns: >=0 Number of ticks elapsed waiting for the response (successful ping) -1 Timeout occurred - no response received within wait time -2 Error other than timeout occurred (e.g., invalid interface number)

// Ping via interface 1 with a 2 second timeout
IPADDR4 target = AsciiToIp4("192.168.1.1");
int result = Ping4ViaInterface(target, 0x5678, 1, TICKS_PER_SECOND * 2, 1);

See also: Ping4(), Ping(), PingViaInterface()

◆ Ping6()

int Ping6	(	const IPADDR &	to,
		uint16_t	id,
		uint16_t	seq,
		uint16_t	maxwaitticks,
		int	size = 32 )

#include <ip.h>

Send an IPv6 "ping" packet and wait the specified timeout for a response.

Sends an ICMPv6 echo request packet to the specified IPv6 destination address and waits for an echo reply. The ping uses the primary network interface. This follows the ICMPv6 echo request/reply protocol defined in RFC 4443.

Parameters

to	Destination IPv6 address to ping
id	ICMP identifier field (typically process ID)
seq	ICMP sequence number field (typically increments per ping)
maxwaitticks	Maximum wait time in system time ticks
size	Size of ping data payload in bytes (default: 32)

Returns: >=0 Number of ticks elapsed waiting for the response (successful ping) -1 Timeout occurred - no response received within maxwaitticks -2 Error other than timeout occurred

Note: IPv6 ping packets may traverse different paths than IPv4 pings to the same host.; Link-local addresses require the appropriate zone ID/interface specification.

See also: Ping6ViaInterface(), Ping4(), Ping()

◆ Ping6ViaInterface()

int Ping6ViaInterface	(	const IPADDR &	to,
		uint16_t	id,
		uint16_t	seq,
		uint16_t	wait,
		int	interface,
		int	size = 32 )

#include <ip.h>

Send an IPv6 "ping" packet via a specific network interface.

Similar to Ping6(), but allows selection of a specific network interface for sending the ICMPv6 echo request. This is particularly important for IPv6 where link-local addresses are interface-specific.

Parameters

to	Destination IPv6 address to ping
id	ICMP identifier field (typically process ID)
seq	ICMP sequence number field
wait	Maximum wait time in system time ticks
interface	Network interface number to use for sending the ping
size	Size of ping data payload in bytes (default: 32)

Returns: >=0 Number of ticks elapsed waiting for the response (successful ping) -1 Timeout occurred - no response received within wait time -2 Error other than timeout occurred

Note: Required for pinging link-local IPv6 addresses.; Interface selection affects which source address is used.

See also: Ping6(), Ping4ViaInterface(), PingViaInterface()

◆ PingViaInterface()

int PingViaInterface	(	const IPADDR &	to,
		uint16_t	id,
		uint16_t	seq,
		uint16_t	wait,
		int	interface,
		int	size = 32 )

inline

#include <ip.h>

Generic ping via interface function that uses IPv6 when IPv6 is enabled.

This inline function provides a generic ping via interface that automatically uses the appropriate IPv6 ping function when IPv6 support is compiled in.

Parameters

to	Destination IP address to ping
id	ICMP identifier field
seq	ICMP sequence number field
wait	Maximum wait time in system time ticks
interface	Network interface number to use
size	Size of ping data payload in bytes (default: 32)

Returns: Same as Ping6ViaInterface()

See also: Ping6ViaInterface(), Ping4ViaInterface()

◆ SendICMPError()

void SendICMPError	(	PoolPtr	pBadPacket,
		uint8_t	type,
		uint8_t	code )

#include <ip.h>

Send an ICMP error message in response to a bad packet.

Generates and sends an appropriate ICMP error message in response to a malformed or problematic IP packet. The original packet data is included in the ICMP error message as required by the ICMP specification (typically the first 8 bytes of the original packet's payload).

Parameters

pBadPacket	Pointer to the buffer containing the problematic packet
type	ICMP error type code (e.g., ICMP_TYPE_DEST_UNREACHABLE)
code	ICMP error code within the type (e.g., ICMP_CODE_PORT_UNREACHABLE)

Note: The function automatically includes the required portion of the original packet.; ICMP error messages are rate-limited to prevent ICMP flooding.; The buffer pBadPacket is typically freed by this function.

See also: ICMP type and code definitions in ip.h

◆ ShowIPBuffer()

void ShowIPBuffer ( PoolPtr rp )

#include <ip.h>

Display the contents of a network buffer for diagnostic purposes.

This function provides a formatted dump of the packet contents in the specified network buffer pool buffer. The output is sent using iprintf() and includes both hexadecimal and ASCII representations of the packet data, making it easy to analyze packet structure and contents.

Typical output format:

Offset in hexadecimal
16 bytes per line in hex
ASCII representation of printable characters
Non-printable characters shown as '.'

Parameters

rp	Packet pointer from network buffer pool to display

Note: Uses iprintf() for output, so output destination depends on the current iprintf configuration (typically serial console).; Useful for debugging network packet issues and protocol analysis.; Does not modify or free the buffer.

// Display contents of received packet for debugging

ShowIPBuffer(received_packet);

ShowIPBuffer

void ShowIPBuffer(PoolPtr rp)

Display the contents of a network buffer for diagnostic purposes.

Variable Documentation

◆ pFragFunc

FragmentProcessFunction* pFragFunc

extern

#include <ip.h>

Global function pointer for fragment processing callback.

Set this pointer to your FragmentProcessFunction implementation to handle fragmented IP packets. Set to NULL (default) to disable fragment processing callbacks, in which case fragmented packets will be silently dropped.

void MyFragmentHandler(PoolPtr pp) {
    // Process fragmented packet
    // Store in reassembly buffer
    // Must free the buffer when done or store for later reassembly
    FreeBuffer(pp);
}
 
// Register the callback during initialization
pFragFunc = MyFragmentHandler;

Note: Default value is NULL (fragmented packets dropped).; Only one global handler can be registered.

◆ pPromisciousPacketFunc

PromisciousPacketFunc* pPromisciousPacketFunc

extern

#include <ip.h>

Global function pointer for promiscuous packet processing callback.

Set this pointer to your PromisciousPacketFunc implementation to handle packets not addressed to this device. Set to NULL (default) to disable promiscuous mode, in which case non-local packets will be silently dropped.

void MyPromiscuousHandler(PoolPtr pp) {
    // Log packet for monitoring
    ShowIPBuffer(pp);
    
    // MUST free the buffer when done
    FreeBuffer(pp);
}
 
// Register the callback
pPromisciousPacketFunc = MyPromiscuousHandler;

Note: Default value is NULL (non-local packets dropped).; Ethernet interface must also be configured for promiscuous mode.; Only one global handler can be registered.

◆ pTaskPacketFunc

TaskPacketFunc* pTaskPacketFunc

extern

#include <ip.h>

Global function pointer for UDP task packet processing callback.

Set this pointer to your TaskPacketFunc implementation to handle UDP packets in task context. Set to NULL (default) to disable task-level UDP packet processing.

Note: Default value is NULL (task-level processing disabled).; Only one global handler can be registered.; Regular UDP socket handlers are not affected by this callback.

Topics

Classes

Macros

Typedefs

Functions

Variables

Global Configuration Variables

Get Packet Functions

IP Version

Header Length

Flags and Fragment Offset

IP Protocol Numbers

ICMP Message Types and Codes

Well-Known Port Numbers

Detailed Description

Typedef Documentation

◆ FragmentProcessFunction

◆ IpHeaderIPv4

◆ PromisciousPacketFunc

Function Documentation

◆ AddInterface()

◆ FixHeaderAndSend()

◆ FixHeaderAndSendViaInterface()

◆ GetEphemeralPort()

◆ GetIpPkt() [1/3]

◆ GetIpPkt() [2/3]

◆ GetIpPkt() [3/3]

◆ GetLocalIPInterface()

◆ GetLocalIPInterface4()

◆ GetLocalIPInterface6()

◆ GetMultiHomeInterface()

◆ GetProperInterface4()

◆ GetSrcIp()

◆ GetSrcIp4()

◆ GetSrcIp6()

◆ GetSrcIp6wIf()

◆ GetSrcIpwIf()

◆ GetSrcIpwIf4()

◆ GetSum()

◆ GetSum20()

◆ GetSumHdr()

◆ GetUdpPkt()

◆ InitializeStack()

◆ IpProcessEthernetPacket()

◆ IsLocal4()

◆ IsMyIp4()

◆ IsMyIp6()

◆ Ping()

◆ Ping4()

◆ Ping4ViaInterface()

◆ Ping6()

◆ Ping6ViaInterface()

◆ PingViaInterface()

◆ SendICMPError()

◆ ShowIPBuffer()

Variable Documentation

◆ pFragFunc

◆ pPromisciousPacketFunc

◆ pTaskPacketFunc