SFML - Simple and Fast Multimedia Library

SMFL 2.3.2

previous page next page
Public Types | Public Member Functions | Protected Types | Protected Member Functions | List of all members
sf::UdpSocket Class Reference
Network module

Specialized socket using the UDP protocol. More...

#include <UdpSocket.hpp>

Inheritance diagram for sf::UdpSocket:
sf::Socket sf::NonCopyable

Public Types

enum  { MaxDatagramSize = 65507 }
 
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)
 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...
 
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...
 

Protected Types

enum  Type { Tcp, Udp }
 Types of protocols that the socket can use. More...
 

Protected Member Functions

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
inherited

Some special values used by sockets.

Enumerator
AnyPort 

Special value that tells the system to pick any available port.

Definition at line 66 of file Socket.hpp.

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.

enum sf::Socket::Status
inherited

Status codes that may be returned by socket functions.

Enumerator
Done 

The socket has sent / received the data.

NotReady 

The socket is not ready to send / receive data yet.

Partial 

The socket sent a part of the data.

Disconnected 

The TCP socket has been disconnected.

Error 

An unexpected error happened.

Definition at line 53 of file Socket.hpp.

enum sf::Socket::Type
protectedinherited

Types of protocols that the socket can use.

Enumerator
Tcp 

TCP protocol.

Udp 

UDP protocol.

Definition at line 114 of file Socket.hpp.

Constructor & Destructor Documentation

sf::UdpSocket::UdpSocket ( )

Default constructor.

Member Function Documentation

Status sf::UdpSocket::bind ( unsigned short  port)

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.

Parameters
portPort to bind the socket to
Returns
Status code
See also
unbind, getLocalPort
void sf::Socket::close ( )
protectedinherited

Close the socket gracefully.

This function can only be accessed by derived classes.

void sf::Socket::create ( )
protectedinherited

Create the internal representation of the socket.

This function can only be accessed by derived classes.

void sf::Socket::create ( SocketHandle  handle)
protectedinherited

Create the internal representation of the socket from a socket handle.

This function can only be accessed by derived classes.

Parameters
handleOS-specific handle of the socket to wrap
SocketHandle sf::Socket::getHandle ( ) const
protectedinherited

Return the internal handle of the socket.

The returned handle may be invalid if the socket was not created yet (or already destroyed). This function can only be accessed by derived classes.

Returns
The internal (OS-specific) handle of the socket
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
bool sf::Socket::isBlocking ( ) const
inherited

Tell whether the socket is in blocking or non-blocking mode.

Returns
True if the socket is blocking, false otherwise
See also
setBlocking
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
dataPointer to the array to fill with the received bytes
sizeMaximum number of bytes that can be received
receivedThis variable is filled with the actual number of bytes received
remoteAddressAddress of the peer that sent the data
remotePortPort of the peer that sent the data
Returns
Status code
See also
send
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
packetPacket to fill with the received data
remoteAddressAddress of the peer that sent the data
remotePortPort of the peer that sent the data
Returns
Status code
See also
send
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
dataPointer to the sequence of bytes to send
sizeNumber of bytes to send
remoteAddressAddress of the receiver
remotePortPort of the receiver to send the data to
Returns
Status code
See also
receive
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
packetPacket to send
remoteAddressAddress of the receiver
remotePortPort of the receiver to send the data to
Returns
Status code
See also
receive
void sf::Socket::setBlocking ( bool  blocking)
inherited

Set the blocking state of the socket.

In blocking mode, calls will not return until they have completed their task. For example, a call to Receive in blocking mode won't return until some data was actually received. In non-blocking mode, calls will always return immediately, using the return code to signal whether there was data available or not. By default, all sockets are blocking.

Parameters
blockingTrue to set the socket as blocking, false for non-blocking
See also
isBlocking
void sf::UdpSocket::unbind ( )

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

The port that the socket was previously using is immediately available after this function is called. 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:
previous page start next page