The UDP handle. More...

#include <udp.h>

Inheritance diagram for uvw::udp_handle:

[legend]

Collaboration diagram for uvw::udp_handle:

[legend]

Public Member Functions
int	init () final
	Initializes the handle. The actual socket is created lazily.

int	open (os_socket_handle socket)
	Opens an existing file descriptor or SOCKET as a UDP handle.

int	connect (const sockaddr &addr)
	Associates the handle to a remote address and port (either IPv4 or IPv6).

int	connect (const std::string &ip, unsigned int port)
	Associates the handle to a remote address and port (either IPv4 or IPv6).

int	connect (socket_address addr)
	Associates the handle to a remote address and port (either IPv4 or IPv6).

int	disconnect ()
	Disconnects the handle.

socket_address	peer () const noexcept
	Gets the remote address to which the handle is connected, if any.

int	bind (const sockaddr &addr, udp_flags opts=udp_flags::_UVW_ENUM)
	Binds the UDP handle to an IP address and port.

int	bind (const std::string &ip, unsigned int port, udp_flags opts=udp_flags::_UVW_ENUM)
	Binds the UDP handle to an IP address and port.

int	bind (socket_address addr, udp_flags opts=udp_flags::_UVW_ENUM)
	Binds the UDP handle to an IP address and port.

socket_address	sock () const noexcept
	Get the local IP and port of the UDP handle.

bool	multicast_membership (const std::string &multicast, const std::string &iface, membership ms)
	Sets membership for a multicast address.

bool	multicast_loop (bool enable=true)
	Sets IP multicast loop flag.

bool	multicast_ttl (int val)
	Sets the multicast ttl.

bool	multicast_interface (const std::string &iface)
	Sets the multicast interface to send or receive data on.

bool	broadcast (bool enable=false)
	Sets broadcast on or off.

bool	ttl (int val)
	Sets the time to live.

int	send (const sockaddr &addr, std::unique_ptr< char[]> data, unsigned int len)
	Sends data over the UDP socket.

int	send (const std::string &ip, unsigned int port, std::unique_ptr< char[]> data, unsigned int len)
	Sends data over the UDP socket.

int	send (socket_address addr, std::unique_ptr< char[]> data, unsigned int len)
	Sends data over the UDP socket.

int	send (const sockaddr &addr, char *data, unsigned int len)
	Sends data over the UDP socket.

int	send (const std::string &ip, unsigned int port, char *data, unsigned int len)
	Sends data over the UDP socket.

int	send (socket_address addr, char *data, unsigned int len)
	Sends data over the UDP socket.

int	try_send (const sockaddr &addr, std::unique_ptr< char[]> data, unsigned int len)
	Sends data over the UDP socket.

int	try_send (const std::string &ip, unsigned int port, std::unique_ptr< char[]> data, unsigned int len)
	Sends data over the UDP socket.

int	try_send (socket_address addr, std::unique_ptr< char[]> data, unsigned int len)
	Sends data over the UDP socket.

int	try_send (const sockaddr &addr, char *data, unsigned int len)
	Sends data over the UDP socket.

int	try_send (const std::string &ip, unsigned int port, char *data, unsigned int len)
	Sends data over the UDP socket.

int	try_send (socket_address addr, char *data, unsigned int len)
	Sends data over the UDP socket.

int	recv ()
	Prepares for receiving data.

int	stop ()
	Stops listening for incoming datagrams.

size_t	send_queue_size () const noexcept
	Gets the number of bytes queued for sending.

size_t	send_queue_count () const noexcept
	Number of send requests currently in the queue awaiting to be processed.

Public Member Functions inherited from uvw::handle< udp_handle, uv_udp_t, send_event, udp_data_event >
handle_category	category () const noexcept
	Gets the category of the handle.

handle_type	type () const noexcept
	Gets the type of the handle.

bool	active () const noexcept
	Checks if the handle is active.

bool	closing () const noexcept
	Checks if a handle is closing or closed.

void	close () noexcept
	Request handle to be closed.

void	reference () noexcept
	Reference the given handle.

void	unreference () noexcept
	Unreference the given handle.

