Network Types

Data Structures
struct	NetQueueConfig
struct	NetAddr
struct	NetPktInfo
	Per-datagram information the IP layer carries alongside the payload. More...
struct	NetMessage
	A received packet, as delivered to a handler. More...
struct	NetMsgQueue
	Simple intrusive FIFO of NetMessage, linked through NetMessage::next. More...

Macros
#define	NET_INVALID_HANDLE   ((NetSockHandle)-1)
	An invalid socket handle. Matches both INVALID_SOCKET (Windows) and a negative fd (Unix).
#define	NET_FILTER_RING_SEGSZ   16384
#define	netMsgQueueEmpty(q)   ((q)->head == NULL)

Typedefs
typedef intptr	NetSockHandle
	Platform-neutral OS socket handle: a Windows SOCKET or a Unix file descriptor.
typedef struct NetQueueConfig	NetQueueConfig
typedef uint64	NetTimerId
	Handle to an armed timer, unique for the lifetime of its queue.
typedef struct NetAddr	NetAddr
typedef enum NetEcn	NetEcn
	Explicit Congestion Notification codepoint, as carried in the IP header.
typedef struct NetPktInfo	NetPktInfo
	Per-datagram information the IP layer carries alongside the payload.
typedef struct NetMessage	NetMessage
	A received packet, as delivered to a handler.
typedef struct NetMsgQueue	NetMsgQueue
	Simple intrusive FIFO of NetMessage, linked through NetMessage::next.

Enumerations
enum	NetQueueFlags { }
	Flags for creating a NetQueue. More...
enum	NetConnectPref {   NCP_Default = 0 , NCP_PreferV4 = 1 , NCP_PreferV6 = 2 , NCP_V4Only = 3 ,   NCP_V6Only = 4 }
enum	NetSocketOpFlags { NSO_None = 0x00 , NSO_Immediate = 0x01 , NSO_Peek = 0x02 }
	Flags for socket send/receive operations. More...
enum	NetSocketType { NST_Stream = 1 , NST_Datagram , NST_Quic }
	Socket types. More...
enum	NetSocketState {   NS_Init = 0 , NS_Connected , NS_Listening , NS_Connecting ,   NS_Resolving , NS_Closed }
	State of a network socket. More...
enum	NetCloseReason {   NCR_None = 0 , NCR_Reclaimed = 1 , NCR_AppClosed = 2 , NCR_PeerClosed = 3 ,   NCR_Error = 4 , NCR_SocketClosed = 5 , NCR_Shutdown = 6 }
enum	NetConnectionState { NCS_NotConnected = 0 , NCS_Connecting = 1 , NCS_Connected = 2 }
	Network connection states (for event notification) More...
enum	NetFilterNotify { NFN_None = 0 , NFN_Secured = 1 , NFN_AppCustom = 1000 }
enum	NetTimerFlags { }
	Flags controlling how an armed timer behaves. More...
enum	NetErrorCode {   NERR_None = 0 , NERR_Unknown = 1 , NERR_ConnectionRefused = 2 , NERR_Timeout = 3 ,   NERR_NetworkUnreachable = 4 , NERR_HostUnreachable = 5 , NERR_NetworkDown = 6 , NERR_AddressInUse = 7 ,   NERR_AlreadyConnected = 8 , NERR_NotConnected = 9 , NERR_ConnectionReset = 10 , NERR_WouldBlock = 11 ,   NERR_Interrupted = 12 }
	Network error codes. More...
enum	NetAddrType { NA_Unknown = 0 , NA_IPv4 = 1 , NA_IPv6 = 2 }
	Network address types. More...
enum	NetEcn { NET_ECN_NotEct = 0 , NET_ECN_Ect1 = 1 , NET_ECN_Ect0 = 2 , NET_ECN_CE = 3 }
	Explicit Congestion Notification codepoint, as carried in the IP header. More...

Functions
void	netMsgQueuePush (NetMsgQueue *q, NetMessage *msg)
NetMessage *	netMsgQueuePop (NetMsgQueue *q)

Detailed Description

Common types and enumerations used in the networking module.

Macro Definition Documentation

NET_FILTER_RING_SEGSZ

#define NET_FILTER_RING_SEGSZ   16384

Segment size for a stream filter's boundary rings (encOut / decOut) and the flow's encode staging ring. A small default; revisit if a real multi-stage chain profiles badly.

Definition at line 185 of file net_shared.h.

netMsgQueueEmpty

#define netMsgQueueEmpty

(

q

)

((q)->head == NULL)

bool netMsgQueueEmpty(NetMsgQueue *q);

Tests whether a message queue has nothing in it

Parameters

q	Queue to test

Returns

true if the queue holds no messages

Definition at line 427 of file net_shared.h.

Typedef Documentation

NetAddr

typedef struct NetAddr NetAddr

Network address structure

Byte order differs by field:

