sockpp
Modern C++ socket library wrapper
Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | List of all members
sockpp::socket Class Reference

Base class for socket objects. More...

#include <socket.h>

Inheritance diagram for sockpp::socket:
sockpp::acceptor sockpp::datagram_socket sockpp::stream_socket sockpp::acceptor_tmpl< STREAM_SOCK, ADDR > sockpp::unix_acceptor sockpp::datagram_socket_tmpl< ADDR > sockpp::connector sockpp::stream_socket_tmpl< ADDR > sockpp::connector_tmpl< STREAM_SOCK, ADDR >

Public Member Functions

 socket ()
 Creates an unconnected (invalid) socket.
 
 socket (socket_t h)
 Creates a socket from an existing OS socket handle. More...
 
 socket (socket &&sock) noexcept
 Move constructor. More...
 
virtual ~socket ()
 Destructor closes the socket.
 
bool is_open () const
 Determines if the socket is open (valid). More...
 
bool operator! () const
 Determines if the socket is closed or in an error state. More...
 
 operator bool () const
 Determines if the socket is open and in an error-free state. More...
 
socket_t handle () const
 Get the underlying OS socket handle. More...
 
virtual sa_family_t family () const
 Gets the network family of the address to which the socket is bound. More...
 
socket clone () const
 Creates a new socket that refers to this one. More...
 
void clear (int val=0)
 Clears the error flag for the object. More...
 
socket_t release ()
 Releases ownership of the underlying socket object. More...
 
void reset (socket_t h=INVALID_SOCKET)
 Replaces the underlying managed socket object. More...
 
socketoperator= (socket &&sock) noexcept
 Move assignment. More...
 
bool bind (const sock_address &addr)
 Binds the socket to the specified address. More...
 
sock_address_any address () const
 Gets the local address to which the socket is bound. More...
 
sock_address_any peer_address () const
 Gets the address of the remote peer, if this socket is connected. More...
 
bool get_option (int level, int optname, void *optval, socklen_t *optlen) const
 Gets the value of a socket option. More...
 
template<typename T >
bool get_option (int level, int optname, T *val) const
 Gets the value of a socket option. More...
 
bool set_option (int level, int optname, const void *optval, socklen_t optlen)
 Sets the value of a socket option. More...
 
template<typename T >
bool set_option (int level, int optname, const T &val)
 Sets the value of a socket option. More...
 
bool set_non_blocking (bool on=true)
 Places the socket into or out of non-blocking mode. More...
 
int last_error () const
 Gets the code for the last errror. More...
 
std::string last_error_str () const
 Gets a string describing the last errror. More...
 
bool shutdown (int how=SHUT_RDWR)
 Shuts down all or part of the full-duplex connection. More...
 
bool close ()
 Closes the socket. More...
 

Static Public Member Functions

static void initialize ()
 Initializes the socket (sockpp) library. More...
 
static void destroy ()
 Shuts down the socket library. More...
 
static socket create (int domain, int type, int protocol=0)
 Creates a socket with the specified communications characterics. More...
 
static std::tuple< socket, socketpair (int domain, int type, int protocol=0)
 Creates a pair of connected sockets. More...
 
static std::string error_str (int errNum)
 Gets a string describing the specified error. More...
 

Protected Member Functions

bool close_on_err ()
 Closes the socket without checking for errors or updating the last error. More...
 
void set_last_error ()
 Cache the last system error code into this object. More...
 
template<typename T >
check_ret (T ret) const
 Checks the value and if less than zero, sets last error. More...
 
template<typename T >
bool check_ret_bool (T ret) const
 Checks the value and if less than zero, sets last error. More...
 
socket_t check_socket (socket_t ret) const
 Checks the value and if it is not a valid socket, sets last error. More...
 
bool check_socket_bool (socket_t ret) const
 Checks the value and if it is INVALID_SOCKET, sets last error. More...
 

Static Protected Member Functions

static int get_last_error ()
 OS-specific means to retrieve the last error from an operation. More...
 

Detailed Description

Base class for socket objects.

This class wraps an OS socket handle and maintains strict ownership semantics. If a socket object has a valid, open socket, then it owns the handle and will close it when the object is destroyed.

Objects of this class are not copyable, but they are moveable.

Constructor & Destructor Documentation

◆ socket() [1/2]

sockpp::socket::socket ( socket_t  h)
inlineexplicit

Creates a socket from an existing OS socket handle.

The object takes ownership of the handle and will close it when destroyed.

Parameters
hAn OS socket handle.

◆ socket() [2/2]

sockpp::socket::socket ( socket &&  sock)
inlinenoexcept

Move constructor.

This takes ownership of the underlying handle in sock.

Parameters
sockAn rvalue reference to a socket object.

Member Function Documentation

◆ address()

sock_address_any sockpp::socket::address ( ) const

Gets the local address to which the socket is bound.