bool	referenced () const noexcept
	Checks if the given handle referenced.

std::size_t	size () const noexcept
	Returns the size of the underlying handle type.

int	send_buffer_size ()
	Gets the size of the send buffer used for the socket.

int	send_buffer_size (int value)
	Sets the size of the send buffer used for the socket.

int	recv_buffer_size ()
	Gets the size of the receive buffer used for the socket.

int	recv_buffer_size (int value)
	Sets the size of the receive buffer used for the socket.

os_file_descriptor	fd () const
	Gets the platform dependent file descriptor equivalent.

Public Member Functions inherited from uvw::resource< T, U, E >
template<typename R = void>
std::shared_ptr< R >	data () const
	Gets user-defined data. `uvw` won't use this field in any case.

void	data (std::shared_ptr< void > udata)
	Sets arbitrary data. `uvw` won't use this field in any case.

Public Member Functions inherited from uvw::uv_type< U >
virtual int	init ()
	Initializes the handle.

loop &	parent () const noexcept
	Gets the loop from which the resource was originated.

const U *	raw () const noexcept
	Gets the underlying raw data structure.

U *	raw () noexcept
	Gets the underlying raw data structure.

Public Member Functions inherited from uvw::emitter< T, E... >
void	on (listener_t< U > f)
	Registers a long-lived listener with the event emitter.

void	reset () noexcept
	Disconnects the listener for the given event type.

void	reset () noexcept
	Disconnects all listeners.

bool	has () const noexcept
	Checks if there is a listener registered for the specific event.

Detailed Description

The UDP handle.

UDP handles encapsulate UDP communication for both clients and servers.
By default, ipv4 is used as a template parameter. The handle already supports IPv6 out-of-the-box by using uvw::ipv6.

To create an udp_handle through a loop, arguments follow:

An optional integer value that indicates optional flags used to initialize the socket.

See the official documentation for further details.

Definition at line 82 of file udp.h.

Member Function Documentation

◆ bind() [1/3]

int uvw::udp_handle::bind	(	const sockaddr &	addr,
		udp_flags	opts = `udp_flags::_UVW_ENUM`
	)

Binds the UDP handle to an IP address and port.

Available flags are:

udp_handle::udp_flags::IPV6ONLY
udp_handle::udp_flags::UDP_PARTIAL
udp_handle::udp_flags::REUSEADDR
udp_handle::udp_flags::UDP_MMSG_CHUNK
udp_handle::udp_flags::UDP_MMSG_FREE
udp_handle::udp_flags::UDP_LINUX_RECVERR
udp_handle::udp_flags::UDP_RECVMMSG

See the official documentation for further details.

Parameters

addr	Initialized `sockaddr_in` or `sockaddr_in6` data structure.
opts	Optional additional flags.

Returns: Underlying return value.

◆ bind() [2/3]

int uvw::udp_handle::bind	(	const std::string &	ip,
		unsigned int	port,
		udp_flags	opts = `udp_flags::_UVW_ENUM`
	)

Binds the UDP handle to an IP address and port.

Available flags are:

udp_handle::udp_flags::IPV6ONLY
udp_handle::udp_flags::UDP_PARTIAL
udp_handle::udp_flags::REUSEADDR
udp_handle::udp_flags::UDP_MMSG_CHUNK
udp_handle::udp_flags::UDP_MMSG_FREE
udp_handle::udp_flags::UDP_LINUX_RECVERR
udp_handle::udp_flags::UDP_RECVMMSG

See the official documentation for further details.

Parameters

ip	The IP address to which to bind.
port	The port to which to bind.
opts	Optional additional flags.

Returns: Underlying return value.

◆ bind() [3/3]

int uvw::udp_handle::bind	(	socket_address	addr,
		udp_flags	opts = `udp_flags::_UVW_ENUM`
	)

Binds the UDP handle to an IP address and port.

Available flags are:

udp_handle::udp_flags::IPV6ONLY
udp_handle::udp_flags::UDP_PARTIAL
udp_handle::udp_flags::REUSEADDR
udp_handle::udp_flags::UDP_MMSG_CHUNK
udp_handle::udp_flags::UDP_MMSG_FREE
udp_handle::udp_flags::UDP_LINUX_RECVERR
udp_handle::udp_flags::UDP_RECVMMSG