• port and scope are host byte order, ordinary integers.
• ipv4 is host order too: ipv4[0] is the least significant octet, so all four bytes can be treated together as a uint32.
• ipv6 is stored in network order exactly as it travels on the wire, ipv6[0] first – IPv6 addresses are just a 16-byte identifier with no meaningful "host order".

NetEcn

typedef enum NetEcn NetEcn

Explicit Congestion Notification codepoint, as carried in the IP header.

The values are the two bits themselves, so a codepoint can be written to or read from a packet without translation. A router that is becoming congested rewrites either ECT mark to NET_ECN_CE instead of dropping the packet, which lets a transport that understands it slow down a round trip earlier than loss would have told it to.

NetMessage

typedef struct NetMessage NetMessage

A received packet, as delivered to a handler.

Arrives as NetEvent.recv.msg (a complete datagram), NetEvent.refused.msg (a packet from a source with no flow), or through a netsocketRecvMsgs() callback. Read the payload from buf and the peer's address from addr. The message itself is only valid until the handler returns – to keep the payload without copying it, take ownership of the buffer (see buf).

NetMsgQueue

typedef struct NetMsgQueue NetMsgQueue

Simple intrusive FIFO of NetMessage, linked through NetMessage::next.

The boundary storage between datagram filter chain stages (see NetDatagramFilter::encOut / decOut in Filters) – the message-queue analog of the byte-oriented BufRing used between NetStreamFilter stages. It needs no locking of its own: every driver pass runs under the owning flow's filter lock, so only one thread is ever inside a chain.

NetPktInfo

typedef struct NetPktInfo NetPktInfo

Per-datagram information the IP layer carries alongside the payload.

On a received datagram this says which of the machine's own addresses the datagram was sent to and how the path marked it. On a send it asks for the same two things: leave from this local address, and put this mark on the packet.

Both fields are optional and both have a have flag, because a platform that cannot report or set one must be distinguishable from one that reported "no mark" – a transport doing ECN has to know which it is before it starts marking packets.

NetQueueConfig

typedef struct NetQueueConfig NetQueueConfig

Creation-time configuration for a NetQueue.

Start from a preset and override what you need:

NetQueueConfig conf;
netqueuePresetServer(&conf);
conf.maxflows = 50000;
NetQueue* q = netqueueCreate(&conf);

NetTimerId

typedef uint64 NetTimerId

Handle to an armed timer, unique for the lifetime of its queue.

Returned by netflowAddTimer() and passed back to netflowCancelTimer() / netflowRearmTimer(). Zero is never a valid timer and means "no timer" everywhere it appears.

Definition at line 210 of file net_shared.h.

Enumeration Type Documentation

NetAddrType

enum NetAddrType

Network address types.

Enumerator
NA_Unknown	Unknown or invalid.
NA_IPv4	IPv4 address.
NA_IPv6	IPv6 address.

Definition at line 269 of file net_shared.h.

NetCloseReason

enum NetCloseReason

Why a flow was closed, carried on NET_FlowClosed.

Only NCR_Reclaimed can resurrect: it means the queue guessed the peer was gone, and an arriving packet can prove that guess wrong. Every other reason is final.

Enumerator
NCR_None	Not closing.
NCR_Reclaimed	Reclaimed under flow cap pressure (resurrectable)
NCR_AppClosed	Application called netflowClose()
NCR_PeerClosed	Stream peer closed the connection cleanly.
NCR_Error	Connection reset or other fatal socket error.
NCR_SocketClosed	The owning socket was closed with flows still live.
NCR_Shutdown	The queue is shutting down.

Definition at line 166 of file net_shared.h.

NetConnectionState

enum NetConnectionState

Network connection states (for event notification)

Enumerator
NCS_NotConnected	Not connected.
NCS_Connecting	Connection in progress.
NCS_Connected	Connected.

Definition at line 177 of file net_shared.h.

NetConnectPref

enum NetConnectPref

Address-family preference for outbound connect, applied to the resolved address list after DNS lookup. Most applications can leave this at NCP_Default; use the other values when a deployment needs to force or exclude a family (an IPv4-only network, for example).

Enumerator
NCP_Default	Interleave; the first address the resolver returned leads.
NCP_PreferV4	Interleave, but IPv4 leads regardless of resolver order.
NCP_PreferV6	Interleave, but IPv6 leads regardless of resolver order.
NCP_V4Only	Discard every IPv6 result.
NCP_V6Only	Discard every IPv4 result.

Definition at line 40 of file net_shared.h.

NetEcn

enum NetEcn

Explicit Congestion Notification codepoint, as carried in the IP header.

The values are the two bits themselves, so a codepoint can be written to or read from a packet without translation. A router that is becoming congested rewrites either ECT mark to NET_ECN_CE instead of dropping the packet, which lets a transport that understands it slow down a round trip earlier than loss would have told it to.

Enumerator
NET_ECN_NotEct	Not ECN-capable: a congested router drops this packet.
NET_ECN_Ect1	ECN-capable transport, codepoint 1.
NET_ECN_Ect0	ECN-capable transport, codepoint 0.
NET_ECN_CE	Congestion experienced: a router marked this packet on the way.

