jsocketpp::internal Namespace Reference

Implementation-only utilities and platform abstractions for jsocketpp. More...

Classes
struct	AddrinfoDeleter
	Custom deleter for addrinfo* pointers to support RAII-style cleanup. More...
class	ScopedBlockingMode
	RAII helper for temporarily overriding a socket's blocking mode. More...

Typedefs
using	AddrinfoPtr = std::unique_ptr<addrinfo, AddrinfoDeleter>
	Smart pointer that manages addrinfo* resources using AddrinfoDeleter.

Functions
std::vector< WSABUF >	toWSABUF (const BufferView *buffers, const std::size_t count)
	Convert a raw array of BufferView elements into a WSABUF array for use with Windows socket APIs.
std::vector< WSABUF >	toWSABUF (const std::span< const BufferView > buffers)
	Convert a span of BufferView elements into a WSABUF array (Windows).
std::vector< iovec >	toIOVec (const BufferView *buffers, const std::size_t count)
	Convert a raw array of BufferView elements into an iovec array for POSIX readv/writev.
std::vector< iovec >	toIOVec (const std::span< const BufferView > buffers)
	Convert a span of BufferView elements into an iovec array for POSIX vectorized I/O.
AddrinfoPtr	resolveAddress (const std::string_view host, const Port port, const int family, const int socktype, const int protocol, const int flags=0)
	Resolves a hostname and port into a list of usable socket address structures.
std::string	getBoundLocalIp (SOCKET sockFd)
	Retrieves the local IP address to which the socket is currently bound.
bool	ipAddressesEqual (const std::string &ip1, const std::string &ip2)
	Compares two IP addresses for logical equality, accounting for IPv4-mapped IPv6 forms.
void	sendExact (SOCKET fd, const void *data, std::size_t size)
	Sends an entire datagram to a connected peer using send().
void	sendExactTo (SOCKET fd, const void *data, std::size_t size, const sockaddr *addr, socklen_t addrLen, void(*afterSuccess)(void *ctx), void *ctx)
	Sends an entire datagram to a specific destination using sendto().
bool	tryCloseNoexcept (const SOCKET fd) noexcept
	Attempts to close a socket descriptor without throwing exceptions.
void	closeOrThrow (const SOCKET fd)
	Closes a socket descriptor and throws on failure.
std::size_t	nextDatagramSize (SOCKET fd) noexcept
	Query the exact size of the next UDP datagram, if the platform can provide it.
ssize_t	recvInto (const SOCKET fd, std::span< std::byte > dst, const int flags, sockaddr_storage *src, socklen_t *srcLen)
	Receive into a caller-provided span, routing to recv() or recvfrom() as needed.
void	throwLastSockError (const std::source_location &loc=std::source_location::current())
	Throw a SocketException for the last socket error, with optional source-location context.
void	resolveNumericHostPort (const sockaddr *sa, const socklen_t len, std::string &host, Port &port)
	Resolve numeric host and port from a socket address.

Detailed Description

Implementation-only utilities and platform abstractions for jsocketpp.

This namespace contains internal helper classes, platform-specific adapters, and low-level abstractions used by the jsocketpp library. These components are not part of the public API and may change at any time without notice.

Contents

• RAII wrappers (e.g., ScopedBlockingMode)
• Platform-specific buffer conversion tools (e.g., toIOVec(), toWSABUF())
• Utility functions for socket state, error codes, and descriptor flags

Usage

Developers using jsocketpp should not depend on symbols in this namespace unless they are contributing to the library itself or extending its internals.

Warning

Not part of the public API. Subject to change or removal in future versions.

Function Documentation

ipAddressesEqual()

bool jsocketpp::internal::ipAddressesEqual ( const std::string & ip1, const std::string & ip2 )

nodiscard

Compares two IP addresses for logical equality, accounting for IPv4-mapped IPv6 forms.

This function compares two IP addresses represented as strings (e.g., "192.168.1.1" or "::ffff:192.168.1.1") and returns true if they refer to the same underlying address, regardless of representation format.

---

Why This Matters

