struct UDPSocket

• UDPSocket
• Struct
• Value
• Object

Overview

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/udp_socket"

# Create server
server = UDPSocket.new "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 Errno::ECONNREFUSED when sending datagrams to a non-listening server. Wrap with an exception handler to prevent raising. Example:

begin
  client.send(message, @destination)
rescue ex : Errno
  if ex.errno == Errno::ECONNREFUSED
    p ex.inspect
  end
end

Defined in:

Constructors

• .new(raw : Socket::Raw)

  Creates a UDPSocket from a raw socket.

• .new(family : Socket::Family = Socket::Family::INET) : UDPSocket

  Creates a UDPSocket and binds it to any available local address and port.

• .new(address : Socket::IPAddress, *, dns_timeout : Time::Span | Number? = nil, connect_timeout : Time::Span | Number? = nil) : UDPSocket

  Creates a UDPSocket and binds it to address.

• .new(host : String, port : Int32 = 0, *, dns_timeout : Time::Span | Number? = nil, connect_timeout : Time::Span | Number? = nil) : UDPSocket

  Creates a UDPSocket and binds it to address and port.

Class Method Summary

• .open(address : Socket::IPAddress, *, dns_timeout : Time::Span | Number? = nil, connect_timeout : Time::Span | Number? = nil, &block)

  Creates a UDPSocket bound to address and yields it to the block.

• .open(host : String, port : Int32 = 0, *, dns_timeout : Time::Span | Number? = nil, connect_timeout : Time::Span | Number? = nil, &block)

  Creates a UDPSocket bound to address and port and yields it to the block.

Instance Method Summary

• #bind(addr : Address | Addrinfo) : Nil

  Binds this socket to a local address.

• #bind(address : String, port : Int) : Nil

  Binds this socket to local address and port.

• #bind(port : Int) : Nil

  Binds this socket to port on any local interface.

• #broadcast=(val : Bool) : Bool
• #broadcast? : Bool
• #close : Nil

  Closes this socket.

• #closed? : Bool

  Returns true if this socket is closed.

• #connect(address : Socket::IPAddress, *, connect_timeout : Time::Span | Number? = nil) : Nil

  Connects this UDP socket to remote address.

• #connect(host : String, port : Int, *, dns_timeout : Time::Span | Number? = nil, connect_timeout : Time::Span | Number? = nil) : Nil

  Connects this UDP socket to remote address host and port.

• #local_address : Socket::IPAddress

  Returns the IPAddress for the local end of the IP socket.

• #raw : Socket::Raw

  Returns the raw socket wrapped by this UDP socket.

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

  Receives a binary message from the previously bound address.

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

  Receives a text message from the previously bound address.

• #recv_buffer_size : Int32

  Returns the receive buffer size for this socket.

• #recv_buffer_size=(value : Int32) : Int32

  Sets the receive buffer size for this socket.

• #remote_address : Socket::IPAddress

  Returns the IPAddress for the remote end of the IP socket.

• #remote_address? : Socket::IPAddress?

  Returns the IPAddress for the remote end of the IP socket or nil if the socket is not connected.

• #reuse_address? : Bool

  Returns true if this socket has been configured to reuse the address (see SO_REUSEADDR).

• #reuse_port? : Bool

  Returns true if this socket has been configured to reuse the port (see SO_REUSEPORT).

• #send(message)
• #send(message, *, to addr : Socket::IPAddress)
• #send_buffer_size : Int32

  Returns the send buffer size for this socket.

• #send_buffer_size=(value : Int32) : Int32

  Sets the send buffer size for this socket.

Constructor Detail

Class Method Detail

Instance Method Detail

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

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

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

message, client_addr = server.receive