 |
jsocketpp 1.0
A cross-platform C++20 socket library.
|
|
jsocketpp 1.0
A cross-platform C++20 socket library.
|
Low-level socket configuration options exposed via the Socket and related classes. More...
Classes | |
| class | jsocketpp::SocketOptions |
| Public base class for raw socket option access via setsockopt() and getsockopt(). More... | |
Functions | |
| int | jsocketpp::MulticastSocket::getTimeToLive () const |
| Get the current default multicast TTL / hop limit cached on this socket. | |
| bool | jsocketpp::MulticastSocket::getLoopbackMode () const |
| Get the current multicast loopback mode cached on this socket. | |
| void | jsocketpp::ServerSocket::setSoTimeout (const int timeoutMillis) |
| Set the logical timeout (in milliseconds) for accepting client connections. | |
| int | jsocketpp::ServerSocket::getSoTimeout () const noexcept |
| Get the logical timeout (in milliseconds) for accept operations. | |
| bool | jsocketpp::ServerSocket::isPassiveSocket () const noexcept override |
| Identifies this socket as a passive (listening) socket. | |
| jsocketpp::SocketOptions::SocketOptions ()=delete | |
| Default constructor (deleted) for SocketOptions base class. | |
| jsocketpp::SocketOptions::SocketOptions (const SOCKET sock) noexcept | |
| Initializes the socket option interface with a specific socket descriptor. | |
| virtual | jsocketpp::SocketOptions::~SocketOptions ()=default |
| Virtual destructor for safe polymorphic destruction. | |
| jsocketpp::SocketOptions::SocketOptions (const SocketOptions &)=delete | |
| Copy constructor (deleted) for SocketOptions. | |
| jsocketpp::SocketOptions::SocketOptions (SocketOptions &&) noexcept=default | |
| Move constructor for SocketOptions. | |
| SocketOptions & | jsocketpp::SocketOptions::operator= (const SocketOptions &)=delete |
| Copy assignment operator (deleted) for SocketOptions. | |
| SocketOptions & | jsocketpp::SocketOptions::operator= (SocketOptions &&) noexcept=default |
| Move assignment operator for SocketOptions. | |
| SOCKET | jsocketpp::SocketOptions::getSocketFd () const noexcept |
| Retrieves the native socket handle (file descriptor or OS-level handle). | |
| void | jsocketpp::SocketOptions::setOption (int level, int optName, int value) |
| Sets a low-level socket option on the underlying socket. | |
| void | jsocketpp::SocketOptions::setOption (int level, int optName, const void *value, socklen_t len) |
| Sets a low-level socket option using a structured or binary value. | |
| int | jsocketpp::SocketOptions::getOption (int level, int optName) const |
| Retrieves the current value of a low-level socket option. | |
| void | jsocketpp::SocketOptions::getOption (int level, int optName, void *result, socklen_t *len) const |
| Retrieves a socket option into a structured or binary buffer. | |
| void | jsocketpp::SocketOptions::setReuseAddress (bool on) |
| Enables or disables the SO_REUSEADDR socket option. | |
| bool | jsocketpp::SocketOptions::getReuseAddress () const |
| Queries whether the socket is currently configured to allow address reuse. | |
| void | jsocketpp::SocketOptions::setReceiveBufferSize (std::size_t size) |
| Sets the socket's receive buffer size (SO_RCVBUF). | |
| int | jsocketpp::SocketOptions::getReceiveBufferSize () const |
| Retrieves the current receive buffer size (SO_RCVBUF) of the socket. | |
| void | jsocketpp::SocketOptions::setSendBufferSize (std::size_t size) |
| Sets the socket's send buffer size (SO_SNDBUF). | |
| int | jsocketpp::SocketOptions::getSendBufferSize () const |
| Retrieves the current send buffer size (SO_SNDBUF) of the socket. | |
| void | jsocketpp::SocketOptions::setSoLinger (bool enable, int seconds) |
| Configures the socket's linger behavior (SO_LINGER) during close. | |
| std::pair< bool, int > | jsocketpp::SocketOptions::getSoLinger () const |
| Retrieves the current SO_LINGER configuration of the socket. | |
| void | jsocketpp::SocketOptions::setKeepAlive (bool on) |
| Enables or disables TCP-level keepalive behavior on the socket (SO_KEEPALIVE). | |
| bool | jsocketpp::SocketOptions::getKeepAlive () const |
| Checks whether TCP-level keepalive (SO_KEEPALIVE) is currently enabled. | |
| void | jsocketpp::SocketOptions::setSoRecvTimeout (int millis) |
| Sets the socket receive timeout (SO_RCVTIMEO) in milliseconds. | |
| void | jsocketpp::SocketOptions::setSoSendTimeout (int millis) |
| Sets the socket send timeout (SO_SNDTIMEO) in milliseconds. | |
| int | jsocketpp::SocketOptions::getSoRecvTimeout () const |
| Retrieves the socket receive timeout (SO_RCVTIMEO) in milliseconds. | |
| int | jsocketpp::SocketOptions::getSoSendTimeout () const |
| Retrieves the socket send timeout (SO_SNDTIMEO) in milliseconds. | |
| void | jsocketpp::SocketOptions::setNonBlocking (bool nonBlocking) |
| Enables or disables non-blocking mode on the socket. | |
| bool | jsocketpp::SocketOptions::getNonBlocking () const |
| Queries whether the socket is currently in non-blocking mode. | |
| void | jsocketpp::SocketOptions::setTcpNoDelay (bool on) |
| Enables or disables Nagle’s algorithm (TCP_NODELAY) on TCP sockets. | |
| bool | jsocketpp::SocketOptions::getTcpNoDelay () const |
| Queries whether Nagle's algorithm (TCP_NODELAY) is currently disabled. | |
| void | jsocketpp::SocketOptions::setBroadcast (bool on) |
| Enables or disables the ability to send UDP broadcast messages. | |
| bool | jsocketpp::SocketOptions::getBroadcast () const |
| Checks whether the socket is currently allowed to send broadcast messages. | |
| void | jsocketpp::SocketOptions::setIPv6Only (bool enable) |
| Enables or disables IPV6_V6ONLY mode for IPv6-capable sockets. | |
| bool | jsocketpp::SocketOptions::getIPv6Only () const |
| Queries whether the IPV6_V6ONLY option is enabled on this socket. | |
| void | jsocketpp::SocketOptions::setReusePort (const bool enable) |
| Enables or disables the SO_REUSEPORT socket option. | |
| bool | jsocketpp::SocketOptions::getReusePort () const |
| Checks whether the SO_REUSEPORT option is currently enabled on the socket. | |
| void | jsocketpp::SocketOptions::setMulticastTTL (int ttl) |
| Set the default multicast hop limit / TTL for this socket. | |
| int | jsocketpp::SocketOptions::getMulticastTTL () const |
| Get the socket’s default multicast hop limit / TTL. | |
| void | jsocketpp::SocketOptions::setMulticastLoopback (bool enable) |
| Enable or disable multicast loopback for this socket. | |
| bool | jsocketpp::SocketOptions::getMulticastLoopback () const |
| Read the socket’s multicast loopback flag. | |
| void | jsocketpp::SocketOptions::setMulticastInterfaceIPv4 (in_addr addr) |
| Select the outgoing IPv4 interface for multicast. | |
| void | jsocketpp::SocketOptions::setMulticastInterfaceIPv6 (unsigned int ifindex) |
| Select the outgoing IPv6 interface for multicast. | |
| void | jsocketpp::SocketOptions::joinGroupIPv4 (in_addr group, in_addr iface) |
| Join an IPv4 any-source multicast (ASM) group on a specific interface. | |
| void | jsocketpp::SocketOptions::leaveGroupIPv4 (in_addr group, in_addr iface) |
| Leave a previously joined IPv4 multicast group on a specific interface. | |
| void | jsocketpp::SocketOptions::joinGroupIPv6 (in6_addr group, unsigned int ifindex) |
| Join an IPv6 any-source multicast (ASM) group on a specific interface index. | |
| void | jsocketpp::SocketOptions::leaveGroupIPv6 (in6_addr group, unsigned int ifindex) |
| Leave a previously joined IPv6 multicast group on a specific interface index. | |
| void | jsocketpp::SocketOptions::setSocketFd (const SOCKET sock) noexcept |
| Updates the socket descriptor used by this object. | |
| virtual bool | jsocketpp::SocketOptions::isPassiveSocket () const noexcept |
| Indicates whether the socket behaves as a passive (listening) socket. | |
| static bool | jsocketpp::SocketOptions::is_ipv4_multicast (const in_addr v4) |
| Test whether an IPv4 address is in the multicast range (224.0.0.0/4). | |
| static bool | jsocketpp::SocketOptions::is_ipv6_multicast (const in6_addr &v6) |
| Test whether an IPv6 address is in the multicast range (ff00::/8). | |
| static int | jsocketpp::SocketOptions::detectFamily (SOCKET fd) |
| Determine the address family (AF_INET or AF_INET6) of a socket. | |
Low-level socket configuration options exposed via the Socket and related classes.
This module contains functions and accessors for configuring standard socket options such as SO_LINGER, SO_RCVTIMEO, TCP_NODELAY, SO_REUSEADDR, and SO_KEEPALIVE.
These options provide fine-grained control over low-level socket behavior such as timeout behavior, connection shutdown semantics, buffering, and performance tuning.
All functions in this group are cross-platform abstractions over setsockopt() and getsockopt().
|
staticnodiscardprotected |
Determine the address family (AF_INET or AF_INET6) of a socket.
Returns the protocol family with which fd was created. On platforms that support it, this first attempts getsockopt(SOL_SOCKET, SO_DOMAIN, ...) and falls back to getsockname() for broad compatibility.
The result is used to pick the correct per-family options for subsequent operations (e.g., IP_MULTICAST_TTL vs IPV6_MULTICAST_HOPS, IP_MULTICAST_LOOP vs IPV6_MULTICAST_LOOP, IP_MULTICAST_IF vs IPV6_MULTICAST_IF, and IPv4/IPv6 group membership APIs).
| [in] | fd | The socket handle to inspect. Must be a valid datagram or stream socket. |
fd is a valid, open socket descriptor/handle.| SocketException |
|
|
nodiscard |
Checks whether the socket is currently allowed to send broadcast messages.
This method retrieves the SO_BROADCAST option using getsockopt() to determine whether the socket can send datagrams to broadcast addresses like 255.255.255.255.
| SocketException | if:
|
|
nodiscard |
Queries whether the IPV6_V6ONLY option is enabled on this socket.
This method checks whether the socket is currently restricted to IPv6-only traffic, or whether it allows dual-stack operation (accepting both IPv6 and IPv4-mapped addresses).
The IPV6_V6ONLY flag is primarily relevant to sockets using the AF_INET6 address family.
| SocketException | if:
|
|
nodiscard |
Checks whether TCP-level keepalive (SO_KEEPALIVE) is currently enabled.
This method queries the socket's current SO_KEEPALIVE setting, which determines whether the operating system sends periodic keepalive probes to verify that idle, stream-oriented connections are still alive.
Keepalive is especially useful for detecting silent disconnects in long-lived connections (e.g., crash, power loss, cable pull) where no TCP FIN/RST is received.
| SocketException | if:
|
|
inlinenodiscard |
Get the current multicast loopback mode cached on this socket.
Reports whether this object is configured to receive local copies of its own multicast transmissions (“loopback”). The value reflects the last successful call to setLoopbackMode(bool) made through this class; it does not perform a fresh kernel query.
Semantics of the returned flag:
This accessor concerns multicast only; it does not affect nor report unicast behavior.
|
nodiscard |
Read the socket’s multicast loopback flag.
Queries whether multicast datagrams transmitted by this socket are eligible for local delivery back to the host (“loopback”).
Semantics of the returned flag:
This is a read-only query of the per-socket default and does not affect unicast traffic, nor does it consider any per-message control data. It reports the socket’s current loopback policy only.
| SocketException | If the query fails for any of the reasons above. The exception carries the OS error code and a descriptive message produced by SocketErrorMessage(...). |
|
nodiscard |
Get the socket’s default multicast hop limit / TTL.
Returns the current per-socket default scope used for outbound multicast transmissions:
The returned value determines how far multicast packets sent from this socket may propagate by default:
This query does not affect unicast traffic—use IP_TTL / IPV6_UNICAST_HOPS for unicast scope—and does not consider any per-message overrides supplied via ancillary data (e.g., IP_MULTICAST_TTL / IPV6_HOPLIMIT control messages). It reports the socket’s default only.
| SocketException | If the query fails for any of the reasons above. The exception carries the OS error code and a descriptive message produced by SocketErrorMessage(...). |
|
nodiscard |
Queries whether the socket is currently in non-blocking mode.
This method inspects the I/O mode of the socket and returns true if it is configured for non-blocking operations. In non-blocking mode, I/O system calls return immediately if they cannot complete, rather than blocking the calling thread.
| SocketException | if:
|
|
nodiscard |
Retrieves the current value of a low-level socket option.
This method queries a socket option using the system-level getsockopt() interface. It returns the current value as an integer and is useful for inspecting platform defaults, runtime configuration, or verifying changes made via setOption().
This method is supported by all socket types provided by the library:
It supports standard protocol levels such as SOL_SOCKET, IPPROTO_TCP, and IPPROTO_UDP.
| [in] | level | Protocol level (e.g., SOL_SOCKET, IPPROTO_TCP) |
| [in] | optName | Socket option name (e.g., SO_KEEPALIVE, SO_SNDBUF) |
| SocketException | if:
|
| void jsocketpp::SocketOptions::getOption | ( | int | level, |
| int | optName, | ||
| void * | result, | ||
| socklen_t * | len ) const |
Retrieves a socket option into a structured or binary buffer.
This overload of getOption() allows querying complex or platform-specific socket options that require structured output (e.g., struct linger, struct timeval, etc.). It wraps the system-level getsockopt() call using a raw memory buffer and returns the result through the provided pointer.
The semantics are identical to the getOption(int, int) overload, but this version is used for retrieving non-integer options.
This method works uniformly across:
| [in] | level | Protocol level (e.g., SOL_SOCKET, IPPROTO_TCP) |
| [in] | optName | Socket option name (e.g., SO_LINGER) |
| [out] | result | Pointer to a buffer to receive the option value |
| [out] | len | Pointer to the size of the buffer. On return, holds the actual size used. |
| SocketException | if:
|
|
nodiscard |
Retrieves the current receive buffer size (SO_RCVBUF) of the socket.
Queries the operating system for the size of the receive buffer allocated to this socket. This buffer temporarily holds incoming data before it is read by the application. The size is determined by system policy, user configuration, and the value set via setReceiveBufferSize().
This method works for:
| SocketException | if:
|
|
nodiscard |
Queries whether the socket is currently configured to allow address reuse.
This method retrieves the state of the SO_REUSEADDR socket option using getsockopt(). When enabled, it allows the socket to bind to a local address/port that is already in use or still in the TIME_WAIT state. This is particularly useful in scenarios such as:
| SocketException | if the socket is invalid or the option cannot be retrieved. |
|
nodiscard |
Checks whether the SO_REUSEPORT option is currently enabled on the socket.
This method queries the SO_REUSEPORT setting via getsockopt() to determine whether the socket is configured to allow multiple bindings to the same address/port.
| SocketException | if:
|
|
nodiscard |
Retrieves the current send buffer size (SO_SNDBUF) of the socket.
Queries the operating system for the size of the send buffer allocated to this socket. This buffer holds outgoing data that has been written by the application but not yet transmitted over the network or IPC channel. A larger send buffer allows the socket to tolerate bursts of data or temporary network slowdowns without blocking the writer.
This method is supported for:
| SocketException | if:
|
|
inlinenodiscardnoexcept |
Retrieves the native socket handle (file descriptor or OS-level handle).
This method provides low-level access to the socket’s operating system identifier:
It is intended for advanced use cases only, such as:
This method exposes the raw handle without ownership transfer. Misuse may lead to:
|
nodiscard |
Retrieves the current SO_LINGER configuration of the socket.
Queries the operating system for the current linger behavior configured on this socket. Linger settings determine whether the socket blocks on close() to allow unsent data to be transmitted, or terminates the connection immediately (potentially discarding unsent data).
Returns a pair {enabled, timeout}:
| SocketException | if:
|
|
nodiscard |
Retrieves the socket receive timeout (SO_RCVTIMEO) in milliseconds.
This method queries the configured timeout for blocking read operations, such as read(), readExact(), receiveFrom(), etc. The value returned represents the number of milliseconds a read will block before failing with a timeout.
| SocketException | if:
|
|
nodiscard |
Retrieves the socket send timeout (SO_SNDTIMEO) in milliseconds.
This method queries the configured timeout for blocking send operations, such as write(), writeAll(), or sendTo(). The returned value represents how long a send operation will block before timing out.
| SocketException | if:
|
|
inlinenodiscardnoexcept |
Get the logical timeout (in milliseconds) for accept operations.
This value determines how long methods like accept() and tryAccept() will wait for an incoming client connection before timing out. It is used internally by select() or similar readiness mechanisms.
|
nodiscard |
Queries whether Nagle's algorithm (TCP_NODELAY) is currently disabled.
This method checks if TCP_NODELAY is set on the socket, which controls the behavior of Nagle's algorithm for TCP connections. When TCP_NODELAY is enabled (true), small writes are sent immediately without waiting to coalesce packets. When disabled (false), the system may buffer small packets to improve network efficiency.
This option applies only to:
It does not apply to:
| SocketException | if:
|
|
inline |
Get the current default multicast TTL / hop limit cached on this socket.
Returns this object’s cached per-socket default scope for outbound multicast transmissions as last set via setTimeToLive(int). It does not perform a fresh kernel query and does not affect any state.
Semantics of the returned value (applies to multicast only):
|
inlinestaticprotected |
Test whether an IPv4 address is in the multicast range (224.0.0.0/4).
Lightweight predicate that checks if v4 lies within the IPv4 multicast block 224.0.0.0/4 (i.e., 224.0.0.0–239.255.255.255). Internally uses the standard IN_MULTICAST() macro against the host-order form of the address.
| [in] | v4 | IPv4 address in a POSIX in_addr struct. Byte order: v4.s_addr must be in network byte order (as produced by inet_pton(AF_INET, ...) or stored in socket APIs). This helper converts to host order before evaluation. |
|
inlinestaticprotected |
Test whether an IPv6 address is in the multicast range (ff00::/8).
Lightweight predicate that checks if v6 lies within the IPv6 multicast prefix ff00::/8. Internally uses the standard IN6_IS_ADDR_MULTICAST() macro.
| [in] | v6 | IPv6 address in a POSIX in6_addr struct. No byte-order adjustment is required by the caller; the macro reads the struct fields directly. |
|
inlinenodiscardoverrideprotectedvirtualnoexcept |
Identifies this socket as a passive (listening) socket.
Overrides the base SocketOptions::isPassiveSocket() to return true, indicating that this ServerSocket instance is intended to accept incoming connections rather than initiate outbound ones.
This designation is important for platform-specific behaviors — particularly on Windows, where passive sockets use SO_EXCLUSIVEADDRUSE instead of SO_REUSEADDR to control address reuse semantics. The SocketOptions interface uses this signal to select the correct option and logic in setReuseAddress() and getReuseAddress().
Reimplemented from jsocketpp::SocketOptions.
|
inlinenodiscardprotectedvirtualnoexcept |
Indicates whether the socket behaves as a passive (listening) socket.
This virtual method is used internally by the SocketOptions interface to determine whether the socket is operating in a passive role — that is, it is a listening socket typically created by a server to accept incoming connections. This distinction is particularly relevant on platforms like Windows, where different socket options apply to passive vs. active sockets.
Specifically, this affects how address reuse logic is applied:
Reimplemented in jsocketpp::ServerSocket.
| void jsocketpp::SocketOptions::joinGroupIPv4 | ( | in_addr | group, |
| in_addr | iface ) |
Join an IPv4 any-source multicast (ASM) group on a specific interface.
Joins group on the IPv4 interface identified by iface. The interface must be specified by its unicast IPv4 address (network order). Use {INADDR_ANY} to let the stack choose a default interface.
| [in] | group | Multicast group address (network order). Must satisfy IN_MULTICAST(). |
| [in] | iface | Local interface address (network order). Use {INADDR_ANY} for default. |
| SocketException | If the socket is invalid, group is not multicast, or the underlying setsockopt(IP_ADD_MEMBERSHIP) fails. Error text is produced by SocketErrorMessage(...). |
| void jsocketpp::SocketOptions::joinGroupIPv6 | ( | in6_addr | group, |
| unsigned int | ifindex ) |
Join an IPv6 any-source multicast (ASM) group on a specific interface index.
Joins group on the interface identified by ifindex. Use 0 for the default interface. group must be a multicast address.
| [in] | group | IPv6 multicast group address. |
| [in] | ifindex | IPv6 interface index (0 for default). |
| SocketException | If the socket is invalid, group is not multicast, or the underlying setsockopt(IPV6_JOIN_GROUP) (POSIX) or IPV6_ADD_MEMBERSHIP (Windows) fails. |
| void jsocketpp::SocketOptions::leaveGroupIPv4 | ( | in_addr | group, |
| in_addr | iface ) |
Leave a previously joined IPv4 multicast group on a specific interface.
| [in] | group | Multicast group address (network order). |
| [in] | iface | Interface address used when joining (network order). |
| SocketException | on failure of setsockopt(IP_DROP_MEMBERSHIP). |
| void jsocketpp::SocketOptions::leaveGroupIPv6 | ( | in6_addr | group, |
| unsigned int | ifindex ) |
Leave a previously joined IPv6 multicast group on a specific interface index.
| [in] | group | IPv6 multicast group address. |
| [in] | ifindex | Interface index used when joining. |
| SocketException | on failure of IPV6_LEAVE_GROUP (POSIX) or IPV6_DROP_MEMBERSHIP (Windows). |
|
delete |
Copy assignment operator (deleted) for SocketOptions.
The copy assignment operator is explicitly deleted to prevent reassignment between SocketOptions instances. Copying would duplicate the socket handle without transferring ownership, leading to potential issues such as:
This deletion is consistent with the rest of the socket library, where all socket classes are designed to be non-copyable and resource-owning via RAII.
|
defaultnoexcept |
Move assignment operator for SocketOptions.
Transfers the socket handle (_sockFd) and internal state from another SocketOptions instance to this one. Any existing state in the current object is overwritten. The moved-from object is left in a valid but unspecified state (usually with _sockFd == INVALID_SOCKET).
This operator supports efficient reassignment of socket resources in derived classes while preserving RAII guarantees and preventing resource leaks.
| void jsocketpp::SocketOptions::setBroadcast | ( | bool | on | ) |
Enables or disables the ability to send UDP broadcast messages.
This method sets the SO_BROADCAST socket option, which allows the socket to send datagrams to broadcast addresses (e.g., 255.255.255.255 or 192.168.1.255).
| [in] | on | true to enable broadcast permission, false to disable it. |
| SocketException | if:
|
| void jsocketpp::SocketOptions::setIPv6Only | ( | bool | enable | ) |
Enables or disables IPV6_V6ONLY mode for IPv6-capable sockets.
This method configures the IPV6_V6ONLY socket option, which determines whether an IPv6 socket can accept only IPv6 connections or both IPv6 and IPv4-mapped addresses (e.g., ::ffff:a.b.c.d).
⚠️ On all platforms, this option must be set before bind(). Changing it afterward is undefined or ignored.
| [in] | enable | true to enable IPv6-only mode (IPV6_V6ONLY = 1), false to allow dual-stack operation (IPV6_V6ONLY = 0). |
| SocketException | if:
|
| void jsocketpp::SocketOptions::setKeepAlive | ( | bool | on | ) |
Enables or disables TCP-level keepalive behavior on the socket (SO_KEEPALIVE).
Configures the SO_KEEPALIVE socket option, which instructs the operating system to periodically send keepalive probes on otherwise idle stream-oriented sockets. This helps detect half-open connections where the remote peer has silently disconnected, crashed, or become unreachable without sending a FIN or RST.
| [in] | on | Set to true to enable keepalive, or false to disable it. |
| SocketException | if:
|
| void jsocketpp::SocketOptions::setMulticastInterfaceIPv4 | ( | in_addr | addr | ) |
Select the outgoing IPv4 interface for multicast.
Sets the per-socket default egress interface used for IPv4 multicast transmissions. For IPv4, the egress is specified by the interface’s unicast IPv4 address. Passing INADDR_ANY (in network byte order) restores the system default route.
This call affects only outbound multicast selection for the IPv4 family; it does not join or leave any multicast group, and it does not affect IPv6.
| [in] | addr | IPv4 address (network byte order) of the desired egress interface. Use in_addr{ .s_addr = htonl(INADDR_ANY) } to reset to the system default. |
| SocketException | If the option cannot be applied. The exception carries the OS error code and a descriptive message produced by SocketErrorMessage(...). |
addr is currently assigned to a local interface. Some stacks may accept the option but later fail to send if routing is not feasible. Prefer to pass an address you know is bound to a local interface.| void jsocketpp::SocketOptions::setMulticastInterfaceIPv6 | ( | unsigned int | ifindex | ) |
Select the outgoing IPv6 interface for multicast.
Sets the per-socket default egress interface used for IPv6 multicast transmissions by specifying a numeric interface index. Passing 0 resets to the system default route.
This call affects only outbound IPv6 multicast selection; it does not join or leave any multicast group and does not affect IPv4 egress.
| [in] | ifindex | IPv6 interface index for multicast egress. Use 0 to restore the system default. On POSIX systems you can obtain this via if_nametoindex(). |
| SocketException | If the option cannot be applied. The exception carries the OS error code and a descriptive message produced by SocketErrorMessage(...). |
| void jsocketpp::SocketOptions::setMulticastLoopback | ( | bool | enable | ) |
Enable or disable multicast loopback for this socket.
Controls whether multicast datagrams transmitted by this socket are delivered back to the local host (“looped back”). This affects only local delivery; it does not influence what remote receivers get.
Semantics (effective for packets sent by this socket):
This setting is per-socket and applies to subsequent sends until changed. It does not affect unicast traffic, and it does not force other sockets to receive or drop multicast that originates elsewhere.
| [in] | enable | true to enable local loopback of this socket’s multicast transmissions; false to suppress local loopback. |
| SocketException | If the option cannot be set for any of the reasons above. The exception includes the OS error code and a descriptive message from SocketErrorMessage(...). |
| void jsocketpp::SocketOptions::setMulticastTTL | ( | int | ttl | ) |
Set the default multicast hop limit / TTL for this socket.
Sets the per-socket default scope for multicast transmissions:
The value controls how far outbound multicast packets may travel:
This setting applies to subsequent multicast sends on this socket until changed again. It does not affect unicast traffic—use IP_TTL / IPV6_UNICAST_HOPS for that.
| [in] | ttl | Hop limit (IPv6) or TTL (IPv4), in the range [0, 255]. |
| SocketException | If ttl is out of range, the socket state is invalid, or the operating system rejects the option. The exception contains the OS error code and a descriptive message produced by SocketErrorMessage(...). |
| void jsocketpp::SocketOptions::setNonBlocking | ( | bool | nonBlocking | ) |
Enables or disables non-blocking mode on the socket.
This method configures the I/O blocking behavior of the socket. In non-blocking mode, system calls such as read(), write(), connect(), and accept() return immediately if they cannot proceed, rather than blocking the calling thread. This enables asynchronous or event-driven designs where the application explicitly manages readiness.
In blocking mode (the default), these calls block the thread until they complete, time out (if configured), or fail.
This operation is available on all socket types in this library:
| Operation | In Blocking Mode | In Non-Blocking Mode |
|---|---|---|
| connect() | Blocks until connected or timeout | Returns immediately; may require polling write |
| read() | Waits for data or EOF | Returns -1 with EWOULDBLOCK if no data |
| write() | Waits for buffer availability | Returns -1 if buffer full |
| accept() | Waits for pending connection | Returns -1 with EWOULDBLOCK if none available |
| recvfrom() | Waits for incoming datagram | Returns -1 if no datagram received |
| [in] | nonBlocking | true to enable non-blocking mode, false to restore blocking mode. |
| SocketException | if:
|
| void jsocketpp::SocketOptions::setOption | ( | int | level, |
| int | optName, | ||
| const void * | value, | ||
| socklen_t | len ) |
Sets a low-level socket option using a structured or binary value.
This overload of setOption() configures advanced socket options that require passing complex values via a memory buffer, such as struct linger, protocol-specific flags, or platform-defined structures.
Socket options allow advanced users to customize performance, transport behavior, and resource usage. This method is applicable to all supported socket types:
It supports options at various protocol levels, including:
| [in] | level | Protocol level (e.g., SOL_SOCKET, IPPROTO_TCP) |
| [in] | optName | Option name (e.g., SO_LINGER, IP_TOS) |
| [in] | value | Pointer to a buffer containing the option value |
| [in] | len | Size of the buffer in bytes |
| SocketException | if:
|
| void jsocketpp::SocketOptions::setOption | ( | int | level, |
| int | optName, | ||
| int | value ) |
Sets a low-level socket option on the underlying socket.
This method configures a socket option using the system-level setsockopt() interface. Socket options allow advanced users to fine-tune behavior related to performance, protocol semantics, reliability, and resource usage.
This API is available on all socket types provided by the library, including:
It supports options at multiple protocol levels, such as SOL_SOCKET, IPPROTO_TCP, and IPPROTO_UDP.
| [in] | level | The protocol level at which the option resides (e.g., SOL_SOCKET, IPPROTO_TCP). |
| [in] | optName | The name of the socket option (e.g., SO_REUSEADDR, TCP_NODELAY). |
| [in] | value | Integer value to assign to the option. |
| SocketException | if:
|
| void jsocketpp::SocketOptions::setReceiveBufferSize | ( | std::size_t | size | ) |
Sets the socket's receive buffer size (SO_RCVBUF).
Configures the size of the kernel-level receive buffer for the underlying socket. This buffer controls how much data the operating system can queue before the application reads from the socket. Increasing this value can reduce packet loss and improve throughput under high load or network delay.
This method is valid for all supported socket types:
| [in] | size | Desired receive buffer size in bytes. Actual value may be adjusted by the OS. |
| SocketException | if:
|
| void jsocketpp::SocketOptions::setReuseAddress | ( | bool | on | ) |
Enables or disables the SO_REUSEADDR socket option.
This option controls whether the socket is permitted to bind to a local address and port that is already in use or in the TIME_WAIT state. It is commonly used in both server and client contexts, and is applicable to TCP, UDP, and Unix domain sockets.
Internally, this method invokes:
| [in] | on | If true, enables address reuse; if false, disables it. |
| SocketException | if the socket is invalid or the option cannot be set. |
| void jsocketpp::SocketOptions::setReusePort | ( | const bool | enable | ) |
Enables or disables the SO_REUSEPORT socket option.
This method configures the SO_REUSEPORT option, which allows multiple sockets to bind to the same IP address and port combination, enabling parallelism in multi-threaded or multi-process applications. Unlike SO_REUSEADDR, which allows re-binding during TIME_WAIT, SO_REUSEPORT permits simultaneous binding by multiple sockets.
| [in] | enable | true to allow multiple sockets to bind the same port (SO_REUSEPORT = 1), or false to disable the shared binding behavior (SO_REUSEPORT = 0). |
| SocketException | if:
|
| void jsocketpp::SocketOptions::setSendBufferSize | ( | std::size_t | size | ) |
Sets the socket's send buffer size (SO_SNDBUF).
Configures the size of the kernel-level send buffer for this socket. This buffer controls how much data the operating system can queue for transmission before blocking the sender or returning a partial write. Larger buffers help improve throughput, especially in high-bandwidth or high-latency network environments.
This method is valid for all socket types:
| [in] | size | Desired send buffer size in bytes. The actual buffer size may be adjusted by the system. |
| SocketException | if:
|
|
inlineprotectednoexcept |
Updates the socket descriptor used by this object.
This method sets the internal socket file descriptor used by the SocketOptions interface. It is typically called by derived classes after the socket has been moved, reassigned, or otherwise changed during the object's lifetime.
This does not open, close, or validate the socket descriptor. It simply updates the internal _sockFd used by methods such as setOption() and getOption().
| [in] | sock | The new socket file descriptor to associate with this object. May be INVALID_SOCKET to mark the socket as uninitialized or closed. |
| void jsocketpp::SocketOptions::setSoLinger | ( | bool | enable, |
| int | seconds ) |
Configures the socket's linger behavior (SO_LINGER) during close.
This method sets the SO_LINGER socket option, which controls how the socket behaves when it is closed and unsent data remains in the transmission buffer. It determines whether close() will return immediately (discarding unsent data), or block until the data is transmitted or a timeout expires.
| [in] | enable | Whether to enable lingering behavior on close. |
| [in] | seconds | Linger timeout (in seconds). Only meaningful if enable == true.
|
| SocketException | if:
|
| void jsocketpp::SocketOptions::setSoRecvTimeout | ( | int | millis | ) |
Sets the socket receive timeout (SO_RCVTIMEO) in milliseconds.
This method configures how long a blocking read operation may wait for incoming data before timing out. It affects all socket types that perform blocking I/O, including:
A timeout of 0 disables the timeout entirely, causing read operations to block indefinitely until data is available, the connection is closed, or an error occurs. A negative timeout is invalid and will result in an exception.
| [in] | millis | Timeout in milliseconds. Must be ≥ 0. Use 0 to disable the timeout. |
| SocketException | if:
|
| void jsocketpp::SocketOptions::setSoSendTimeout | ( | int | millis | ) |
Sets the socket send timeout (SO_SNDTIMEO) in milliseconds.
This method configures how long a blocking send operation (e.g., write(), writeAll()) may block before timing out. It affects all socket types that support writing:
A timeout of 0 disables the timeout entirely, allowing send operations to block indefinitely until buffer space is available. A negative timeout is invalid and will result in an exception.
| [in] | millis | Timeout in milliseconds. Must be ≥ 0. Use 0 to disable the timeout. |
| SocketException | if:
|
|
inline |
Set the logical timeout (in milliseconds) for accepting client connections.
This timeout applies to methods like accept() and tryAccept(), and determines how long the server socket will wait for a client connection before timing out.
Unlike Socket::setSoTimeout(), this method does not call setsockopt() and does not affect the underlying socket descriptor. Instead, it is used internally to control the behavior of select() during accept operations.
| timeoutMillis | Timeout value in milliseconds |
| void jsocketpp::SocketOptions::setTcpNoDelay | ( | bool | on | ) |
Enables or disables Nagle’s algorithm (TCP_NODELAY) on TCP sockets.
This method configures the TCP_NODELAY option, which controls the behavior of Nagle's algorithm for stream-oriented TCP sockets (SOCK_STREAM). Nagle's algorithm aims to reduce network congestion by delaying small outgoing packets until previous ones are acknowledged — effectively "coalescing" writes.
Disabling Nagle’s algorithm (i.e., setting TCP_NODELAY = 1) allows small packets to be sent immediately, which is ideal for latency-sensitive applications. Enabling it (i.e., setting TCP_NODELAY = 0) improves throughput by batching writes, but introduces potential delays.
| [in] | on | If true, disables Nagle's algorithm (TCP_NODELAY = 1), enabling immediate sends. If false, enables Nagle's algorithm (TCP_NODELAY = 0) to batch small writes. |
| SocketException | if:
|
|
delete |
Default constructor (deleted) for SocketOptions base class.
This constructor is explicitly deleted to prevent the creation of uninitialized SocketOptions objects. Subclasses like Socket, ServerSocket, or DatagramSocket must initialize the socket handle explicitly via constructor arguments or system calls.
|
inlineexplicitnoexcept |
Initializes the socket option interface with a specific socket descriptor.
Constructs a SocketOptions object that uses the provided socket file descriptor for all subsequent setOption() and getOption() calls. This constructor is intended to be used by derived socket classes (e.g., Socket, ServerSocket, UnixSocket) to delegate option-handling responsibilities without duplicating system-specific logic.
| [in] | sock | A valid socket descriptor (e.g., from socket(), accept(), etc.), or INVALID_SOCKET if the object is not yet initialized. |
|
delete |
Copy constructor (deleted) for SocketOptions.
The copy constructor is explicitly deleted to prevent accidental copying of SocketOptions instances. Since the class wraps a native socket handle (SOCKET), copying it would result in multiple objects referring to the same socket, leading to unsafe behavior such as double-closing or unexpected side effects.
All derived socket classes in the library (e.g., Socket, ServerSocket, DatagramSocket) are also non-copyable to preserve strict ownership semantics and RAII guarantees.
|
defaultnoexcept |
Move constructor for SocketOptions.
Transfers the socket handle (_sockFd) and internal state from another SocketOptions instance. After the move, the source object is left in a valid but unspecified state (typically with _sockFd set to INVALID_SOCKET).
This enables safe and efficient transfer of socket ownership in derived classes, such as Socket, DatagramSocket, or ServerSocket, without invoking unnecessary system calls or duplicating file descriptors.
|
virtualdefault |
Virtual destructor for safe polymorphic destruction.
Ensures that derived classes can be safely destroyed through a pointer to SocketOptions. This is important for preventing resource leaks and undefined behavior when using socket option interfaces polymorphically (e.g., in unit tests or abstraction layers).
This destructor does not perform any cleanup of the socket descriptor itself, as SocketOptions does not own or manage the socket lifecycle. Derived classes are responsible for closing or releasing the socket if needed.
1.15.0