Definition at line 312 of file net_shared.h.

NetErrorCode

enum NetErrorCode

Network error codes.

Enumerator
NERR_None	No error.
NERR_Unknown	Unknown error.
NERR_ConnectionRefused	Connection was refused by the remote host.
NERR_Timeout	Connection timed out.
NERR_NetworkUnreachable	Network is unreachable.
NERR_HostUnreachable	Host is unreachable.
NERR_NetworkDown	Network is down.
NERR_AddressInUse	Address already in use.
NERR_AlreadyConnected	Socket is already connected.
NERR_NotConnected	Socket is not connected.
NERR_ConnectionReset	Connection was reset by peer.
NERR_WouldBlock	The operation would have blocked; no data available yet. Not a failure -- readiness backends report this often (for example, another thread may have already read the data). Just try again later.
NERR_Interrupted	Interrupted by a signal before anything was transferred. Unix only in practice; the caller should simply retry. Windows has no equivalent.

Definition at line 243 of file net_shared.h.

NetFilterNotify

enum NetFilterNotify

Filter notification code, carried as the payload of a NET_FilterNotify event (see Filters)

A filter raises one of these through netflowfilterNotify() when it reaches a milestone the application should hear about. Confining filter signals to their own enum – delivered on a dedicated event with a dedicated payload arm – means a filter can raise application-visible notifications without being able to forge an ordinary NET_ event whose payload it could not populate correctly.

Enumerator
NFN_None	No notification.
NFN_Secured	The filter's secure channel is up; the application may send now.
NFN_AppCustom	First code reserved for application-defined filter notifications. Built-in notifications stay below this line; a custom filter numbers its own notifications at NFN_AppCustom and above, so they can never collide with codes the framework adds later.

Definition at line 195 of file net_shared.h.

NetQueueFlags

enum NetQueueFlags

Flags for creating a NetQueue.

Enumerator
NQ_SelectOnly	Force use of the select() API, even if more efficient backends are available.
NQ_AutoAccept	Automatically add accepted sockets to the queue. Without this flag, the application must listen for NET_Accepted events and either add the socket to a queue, or use objAcquire() to hold onto a reference to the new socket and prevent it from being destroyed

Definition at line 23 of file net_shared.h.

NetSocketOpFlags

enum NetSocketOpFlags

Flags for socket send/receive operations.

Enumerator
NSO_None	No special options.
NSO_Immediate	For send operations, do not queue data if the socket is not currently writable. Instead, return immediately with the number of bytes actually sent (may be zero). Not valid if the socket has a filter attached.
NSO_Peek	For receive operations, peek at the data without removing it from the socket buffer.

Definition at line 121 of file net_shared.h.

NetSocketState

enum NetSocketState

State of a network socket.

Enumerator
NS_Init	Socket is not yet used.
NS_Connected	Socket is connected (default for bound connectionless sockets)
NS_Listening	Socket is listening for incoming connections.
NS_Connecting	Socket is in the process of connecting.
NS_Resolving	Waiting for name resolution.
NS_Closed	Socket is closed and cannot be reused.

Definition at line 153 of file net_shared.h.

NetSocketType

enum NetSocketType

Socket types.

Enumerator
NST_Stream	Stream socket (TCP) Note This socket type requires a connection
NST_Datagram	Datagram socket (UDP) Note This socket type is connectionless
NST_Quic	QUIC connection or listener, implemented by cxquic on top of a datagram socket. A socket of this type has no OS handle of its own: the real UDP endpoint is a separate NST_Datagram socket that cxquic owns and shares between every connection on it. It has both a control flow (`flow`, where connection-level events are delivered) and a flow table (`flows`, one entry per QUIC stream, keyed on the stream id rather than a peer address).

Definition at line 134 of file net_shared.h.

NetTimerFlags

enum NetTimerFlags

Flags controlling how an armed timer behaves.

Enumerator
NTF_Repeat	Re-arm automatically after each fire, at the same delay. The timer keeps its NetTimerId across firings, so one cancel stops it for good -- including a cancel issued from inside its own callback.

Definition at line 213 of file net_shared.h.

Function Documentation

netMsgQueuePop()

NetMessage * netMsgQueuePop ( NetMsgQueue *  q )

inline

Remove and return the oldest message in a message queue

Ownership passes to the caller. A filter consuming its input queue pops from src in a loop until this returns NULL, or stops early to leave the rest for a later pass.

Parameters

q	Queue to pop from

Returns

The oldest queued message, or NULL if the queue is empty

Definition at line 453 of file net_shared.h.

netMsgQueuePush()

void netMsgQueuePush ( NetMsgQueue *  q, NetMessage *  msg  )

inline

Append a message to the end of a message queue

Takes ownership of the message. This is how a datagram filter stage emits output: push onto self->encOut for the wire direction, self->decOut for the application direction.

Parameters

q	Queue to append to
msg	Message to append (ownership transferred)

Definition at line 436 of file net_shared.h.

References NetMsgQueue::tail.