Core Utilities and Types

Internal types, platform abstractions, and utility functions used across the jsocketpp library. More...

Collaboration diagram for Core Utilities and Types:

Namespaces
namespace	jsocketpp::net
	Endianness utilities for network byte order conversion.

Classes
struct	jsocketpp::BufferView
	Represents a raw writable memory region for scatter/gather I/O. More...

Typedefs
using	jsocketpp::Port = std::uint16_t
	Type alias representing a TCP or UDP port number (1–65535).

Functions
bool	jsocketpp::isIPv4MappedIPv6 (const sockaddr_in6 *addr6)
	Checks if a given sockaddr_in6 represents an IPv4-mapped IPv6 address.
sockaddr_in	jsocketpp::convertIPv4MappedIPv6ToIPv4 (const sockaddr_in6 &addr6)
	Converts an IPv4-mapped IPv6 address to a pure IPv4 sockaddr_in.
void	jsocketpp::internal::resolveNumericHostPort (const sockaddr *sa, const socklen_t len, std::string &host, Port &port)
	Resolve numeric host and port from a socket address.

Variables
constexpr std::size_t	jsocketpp::DefaultBufferSize = 4096
	Default internal buffer size (in bytes) for socket read operations.
constexpr std::size_t	jsocketpp::DefaultDatagramReceiveSize = 8192
	Fallback receive size (in bytes) for UDP datagrams when the exact size is unknown.
constexpr std::size_t	jsocketpp::MaxDatagramPayloadSafe = 65507
	Maximum UDP payload size (in bytes) that is safely valid across common stacks.
constexpr std::size_t	jsocketpp::MaxUdpPayloadIPv4 = 65507
	Maximum UDP payload size (in bytes) over IPv4.
constexpr std::size_t	jsocketpp::MaxUdpPayloadIPv6 = 65527
	Theoretical maximum UDP payload size (in bytes) over IPv6.

Detailed Description

Internal types, platform abstractions, and utility functions used across the jsocketpp library.

This group contains foundational components of the jsocketpp socket library, including common type aliases, byte-order conversion utilities, and cross-platform compatibility helpers.

Components in this group are typically not used directly by application-level code, but are essential for internal implementation and protocol correctness.

Includes:

• jsocketpp::Port – type alias for network ports
• jsocketpp::net – byte order conversion utilities (host ↔ network)
• Platform-specific type abstractions (SOCKET, INVALID_SOCKET, etc.)

See also

jsocketpp::net

Port

Typedef Documentation

Port

using jsocketpp::Port = std::uint16_t

Type alias representing a TCP or UDP port number (1–65535).

This alias provides strong typing for network port numbers across the jsocketpp library. It improves readability and makes function signatures semantically clearer when dealing with socket operations.

Using Port instead of a plain uint16_t or unsigned short helps:

• Differentiate port values from other numeric parameters
• Assist with static analysis and overload resolution
• Align with best practices in modern C++ design

Note

Although a Port is technically an integer, it represents a well-defined semantic domain (TCP/UDP port number).

Function Documentation

convertIPv4MappedIPv6ToIPv4()

sockaddr_in jsocketpp::convertIPv4MappedIPv6ToIPv4 ( const sockaddr_in6 & addr6 )

inline

Converts an IPv4-mapped IPv6 address to a pure IPv4 sockaddr_in.

This function extracts the embedded IPv4 address from an IPv4-mapped IPv6 address. It preserves the port number and fills a fully valid sockaddr_in.

Preconditions

• The input must be an IPv4-mapped IPv6 address.
• You should call isIPv4MappedIPv6() before using this function.

Parameters

addr6

A sockaddr_in6 known to be IPv4-mapped.

Returns

A sockaddr_in representing the embedded IPv4 address and port.

isIPv4MappedIPv6()

bool jsocketpp::isIPv4MappedIPv6 ( const sockaddr_in6 * addr6 )

inline

Checks if a given sockaddr_in6 represents an IPv4-mapped IPv6 address.

IPv4-mapped IPv6 addresses allow IPv6-only sockets to interoperate with IPv4 clients by embedding an IPv4 address inside a special IPv6 format:

::ffff:a.b.c.d   // 0000:0000:0000:0000:0000:ffff:abcd:efgh

This function identifies such addresses so they can be normalized to pure IPv4.

Parameters

addr6

Pointer to a sockaddr_in6 structure.

Returns

true if the address is IPv4-mapped; false otherwise.

resolveNumericHostPort()

void jsocketpp::internal::resolveNumericHostPort ( const sockaddr * sa, const socklen_t len, std::string & host, Port & port )

inline

Resolve numeric host and port from a socket address.

Calls getnameinfo() with NI_NUMERICHOST | NI_NUMERICSERV (and NI_NUMERICSCOPE where available) to obtain the sender’s numeric IP and service strings without DNS lookups. Parses the service string to a Port and validates it fits the type’s range. On failure, throws using the library’s cross-platform getnameinfo error pattern.

Parameters

[in]	sa	Pointer to a valid sockaddr (e.g., sockaddr_in/sockaddr_in6).
[in]	len	Size of the structure pointed to by sa.
[out]	host	Receives the numeric host string (e.g., "192.0.2.10", "fe80::1eth0").
[out]	port	Receives the numeric service string (e.g., "8080").

Exceptions

SocketException

If getnameinfo() fails.

Note

Uses purely numeric resolution to avoid blocking DNS queries.

Since

1.0

Variable Documentation

DefaultBufferSize

std::size_t jsocketpp::DefaultBufferSize = 4096

inlineconstexpr

Default internal buffer size (in bytes) for socket read operations.

