sf::UdpSocket Class Reference

Specialized socket using the UDP protocol. More...

#include <UdpSocket.hpp>

Inheritance diagram for sf::UdpSocket:

Collaboration diagram for sf::UdpSocket:

Public Types
enum	{ MaxDatagramSize = 65507 }
Public Types inherited from sf::Socket
enum	Status {   Done , NotReady , Partial , Disconnected ,   Error }
	Status codes that may be returned by socket functions. More...
enum	{ AnyPort = 0 }
	Some special values used by sockets. More...

Public Member Functions
	UdpSocket ()
	Default constructor. More...
unsigned short	getLocalPort () const
	Get the port to which the socket is bound locally. More...
Status	bind (unsigned short port, const IpAddress &address=IpAddress::Any)
	Bind the socket to a specific port. More...
void	unbind ()
	Unbind the socket from the local port to which it is bound. More...
Status	send (const void *data, std::size_t size, const IpAddress &remoteAddress, unsigned short remotePort)
	Send raw data to a remote peer. More...
Status	receive (void *data, std::size_t size, std::size_t &received, IpAddress &remoteAddress, unsigned short &remotePort)
	Receive raw data from a remote peer. More...
Status	send (Packet &packet, const IpAddress &remoteAddress, unsigned short remotePort)
	Send a formatted packet of data to a remote peer. More...
Status	receive (Packet &packet, IpAddress &remoteAddress, unsigned short &remotePort)
	Receive a formatted packet of data from a remote peer. More...
Public Member Functions inherited from sf::Socket
virtual	~Socket ()
	Destructor. More...
void	setBlocking (bool blocking)
	Set the blocking state of the socket. More...
bool	isBlocking () const
	Tell whether the socket is in blocking or non-blocking mode. More...

Additional Inherited Members
Protected Types inherited from sf::Socket
enum	Type { Tcp , Udp }
	Types of protocols that the socket can use. More...
Protected Member Functions inherited from sf::Socket
	Socket (Type type)
	Default constructor. More...
SocketHandle	getHandle () const
	Return the internal handle of the socket. More...
void	create ()
	Create the internal representation of the socket. More...
void	create (SocketHandle handle)
	Create the internal representation of the socket from a socket handle. More...
void	close ()
	Close the socket gracefully. More...

Detailed Description

Specialized socket using the UDP protocol.

A UDP socket is a connectionless socket.

Instead of connecting once to a remote host, like TCP sockets, it can send to and receive from any host at any time.

It is a datagram protocol: bounded blocks of data (datagrams) are transfered over the network rather than a continuous stream of data (TCP). Therefore, one call to send will always match one call to receive (if the datagram is not lost), with the same data that was sent.

The UDP protocol is lightweight but unreliable. Unreliable means that datagrams may be duplicated, be lost or arrive reordered. However, if a datagram arrives, its data is guaranteed to be valid.

UDP is generally used for real-time communication (audio or video streaming, real-time games, etc.) where speed is crucial and lost data doesn't matter much.

Sending and receiving data can use either the low-level or the high-level functions. The low-level functions process a raw sequence of bytes, whereas the high-level interface uses packets (see sf::Packet), which are easier to use and provide more safety regarding the data that is exchanged. You can look at the sf::Packet class to get more details about how they work.

It is important to note that UdpSocket is unable to send datagrams bigger than MaxDatagramSize. In this case, it returns an error and doesn't send anything. This applies to both raw data and packets. Indeed, even packets are unable to split and recompose data, due to the unreliability of the protocol (dropped, mixed or duplicated datagrams may lead to a big mess when trying to recompose a packet).

If the socket is bound to a port, it is automatically unbound from it when the socket is destroyed. However, you can unbind the socket explicitly with the Unbind function if necessary, to stop receiving messages or make the port available for other sockets.

Usage example:

// ----- The client -----
 
// Create a socket and bind it to the port 55001
sf::UdpSocket socket;
socket.bind(55001);
 
// Send a message to 192.168.1.50 on port 55002
std::string message = "Hi, I am " + sf::IpAddress::getLocalAddress().toString();
socket.send(message.c_str(), message.size() + 1, "192.168.1.50", 55002);
 
// Receive an answer (most likely from 192.168.1.50, but could be anyone else)
char buffer[1024];
std::size_t received = 0;
sf::IpAddress sender;
unsigned short port;
socket.receive(buffer, sizeof(buffer), received, sender, port);
std::cout << sender.ToString() << " said: " << buffer << std::endl;
 
