Options controlling a single UDP receive operation. More...

#include <DatagramSocket.hpp>

Public Attributes
DatagramReceiveMode	mode = DatagramReceiveMode::NoPreflight
	Datagram sizing policy to use during receive.
bool	allowGrow = true
	Whether the packet buffer may grow before receive (applies to DatagramPacket).
bool	allowShrink = true
	Whether the packet buffer may shrink after receive (applies to DatagramPacket).
int	recvFlags = 0
	Extra flags passed to recv/recvfrom (e.g., MSG_PEEK).
bool	updateLastRemote = true
	Whether to persist sender into the socket's "last remote" (unconnected sockets).
bool	resolveNumeric = true
	Whether to resolve numeric host/port into DatagramPacket after receive.
bool	errorOnTruncate {true}
	When true, the read fails if the incoming datagram would be truncated.

Detailed Description

Options controlling a single UDP receive operation.

This structure encapsulates the configurable parameters that control how a UDP datagram is received and processed by the DatagramSocket class. It provides fine-grained control over buffer management, system flags, and post-receive behavior.

Key Features:

Controls datagram sizing policy
Manages buffer resizing behavior
Sets system receive flags
Controls remote peer tracking
Configures address resolution

See also: DatagramSocket::read(); DatagramReceiveMode

Since: 1.0

Member Data Documentation

◆ allowGrow

bool jsocketpp::DatagramReadOptions::allowGrow = true

Whether the packet buffer may grow before receive (applies to DatagramPacket).

When true and using PreflightSize mode, allows the implementation to grow the packet buffer if the probed datagram size exceeds current capacity. This can prevent truncation at the cost of potential allocation.

◆ allowShrink

bool jsocketpp::DatagramReadOptions::allowShrink = true

Whether the packet buffer may shrink after receive (applies to DatagramPacket).

When true, allows the implementation to shrink the packet buffer to exactly match the received datagram size after a successful receive. This can reduce memory usage but may trigger reallocation on subsequent receives.

◆ errorOnTruncate

bool jsocketpp::DatagramReadOptions::errorOnTruncate {true}

When true, the read fails if the incoming datagram would be truncated.

This option determines whether a receive operation should throw when the destination buffer cannot hold the entire datagram:

With DatagramReceiveMode::PreflightSize, size is probed before reading. If the probed size exceeds the destination capacity and errorOnTruncate == true, the function throws before consuming the datagram. If false, the read proceeds and the datagram is truncated to the provided capacity.
With DatagramReceiveMode::NoPreflight, truncation can only be detected after the receive. If truncation occurs and errorOnTruncate == true, the function throws after the datagram has been consumed by the kernel (the tail is lost). If false, it returns the truncated bytes without error.

Note: This flag primarily affects APIs that read into a fixed-size buffer (e.g., readAvailable(std::span<char> ...), readInto(void*, size_t, ...)). It has no practical effect for string-returning APIs that allocate exactly to fit the datagram after a successful size preflight; however, if size probing is not available on the platform and a safe cap is used, a datagram larger than that cap will trigger this check.

Warning: With NoPreflight, a thrown error occurs after data consumption; the datagram tail cannot be recovered. Prefer PreflightSize if you must avoid truncation entirely.

◆ mode

DatagramReceiveMode jsocketpp::DatagramReadOptions::mode = DatagramReceiveMode::NoPreflight

Datagram sizing policy to use during receive.

Controls whether to probe the datagram size before receiving (preflight) or directly read into the provided buffer. See DatagramReceiveMode for details.

◆ recvFlags

int jsocketpp::DatagramReadOptions::recvFlags = 0

Extra flags passed to recv/recvfrom (e.g., MSG_PEEK).

Platform-specific flags that modify the behavior of the underlying receive operation. Common values include:

MSG_PEEK: Look at data without removing it from the receive queue
MSG_WAITALL: Block until the full request can be satisfied
MSG_DONTWAIT: Non-blocking operation

◆ resolveNumeric

bool jsocketpp::DatagramReadOptions::resolveNumeric = true

Whether to resolve numeric host/port into DatagramPacket after receive.

When true, attempts to convert the sender's address into a human-readable IP string and port number. This may incur additional syscalls but provides convenient access to peer information via DatagramPacket::address and DatagramPacket::port.

◆ updateLastRemote

bool jsocketpp::DatagramReadOptions::updateLastRemote = true

Whether to persist sender into the socket's "last remote" (unconnected sockets).

When true on an unconnected socket, updates the internal state tracking the most recent peer address. This enables getRemoteIp() and getRemotePort() to return information about the last datagram sender.

The documentation for this struct was generated from the following file:

include/jsocketpp/DatagramSocket.hpp

Public Attributes