qb::io::udp::socket Class Reference

Class implementing UDP socket functionality for datagram-based communication. More...

#include <socket.h>

Inheritance diagram for qb::io::udp::socket:

Collaboration diagram for qb::io::udp::socket:

Public Member Functions
	socket ()=default
	Default constructor.
	socket (socket const &)=delete
	Deleted copy constructor.
	socket (socket &&)=default
	Default move constructor.
socket &	operator= (socket &&)=default
	Default move assignment operator.
	socket (io::socket &&sock) noexcept
	Constructor from a generic qb::io::socket (move semantics).
socket &	operator= (io::socket &&sock) noexcept
	Move assignment operator from a generic qb::io::socket.
bool	init (int af=AF_INET) noexcept
	Initialize (open) the UDP socket.
int	bind (qb::io::endpoint const &ep) noexcept
	Bind the socket to a specific local endpoint.
int	bind (qb::io::uri const &u) noexcept
	Bind the socket to an endpoint specified by a URI.
int	bind_v4 (uint16_t port, std::string const &host="0.0.0.0") noexcept
	Bind the socket to a specific IPv4 address and port.
int	bind_v6 (uint16_t port, std::string const &host="::") noexcept
	Bind the socket to a specific IPv6 address and port.
int	bind_un (std::string const &path) noexcept
	Bind the socket to a Unix domain socket path (for datagrams).
int	read (void *dest, std::size_t len, qb::io::endpoint &peer) const noexcept
	Read a datagram from the socket and get the sender's endpoint.
int	read_timeout (void *dest, std::size_t len, qb::io::endpoint &peer, const std::chrono::microseconds &timeout) const noexcept
	Read a datagram from the socket with a specified timeout.
int	try_read (void *dest, std::size_t len, qb::io::endpoint &peer) const noexcept
	Try to read a datagram from the socket (non-blocking attempt).
int	write (const void *data, std::size_t len, qb::io::endpoint const &to) const noexcept
	Write (send) a datagram to a specific remote endpoint.
int	set_buffer_size (std::size_t size) noexcept
	Set the socket's send and receive buffer sizes (SO_SNDBUF, SO_RCVBUF).
int	set_broadcast (bool enable) noexcept
	Enable or disable the SO_BROADCAST socket option.
int	join_multicast_group (const std::string &group, const std::string &iface="") noexcept
	Join an IPv4 or IPv6 multicast group.
int	leave_multicast_group (const std::string &group, const std::string &iface="") noexcept
	Leave an IPv4 or IPv6 multicast group.
int	set_multicast_ttl (int ttl) noexcept
	Set the multicast Time-To-Live (TTL) for outgoing IPv4 packets or hop limit for IPv6.
int	set_multicast_loopback (bool enable) noexcept
	Set whether multicast packets sent from this socket are looped back to the local host.
int	address_family () const noexcept
	Get the address family of this UDP socket (e.g., AF_INET, AF_INET6).
bool	is_bound () const noexcept
	Check if the UDP socket is currently bound to a local address and port.
int	disconnect () const noexcept
	Disconnect a previously connected UDP socket or clear default remote endpoint.

Static Public Attributes
static constexpr const std::size_t	DefaultDatagramSize = 512
	Default maximum size of a UDP datagram.
static constexpr const std::size_t	MaxDatagramSize = 65507
	Maximum possible size of a UDP datagram.

Detailed Description

Class implementing UDP socket functionality for datagram-based communication.

This class provides UDP socket functionality, inheriting protectedly from qb::io::socket. It supports sending and receiving datagrams over UDP/IPv4, UDP/IPv6, and Unix Domain Sockets (datagram type). It also includes methods for managing multicast group memberships. Used as the underlying I/O primitive for qb::io::transport::udp.

Constructor & Destructor Documentation

socket() [1/3]

qb::io::udp::socket::socket ( )

default

Default constructor.

Creates an uninitialized UDP socket. Call init() before use.

socket() [2/3]

qb::io::udp::socket::socket ( socket const & )

delete

Deleted copy constructor.

Sockets are not copyable.

socket() [3/3]

qb::io::udp::socket::socket ( io::socket && sock )

noexcept

Constructor from a generic qb::io::socket (move semantics).

Parameters

sock	A generic qb::io::socket instance, typically already opened with SOCK_DGRAM. The state of sock is moved into this udp::socket.

