qb::io::tcp::listener Class Reference

Class implementing a TCP listener for accepting incoming connections. More...

#include <listener.h>

Inheritance diagram for qb::io::tcp::listener:

Collaboration diagram for qb::io::tcp::listener:

Public Member Functions
int	listen (io::endpoint const &ep) noexcept
	Start listening on a specific local endpoint.
int	listen (io::uri const &uri) noexcept
	Start listening on an endpoint specified by a URI.
int	listen_v4 (uint16_t port, std::string const &host="0.0.0.0") noexcept
	Start listening on a specific IPv4 address and port.
int	listen_v6 (uint16_t port, std::string const &host="::") noexcept
	Start listening on a specific IPv6 address and port.
int	listen_un (std::string const &path) noexcept
	Start listening on a Unix domain socket.
tcp::socket	accept () const noexcept
	Accept a new incoming TCP connection and return it as a new tcp::socket.
int	accept (tcp::socket &sock) const noexcept
	Accept a new incoming TCP connection into an existing tcp::socket object.
int	disconnect () const noexcept
	Disconnect the listener socket, stopping it from accepting new connections.

Static Public Member Functions
static constexpr bool	is_secure () noexcept
	Indicates that this socket implementation is not secure.

Detailed Description

Class implementing a TCP listener for accepting incoming connections.

This class provides functionality for listening for incoming TCP connections. It inherits protectedly from the base qb::io::socket class and provides methods for binding to a local address, listening for connections, and accepting them. It supports IPv4, IPv6, and Unix Domain Sockets (if enabled).

Member Function Documentation

listen() [1/2]

int qb::io::tcp::listener::listen ( io::endpoint const & ep )

noexcept

Start listening on a specific local endpoint.

Parameters

ep	The qb::io::endpoint specifying the local IP address and port to listen on.

Returns

0 on success, or a non-zero error code on failure (e.g., if binding or listening fails).

This method first opens a socket with the address family of the endpoint, then binds to the endpoint and starts listening for incoming connections. Default backlog is SOMAXCONN.

listen() [2/2]

int qb::io::tcp::listener::listen ( io::uri const & uri )

noexcept

Start listening on an endpoint specified by a URI.

Parameters

uri	The qb::io::uri specifying the scheme (e.g., "tcp", "unix"), address, and port.

Returns

0 on success, or a non-zero error code on failure.

Parses the URI to determine the address and port, then calls the appropriate listen_v4, listen_v6, or listen_un method.

listen_v4()

int qb::io::tcp::listener::listen_v4 ( uint16_t port, std::string const & host = "0.0.0.0" )

noexcept

Start listening on a specific IPv4 address and port.

Parameters

port	The port number to listen on.
host	The IPv4 host address string (e.g., "0.0.0.0" for all interfaces, or a specific IP). Defaults to "0.0.0.0".

Returns

0 on success, or a non-zero error code on failure.

listen_v6()

int qb::io::tcp::listener::listen_v6 ( uint16_t port, std::string const & host = "::" )

noexcept

Start listening on a specific IPv6 address and port.

Parameters

port	The port number to listen on.
host	The IPv6 host address string (e.g., "::" for all interfaces, or a specific IP). Defaults to "::".

Returns

0 on success, or a non-zero error code on failure.

listen_un()

int qb::io::tcp::listener::listen_un ( std::string const & path )

noexcept

Start listening on a Unix domain socket.

Parameters

path	The file system path for the Unix domain socket.

Returns

0 on success, or a non-zero error code on failure.

Note

This is only effective if QB_ENABLE_UDS is active and the system supports AF_UNIX. The socket file will be created if it doesn't exist, and may need to be unlinked manually before reuse if the program terminates abnormally.

accept() [1/2]

tcp::socket qb::io::tcp::listener::accept ( ) const

noexcept

Accept a new incoming TCP connection and return it as a new tcp::socket.

Returns

A new tcp::socket instance representing the connected client. If an error occurs during accept, the returned socket will not be open (is_open() will be false).

This is a blocking call by default if the listener socket is blocking. For non-blocking accept, the listener socket should be set to non-blocking, and this method would typically be called when select or an event loop indicates readability.

accept() [2/2]

int qb::io::tcp::listener::accept ( tcp::socket & sock ) const

noexcept

Accept a new incoming TCP connection into an existing tcp::socket object.

Parameters

sock	A reference to a tcp::socket object where the new connection will be placed. If a connection is accepted, sock will wrap the new client socket descriptor.

Returns

0 on success, indicating sock now represents the new connection. A non-zero error code (typically negative) on failure (e.g., EWOULDBLOCK if non-blocking).

Similar to the other accept() method, but uses a pre-existing socket object.

disconnect()

int qb::io::tcp::listener::disconnect ( ) const

noexcept

Disconnect the listener socket, stopping it from accepting new connections.

Returns

0 on success, or a non-zero error code on failure.

This typically calls qb::io::socket::shutdown() and close() on the underlying listener socket.