Returns
The local address to which the socket is bound.

◆ bind()

bool sockpp::socket::bind ( const sock_address addr)

Binds the socket to the specified address.

Parameters
addrThe address to which we get bound.
Returns
true on success, false on error

◆ check_ret()

template<typename T >
T sockpp::socket::check_ret ( ret) const
inlineprotected

Checks the value and if less than zero, sets last error.

Template Parameters
TA signed integer type of any size
Parameters
retThe return value from a library or system call.
Returns
Returns the value sent to it, ret.

◆ check_ret_bool()

template<typename T >
bool sockpp::socket::check_ret_bool ( ret) const
inlineprotected

Checks the value and if less than zero, sets last error.

Template Parameters
TA signed integer type of any size
Parameters
retThe return value from a library or system call.
Returns
true if the value is a typical system success value (>=0) or false is is an error (<0)

◆ check_socket()

socket_t sockpp::socket::check_socket ( socket_t  ret) const
inlineprotected

Checks the value and if it is not a valid socket, sets last error.

This is specifically required for Windows which uses an unsigned type for its SOCKET.

Parameters
retThe return value from a library or system call that returns a socket, such as socket() or accept().
Returns
Returns the value sent to it, ret.

◆ check_socket_bool()

bool sockpp::socket::check_socket_bool ( socket_t  ret) const
inlineprotected

Checks the value and if it is INVALID_SOCKET, sets last error.

This is specifically required for Windows which uses an unsigned type for its SOCKET.

Parameters
retThe return value from a library or system call that returns a socket such as socket() or accept().
Returns
true if the value is a valid socket (not INVALID_SOCKET) or false is is an error (INVALID_SOCKET)

◆ clear()

void sockpp::socket::clear ( int  val = 0)
inline

Clears the error flag for the object.

Parameters
valThe value to set the flag, normally zero.

◆ clone()

socket sockpp::socket::clone ( ) const

Creates a new socket that refers to this one.

This creates a new object with an independent lifetime, but refers back to this same socket. On most systems, this duplicates the file handle using the dup() call. A typical use of this is to have separate threads for reading and writing the socket. One thread would get the original socket and the other would get the cloned one.

Returns
A new socket object that refers to the same socket as this one.

◆ close()

bool sockpp::socket::close ( )

Closes the socket.

After closing the socket, the handle is invalid, and can not be used again until reassigned.

Returns
true if the sock is closed, false on error.

◆ close_on_err()

bool sockpp::socket::close_on_err ( )
inlineprotected

Closes the socket without checking for errors or updating the last error.

This is used in internal open/connect type functions that fail after creating the socket, but want to preserve the previous failure condition. Assumes that the socket handle is valid.

Returns
Always returns false.

◆ create()

static socket sockpp::socket::create ( int  domain,
int  type,
int  protocol = 0 
)
static

Creates a socket with the specified communications characterics.

Not that this is not normally how a socket is creates in the sockpp library. Applications would typically create a connector (client) or acceptor (server) socket which would take care of the details.

This is included for completeness or for creating different types of sockets than are supported by the library.

Parameters
domainThe communications domain for the sockets (i.e. the address family)
typeThe communication semantics for the sockets (SOCK_STREAM, SOCK_DGRAM, etc).
protocolThe particular protocol to be used with the sockets
Returns
A socket with the requested communications characteristics.

◆ destroy()

static void sockpp::socket::destroy ( )
static

Shuts down the socket library.

This is only required for Win32. On platforms that use a standard socket implementation this is an empty call.

◆ error_str()

static std::string sockpp::socket::error_str ( int  errNum)
static

Gets a string describing the specified error.

This is typically the returned message from the system strerror().

Parameters
errNumThe error number.
Returns
A string describing the specified error.

◆ family()

virtual sa_family_t sockpp::socket::family ( ) const
inlinevirtual

Gets the network family of the address to which the socket is bound.

Returns
The network family of the address (AF_INET, etc) to which the socket is bound. If the socket is not bound, or the address is not known, returns AF_UNSPEC.

◆ get_last_error()

static int sockpp::socket::get_last_error ( )
staticprotected

OS-specific means to retrieve the last error from an operation.

This should be called after a failed system call to set the lastErr_ member variable. Normally this would be called from check_ret.

◆ get_option() [1/2]

bool sockpp::socket::get_option ( int  level,
int  optname,
void *  optval,
socklen_t *  optlen 
) const

Gets the value of a socket option.

This is a thin wrapper for the system getsockopt.

Parameters
levelThe protocol level at which the option resides, such as SOL_SOCKET.
optnameThe option passed directly to the protocol module.
optvalThe buffer for the value to retrieve
optlenInitially contains the lenth of the buffer, and on return contains the length of the value retrieved.
Returns
bool true if the value was retrieved, false if an error occurred.

◆ get_option() [2/2]