Member Function Documentation

operator=() [1/2]

socket & qb::io::udp::socket::operator= ( socket && )

default

Default move assignment operator.

Returns

Reference to this socket.

operator=() [2/2]

socket & qb::io::udp::socket::operator= ( io::socket && sock )

noexcept

Move assignment operator from a generic qb::io::socket.

Parameters

sock	A generic qb::io::socket to move from.

Returns

Reference to this udp::socket.

init()

bool qb::io::udp::socket::init ( int af = AF_INET )

noexcept

Initialize (open) the UDP socket.

Parameters

af	Address family (e.g., AF_INET, AF_INET6, AF_UNIX). Defaults to AF_INET.

Returns

true on success, false on failure to open the socket.

This method calls the base qb::io::socket::open() with SOCK_DGRAM type.

bind() [1/2]

int qb::io::udp::socket::bind ( qb::io::endpoint const & ep )

noexcept

Bind the socket to a specific local endpoint.

Parameters

ep	The qb::io::endpoint to bind to. For UDP, this sets the local address and port from which packets will be sent and received.

Returns

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

See also

qb::io::socket::bind(const endpoint &)

bind() [2/2]

int qb::io::udp::socket::bind ( qb::io::uri const & u )

noexcept

Bind the socket to an endpoint specified by a URI.

Parameters

u	The qb::io::uri specifying the local address and port to bind to. Scheme should typically be "udp".

Returns

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

bind_v4()

int qb::io::udp::socket::bind_v4 ( uint16_t port, std::string const & host = "0.0.0.0" )

noexcept

Bind the socket to a specific IPv4 address and port.

Parameters

port	The port number to bind to.
host	The IPv4 host address string (e.g., "0.0.0.0" for all interfaces). Defaults to "0.0.0.0".

Returns

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

bind_v6()

int qb::io::udp::socket::bind_v6 ( uint16_t port, std::string const & host = "::" )

noexcept

Bind the socket to a specific IPv6 address and port.

Parameters

port	The port number to bind to.
host	The IPv6 host address string (e.g., "::" for all interfaces). Defaults to "::".

Returns

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

bind_un()

int qb::io::udp::socket::bind_un ( std::string const & path )

noexcept

Bind the socket to a Unix domain socket path (for datagrams).

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 with SOCK_DGRAM.

read()

int qb::io::udp::socket::read ( void * dest, std::size_t len, qb::io::endpoint & peer ) const

noexcept

Read a datagram from the socket and get the sender's endpoint.

Parameters

dest	Pointer to the buffer where the received datagram will be stored.
len	Maximum number of bytes to read (size of the dest buffer).
peer	Output parameter: A qb::io::endpoint reference that will be populated with the source address of the received datagram.

Returns

Number of bytes actually read. Returns a negative value on error (e.g., WSAEWOULDBLOCK or EAGAIN if non-blocking and no data available).

See also

qb::io::socket::recvfrom(void*, int, endpoint&, int)

read_timeout()

int qb::io::udp::socket::read_timeout ( void * dest, std::size_t len, qb::io::endpoint & peer, const std::chrono::microseconds & timeout ) const

noexcept

Read a datagram from the socket with a specified timeout.

Parameters

dest	Pointer to the buffer for received data.
len	Maximum number of bytes to read.
peer	Output parameter for the sender's endpoint.
timeout	Maximum time to wait for data. If the timeout expires before data arrives, an error (typically ETIMEDOUT or equivalent) is returned.

Returns

Number of bytes read, or a negative value on error or timeout.

Uses qb::io::socket::recv_n which internally uses select for timeout handling.

try_read()

int qb::io::udp::socket::try_read ( void * dest, std::size_t len, qb::io::endpoint & peer ) const

noexcept

Try to read a datagram from the socket (non-blocking attempt).

Parameters

dest	Pointer to the buffer for received data.
len	Maximum number of bytes to read.
peer	Output parameter for the sender's endpoint if data is successfully read.

Returns

Number of bytes read if data was available immediately. Returns 0 if no data was available (and socket is non-blocking, would otherwise block). Returns a negative value on error.

Sets the socket to non-blocking, attempts a read, then restores its original blocking state.

write()

int qb::io::udp::socket::write ( const void * data, std::size_t len, qb::io::endpoint const & to ) const