See the official documentation for further details.

Parameters

addr	A valid instance of socket_address.
opts	Optional additional flags.

Returns: Underlying return value.

◆ broadcast()

bool uvw::udp_handle::broadcast ( bool enable = false )

Sets broadcast on or off.

Parameters

enable True to set broadcast on, false otherwise.

Returns: True in case of success, false otherwise.

◆ connect() [1/3]

int uvw::udp_handle::connect ( const sockaddr & addr )

Associates the handle to a remote address and port (either IPv4 or IPv6).

Every message sent by this handle is automatically sent to the given destination.
Trying to call this function on an already connected handle isn't allowed.

Parameters

addr	Initialized `sockaddr_in` or `sockaddr_in6` data structure.

Returns: Underlying return value.

◆ connect() [2/3]

int uvw::udp_handle::connect	(	const std::string &	ip,
		unsigned int	port
	)

Associates the handle to a remote address and port (either IPv4 or IPv6).

Every message sent by this handle is automatically sent to the given destination.
Trying to call this function on an already connected handle isn't allowed.

Parameters

ip	The address to which to bind.
port	The port to which to bind.

Returns: Underlying return value.

◆ connect() [3/3]

int uvw::udp_handle::connect ( socket_address addr )

Associates the handle to a remote address and port (either IPv4 or IPv6).

Every message sent by this handle is automatically sent to the given destination.
Trying to call this function on an already connected handle isn't allowed.

Parameters

addr	A valid instance of socket_address.

Returns: Underlying return value.

◆ disconnect()

int uvw::udp_handle::disconnect ( )

Disconnects the handle.

Trying to disconnect a handle that is not connected isn't allowed.

Returns: Underlying return value.

◆ init()

int uvw::udp_handle::init ( )

finalvirtual

Initializes the handle. The actual socket is created lazily.

Returns: Underlying return value.

Reimplemented from uvw::uv_type< U >.

◆ multicast_interface()

bool uvw::udp_handle::multicast_interface ( const std::string & iface )

Sets the multicast interface to send or receive data on.

Parameters

iface Interface address.

Returns: True in case of success, false otherwise.

◆ multicast_loop()

bool uvw::udp_handle::multicast_loop ( bool enable = true )

Sets IP multicast loop flag.

This makes multicast packets loop back to local sockets.

Parameters

enable True to enable multicast loop, false otherwise.

Returns: True in case of success, false otherwise.

◆ multicast_membership()

bool uvw::udp_handle::multicast_membership	(	const std::string &	multicast,
		const std::string &	iface,
		membership	ms
	)

Sets membership for a multicast address.

Available values for ms are:

udp_handle::membership::LEAVE_GROUP
udp_handle::membership::JOIN_GROUP

Parameters

multicast	Multicast address to set membership for.
iface	Interface address.
ms	Action to be performed.

Returns: True in case of success, false otherwise.

◆ multicast_ttl()

bool uvw::udp_handle::multicast_ttl ( int val )

Sets the multicast ttl.

Parameters

val	A value in the range `[1, 255]`.

Returns: True in case of success, false otherwise.

◆ open()

int uvw::udp_handle::open ( os_socket_handle socket )

Opens an existing file descriptor or SOCKET as a UDP handle.

The passed file descriptor or SOCKET is not checked for its type, but it’s required that it represents a valid datagram socket.

See the official documentation for further details.

Parameters

socket A valid socket handle (either a file descriptor or a SOCKET).

Returns: Underlying return value.

◆ peer()

socket_address uvw::udp_handle::peer ( ) const

noexcept

Gets the remote address to which the handle is connected, if any.

Returns: A valid instance of socket_address, an empty one in case of errors.

◆ recv()

int uvw::udp_handle::recv ( )

Prepares for receiving data.

Note that if the socket has not previously been bound with bind(), it is bound to 0.0.0.0 (the all interfaces IPv4 address) and a random port number.

An UDP data event will be emitted when the handle receives data.

