WPILibC++ 2024.3.2
wpi::uv::Udp Class Referencefinal

UDP handle. More...

#include <wpinet/uv/Udp.h>

Inheritance diagram for wpi::uv::Udp:
wpi::uv::HandleImpl< Udp, uv_udp_t > wpi::uv::Handle

Public Member Functions

 Udp (const private_init &)
 
 ~Udp () noexcept override=default
 
void Open (uv_os_sock_t sock)
 Open an existing file descriptor or SOCKET as a UDP handle. More...
 
void Bind (const sockaddr &addr, unsigned int flags=0)
 Bind the handle to an IPv4 or IPv6 address and port. More...
 
void Bind (const sockaddr_in &addr, unsigned int flags=0)
 
void Bind (const sockaddr_in6 &addr, unsigned int flags=0)
 
void Bind (std::string_view ip, unsigned int port, unsigned int flags=0)
 Bind the handle to an IPv4 address and port. More...
 
void Bind6 (std::string_view ip, unsigned int port, unsigned int flags=0)
 Bind the handle to an IPv6 address and port. More...
 
void Connect (const sockaddr &addr)
 Associate the handle to a remote address and port, so every message sent by this handle is automatically sent to that destination. More...
 
void Connect (const sockaddr_in &addr)
 
void Connect (const sockaddr_in6 &addr)
 
void Connect (std::string_view ip, unsigned int port)
 Associate the handle to an IPv4 address and port, so every message sent by this handle is automatically sent to that destination. More...
 
void Connect6 (std::string_view ip, unsigned int port)
 Associate the handle to an IPv6 address and port, so every message sent by this handle is automatically sent to that destination. More...
 
sockaddr_storage GetPeer ()
 Get the remote IP and port on connected UDP handles. More...
 
sockaddr_storage GetSock ()
 Get the current address to which the handle is bound. More...
 
void SetMembership (std::string_view multicastAddr, std::string_view interfaceAddr, uv_membership membership)
 Set membership for a multicast address. More...
 
void SetSourceMembership (std::string_view multicastAddr, std::string_view interfaceAddr, std::string_view sourceAddr, uv_membership membership)
 Set membership for a source-specific multicast group. More...
 
void SetMulticastLoop (bool enabled)
 Set IP multicast loop flag. More...
 
void SetMulticastTtl (int ttl)
 Set the multicast TTL. More...
 
void SetMulticastInterface (std::string_view interfaceAddr)
 Set the multicast interface to send or receive data on. More...
 
void SetBroadcast (bool enabled)
 Set broadcast on or off. More...
 
void SetTtl (int ttl)
 Set the time to live (TTL). More...
 
void Send (const sockaddr &addr, std::span< const Buffer > bufs, const std::shared_ptr< UdpSendReq > &req)
 Send data over the UDP socket. More...
 
void Send (const sockaddr_in &addr, std::span< const Buffer > bufs, const std::shared_ptr< UdpSendReq > &req)
 
void Send (const sockaddr_in6 &addr, std::span< const Buffer > bufs, const std::shared_ptr< UdpSendReq > &req)
 
void Send (std::span< const Buffer > bufs, const std::shared_ptr< UdpSendReq > &req)
 Variant of Send() for connected sockets. More...
 
void Send (const sockaddr &addr, std::span< const Buffer > bufs, std::function< void(std::span< Buffer >, Error)> callback)
 Send data over the UDP socket. More...
 
void Send (const sockaddr_in &addr, std::span< const Buffer > bufs, std::function< void(std::span< Buffer >, Error)> callback)
 
void Send (const sockaddr_in6 &addr, std::span< const Buffer > bufs, std::function< void(std::span< Buffer >, Error)> callback)
 
void Send (std::span< const Buffer > bufs, std::function< void(std::span< Buffer >, Error)> callback)
 Variant of Send() for connected sockets. More...
 
int TrySend (const sockaddr &addr, std::span< const Buffer > bufs)
 Same as Send(), but won't queue a send request if it can't be completed immediately. More...
 
int TrySend (const sockaddr_in &addr, std::span< const Buffer > bufs)
 
int TrySend (const sockaddr_in6 &addr, std::span< const Buffer > bufs)
 
int TrySend (std::span< const Buffer > bufs)
 Variant of TrySend() for connected sockets. More...
 
void StartRecv ()
 Prepare for receiving data. More...
 
void StopRecv ()
 Stop listening for incoming datagrams. More...
 
bool IsUsingRecvmmsg () const
 Returns true if the UDP handle was created with the UV_UDP_RECVMMSG flag and the platform supports recvmmsg(2), false otherwise. More...
 
size_t GetSendQueueSize () const noexcept
 Gets the amount of queued bytes waiting to be sent. More...
 
size_t GetSendQueueCount () const noexcept
 Gets the amount of queued packets waiting to be sent. More...
 