IPv4 addresses can be represented in IPv6 as IPv4-mapped addresses (e.g., "::ffff:192.168.1.1"), which are equivalent to their native IPv4 forms but will not compare equal as strings.

This helper resolves both input strings using inet_pton() and normalizes any IPv4 addresses into the IPv6-mapped space for byte-wise comparison.

---

Supported Inputs

• IPv4 addresses (e.g., "10.0.0.1")
• IPv6 addresses (e.g., "2001:db8::1")
• IPv4-mapped IPv6 addresses (e.g., "::ffff:10.0.0.1")

---

Parameters

[in]	ip1	First IP address as a numeric string.
[in]	ip2	Second IP address as a numeric string.

Returns

true if the addresses are equivalent (including cross-family matches), false otherwise.

Note

This function performs no DNS resolution. Only numeric addresses are supported.

Both inputs must be valid IP addresses. Invalid strings return false.

See also

getBoundLocalIp(), getMTU(), inet_pton()

nextDatagramSize()

std::size_t jsocketpp::internal::nextDatagramSize ( SOCKET fd )

inlinenoexcept

Query the exact size of the next UDP datagram, if the platform can provide it.

On many platforms, FIONREAD returns the size of the next pending datagram in bytes. On POSIX systems where FIONREAD is not reliable, we fall back to a zero-length recvfrom() with MSG_PEEK|MSG_TRUNC, which returns the exact datagram size without consuming it. If neither path yields a size, returns 0 and the caller must choose a fallback (e.g., internal buffer size or a default).

This function is stateless and does not modify socket state.

Parameters

[in]

fd

Socket descriptor/handle.

Returns

Size in bytes of the next UDP datagram, or 0 if unknown.

Example

const std::size_t n = jsocketpp::internal::nextDatagramSize(sockFd);
if (n == 0) {
    // fall back to buffer/default
}

Since

1.0

recvInto()

ssize_t jsocketpp::internal::recvInto ( const SOCKET fd, std::span< std::byte > dst, const int flags, sockaddr_storage * src, socklen_t * srcLen )

inline

Receive into a caller-provided span, routing to recv() or recvfrom() as needed.

If src and srcLen are non-null, this calls recvfrom() and fills the sender address; otherwise, it calls recv(). The function performs the platform-specific cast for the length parameter on Windows.

Parameters

[in]	fd	Socket descriptor/handle.
[in,out]	dst	Destination buffer span. The function attempts to fill up to dst.size() bytes.
[in]	flags	Receive flags (e.g., 0, MSG_PEEK).
[out]	src	Optional sender address storage for unconnected sockets; may be null.
[in,out]	srcLen	Length in/out of src; may be null if src is null.

Return values

>=0	The number of bytes received (may be 0 for zero-length UDP datagrams).
SOCKET_ERROR	On error; call GetSocketError() for details.

Note

This function does not throw; it mirrors the system call semantics.

Since

1.0

throwLastSockError()

void jsocketpp::internal::throwLastSockError ( const std::source_location & loc = std::source_location::current() )

inline

Throw a SocketException for the last socket error, with optional source-location context.

Captures the thread-local last socket error via GetSocketError() and throws using the project’s canonical two-argument pattern:

throw SocketException(err, SocketErrorMessage(err));

When internal error-context is enabled (see build-time switch JSOCKETPP_INCLUDE_ERROR_CONTEXT), the human-readable message is augmented with call-site information derived from std::source_location (i.e., file:line function). This function is marked [[noreturn]] and always throws.

Parameters

[in]

loc

Call-site source information. Defaults to std::source_location::current().

Exceptions

SocketException

Always thrown. The first argument is the integer error code returned by GetSocketError(). The second argument is the human-readable message produced by SocketErrorMessage(err), optionally suffixed with the source location when enabled.

Note

Requires C++20 (<source_location>).

Thread-safe: reads a thread-local error code (GetSocketError() should return the error for the calling thread).

Example

// Typical usage in an error branch:
if (n == SOCKET_ERROR) {
    jsocketpp::internal::throwLastSockError(); // source location captured automatically
}

See also

GetSocketError(), SocketErrorMessage(int), SocketException

Since

1.0