uvw 2.12.1
Loading...
Searching...
No Matches
uvw::UDPHandle Class Referencefinal

The UDPHandle handle. More...

#include <udp.h>

Inheritance diagram for uvw::UDPHandle:
Collaboration diagram for uvw::UDPHandle:

Public Member Functions

bool init ()
 Initializes the handle. The actual socket is created lazily.
 
void open (OSSocketHandle socket)
 Opens an existing file descriptor or SOCKET as a UDP handle.
 
void bind (const sockaddr &addr, Flags< Bind > opts=Flags< Bind >{})
 Binds the UDP handle to an IP address and port.
 
void connect (const sockaddr &addr)
 Associates the handle to a remote address and port (either IPv4 or IPv6).
 
template<typename I = IPv4>
void connect (const std::string &ip, unsigned int port)
 Associates the handle to a remote address and port (either IPv4 or IPv6).
 
template<typename I = IPv4>
void connect (Addr addr)
 Associates the handle to a remote address and port (either IPv4 or IPv6).
 
void disconnect ()
 Disconnects the handle.
 
template<typename I = IPv4>
Addr peer () const noexcept
 Gets the remote address to which the handle is connected, if any.
 
template<typename I = IPv4>
void bind (const std::string &ip, unsigned int port, Flags< Bind > opts=Flags< Bind >{})
 Binds the UDP handle to an IP address and port.
 
template<typename I = IPv4>
void bind (Addr addr, Flags< Bind > opts=Flags< Bind >{})
 Binds the UDP handle to an IP address and port.
 
template<typename I = IPv4>
Addr sock () const noexcept
 Get the local IP and port of the UDP handle.
 
template<typename I = IPv4>
bool multicastMembership (const std::string &multicast, const std::string &iface, Membership membership)
 Sets membership for a multicast address.
 
bool multicastLoop (bool enable=true)
 Sets IP multicast loop flag.
 
bool multicastTtl (int val)
 Sets the multicast ttl.
 