- Public Member Functions inherited from wpi::uv::HandleImpl< Udp, uv_udp_t >
std::shared_ptr< Udpshared_from_this ()
 
std::shared_ptr< const Udpshared_from_this () const
 
uv_udp_tGetRaw () const noexcept
 Get the underlying handle data structure. More...
 
- Public Member Functions inherited from wpi::uv::Handle
 Handle (const Handle &)=delete
 
 Handle (Handle &&)=delete
 
Handleoperator= (const Handle &)=delete
 
Handleoperator= (Handle &&)=delete
 
virtual ~Handle () noexcept
 
Type GetType () const noexcept
 Get the type of the handle. More...
 
std::string_view GetTypeName () const noexcept
 Get the name of the type of the handle. More...
 
std::shared_ptr< LoopGetLoop () const noexcept
 Get the loop where this handle runs. More...
 
LoopGetLoopRef () const noexcept
 Get the loop where this handle runs. More...
 
bool IsActive () const noexcept
 Check if the handle is active. More...
 
bool IsClosing () const noexcept
 Check if a handle is closing or closed. More...
 
void Close () noexcept
 Request handle to be closed. More...
 
void SetLoopClosing (bool loopClosing) noexcept
 Set if the loop is closing. More...
 
bool IsLoopClosing () const noexcept
 Get the loop closing status. More...
 
void Reference () noexcept
 Reference the given handle. More...
 
void Unreference () noexcept
 Unreference the given handle. More...
 
bool HasReference () const noexcept
 Check if the given handle is referenced. More...
 
size_t RawSize () const noexcept
 Return the size of the underlying handle type. More...
 
uv_handle_tGetRawHandle () const noexcept
 Get the underlying handle data structure. More...
 
void SetBufferAllocator (std::function< Buffer(size_t)> alloc, std::function< void(Buffer &)> dealloc)
 Set the functions used for allocating and releasing buffers. More...
 
void FreeBuf (Buffer &buf) const noexcept
 Free a buffer. More...
 
template<typename T = void>
std::shared_ptr< T > GetData () const
 Gets user-defined data. More...
 
void SetData (std::shared_ptr< void > data)
 Sets user-defined data. More...
 
void SetLogger (Logger *logger)
 Sets logger. More...
 
LoggerGetLogger () const
 Gets logger. More...
 
void ReportError (int err) const
 Report an error. More...
 

Static Public Member Functions

static std::shared_ptr< UdpCreate (Loop &loop, unsigned int flags=AF_UNSPEC)
 Create a UDP handle. More...
 
static std::shared_ptr< UdpCreate (const std::shared_ptr< Loop > &loop, unsigned int flags=AF_UNSPEC)
 Create a UDP handle. More...
 

Public Attributes

sig::Signal< Buffer &, size_t, const sockaddr &, unsigned > received
 Signal generated for each incoming datagram. More...
 
- Public Attributes inherited from wpi::uv::Handle
sig::Signal< Errorerror
 Error signal. More...
 
sig::Signal closed
 Closed signal. More...
 

Additional Inherited Members

- Public Types inherited from wpi::uv::Handle
using Type = uv_handle_type
 
- Protected Member Functions inherited from wpi::uv::HandleImpl< Udp, uv_udp_t >
 HandleImpl ()
 
- Protected Member Functions inherited from wpi::uv::Handle
 Handle (uv_handle_t *uv_handle)
 
void Keep () noexcept
 
void Release () noexcept
 
void ForceClosed () noexcept
 
template<typename F , typename... Args>
bool Invoke (F &&f, Args &&... args) const
 
- Static Protected Member Functions inherited from wpi::uv::Handle
static void AllocBuf (uv_handle_t *handle, size_t size, uv_buf_t *buf)
 
static void DefaultFreeBuf (Buffer &buf)
 

Detailed Description

UDP handle.

UDP handles encapsulate UDP communication for both clients and servers.

Constructor & Destructor Documentation

◆ Udp()

wpi::uv::Udp::Udp ( const private_init &  )
inlineexplicit

◆ ~Udp()

wpi::uv::Udp::~Udp ( )
overridedefaultnoexcept

Member Function Documentation

◆ Bind() [1/4]

void wpi::uv::Udp::Bind ( const sockaddr &  addr,
unsigned int  flags = 0 
)
inline

Bind the handle to an IPv4 or IPv6 address and port.

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

◆ Bind() [2/4]

void wpi::uv::Udp::Bind ( const sockaddr_in &  addr,
unsigned int  flags = 0 
)
inline

◆ Bind() [3/4]

void wpi::uv::Udp::Bind ( const sockaddr_in6 &  addr,
unsigned int  flags = 0 
)
inline

◆ Bind() [4/4]

void wpi::uv::Udp::Bind ( std::string_view  ip,
unsigned int  port,
unsigned int  flags = 0 
)