This constant defines the default size (4096 bytes / 4 KB) of the internal read buffer used across various socket classes in the library unless explicitly overridden.

Applies to

• TCP client sockets (Socket) when constructed without a custom internalBufferSize
• Accepted TCP sockets via ServerSocket::accept()
• UDP sockets (DatagramSocket) when no explicit bufferSize is passed
• May also serve as a guideline for other buffer sizes (e.g., send/receive buffers)

Rationale

• Memory-efficient: 4096 bytes aligns with the typical memory page size on most systems.
• Performance-optimized: Large enough for common protocol messages (e.g., HTTP, DNS, WebSocket)
• Concurrency-friendly: Balances throughput and memory usage across many simultaneous sockets.

Customization

Override this value by:

• Passing a custom buffer size to socket constructors (e.g., DatagramSocket(port, 8192))
• Calling setInternalBufferSize() after construction
• Tuning system-level buffers via setReceiveBufferSize() or setSendBufferSize()

When to Adjust

Increase if:

• Your application transfers large datagrams or stream data (e.g., file uploads, media streams)
• You want to reduce syscall overhead by reading more per call

Decrease if:

• Operating in memory-constrained environments (e.g., embedded systems)
• Managing a large number of idle sockets where footprint matters more than speed

See also

Socket

ServerSocket

DatagramSocket

Socket::setInternalBufferSize()

SocketOptions::setReceiveBufferSize()

SocketOptions::setSendBufferSize()

DefaultDatagramReceiveSize

std::size_t jsocketpp::DefaultDatagramReceiveSize = 8192

inlineconstexpr

Fallback receive size (in bytes) for UDP datagrams when the exact size is unknown.

This constant defines the default number of bytes we ask the OS to deliver when receiving a UDP datagram and the platform cannot report the pending datagram's exact size (via FIONREAD or the POSIX MSG_PEEK|MSG_TRUNC probe) and the caller has not provisioned _internalBuffer (i.e., its size is 0).

Applies to

• UDP sockets (DatagramSocket) in read() overloads that construct a std::string or otherwise need a temporary buffer when the exact size is unavailable and _internalBuffer is unset.
• May be used by other UDP-related helpers where a conservative per-call buffer is required.

Semantics & policy

• We do not resize _internalBuffer based on this value; it is a one-shot receive size when the caller has not sized a reusable buffer.
• If the incoming datagram is larger than this value and the OS cannot tell us the exact size up-front, the payload may be truncated to this size (standard UDP behavior).
• A safety cap of 65,507 bytes (maximum safe UDP payload) is always honored, even if this constant is set higher.

Rationale (default: 8192 / 8 KiB)

• Practicality: Big enough for common application messages while avoiding large, frequent allocations when size probing is unavailable.
• Performance: Reduces syscall overhead compared to very small defaults without bloating per-receive memory.

Customization

• Increase if your application expects larger datagrams and you prefer to minimize truncation when size probing is unavailable.
• Decrease in memory-constrained environments if your datagrams are typically small.

Examples

// Typical path inside read<std::string>():
// 1) Try exact size via nextDatagramSize(fd)
// 2) If 0 and _internalBuffer.size() == 0, use DefaultDatagramReceiveSize
// 3) Read up to std::min(DefaultDatagramReceiveSize, 65507)

Note

When _internalBuffer is already sized by the user, its capacity takes precedence as the "caller-provided buffer" (Java-like semantics); this constant is not used then.

See also

jsocketpp::internal::nextDatagramSize()

DatagramSocket

Since

1.0

MaxDatagramPayloadSafe

std::size_t jsocketpp::MaxDatagramPayloadSafe = 65507

inlineconstexpr

Maximum UDP payload size (in bytes) that is safely valid across common stacks.

This constant represents a conservative upper bound for a single UDP payload that is widely supported across platforms and socket APIs. It equals the IPv4 maximum payload:

65,535 (IPv4 total length) − 20 (minimum IPv4 header) − 8 (UDP header) = 65,507 bytes

Why a "safe" cap?

• Many APIs and stacks historically enforce the IPv4 limit even for IPv6 sockets for compatibility. Using this value avoids surprises (e.g., EMSGSIZE) and simplifies buffer sizing when the address family is not known in advance.

Usage

• Clamp opportunistic receive sizes to MaxDatagramPayloadSafe to prevent oversizing.
• When sending, avoid constructing payloads larger than this unless you know you are on IPv6 and have validated larger limits (see MaxUdpPayloadIPv6).

See also

MaxUdpPayloadIPv4

MaxUdpPayloadIPv6

Since

1.0

MaxUdpPayloadIPv4

std::size_t jsocketpp::MaxUdpPayloadIPv4 = 65507

inlineconstexpr

Maximum UDP payload size (in bytes) over IPv4.

Computed as: 65,535 (IPv4 total length) − 20 (IPv4 header) − 8 (UDP header) = 65,507 bytes. Use this when you know the socket/address family is IPv4.

See also

MaxDatagramPayloadSafe

Since

1.0

MaxUdpPayloadIPv6

std::size_t jsocketpp::MaxUdpPayloadIPv6 = 65527

inlineconstexpr

Theoretical maximum UDP payload size (in bytes) over IPv6.

Computed as: 65,535 (IPv6 payload length, excludes the 40-byte IPv6 header) − 8 (UDP header) = 65,527 bytes.

Note

Real-world effective limits can be smaller due to extension headers, PMTU, and stack constraints. Many stacks still behave as if the IPv4 limit applies. Prefer MaxDatagramPayloadSafe unless you have verified larger datagrams are supported.

See also

MaxDatagramPayloadSafe

Since

1.0