Returns: Underlying return value.

◆ send() [1/6]

int uvw::udp_handle::send	(	const sockaddr &	addr,
		char *	data,
		unsigned int	len
	)

Sends data over the UDP socket.

Note that if the socket has not previously been bound with bind(), it will be bound to 0.0.0.0 (the all interfaces IPv4 address) and a random port number.

The handle doesn't take the ownership of the data. Be sure that their lifetime overcome the one of the request.

A send event will be emitted when the data have been sent.

Parameters

addr	Initialized `sockaddr_in` or `sockaddr_in6` data structure.
data	The data to be sent.
len	The lenght of the submitted data.

Returns: Underlying return value.

◆ send() [2/6]

int uvw::udp_handle::send	(	const sockaddr &	addr,
		std::unique_ptr< char[]>	data,
		unsigned int	len
	)

Sends data over the UDP socket.

Note that if the socket has not previously been bound with bind(), it will be bound to 0.0.0.0 (the all interfaces IPv4 address) and a random port number.

The handle takes the ownership of the data and it is in charge of delete them.

A send event will be emitted when the data have been sent.

Parameters

addr	Initialized `sockaddr_in` or `sockaddr_in6` data structure.
data	The data to be sent.
len	The lenght of the submitted data.

Returns: Underlying return value.

◆ send() [3/6]

int uvw::udp_handle::send	(	const std::string &	ip,
		unsigned int	port,
		char *	data,
		unsigned int	len
	)

Sends data over the UDP socket.

Note that if the socket has not previously been bound with bind(), it will be bound to 0.0.0.0 (the all interfaces IPv4 address) and a random port number.

The handle doesn't take the ownership of the data. Be sure that their lifetime overcome the one of the request.

A send event will be emitted when the data have been sent.

Parameters

ip	The address to which to send data.
port	The port to which to send data.
data	The data to be sent.
len	The lenght of the submitted data.

Returns: Underlying return value.

◆ send() [4/6]

int uvw::udp_handle::send	(	const std::string &	ip,
		unsigned int	port,
		std::unique_ptr< char[]>	data,
		unsigned int	len
	)

Sends data over the UDP socket.

Note that if the socket has not previously been bound with bind(), it will be bound to 0.0.0.0 (the all interfaces IPv4 address) and a random port number.

The handle takes the ownership of the data and it is in charge of delete them.

A send event will be emitted when the data have been sent.

Parameters

ip	The address to which to send data.
port	The port to which to send data.
data	The data to be sent.
len	The lenght of the submitted data.

Returns: Underlying return value.

◆ send() [5/6]

int uvw::udp_handle::send	(	socket_address	addr,
		char *	data,
		unsigned int	len
	)

Sends data over the UDP socket.

Note that if the socket has not previously been bound with bind(), it will be bound to 0.0.0.0 (the all interfaces IPv4 address) and a random port number.

The handle doesn't take the ownership of the data. Be sure that their lifetime overcome the one of the request.

A send event will be emitted when the data have been sent.

Parameters

addr	A valid instance of socket_address.
data	The data to be sent.
len	The lenght of the submitted data.

Returns: Underlying return value.

◆ send() [6/6]

int uvw::udp_handle::send	(	socket_address	addr,
		std::unique_ptr< char[]>	data,
		unsigned int	len
	)

Sends data over the UDP socket.

Note that if the socket has not previously been bound with bind(), it will be bound to 0.0.0.0 (the all interfaces IPv4 address) and a random port number.

The handle takes the ownership of the data and it is in charge of delete them.

A send event will be emitted when the data have been sent.

Parameters

addr	A valid instance of socket_address.
data	The data to be sent.
len	The lenght of the submitted data.

Returns: Underlying return value.

◆ send_queue_count()

size_t uvw::udp_handle::send_queue_count ( ) const

noexcept

Number of send requests currently in the queue awaiting to be processed.

Returns: Number of send requests currently in the queue.

◆ send_queue_size()

size_t uvw::udp_handle::send_queue_size ( ) const

noexcept

Gets the number of bytes queued for sending.

It strictly shows how much information is currently queued.