noexcept

Write (send) a datagram to a specific remote endpoint.

Parameters

data	Pointer to the data to be sent.
len	Number of bytes to send from the data buffer.
to	The destination qb::io::endpoint.

Returns

Number of bytes actually sent. For UDP, this is usually len on success. Returns a negative value on error.

See also

qb::io::socket::sendto(const void*, int, const endpoint&, int)

set_buffer_size()

int qb::io::udp::socket::set_buffer_size ( std::size_t size )

noexcept

Set the socket's send and receive buffer sizes (SO_SNDBUF, SO_RCVBUF).

Parameters

size	The desired buffer size in bytes for both send and receive buffers.

Returns

0 on success for both options, or a non-zero error code if setting either option fails.

set_broadcast()

int qb::io::udp::socket::set_broadcast ( bool enable )

noexcept

Enable or disable the SO_BROADCAST socket option.

Parameters

enable

true to enable broadcasting, false to disable.

Returns

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

Enabling this allows the socket to send packets to a broadcast address.

join_multicast_group()

int qb::io::udp::socket::join_multicast_group ( const std::string & group, const std::string & iface = "" )

noexcept

Join an IPv4 or IPv6 multicast group.

Parameters

group	Multicast group address string (e.g., "224.0.0.1" or "ff02::1").
iface	Optional local interface address string or interface name to join the group on. If empty or null, the system chooses a default interface.

Returns

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

Uses IP_ADD_MEMBERSHIP or IPV6_JOIN_GROUP socket options.

leave_multicast_group()

int qb::io::udp::socket::leave_multicast_group ( const std::string & group, const std::string & iface = "" )

noexcept

Leave an IPv4 or IPv6 multicast group.

Parameters

group	Multicast group address string.
iface	Optional local interface address string or interface name used when joining.

Returns

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

Uses IP_DROP_MEMBERSHIP or IPV6_LEAVE_GROUP socket options.

set_multicast_ttl()

int qb::io::udp::socket::set_multicast_ttl ( int ttl )

noexcept

Set the multicast Time-To-Live (TTL) for outgoing IPv4 packets or hop limit for IPv6.

Parameters

ttl	The TTL (for IPv4, typically 1-255) or hop limit (for IPv6) value. A TTL of 0 restricts packets to the local host. A TTL of 1 restricts packets to the local subnet.

Returns

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

Uses IP_MULTICAST_TTL or IPV6_MULTICAST_HOPS socket options.

set_multicast_loopback()

int qb::io::udp::socket::set_multicast_loopback ( bool enable )

noexcept

Set whether multicast packets sent from this socket are looped back to the local host.

Parameters

enable

true to enable multicast loopback (sender receives its own packets), false to disable (default is usually enabled).

Returns

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

Uses IP_MULTICAST_LOOP or IPV6_MULTICAST_LOOP socket options.

address_family()

int qb::io::udp::socket::address_family ( ) const

noexcept

Get the address family of this UDP socket (e.g., AF_INET, AF_INET6).

Returns

The integer value representing the address family.

Retrieves this from the underlying qb::io::socket's endpoint information if bound, or the family it was initialized with.

is_bound()

bool qb::io::udp::socket::is_bound ( ) const

noexcept

Check if the UDP socket is currently bound to a local address and port.

Returns

true if the socket is bound, false otherwise.

A UDP socket must be bound to receive unicast messages or to send packets from a specific local port.

disconnect()

int qb::io::udp::socket::disconnect ( ) const

noexcept

Disconnect a previously connected UDP socket or clear default remote endpoint.

Returns

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

For UDP, connect can be used to set a default destination for send() and to filter incoming packets to only those from that destination. This disconnect call removes that association. It then calls qb::io::socket::close().

Member Data Documentation

DefaultDatagramSize

const std::size_t qb::io::udp::socket::DefaultDatagramSize = 512

staticconstexpr

Default maximum size of a UDP datagram.

The theoretical maximum size of a UDP datagram is 65507 bytes, but this implementation uses a more conservative default value of 512 bytes. This can be adjusted by using set_buffer_size() method.

MaxDatagramSize

const std::size_t qb::io::udp::socket::MaxDatagramSize = 65507

staticconstexpr

Maximum possible size of a UDP datagram.

The theoretical maximum size of a UDP datagram is 65507 bytes (IPv4).