UdpSocket

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 explicitely with the Unbind function if necessary, to stop receiving messages or make the port available for other sockets.

class UdpSocket : Socket {

package

sfUdpSocket* sfPtr;

enum maxDatagramSize;

this();

~this();

ushort getLocalPort();

void setBlocking(bool blocking);

Status bind(ushort port);

bool isBlocking();

Status send(const(void)[] data, IpAddress address, ushort port);

Status send(Packet packet, IpAddress address, ushort port);

Status receive(void[] data, size_t sizeReceived, IpAddress address, ushort port);

Status receive(Packet packet, IpAddress address, ushort port);

void unbind();

}

Constructors

this this(): Default constructor

Destructor

~this ~this(): Destructor

Members

Functions

bind Status bind(ushort port): Bind the socket to a specific port.
getLocalPort ushort getLocalPort(): Get the port to which the socket is bound locally.
isBlocking bool isBlocking(): Tell whether the socket is in blocking or non-blocking mode.
receive Status receive(void[] data, size_t sizeReceived, IpAddress address, ushort port): Receive raw data from a remote peer.
receive Status receive(Packet packet, IpAddress address, ushort port): Receive a formatted packet of data from a remote peer.
send Status send(const(void)[] data, IpAddress address, ushort port): Send raw data to a remote peer.
send Status send(Packet packet, IpAddress address, ushort port): Send a formatted packet of data to a remote peer.
setBlocking void setBlocking(bool blocking): Set the blocking state of the socket.
unbind void unbind(): Unbind the socket from the local port to which it is bound.

Manifest constants

maxDatagramSize enum maxDatagramSize;: The maximum number of bytes that can be sent in a single UDP datagram.

Variables

sfPtr sfUdpSocket* sfPtr;: Undocumented in source.

Inherited Members

From Socket

Status enum Status: Status codes that may be returned by socket functions.
AnyPort enum AnyPort;: Special value that tells the system to pick any available port.