template<typename T >
bool sockpp::socket::get_option ( int  level,
int  optname,
T *  val 
) const
inline

Gets the value of a socket option.

Parameters
levelThe protocol level at which the option resides, such as SOL_SOCKET.
optnameThe option passed directly to the protocol module.
valThe value to retrieve
Returns
bool true if the value was retrieved, false if an error occurred.

◆ handle()

socket_t sockpp::socket::handle ( ) const
inline

Get the underlying OS socket handle.

Returns
The underlying OS socket handle.

◆ initialize()

static void sockpp::socket::initialize ( )
static

Initializes the socket (sockpp) library.

This is only required for Win32. On platforms that use a standard socket implementation this is an empty call.

◆ is_open()

bool sockpp::socket::is_open ( ) const
inline

Determines if the socket is open (valid).

Returns
true if the socket is open, false otherwise.

◆ last_error()

int sockpp::socket::last_error ( ) const
inline

Gets the code for the last errror.

This is typically the code from the underlying OS operation.

Returns
The code for the last errror.

◆ last_error_str()

std::string sockpp::socket::last_error_str ( ) const
inline

Gets a string describing the last errror.

This is typically the returned message from the system strerror().

Returns
A string describing the last errror.

◆ operator bool()

sockpp::socket::operator bool ( ) const
inlineexplicit

Determines if the socket is open and in an error-free state.

Returns
true if the socket is open and in an error-free state, false otherwise.

◆ operator!()

bool sockpp::socket::operator! ( ) const
inline

Determines if the socket is closed or in an error state.

Returns
true if the socket is closed or in an error state, false otherwise.

◆ operator=()

socket& sockpp::socket::operator= ( socket &&  sock)
inlinenoexcept

Move assignment.

This assigns ownership of the socket from the other object to this one.

Returns
A reference to this object.

◆ pair()

static std::tuple<socket, socket> sockpp::socket::pair ( int  domain,
int  type,
int  protocol = 0 
)
static

Creates a pair of connected sockets.

Whether this will work at all is highly system and domain dependent. Currently it is only known to work for Unix-domain sockets on *nix systems.

Note that applications would normally call this from a derived socket class which would return the properly type-cast sockets to match the domain and type.

Parameters
domainThe communications domain for the sockets (i.e. the address family)
typeThe communication semantics for the sockets (SOCK_STREAM, SOCK_DGRAM, etc).
protocolThe particular protocol to be used with the sockets
Returns
A std::tuple of sockets. On error both sockets will be in an error state with the

◆ peer_address()

sock_address_any sockpp::socket::peer_address ( ) const

Gets the address of the remote peer, if this socket is connected.

Returns
The address of the remote peer, if this socket is connected.

◆ release()

socket_t sockpp::socket::release ( )
inline

Releases ownership of the underlying socket object.

Returns
The OS socket handle.

◆ reset()

void sockpp::socket::reset ( socket_t  h = INVALID_SOCKET)

Replaces the underlying managed socket object.

Parameters
hThe new socket handle to manage.

◆ set_last_error()

void sockpp::socket::set_last_error ( )
inlineprotected

Cache the last system error code into this object.

This should be called after a failed system call to store the error value.

◆ set_non_blocking()

bool sockpp::socket::set_non_blocking ( bool  on = true)

Places the socket into or out of non-blocking mode.

When in non-blocking mode, a call that is not immediately ready to complete (read, write, accept, etc) will return immediately with the error EWOULDBLOCK.

Parameters
onWhether to turn non-blocking mode on or off.
Returns
true on success, false on failure.

◆ set_option() [1/2]

bool sockpp::socket::set_option ( int  level,
int  optname,
const void *  optval,
socklen_t  optlen 
)

Sets the value of a socket option.

This is a thin wrapper for the system setsockopt.

Parameters
levelThe protocol level at which the option resides, such as SOL_SOCKET.
optnameThe option passed directly to the protocol module.
optvalThe buffer with the value to set.
optlenContains the lenth of the value buffer.
Returns
bool true if the value was set, false if an error occurred.

◆ set_option() [2/2]

template<typename T >
bool sockpp::socket::set_option ( int  level,
int  optname,
const T &  val 
)
inline

Sets the value of a socket option.

Parameters
levelThe protocol level at which the option resides, such as SOL_SOCKET.
optnameThe option passed directly to the protocol module.
valThe value to set.
Returns
bool true if the value was set, false if an error occurred.

◆ shutdown()

bool sockpp::socket::shutdown ( int  how = SHUT_RDWR)

Shuts down all or part of the full-duplex connection.

Parameters
howWhich part of the connection should be shut:
  • SHUT_RD (0) Further reads disallowed.
  • SHUT_WR (1) Further writes disallowed
  • SHUT_RDWR (2) Further reads and writes disallowed.
Returns
true on success, false on error.

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