class SF::UdpSocket
inherits SF::Socket
#
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
socket = SF::UdpSocket.new
socket.bind(55001)
# Send a message to 192.168.1.50 on port 55002
message = "Hi, I am #{SF::IpAddress.local_address}"
socket.send(message.to_slice, "192.168.1.50", 55002)
# Receive an answer (most likely from 192.168.1.50, but could be anyone else)
buffer = Slice(UInt8).new(1024)
status, received, sender, port = socket.receive(buffer)
puts "#{sender} said: #{buffer}"
# ----- The server -----
# Create a socket and bind it to the port 55002
socket = SF::UdpSocket.new
socket.bind(55002)
# Receive a message from anyone
buffer = Slice(UInt8).new(1024)
status, received, sender, port = socket.receive(buffer)
puts "#{sender} said: #{buffer}"
# Send an answer
message = "Welcome #{sender}"
socket.send(message.to_slice, sender, port)
See also: SF::Socket, SF::TcpSocket, SF::Packet
Constants#
MaxDatagramSize = 65507#
The maximum number of bytes that can be sent in a single UDP datagram
Constructors#
Methods#
#bind(port : Int, address : IpAddress = IpAddress::Any) : Socket::Status#
Bind the socket to a specific port
Binding the socket to a port is necessary for being able to receive data on that port.
When providing SF::Socket::AnyPort as port, the listener
will request an available port from the system.
The chosen port can be retrieved by calling local_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.
- port - Port to bind the socket to
- address - Address of the interface to bind to
Returns: Status code
See also: unbind, local_port
#local_port : UInt16#
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(data : Slice) : Tuple(Socket::Status, Int32, IpAddress, UInt16)#
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.
- data - The slice to fill with the received bytes
Returns:
- Status code
- The actual number of bytes received
- Address of the peer that sent the data
- Port of the peer that sent the data
See also: send
#receive(packet : Packet) : Tuple(Socket::Status, IpAddress, UInt16)#
Receive a formatted packet of data from a remote peer
In blocking mode, this function will wait until the whole packet has been received.
- packet - Packet to fill with the received data
Returns:
- Status code
- Address of the peer that sent the data
- Port of the peer that sent the data
See also: send
#send(data : Slice, remote_address : IpAddress, remote_port : Int) : Socket::Status#
Send raw data to a remote peer
Make sure that data size is not greater than
UdpSocket::MaxDatagramSize, otherwise this function will
fail and no data will be sent.
- data - Slice containing the sequence of bytes to send
- remote_address - Address of the receiver
- remote_port - Port of the receiver to send the data to
Returns: Status code
See also: receive
#send(packet : Packet, remote_address : IpAddress, remote_port : Int) : Socket::Status#
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.
- packet - Packet to send
- remote_address - Address of the receiver
- remote_port - Port of the receiver to send the data to
Returns: Status code
See also: receive
#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