Bind the handle to an IPv4 address and port.

Parameters
ipThe address to which to bind.
portThe port to which to bind.
flagsOptional additional flags.

◆ Bind6()

void wpi::uv::Udp::Bind6 ( std::string_view  ip,
unsigned int  port,
unsigned int  flags = 0 
)

Bind the handle to an IPv6 address and port.

Parameters
ipThe address to which to bind.
portThe port to which to bind.
flagsOptional additional flags.

◆ Connect() [1/4]

void wpi::uv::Udp::Connect ( const sockaddr &  addr)
inline

Associate the handle to a remote address and port, so every message sent by this handle is automatically sent to that destination.

Parameters
addrInitialized sockaddr_in or sockaddr_in6 data structure.

◆ Connect() [2/4]

void wpi::uv::Udp::Connect ( const sockaddr_in &  addr)
inline

◆ Connect() [3/4]

void wpi::uv::Udp::Connect ( const sockaddr_in6 &  addr)
inline

◆ Connect() [4/4]

void wpi::uv::Udp::Connect ( std::string_view  ip,
unsigned int  port 
)

Associate the handle to an IPv4 address and port, so every message sent by this handle is automatically sent to that destination.

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

◆ Connect6()

void wpi::uv::Udp::Connect6 ( std::string_view  ip,
unsigned int  port 
)

Associate the handle to an IPv6 address and port, so every message sent by this handle is automatically sent to that destination.

Parameters
ipThe address to which to bind.
portThe port to which to bind.
flagsOptional additional flags.

◆ Create() [1/2]

static std::shared_ptr< Udp > wpi::uv::Udp::Create ( const std::shared_ptr< Loop > &  loop,
unsigned int  flags = AF_UNSPEC 
)
inlinestatic

Create a UDP handle.

Parameters
loopLoop object where this handle runs.
flagsFlags

◆ Create() [2/2]

static std::shared_ptr< Udp > wpi::uv::Udp::Create ( Loop loop,
unsigned int  flags = AF_UNSPEC 
)
static

Create a UDP handle.

Parameters
loopLoop object where this handle runs.
flagsFlags

◆ GetPeer()

sockaddr_storage wpi::uv::Udp::GetPeer ( )

Get the remote IP and port on connected UDP handles.

Returns
The address (will be zeroed if an error occurred).

◆ GetSendQueueCount()

size_t wpi::uv::Udp::GetSendQueueCount ( ) const
inlinenoexcept

Gets the amount of queued packets waiting to be sent.

Returns
Amount of queued packets waiting to be sent.

◆ GetSendQueueSize()

size_t wpi::uv::Udp::GetSendQueueSize ( ) const
inlinenoexcept

Gets the amount of queued bytes waiting to be sent.

Returns
Amount of queued bytes waiting to be sent.

◆ GetSock()

sockaddr_storage wpi::uv::Udp::GetSock ( )

Get the current address to which the handle is bound.

Returns
The address (will be zeroed if an error occurred).

◆ IsUsingRecvmmsg()

bool wpi::uv::Udp::IsUsingRecvmmsg ( ) const
inline

Returns true if the UDP handle was created with the UV_UDP_RECVMMSG flag and the platform supports recvmmsg(2), false otherwise.

Returns
True if the UDP handle is using recvmmsg.

◆ Open()

void wpi::uv::Udp::Open ( uv_os_sock_t  sock)
inline

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

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

◆ Send() [1/8]

void wpi::uv::Udp::Send ( const sockaddr &  addr,
std::span< const Buffer bufs,
const std::shared_ptr< UdpSendReq > &  req 
)

Send data over the UDP socket.

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.

Data are written in order. The lifetime of the data pointers passed in the bufs parameter must exceed the lifetime of the send request. The callback can be used to free data after the request completes.

HandleSendComplete() will be called on the request object when the data has been written. HandleSendComplete() is called even if an error occurs. HandleError() will be called on the request object in case of errors.

Parameters
addrsockaddr_in or sockaddr_in6 with the address and port of the remote peer.
bufsThe buffers to be written to the stream.
reqwrite request

◆ Send() [2/8]

void wpi::uv::Udp::Send ( const sockaddr &  addr,
std::span< const Buffer bufs,
std::function< void(std::span< Buffer >, Error)>  callback 
)

Send data over the UDP socket.

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.

Data are written in order. The lifetime of the data pointers passed in the bufs parameter must exceed the lifetime of the send request. The callback can be used to free data after the request completes.

The callback will be called when the data has been sent. Errors will be reported via the error signal.

Parameters
addrsockaddr_in or sockaddr_in6 with the address and port of the remote peer.
bufsThe buffers to be sent.
callbackCallback function to call when the data has been sent.

◆ Send() [3/8]

void wpi::uv::Udp::Send ( const sockaddr_in &  addr,
std::span< const Buffer bufs,
const std::shared_ptr< UdpSendReq > &  req 
)
inline

◆ Send() [4/8]

void wpi::uv::Udp::Send ( const sockaddr_in &  addr,
std::span< const Buffer bufs,
std::function< void(std::span< Buffer >, Error)>  callback 
)
inline

◆ Send() [5/8]

void wpi::uv::Udp::Send ( const sockaddr_in6 &  addr,
std::span< const Buffer bufs,
const std::shared_ptr< UdpSendReq > &  req 
)
inline

◆ Send() [6/8]

void wpi::uv::Udp::Send ( const sockaddr_in6 &  addr,
std::span< const Buffer bufs,
std::function< void(std::span< Buffer >, Error)>  callback 
)
inline

◆ Send() [7/8]

void wpi::uv::Udp::Send ( std::span< const Buffer bufs,
const std::shared_ptr< UdpSendReq > &  req 
)

Variant of Send() for connected sockets.

Cannot be used with connectionless sockets.

Parameters
bufsThe buffers to be written to the stream.
reqwrite request

◆ Send() [8/8]

void wpi::uv::Udp::Send ( std::span< const Buffer bufs,
std::function< void(std::span< Buffer >, Error)>  callback 
)

Variant of Send() for connected sockets.

Cannot be used with connectionless sockets.

Parameters
bufsThe buffers to be written to the stream.
callbackCallback function to call when the data has been sent.

◆ SetBroadcast()

void wpi::uv::Udp::SetBroadcast ( bool  enabled)
inline

Set broadcast on or off.

Parameters
enabledTrue for enabled, false for disabled

◆ SetMembership()

void wpi::uv::Udp::SetMembership ( std::string_view  multicastAddr,
std::string_view  interfaceAddr,
uv_membership  membership 
)

Set membership for a multicast address.

Parameters
multicastAddrMulticast address to set membership for
interfaceAddrInterface address
membershipShould be UV_JOIN_GROUP or UV_LEAVE_GROUP

◆ SetMulticastInterface()

void wpi::uv::Udp::SetMulticastInterface ( std::string_view  interfaceAddr)

Set the multicast interface to send or receive data on.

Parameters
interfaceAddrInterface address

◆ SetMulticastLoop()

void wpi::uv::Udp::SetMulticastLoop ( bool  enabled)
inline

Set IP multicast loop flag.

Makes multicast packets loop back to local sockets.

Parameters
enabledTrue for enabled, false for disabled

◆ SetMulticastTtl()

void wpi::uv::Udp::SetMulticastTtl ( int  ttl)
inline

Set the multicast TTL.

Parameters
ttlTime to live (1-255)

◆ SetSourceMembership()

void wpi::uv::Udp::SetSourceMembership ( std::string_view  multicastAddr,
std::string_view  interfaceAddr,
std::string_view  sourceAddr,
uv_membership  membership 
)

Set membership for a source-specific multicast group.

Parameters
multicastAddrMulticast address to set membership for
interfaceAddrInterface address
sourceAddrSource address
membershipShould be UV_JOIN_GROUP or UV_LEAVE_GROUP

◆ SetTtl()

void wpi::uv::Udp::SetTtl ( int  ttl)
inline

Set the time to live (TTL).

Parameters
ttlTime to live (1-255)

◆ StartRecv()

void wpi::uv::Udp::StartRecv ( )

Prepare for receiving data.

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.

A received signal will be emitted for each received data packet until StopRecv() is called.

◆ StopRecv()

void wpi::uv::Udp::StopRecv ( )
inline

Stop listening for incoming datagrams.

◆ TrySend() [1/4]

int wpi::uv::Udp::TrySend ( const sockaddr &  addr,
std::span< const Buffer bufs 
)
inline

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

Parameters
addrsockaddr_in or sockaddr_in6 with the address and port of the remote peer.
bufsThe buffers to be send.
Returns
Number of bytes sent.

◆ TrySend() [2/4]

int wpi::uv::Udp::TrySend ( const sockaddr_in &  addr,
std::span< const Buffer bufs 
)
inline

◆ TrySend() [3/4]

int wpi::uv::Udp::TrySend ( const sockaddr_in6 &  addr,
std::span< const Buffer bufs 
)
inline

◆ TrySend() [4/4]

int wpi::uv::Udp::TrySend ( std::span< const Buffer bufs)
inline

Variant of TrySend() for connected sockets.

Cannot be used with connectionless sockets.

Parameters
bufsThe buffers to be written to the stream.
Returns
Number of bytes sent.

Member Data Documentation

◆ received

sig::Signal<Buffer&, size_t, const sockaddr&, unsigned> wpi::uv::Udp::received

Signal generated for each incoming datagram.

Parameters are the buffer, the number of bytes received, the address of the sender, and flags.


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