qb::io::transport::udp Class Reference

UDP transport providing connectionless, datagram-based communication. More...

#include <udp.h>

Inheritance diagram for qb::io::transport::udp:

Collaboration diagram for qb::io::transport::udp:

Classes
struct	identity
	Identifies a UDP endpoint, extending qb::io::endpoint with hashing support. More...
class	ProxyOut
	Proxy class providing a stream-like interface for sending UDP datagrams. More...

Public Member Functions
constexpr bool	is_secure () const noexcept
	Indicates that this transport implementation is not secure.
const udp::identity &	getSource () const noexcept
	Get the source udp::identity (endpoint) of the last successfully received datagram.
void	setDestination (udp::identity const &to) noexcept
	Set the destination udp::identity for subsequent outgoing datagrams sent via out() or operator<<.
auto &	out ()
	Get the output proxy (ProxyOut) for stream-like sending to the current destination.
int	read () noexcept
	Read a single datagram from the UDP socket.
int	write () noexcept
	Write the next complete datagram from the output buffer to its destination.
char *	publish (char const *data, std::size_t size) noexcept
	Publish (enqueue) data to be sent to the current default destination (_remote_dest).
char *	publish_to (udp::identity const &to, char const *data, std::size_t size) noexcept
	Publish (enqueue) data to be sent to a specific udp::identity destination.
Public Member Functions inherited from qb::io::stream< io::udp::socket >
output_buffer_type &	out () noexcept
	Get the output buffer.
std::size_t	pendingWrite () const noexcept
	Get the number of bytes pending for writing.
int	write (std::enable_if_t< has_method_write< io::udp::socket, int, const char *, std::size_t >::value, Available > *=nullptr) noexcept
	Write data from the output buffer to the transport.
char *	publish (char const *data, std::size_t size) noexcept
	Add data to the output buffer for later writing.
void	close () noexcept
	Close the stream.
Public Member Functions inherited from qb::io::istream< _IO_ >
	~istream () noexcept
	Destructor.
_IO_ &	transport () noexcept
	Get the underlying transport object.
const _IO_ &	transport () const noexcept
	Get the underlying transport object (const version)
input_buffer_type &	in () noexcept
	Get the input buffer.
std::size_t	pendingRead () const noexcept
	Get the number of bytes available for reading.
template<typename Available = void>
int	read (std::enable_if_t< has_method_read< _IO_, int, char *, std::size_t >::value, Available > *=nullptr) noexcept
	Read data from the transport into the input buffer.
void	flush (std::size_t size) noexcept
	Remove data from the front of the input buffer.
void	eof () noexcept
	Handle end-of-file condition.
void	close () noexcept
	Close the stream.

Public Attributes
friend	ProxyOut
	ProxyOut needs access to private members.

Static Public Attributes
static constexpr const bool	has_reset_on_pending_read = true
	Indicates that this transport implementation resets its input buffer state when a read operation is pending (characteristic of datagram processing).
Static Public Attributes inherited from qb::io::stream< io::udp::socket >
static constexpr const bool	has_reset_on_pending_read
	Flag indicating whether the implementation resets pending reads.

Additional Inherited Members
Public Types inherited from qb::io::stream< io::udp::socket >
using	transport_io_type
	Type of the underlying transport IO.
using	output_buffer_type
	Type of the output buffer.
Public Types inherited from qb::io::istream< _IO_ >
using	transport_io_type = _IO_
	Type of the underlying transport IO.
using	input_buffer_type = qb::allocator::pipe<char>
	Type of the input buffer.
Protected Attributes inherited from qb::io::stream< io::udp::socket >
output_buffer_type	_out_buffer
	Buffer for outgoing data.
Protected Attributes inherited from qb::io::istream< _IO_ >
_IO_	_in
	The underlying IO object.
input_buffer_type	_in_buffer
	Buffer for incoming data.

Detailed Description

UDP transport providing connectionless, datagram-based communication.

This class implements a transport layer for UDP sockets by extending the generic qb::io::stream class, specializing it with qb::io::udp::socket. It provides support for identity tracking of remote endpoints, message buffering specific to datagrams, and methods for sending and receiving UDP packets.

Member Function Documentation

getSource()

const udp::identity & qb::io::transport::udp::getSource ( ) const

inlinenoexcept

Get the source udp::identity (endpoint) of the last successfully received datagram.

Returns

Constant reference to the source udp::identity.

Note

This is updated by the read() method upon successful reception of a datagram.

setDestination()

void qb::io::transport::udp::setDestination ( udp::identity const & to )

inlinenoexcept

Set the destination udp::identity for subsequent outgoing datagrams sent via out() or operator<<.

Parameters

to	The udp::identity of the remote endpoint to send to.

If the destination changes from the previously set one, or if the output buffer is empty, a new datagram header (pushed_message) will be created in the output buffer upon the next write operation via out().

out()

auto & qb::io::transport::udp::out ( )

inline

Get the output proxy (ProxyOut) for stream-like sending to the current destination.

Returns

Reference to the ProxyOut instance.

If no datagram is currently being constructed for the current _remote_dest, this method initializes a new pushed_message header in the output buffer. Subsequent writes via the returned proxy will append to this datagram.

read()

int qb::io::transport::udp::read ( )

inlinenoexcept

Read a single datagram from the UDP socket.

Returns

Number of bytes read on success (size of the datagram). Returns a negative value on error (e.g., from socket::recvfrom). Returns 0 if the read operation would block (in non-blocking mode and no data available).

Reads a datagram into the internal input buffer (_in_buffer). Upon successful read, _remote_source is updated with the sender's endpoint, and setDestination(_remote_source) is called to set this as the default reply-to target. The maximum datagram size read is io::udp::socket::MaxDatagramSize.

write()

int qb::io::transport::udp::write ( )

inlinenoexcept

Write the next complete datagram from the output buffer to its destination.

Returns

Number of bytes successfully written from the datagram. Returns a negative value on error (e.g., from socket::sendto). Returns 0 if the output buffer is empty.

Attempts to send the first datagram queued in the _out_buffer. A datagram might be sent in multiple chunks if it exceeds io::udp::socket::MaxDatagramSize, though typically UDP sends entire datagrams or fails. If a datagram is completely sent, it's removed from the _out_buffer. Manages partial sends by updating pushed_message::offset.

publish()

char * qb::io::transport::udp::publish ( char const * data, std::size_t size )

inlinenoexcept

Publish (enqueue) data to be sent to the current default destination (_remote_dest).

Parameters

data	Pointer to the data to publish.
size	Size of the data in bytes.

Returns

Pointer to the copied data within the output buffer.

This is a convenience method that calls publish_to(_remote_dest, data, size). The data is added as a new datagram or appended to the current one being built for _remote_dest.

publish_to()

char * qb::io::transport::udp::publish_to ( udp::identity const & to, char const * data, std::size_t size )

inlinenoexcept

Publish (enqueue) data to be sent to a specific udp::identity destination.

Parameters

to	The destination udp::identity (endpoint).
data	Pointer to the data to publish.
size	Size of the data in bytes.

Returns

Pointer to the copied data within the output buffer.

Adds the data as a new datagram in the _out_buffer, targeting the specified to endpoint. A pushed_message header is prepended to manage this datagram.