jsocketpp::SocketException Class Reference

Represents socket-related errors in the jsocketpp library. More...

#include <SocketException.hpp>

Inheritance diagram for jsocketpp::SocketException:

Collaboration diagram for jsocketpp::SocketException:

Public Member Functions
	SocketException (const std::string &message="SocketException")
	Constructs a SocketException with a custom error message and no associated error code.
	SocketException (const int code, const std::string &message="SocketException")
	Constructs a SocketException with a platform-specific error code and custom message.
	SocketException (const std::string &message, std::exception_ptr nested)
	Constructs a SocketException with a message and a nested exception.
int	getErrorCode () const noexcept
	Retrieves the platform-specific error code associated with this exception.
std::exception_ptr	getNestedException () const noexcept
	Retrieves the nested exception captured at construction time, if any.
	~SocketException () override=default
	Destroys the SocketException.

Static Private Member Functions
static std::string	buildErrorMessage (const std::string &msg, const int code)
	Builds a formatted error message combining a textual description and an error code.

Private Attributes
int	_errorCode
	Platform-specific error code (e.g., errno, WSA error).
std::exception_ptr	_nested {}
	Captured nested exception for chaining, if any.

Detailed Description

Represents socket-related errors in the jsocketpp library.

SocketException is the standard exception type thrown by the jsocketpp socket library whenever a socket operation fails (e.g., connect, bind, send, or receive). It encapsulates both a platform-specific error code (e.g., errno or WSA error) and a descriptive error message.

The class also supports optional exception chaining through a stored std::exception_ptr, allowing users to propagate and inspect nested causes of socket failures.

Exception Chaining

Nested exceptions can be attached explicitly via constructor or with std::throw_with_nested(), enabling structured error propagation and diagnostics across API boundaries.

Example: Catching and Handling Socket Exceptions

#include <jsocketpp/SocketException.hpp>
#include <jsocketpp/Socket.hpp>
using namespace jsocketpp;
 
try {
    Socket sock("example.com", 80);
    sock.connect();
    // ... other operations ...
} catch (const SocketException& ex) {
    std::cerr << "Socket error (" << ex.getErrorCode() << "): " << ex.what() << std::endl;
    try {
        std::rethrow_if_nested(ex.getNestedException());
    } catch (const std::exception& nested) {
        std::cerr << "Caused by: " << nested.what() << std::endl;
    }
}

Note

This class is exception-safe and designed for cross-platform error reporting.

Nested exceptions are supported but optional.

Constructor & Destructor Documentation

SocketException() [1/2]

jsocketpp::SocketException::SocketException ( const int code, const std::string & message = "SocketException" )

inlineexplicit

Constructs a SocketException with a platform-specific error code and custom message.

This overload is used when a socket-related failure produces a known system error code (such as errno on POSIX or WSAGetLastError() on Windows), which is stored and included in the final exception message.

The formatted error message passed to std::runtime_error includes the original message and the error code (e.g., "Connection failed (error code 111)").

Parameters

code	Integer error code returned by the operating system.
message	Descriptive error message describing the failure context.

See also

getErrorCode()

SocketException() [2/2]

jsocketpp::SocketException::SocketException ( const std::string & message, std::exception_ptr nested )

inline

Constructs a SocketException with a message and a nested exception.

This constructor is used to explicitly chain exceptions by attaching a previously caught exception (via std::current_exception() or std::throw_with_nested()), preserving the original cause.

This enables users to propagate contextual errors while retaining the underlying source of failure. The nested exception can later be retrieved via getNestedException() and rethrown with std::rethrow_if_nested().

Example: Manual nesting

try {
    mayThrow();
} catch (...) {
    throw SocketException("socket failed", std::current_exception());
}

Parameters

message	Descriptive message for the higher-level socket failure.
nested	Exception pointer representing the original cause (typically captured from a catch block).

See also

getNestedException()

std::rethrow_if_nested

~SocketException()

jsocketpp::SocketException::~SocketException ( )

overridedefault

Destroys the SocketException.

This destructor is explicitly marked override to ensure correct polymorphic behavior when SocketException is used through a base class pointer (e.g., std::exception*). It is declared default because the base class destructors (std::runtime_error) and all members (int, std::exception_ptr) are trivially destructible.

No resources are dynamically allocated by this class.

Member Function Documentation

buildErrorMessage()

std::string jsocketpp::SocketException::buildErrorMessage ( const std::string & msg, const int code )

inlinestaticprivate

Builds a formatted error message combining a textual description and an error code.

This utility function is used internally to generate consistent exception messages that include both the high-level context and the underlying system error code.

The resulting string takes the form: "message (error code 123)".

Parameters

msg	Descriptive error message explaining the context of the failure.
code	Platform-specific error code to append (e.g., errno, WSA error).

Returns

Formatted string combining the message and error code.

Note

This method is used by constructors of SocketException and is not intended for external use.

getErrorCode()

int jsocketpp::SocketException::getErrorCode ( ) const

inlinenodiscardnoexcept

Retrieves the platform-specific error code associated with this exception.

The error code is typically captured from system APIs such as errno (on POSIX) or WSAGetLastError() (on Windows), and represents the low-level cause of the socket failure. This code is preserved separately from the textual message and can be used for diagnostics, logging, or error-specific handling.

Returns

Integer error code reported by the system at the time the exception was constructed.

See also

SocketException(int, const std::string&)

getNestedException()

std::exception_ptr jsocketpp::SocketException::getNestedException ( ) const

inlinenodiscardnoexcept

Retrieves the nested exception captured at construction time, if any.

This method returns the std::exception_ptr that was explicitly provided to the constructor or captured using std::current_exception(). If no nested exception was set, the returned pointer will be null.

This facility enables exception chaining: higher-level exceptions (like SocketException) can propagate contextual errors while retaining the original failure for inspection or rethrow.

To rethrow the nested exception, use std::rethrow_if_nested(getNestedException()).

Returns

An exception pointer referring to the nested exception, or nullptr if none was provided.

See also

std::current_exception()

std::rethrow_if_nested()

SocketException(const std::string&, std::exception_ptr)

Member Data Documentation

_errorCode

int jsocketpp::SocketException::_errorCode

private

Platform-specific error code (e.g., errno, WSA error).

_nested

std::exception_ptr jsocketpp::SocketException::_nested {}

private

Captured nested exception for chaining, if any.

---

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

• include/jsocketpp/SocketException.hpp