Returns: Number of bytes queued for sending.

◆ sock()

socket_address uvw::udp_handle::sock ( ) const

noexcept

Get the local IP and port of the UDP handle.

Returns: A valid instance of socket_address, an empty one in case of errors.

◆ stop()

int uvw::udp_handle::stop ( )

Stops listening for incoming datagrams.

Returns: Underlying return value.

◆ try_send() [1/6]

int uvw::udp_handle::try_send	(	const sockaddr &	addr,
		char *	data,
		unsigned int	len
	)

Sends data over the UDP socket.

Same as send(), but it won’t queue a send request if it can’t be completed immediately.

Parameters

addr	Initialized `sockaddr_in` or `sockaddr_in6` data structure.
data	The data to be sent.
len	The lenght of the submitted data.

Returns: Underlying return value.

◆ try_send() [2/6]

int uvw::udp_handle::try_send	(	const sockaddr &	addr,
		std::unique_ptr< char[]>	data,
		unsigned int	len
	)

Sends data over the UDP socket.

Same as send(), but it won’t queue a send request if it can’t be completed immediately.

Parameters

addr	Initialized `sockaddr_in` or `sockaddr_in6` data structure.
data	The data to be sent.
len	The lenght of the submitted data.

Returns: Underlying return value.

◆ try_send() [3/6]

int uvw::udp_handle::try_send	(	const std::string &	ip,
		unsigned int	port,
		char *	data,
		unsigned int	len
	)

Sends data over the UDP socket.

Same as send(), but it won’t queue a send request if it can’t be completed immediately.

Parameters

ip	The address to which to send data.
port	The port to which to send data.
data	The data to be sent.
len	The lenght of the submitted data.

Returns: Underlying return value.

◆ try_send() [4/6]

int uvw::udp_handle::try_send	(	const std::string &	ip,
		unsigned int	port,
		std::unique_ptr< char[]>	data,
		unsigned int	len
	)

Sends data over the UDP socket.

Same as send(), but it won’t queue a send request if it can’t be completed immediately.

Parameters

ip	The address to which to send data.
port	The port to which to send data.
data	The data to be sent.
len	The lenght of the submitted data.

Returns: Underlying return value.

◆ try_send() [5/6]

int uvw::udp_handle::try_send	(	socket_address	addr,
		char *	data,
		unsigned int	len
	)

Sends data over the UDP socket.

Same as send(), but it won’t queue a send request if it can’t be completed immediately.

Parameters

addr	A valid instance of socket_address.
data	The data to be sent.
len	The lenght of the submitted data.

Returns: Underlying return value.

◆ try_send() [6/6]

int uvw::udp_handle::try_send	(	socket_address	addr,
		std::unique_ptr< char[]>	data,
		unsigned int	len
	)

Sends data over the UDP socket.

Same as send(), but it won’t queue a send request if it can’t be completed immediately.

Parameters

addr	A valid instance of socket_address.
data	The data to be sent.
len	The lenght of the submitted data.

Returns: Underlying return value.

◆ ttl()

bool uvw::udp_handle::ttl ( int val )

Sets the time to live.

Parameters

val	A value in the range `[1, 255]`.

Returns: True in case of success, false otherwise.

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

src/uvw/udp.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ bind() [1/3]

◆ bind() [2/3]

◆ bind() [3/3]

◆ broadcast()

◆ connect() [1/3]

◆ connect() [2/3]

◆ connect() [3/3]

◆ disconnect()

◆ init()

◆ multicast_interface()

◆ multicast_loop()

◆ multicast_membership()

◆ multicast_ttl()

◆ open()

◆ peer()

◆ recv()

◆ send() [1/6]

◆ send() [2/6]

◆ send() [3/6]

◆ send() [4/6]

◆ send() [5/6]

◆ send() [6/6]

◆ send_queue_count()

◆ send_queue_size()

◆ sock()

◆ stop()

◆ try_send() [1/6]

◆ try_send() [2/6]

◆ try_send() [3/6]

◆ try_send() [4/6]

◆ try_send() [5/6]

◆ try_send() [6/6]

◆ ttl()