class UDPSocket

Overview

A User Datagram Protocol 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

client.puts "message" # send message to server
server.gets           # => "message\n"

# 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:

socket/udp_socket.cr

Class Method Summary

Instance Method Summary

Instance methods inherited from class IPSocket

local_address local_address, remote_address remote_address

Instance methods inherited from class Socket

broadcast=(val : Bool) broadcast=, broadcast? broadcast?, close_read close_read, close_write close_write, getsockopt(optname, optval, level = LibC::SOL_SOCKET) getsockopt, inspect(io) inspect, keepalive=(val : Bool) keepalive=, keepalive? keepalive?, linger linger, linger=(val : Int | Nil) linger=, recv_buffer_size recv_buffer_size, recv_buffer_size=(val : Int32) recv_buffer_size=, reuse_address=(val : Bool) reuse_address=, reuse_address? reuse_address?, send_buffer_size send_buffer_size, send_buffer_size=(val : Int32) send_buffer_size=, setsockopt(optname, optval, level = LibC::SOL_SOCKET) setsockopt

Class methods inherited from class Socket

ip?(string : String) ip?, new(fd, blocking = false) new

Instance methods inherited from class IO::FileDescriptor

blocking blocking, blocking=(value) blocking=, close_on_exec=(arg : Bool) close_on_exec=, close_on_exec? close_on_exec?, closed? : Bool closed?, cooked(&block) cooked, cooked! cooked!, fcntl(cmd, arg = 0) fcntl, fd : Int32 fd, finalize finalize, inspect(io) inspect, noecho(&block) noecho, noecho! noecho!, pos pos, pos=(value) pos=, raw(&block) raw, raw! raw!, read_timeout=(read_timeout : Time::Span)
read_timeout=(read_timeout : Number)
read_timeout=(read_timeout : Nil) read_timeout=, reopen(other : IO::FileDescriptor) reopen, seek(offset, whence : Seek = Seek::Set) seek, stat stat, tell tell, tty? tty?, write_timed_out : Bool write_timed_out, write_timed_out=(write_timed_out : Bool) write_timed_out=, write_timeout=(write_timeout : Number)
write_timeout=(write_timeout : Nil)
write_timeout=(write_timeout : Time::Span) write_timeout=

Class methods inherited from class IO::FileDescriptor

fcntl(fd, cmd, arg = 0) fcntl, new(fd : Int32, blocking = false, edge_triggerable = false) new

Instance methods inherited from module IO::Buffered

close close, flush flush, flush_on_newline=(flush_on_newline) flush_on_newline=, flush_on_newline? flush_on_newline?, read(slice : Slice(UInt8)) read, rewind rewind, sync=(sync) sync=, sync? sync?, unbuffered_close unbuffered_close, unbuffered_flush unbuffered_flush, unbuffered_read(slice : Slice(UInt8)) unbuffered_read, unbuffered_rewind unbuffered_rewind, unbuffered_write(slice : Slice(UInt8)) unbuffered_write, write(slice : Slice(UInt8)) write

Instance methods inherited from module IO

<<(obj) : self <<, close close, closed? closed?, each_byte(&block)
each_byte each_byte, each_char(&block)
each_char each_char, each_line(*args, **options)
each_line(*args, **options, &block) each_line, encoding : String encoding, flush flush, gets(limit : Int) : String | Nil
gets(delimiter : Char, limit : Int) : String | Nil
gets(delimiter : Char) : String | Nil
gets : String | Nil
gets(delimiter : String) : String | Nil gets, gets_to_end : String gets_to_end, print(obj) : Nil
print(*objects : _) : Nil print, printf(format_string, *args) : Nil
printf(format_string, args : Array | Tuple) : Nil printf, puts(*objects : _) : Nil
puts : Nil
puts(string : String) : Nil
puts(obj) : Nil puts, read(slice : Slice(UInt8)) read, read_byte : UInt8 | Nil read_byte, read_bytes(type, format : IO::ByteFormat = IO::ByteFormat::SystemEndian) read_bytes, read_char : Char | Nil read_char, read_fully(slice : Slice(UInt8)) read_fully, read_line(*args, **options) : String | Nil read_line, read_utf8(slice : Slice(UInt8)) read_utf8, read_utf8_byte read_utf8_byte, rewind rewind, set_encoding(encoding : String, invalid : Symbol | Nil = nil) set_encoding, skip(bytes_count : Int) : Nil skip, tty? : Bool tty?, write(slice : Slice(UInt8)) : Nil write, write_byte(byte : UInt8) write_byte, write_bytes(object, format : IO::ByteFormat = IO::ByteFormat::SystemEndian) write_bytes, write_utf8(slice : Slice(UInt8)) write_utf8

Class methods inherited from module IO

copy(src, dst, limit : Int)
copy(src, dst) copy, pipe(read_blocking = false, write_blocking = false, &block)
pipe(read_blocking = false, write_blocking = false) pipe, select(read_ios, write_ios, error_ios, timeout_sec : LibC::TimeT | Int | Float | Nil)
select(read_ios, write_ios = nil, error_ios = nil) select

Instance methods inherited from module JSON::Builder

json_array(&block) json_array, json_object(&block) json_object

Instance methods inherited from class Reference

==(other)
==(other : self) ==, dup dup, hash hash, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, same?(other : Reference)
same?(other : Nil) same?, to_s(io : IO) : Nil to_s

Instance methods inherited from class Object

!=(other) !=, !~(other) !~, ==(other) ==, ===(other)
===(other : YAML::Any)
===(other : JSON::Any) ===, =~(other) =~, class class, crystal_type_id crystal_type_id, dup dup, hash hash, inspect(io : IO)
inspect inspect, itself itself, not_nil! not_nil!, tap(&block) tap, to_json to_json, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, indent : String = " ") to_pretty_json, to_s
to_s(io : IO) to_s, to_yaml
to_yaml(io : IO) to_yaml, try(&block) try

Class methods inherited from class Object

==(other : Class) ==, ===(other) ===, cast(other) : self cast, clone clone, dup dup, from_json(string_or_io) : self
from_json(string_or_io, root : String) : self from_json, from_yaml(string : String) : self from_yaml, hash hash, inspect(io) inspect, name : String name, nilable? nilable?, to_s(io) to_s, |(other : U.class) forall U |

Class Method Detail

def self.new(family : Family = Family::INET) #

[View source]

Instance Method Detail

def bind(host, port, dns_timeout = nil) #

Binds the UDP socket to a local address.

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

[View source]
def connect(host, port, dns_timeout = nil, connect_timeout = nil) #

Connects the UDP socket to a remote address to send messages to.

client = UDPSocket.new
client.connect("localhost", 1234)
client.send("a text message")

[View source]
def receive(message : Slice(UInt8)) : Tuple(Int32, IPAddress) #

Receives a binary message on the previously bound address.

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

message = Slice(UInt8).new(32)
message_size, client_addr = server.receive(message)

[View source]
def send(message : Slice(UInt8)) #

Sends a binary message to the previously connected remote address. See #connect.


[View source]
def send(message : String) #

Sends a text message to the previously connected remote address. See #connect.


[View source]
def send(message : String, addr : IPAddress) #

Sends a text message to the specified remote address.


[View source]
def send(message : Slice(UInt8), addr : IPAddress) #

Sends a binary message to the specified remote address.


[View source]