// ----- The server -----
 
// Create a socket and bind it to the port 55002
sf::UdpSocket socket;
socket.bind(55002);
 
// Receive a message from anyone
char buffer[1024];
std::size_t received = 0;
sf::IpAddress sender;
unsigned short port;
socket.receive(buffer, sizeof(buffer), received, sender, port);
std::cout << sender.ToString() << " said: " << buffer << std::endl;
 
// Send an answer
std::string message = "Welcome " + sender.toString();
socket.send(message.c_str(), message.size() + 1, sender, port);

See also

sf::Socket, sf::TcpSocket, sf::Packet

Definition at line 45 of file UdpSocket.hpp.

Member Enumeration Documentation

anonymous enum

anonymous enum

Enumerator
MaxDatagramSize	The maximum number of bytes that can be sent in a single UDP datagram.

Definition at line 52 of file UdpSocket.hpp.

Constructor & Destructor Documentation

UdpSocket()

sf::UdpSocket::UdpSocket

(

)

Default constructor.

Member Function Documentation

bind()

Status sf::UdpSocket::bind	(	unsigned short	port,
		const IpAddress &	address = IpAddress::Any
	)

Bind the socket to a specific port.

Binding the socket to a port is necessary for being able to receive data on that port. You can use the special value Socket::AnyPort to tell the system to automatically pick an available port, and then call getLocalPort to retrieve the chosen port.

Since the socket can only be bound to a single port at any given moment, if it is already bound when this function is called, it will be unbound from the previous port before being bound to the new one.

Parameters

port	Port to bind the socket to
address	Address of the interface to bind to

Returns

Status code

See also

unbind, getLocalPort

getLocalPort()

unsigned short sf::UdpSocket::getLocalPort

(

)

const

Get the port to which the socket is bound locally.

If the socket is not bound to a port, this function returns 0.

Returns

Port to which the socket is bound

See also

bind

receive() [1/2]

Status sf::UdpSocket::receive	(	Packet &	packet,
		IpAddress &	remoteAddress,
		unsigned short &	remotePort
	)

Receive a formatted packet of data from a remote peer.

In blocking mode, this function will wait until the whole packet has been received.

Parameters

packet	Packet to fill with the received data
remoteAddress	Address of the peer that sent the data
remotePort	Port of the peer that sent the data

Returns

Status code

See also

send

receive() [2/2]

Status sf::UdpSocket::receive	(	void *	data,
		std::size_t	size,
		std::size_t &	received,
		IpAddress &	remoteAddress,
		unsigned short &	remotePort
	)

Receive raw data from a remote peer.

In blocking mode, this function will wait until some bytes are actually received. Be careful to use a buffer which is large enough for the data that you intend to receive, if it is too small then an error will be returned and all the data will be lost.

Parameters

data	Pointer to the array to fill with the received bytes
size	Maximum number of bytes that can be received
received	This variable is filled with the actual number of bytes received
remoteAddress	Address of the peer that sent the data
remotePort	Port of the peer that sent the data

Returns

Status code

See also

send

send() [1/2]

Status sf::UdpSocket::send	(	const void *	data,
		std::size_t	size,
		const IpAddress &	remoteAddress,
		unsigned short	remotePort
	)

Send raw data to a remote peer.

Make sure that size is not greater than UdpSocket::MaxDatagramSize, otherwise this function will fail and no data will be sent.

Parameters

data	Pointer to the sequence of bytes to send
size	Number of bytes to send
remoteAddress	Address of the receiver
remotePort	Port of the receiver to send the data to

Returns

Status code

See also

receive

send() [2/2]

Status sf::UdpSocket::send	(	Packet &	packet,
		const IpAddress &	remoteAddress,
		unsigned short	remotePort
	)

Send a formatted packet of data to a remote peer.

Make sure that the packet size is not greater than UdpSocket::MaxDatagramSize, otherwise this function will fail and no data will be sent.

Parameters

packet	Packet to send
remoteAddress	Address of the receiver
remotePort	Port of the receiver to send the data to

Returns

Status code

See also

receive

unbind()

void sf::UdpSocket::unbind

(

)

Unbind the socket from the local port to which it is bound.

The port that the socket was previously bound to is immediately made available to the operating system after this function is called. This means that a subsequent call to bind() will be able to re-bind the port if no other process has done so in the mean time. If the socket is not bound to a port, this function has no effect.

See also

bind

---

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

• UdpSocket.hpp