template<typename I = IPv4>
bool multicastInterface (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.
 
void send (const sockaddr &addr, std::unique_ptr< char[]> data, unsigned int len)
 Sends data over the UDP socket.
 
template<typename I = IPv4>
void send (const std::string &ip, unsigned int port, std::unique_ptr< char[]> data, unsigned int len)
 Sends data over the UDP socket.
 
template<typename I = IPv4>
void send (Addr addr, std::unique_ptr< char[]> data, unsigned int len)
 Sends data over the UDP socket.
 
void send (const sockaddr &addr, char *data, unsigned int len)
 Sends data over the UDP socket.
 
template<typename I = IPv4>
void send (const std::string &ip, unsigned int port, char *data, unsigned int len)
 Sends data over the UDP socket.
 
template<typename I = IPv4>
void send (Addr addr, char *data, unsigned int len)
 Sends data over the UDP socket.
 
template<typename I = IPv4>
int trySend (const sockaddr &addr, std::unique_ptr< char[]> data, unsigned int len)
 Sends data over the UDP socket.
 
template<typename I = IPv4>
int trySend (const std::string &ip, unsigned int port, std::unique_ptr< char[]> data, unsigned int len)
 Sends data over the UDP socket.
 
template<typename I = IPv4>
int trySend (Addr addr, std::unique_ptr< char[]> data, unsigned int len)
 Sends data over the UDP socket.
 
template<typename I = IPv4>
int trySend (const sockaddr &addr, char *data, unsigned int len)
 Sends data over the UDP socket.
 
template<typename I = IPv4>
int trySend (const std::string &ip, unsigned int port, char *data, unsigned int len)
 Sends data over the UDP socket.
 
template<typename I = IPv4>
int trySend (Addr addr, char *data, unsigned int len)
 Sends data over the UDP socket.
 
template<typename I = IPv4>
void recv ()
 Prepares for receiving data.
 
void stop ()
 Stops listening for incoming datagrams.
 
size_t sendQueueSize () const noexcept
 Gets the number of bytes queued for sending.
 
size_t sendQueueCount () const noexcept
 Number of send requests currently in the queue awaiting to be processed.
 
- Public Member Functions inherited from uvw::Handle< UDPHandle, uv_udp_t >
HandleCategory category () const noexcept
 Gets the category of the handle.
 
HandleType 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 sendBufferSize ()
 Gets the size of the send buffer used for the socket.
 
bool sendBufferSize (int value)
 Sets the size of the send buffer used for the socket.
 
int recvBufferSize ()
 Gets the size of the receive buffer used for the socket.
 
bool recvBufferSize (int value)
 Sets the size of the receive buffer used for the socket.
 
OSFileDescriptor fd () const
 Gets the platform dependent file descriptor equivalent.
 
- Public Member Functions inherited from uvw::Resource< UDPHandle, uv_udp_t >
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::UnderlyingType< UDPHandle, uv_udp_t >
Looploop () const noexcept
 Gets the loop from which the resource was originated.
 
const uv_udp_t * raw () const noexcept
 Gets the underlying raw data structure.
 
uv_udp_t * raw () noexcept
 Gets the underlying raw data structure.
 
- Public Member Functions inherited from uvw::Emitter< UDPHandle >
Connection< E > on (Listener< E > f)
 Registers a long-lived listener with the event emitter.
 
Connection< E > once (Listener< E > f)
 Registers a short-lived listener with the event emitter.
 
void erase (Connection< E > conn) noexcept
 Disconnects a listener from the event emitter.
 
void clear () noexcept
 Disconnects all the listeners for the given event type.
 
void clear () noexcept
 Disconnects all the listeners.
 
bool empty () const noexcept
 Checks if there are listeners registered for the specific event.
 
bool empty () const noexcept
 Checks if there are listeners registered with the event emitter.
 

Additional Inherited Members

- Public Types inherited from uvw::Emitter< UDPHandle >
- Static Public Member Functions inherited from uvw::UnderlyingType< UDPHandle, uv_udp_t >
static std::shared_ptr< UDPHandlecreate (Args &&...args)
 Creates a new resource of the given type.
 
- Protected Types inherited from uvw::Resource< UDPHandle, uv_udp_t >
- Protected Member Functions inherited from uvw::Handle< UDPHandle, uv_udp_t >
- Protected Member Functions inherited from uvw::Resource< UDPHandle, uv_udp_t >
- Protected Member Functions inherited from uvw::UnderlyingType< UDPHandle, uv_udp_t >
- Protected Member Functions inherited from uvw::Emitter< UDPHandle >
- Static Protected Member Functions inherited from uvw::Handle< UDPHandle, uv_udp_t >

Detailed Description

The UDPHandle 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 UDPHandle 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 85 of file udp.h.

Member Function Documentation

◆ bind() [1/3]

template<typename I = IPv4>
void uvw::UDPHandle::bind ( Addr addr,
Flags< Bind > opts = Flags< Bind >{} )

Binds the UDP handle to an IP address and port.

Available flags are:

  • UDPHandle::Bind::IPV6ONLY
  • UDPHandle::Bind::UDP_PARTIAL
  • UDPHandle::Bind::REUSEADDR
  • UDPHandle::Bind::UDP_MMSG_CHUNK
  • UDPHandle::Bind::UDP_MMSG_FREE
  • UDPHandle::Bind::UDP_LINUX_RECVERR
  • UDPHandle::Bind::UDP_RECVMMSG

See the official documentation for further details.

Parameters
addrA valid instance of Addr.
optsOptional additional flags.

◆ bind() [2/3]

void uvw::UDPHandle::bind ( const sockaddr & addr,
Flags< Bind > opts = Flags< Bind >{} )

Binds the UDP handle to an IP address and port.

Available flags are:

  • UDPHandle::Bind::IPV6ONLY
  • UDPHandle::Bind::UDP_PARTIAL
  • UDPHandle::Bind::REUSEADDR
  • UDPHandle::Bind::UDP_MMSG_CHUNK
  • UDPHandle::Bind::UDP_MMSG_FREE
  • UDPHandle::Bind::UDP_LINUX_RECVERR
  • UDPHandle::Bind::UDP_RECVMMSG

See the official documentation for further details.

Parameters
addrInitialized sockaddr_in or sockaddr_in6 data structure.
optsOptional additional flags.

◆ bind() [3/3]

template<typename I = IPv4>
void uvw::UDPHandle::bind ( const std::string & ip,
unsigned int port,
Flags< Bind > opts = Flags< Bind >{} )

Binds the UDP handle to an IP address and port.

Available flags are:

  • UDPHandle::Bind::IPV6ONLY
  • UDPHandle::Bind::UDP_PARTIAL
  • UDPHandle::Bind::REUSEADDR
  • UDPHandle::Bind::UDP_MMSG_CHUNK
  • UDPHandle::Bind::UDP_MMSG_FREE
  • UDPHandle::Bind::UDP_LINUX_RECVERR
  • UDPHandle::Bind::UDP_RECVMMSG

See the official documentation for further details.

Parameters
ipThe IP address to which to bind.
portThe port to which to bind.
optsOptional additional flags.

◆ broadcast()

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

Sets broadcast on or off.

Parameters
enableTrue to set broadcast on, false otherwise.
Returns
True in case of success, false otherwise.

◆ connect() [1/3]

template<typename I = IPv4>
void uvw::UDPHandle::connect ( Addr 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.

An ErrorEvent event is emitted in case of errors during the connection.

Parameters
addrA valid instance of Addr.

◆ connect() [2/3]

void uvw::UDPHandle::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.

An ErrorEvent event is emitted in case of errors during the connection.

Parameters
addrInitialized sockaddr_in or sockaddr_in6 data structure.

◆ connect() [3/3]

template<typename I = IPv4>
void uvw::UDPHandle::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.

An ErrorEvent event is emitted in case of errors during the connection.

Parameters
ipThe address to which to bind.
portThe port to which to bind.

◆ disconnect()

void uvw::UDPHandle::disconnect ( )

Disconnects the handle.

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

An ErrorEvent event is emitted in case of errors.

◆ init()

bool uvw::UDPHandle::init ( )

Initializes the handle. The actual socket is created lazily.

Returns
True in case of success, false otherwise.

◆ multicastInterface()

template<typename I = IPv4>
bool uvw::UDPHandle::multicastInterface ( const std::string & iface)

Sets the multicast interface to send or receive data on.

Parameters
ifaceInterface address.
Returns
True in case of success, false otherwise.

◆ multicastLoop()

bool uvw::UDPHandle::multicastLoop ( bool enable = true)

Sets IP multicast loop flag.

This makes multicast packets loop back to local sockets.

Parameters
enableTrue to enable multicast loop, false otherwise.
Returns
True in case of success, false otherwise.

◆ multicastMembership()

template<typename I = IPv4>
bool uvw::UDPHandle::multicastMembership ( const std::string & multicast,
const std::string & iface,
Membership membership )

Sets membership for a multicast address.

Available values for membership are:

  • UDPHandle::Membership::LEAVE_GROUP
  • UDPHandle::Membership::JOIN_GROUP
Parameters
multicastMulticast address to set membership for.
ifaceInterface address.
membershipAction to be performed.
Returns
True in case of success, false otherwise.

◆ multicastTtl()

bool uvw::UDPHandle::multicastTtl ( int val)

Sets the multicast ttl.

Parameters
valA value in the range [1, 255].
Returns
True in case of success, false otherwise.

◆ open()

void uvw::UDPHandle::open ( OSSocketHandle 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
socketA valid socket handle (either a file descriptor or a SOCKET).

◆ peer()

template<typename I = IPv4>
Addr uvw::UDPHandle::peer ( ) const
noexcept

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

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

◆ recv()

template<typename I = IPv4>
void uvw::UDPHandle::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 UDPDataEvent event will be emitted when the handle receives data.
An ErrorEvent event will be emitted in case of errors.

◆ send() [1/6]

template<typename I = IPv4>
void uvw::UDPHandle::send ( Addr 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 SendEvent event will be emitted when the data have been sent.
An ErrorEvent event will be emitted in case of errors.

Parameters
addrA valid instance of Addr.
dataThe data to be sent.
lenThe lenght of the submitted data.

◆ send() [2/6]

template<typename I = IPv4>
void uvw::UDPHandle::send ( Addr 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 SendEvent event will be emitted when the data have been sent.
An ErrorEvent event will be emitted in case of errors.

Parameters
addrA valid instance of Addr.
dataThe data to be sent.
lenThe lenght of the submitted data.

◆ send() [3/6]

void uvw::UDPHandle::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 SendEvent event will be emitted when the data have been sent.
An ErrorEvent event will be emitted in case of errors.

Parameters
addrInitialized sockaddr_in or sockaddr_in6 data structure.
dataThe data to be sent.
lenThe lenght of the submitted data.

◆ send() [4/6]

void uvw::UDPHandle::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 SendEvent event will be emitted when the data have been sent.
An ErrorEvent event will be emitted in case of errors.

Parameters
addrInitialized sockaddr_in or sockaddr_in6 data structure.
dataThe data to be sent.
lenThe lenght of the submitted data.

◆ send() [5/6]

template<typename I = IPv4>
void uvw::UDPHandle::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 SendEvent event will be emitted when the data have been sent.
An ErrorEvent event will be emitted in case of errors.

Parameters
ipThe address to which to send data.
portThe port to which to send data.
dataThe data to be sent.
lenThe lenght of the submitted data.

◆ send() [6/6]

template<typename I = IPv4>
void uvw::UDPHandle::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 SendEvent event will be emitted when the data have been sent.
An ErrorEvent event will be emitted in case of errors.

Parameters
ipThe address to which to send data.
portThe port to which to send data.
dataThe data to be sent.
lenThe lenght of the submitted data.

◆ sendQueueCount()

size_t uvw::UDPHandle::sendQueueCount ( ) const
noexcept

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

Returns
Number of send requests currently in the queue.

◆ sendQueueSize()

size_t uvw::UDPHandle::sendQueueSize ( ) 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()

template<typename I = IPv4>
Addr uvw::UDPHandle::sock ( ) const
noexcept

Get the local IP and port of the UDP handle.

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

◆ trySend() [1/6]

template<typename I = IPv4>
int uvw::UDPHandle::trySend ( Addr 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
addrA valid instance of Addr.
dataThe data to be sent.
lenThe lenght of the submitted data.
Returns
Number of bytes written.

◆ trySend() [2/6]

template<typename I = IPv4>
int uvw::UDPHandle::trySend ( Addr 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
addrA valid instance of Addr.
dataThe data to be sent.
lenThe lenght of the submitted data.
Returns
Number of bytes written.

◆ trySend() [3/6]

template<typename I = IPv4>
int uvw::UDPHandle::trySend ( 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
addrInitialized sockaddr_in or sockaddr_in6 data structure.
dataThe data to be sent.
lenThe lenght of the submitted data.
Returns
Number of bytes written.

◆ trySend() [4/6]

template<typename I = IPv4>
int uvw::UDPHandle::trySend ( 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
addrInitialized sockaddr_in or sockaddr_in6 data structure.
dataThe data to be sent.
lenThe lenght of the submitted data.
Returns
Number of bytes written.

◆ trySend() [5/6]

template<typename I = IPv4>
int uvw::UDPHandle::trySend ( 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
ipThe address to which to send data.
portThe port to which to send data.
dataThe data to be sent.
lenThe lenght of the submitted data.
Returns
Number of bytes written.

◆ trySend() [6/6]

template<typename I = IPv4>
int uvw::UDPHandle::trySend ( 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
ipThe address to which to send data.
portThe port to which to send data.
dataThe data to be sent.
lenThe lenght of the submitted data.
Returns
Number of bytes written.

◆ ttl()

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

Sets the time to live.

Parameters
valA 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: