#include <Pt/Net/UdpSocket.h>

UDP datagram socket. More...

Public Member Functions
	UdpSocket ()
	Creates a closed socket.
	UdpSocket (System::EventLoop &loop)
	Creates a socket and attaches it to loop.
	~UdpSocket ()
	Destroys the socket.
void	bind (const Endpoint &ep)
	Binds to local endpoint ep.
void	bind (const Endpoint &ep, const UdpSocketOptions &o)
	Binds to ep with o.
bool	beginBind (const Endpoint &ep)
	Begins binding to ep.
bool	beginBind (const Endpoint &ep, const UdpSocketOptions &o)
	Begins binding to ep with o.
void	endBind ()
	Ends binding to a local endpoint.
Signal< UdpSocket & > &	bound ()
	Returns the signal that the socket was bound.
bool	isBound () const
	Returns true if the socket is bound.
void	connect (const Endpoint &ep)
	Connects to ep.
void	connect (const Endpoint &ep, const UdpSocketOptions &o)
	Connects to ep with o.
void	setTarget (const Endpoint &ep)
	Sets the send target to ep.
void	setTarget (const Endpoint &ep, const UdpSocketOptions &o)
	Sets the send target to ep with o.
bool	beginConnect (const Endpoint &ep)
	Begins connecting to ep.
bool	beginConnect (const Endpoint &ep, const UdpSocketOptions &o)
	Begins connecting to ep with o.
void	endConnect ()
	Ends connecting to an endpoint.
Signal< UdpSocket & > &	connected ()
	Returns the signal that the socket was connected.
bool	isConnected () const
	Returns true if the socket is connected.
void	joinMulticastGroup (const std::string &ipaddr)
	Joins multicast group ipaddr.
void	localEndpoint (Endpoint &ep) const
	Writes the local endpoint into ep.
const Endpoint &	remoteEndpoint () const
	Returns the remote endpoint.
void	close ()
	Closes the device.
void	setTimeout (std::size_t timeout)
	Sets the timeout for blocking I/O in milliseconds.
void	beginRead (char *buffer, std::size_t n)
	Begins to read data.
std::size_t	endRead ()
	Ends reading data.
std::size_t	read (char *buffer, std::size_t n)
	Read data from I/O device.
void	beginWrite (const char *buffer, std::size_t n)
	Begins to write data.
std::size_t	endWrite ()
	Ends writing data.
std::size_t	write (const char *buffer, std::size_t n)
	Write data to I/O device.
bool	seekable () const
	Returns true if device is seekable.
pos_type	seek (off_type offset, seekdir sd)
	Moves the read position to the given offset.
std::size_t	peek (char *buffer, std::size_t n)
	Peek data from I/O device without consuming them.
void	sync ()
	Synchronize device.
pos_type	position ()
	Returns the current I/O position.
bool	isEof () const
	Returns if the device has reached EOF.
Signal< IODevice & > &	inputReady ()
	Notifies about available data.
Signal< IODevice & > &	outputReady ()
	Notifies when data can be written.
bool	isReading () const
	Returns true if the device is reading.
bool	isWriting () const
	Returns true if the device is writing.
EventLoop *	loop () const
	Returns the used event loop.
void	setActive (EventLoop &parent)
	Sets the parent loop, so that operations can be run.
void	detach ()
	Remove from event loop and cancels outstanding operations.
void	cancel ()
	Cancels all operations.
bool	run ()
	Run operation if it is ready.
EventLoop *	parent () const
	Returns the used event loop.

Protected Member Functions
virtual bool	onRun ()
	Check if ready and run.
virtual void	onCancel ()
	Blocks until operation has cancelled.
void	post ()
	Posts this selectable to its event loop from any thread.
virtual void	onAttach (EventLoop &)
	Attached to loop.
virtual void	onDetach (EventLoop &)
	Detached from loop.

Detailed Description

UdpSocket is the datagram IODevice for unicast, broadcast, and multicast, so one type covers all three modes. After a local bind or a send destination is set, read() and write() are the inherited device operations, blocking or asynchronous, except that each write() sends one datagram and each read() receives one datagram.

bind() sets the local endpoint that receives datagrams, throwing AddressInUse if that address is already occupied and AccessFailed if the host cannot be used. connect() associates a remote peer so writes go there and reads come from it, while setTarget() sets a send destination without associating the socket, which is the path broadcast and multicast sends use. connect() and setTarget() throw AccessFailed when the host is not reachable.

Asynchronous bind and connect

beginBind() and beginConnect() start those operations on an attached event loop and return true when the operation completed immediately. bound() and connected() are emitted when the attempt finishes, and endBind() and endConnect() complete it. The socket must be attached before either begin method is called. isBound() and isConnected() report the current associations, localEndpoint() writes the local side, and remoteEndpoint() is the associated peer.

Broadcast and multicast

Broadcast send sets the broadcast option and uses the IPv4 broadcast endpoint as the target, while multicast send uses a multicast group address as the target. To receive a group's datagrams, bind first, then joinMulticastGroup(). UdpSocketOptions also set the hop limit; those values configure an operation, but they do not open a socket.

The first example is asynchronous unicast: one socket binds the local any-address, the other connects to loopback, and each slot completes the begin operation before I/O. The second example is a broadcast send, and the third binds, joins a group, and sends to that group.

char buffer[256];
 
void onBound(Pt::Net::UdpSocket& socket)
{
    socket.endBind();
    socket.beginRead(buffer, sizeof(buffer));
}
 
void onConnected(Pt::Net::UdpSocket& socket)
{
    socket.endConnect();
    socket.beginWrite("Hello", 5);
}
 
Pt::System::MainLoop loop;
 
Pt::Net::UdpSocket receiver;
receiver.setActive(loop);
receiver.bound() += Pt::slot(onBound);
receiver.beginBind(Pt::Net::Endpoint::ip4Any(8000));
 
Pt::Net::UdpSocket sender;
sender.setActive(loop);
sender.connected() += Pt::slot(onConnected);
sender.beginConnect(Pt::Net::Endpoint::ip4Loopback(8000));
 
loop.run();

Pt::Net::UdpSocketOptions opts;
opts.setBroadcast();
 
Pt::Net::UdpSocket sender;
sender.setTarget(Pt::Net::Endpoint::ip4Broadcast(8000), opts);
sender.write("Hello", 5);

Pt::Net::UdpSocket receiver;
receiver.bind(Pt::Net::Endpoint::ip4Any(8000));
receiver.joinMulticastGroup("224.0.1.1");
 
Pt::Net::UdpSocket sender;
sender.setTarget(Pt::Net::Endpoint("224.0.1.1", 8000));
sender.write("Hello", 5);

Member Function Documentation

◆ bind() [1/2]

void bind ( const Endpoint & ep )

Exceptions

%AddressInUse	if the local address is already occupied.
%System::AccessFailed	if the host is not reachable.

◆ bind() [2/2]

void bind	(	const Endpoint &	ep,
		const UdpSocketOptions &	o )

Exceptions

%AddressInUse	if the local address is already occupied.
%System::AccessFailed	if the host is not reachable.

◆ beginBind() [1/2]

bool beginBind ( const Endpoint & ep )

The socket must be attached to an event loop.

Returns: true if the bind completed immediately

Exceptions

%AddressInUse	if the local address is already occupied.
%System::AccessFailed	if the host is not reachable.

◆ beginBind() [2/2]

bool beginBind	(	const Endpoint &	ep,
		const UdpSocketOptions &	o )

The socket must be attached to an event loop.

Returns: true if the bind completed immediately

Exceptions

%AddressInUse	if the local address is already occupied.
%System::AccessFailed	if the host is not reachable.

◆ endBind()

void endBind ( )

Exceptions

%AddressInUse	if the local address is already occupied.
%System::AccessFailed	if the host is not reachable.