class UDPSocket
inherits IPSocket

A User Datagram Protocol (UDP) socket.

UDP runs on top of the Internet Protocol (IP) and was developed for applications that do not require reliability, acknowledgement, or flow control features at the transport layer. This simple protocol provides transport layer addressing in the form of UDP ports and an optional checksum capability.

UDP is a very simple protocol. Messages, so called datagrams, are sent to other hosts on an IP network without the need to set up special transmission channels or data paths beforehand. The UDP socket only needs to be opened for communication. It listens for incoming messages and sends outgoing messages on request.

This implementation supports both IPv4 and IPv6 addresses. For IPv4 addresses you must use Socket::Family::INET family (default) or Socket::Family::INET6 for IPv6 # addresses.

Usage example:

require "socket"

# Create server
server = UDPSocket.new
server.bind "localhost", 1234

# Create client and connect to server
client = UDPSocket.new
client.connect "localhost", 1234

# Send a text message to server
client.send "message"

# Receive text message from client
message, client_addr = server.receive

# Close client and server
client.close
server.close

The send methods may sporadically fail with Socket::ConnectError when sending datagrams to a non-listening server. Wrap with an exception handler to prevent raising. Example:

begin
  client.send(message, @destination)
rescue ex : Socket::ConnectError
  p ex.inspect
end

Class methods

.new(family : Family = Family::INET)

View source

Methods

#join_group(address : IPAddress)

A host must become a member of a multicast group before it can receive datagrams sent to the group. Raises Socket::Error if an incompatible address is provided.

View source

#leave_group(address : IPAddress)

Drops membership to the specified group. Memberships are automatically dropped when the socket is closed or the process exits. Raises Socket::Error if an incompatible address is provided.

View source

#multicast_hops

Returns the current value of the hoplimit field on uni-cast packets. Datagrams with a hoplimit of 1 are not forwarded beyond the local network. Multicast datagrams with a hoplimit of 0 will not be transmitted on any network, but may be delivered locally if the sending host belongs to the destination group and multicast loopback is enabled.

View source

#multicast_hops=(val : Int)

The multicast hops option controls the hoplimit field on uni-cast packets. If -1 is specified, the kernel will use a default value. If a value of 0 to 255 is specified, the packet will have the specified value as hoplimit. Other values are considered invalid and Socket::Error will be raised. Datagrams with a hoplimit of 1 are not forwarded beyond the local network. Multicast datagrams with a hoplimit of 0 will not be transmitted on any network, but may be delivered locally if the sending host belongs to the destination group and multicast loopback is enabled.

View source

#multicast_interface(address : IPAddress)

For hosts with multiple interfaces, each multicast transmission is sent from the primary network interface. This function overrides the default IPv4 interface address for subsequent transmissions. Setting the interface to 0.0.0.0 will select the default interface. Raises Socket::Error unless the socket is IPv4 and an IPv4 address is provided.

View source

#multicast_interface(index : UInt32)

For hosts with multiple interfaces, each multicast transmission is sent from the primary network interface. This function overrides the default IPv6 interface for subsequent transmissions. Setting the interface to index 0 will select the default interface.

View source

#multicast_loopback=(val : Bool)

Sets whether transmitted multicast packets should be copied and sent back to the originator, if the host has joined the multicast group.

View source

#multicast_loopback?

Reports whether transmitted multicast packets should be copied and sent back to the originator.

View source

#receive(message : Bytes) : Tuple(Int32, IPAddress)

Receives a binary message from the previously bound address.

require "socket"

server = UDPSocket.new
server.bind "localhost", 1234

message = Bytes.new(32)
bytes_read, client_addr = server.receive(message)

View source

#receive(max_message_size = 512) : Tuple(String, IPAddress)

Receives a text message from the previously bound address.

require "socket"

server = UDPSocket.new
server.bind("localhost", 1234)

message, client_addr = server.receive

View source