Socket::Addrinfo - Crystal 1.16.3

# struct Socket::Addrinfo

- Socket::Addrinfo
- Struct
- Value
- Object

##
Overview

Domain name resolver.

#
Query Concurrency Behaviour

On most platforms, DNS queries are currently resolved synchronously. Calling a resolve method blocks the entire thread until it returns. This can cause latencies, especially in single-threaded processes.

DNS queries resolve asynchronously on the following platforms:

- Windows 8 and higher

NOTE Follow the discussion in Async DNS resolution (#13619) for more details.

##
Included Modules

- Crystal::System::Addrinfo

##
Defined in:

socket/addrinfo.cr

##
Class Method Summary

- .resolve(domain : String, service, family : Family | Nil = nil, type : Type = nil, protocol : Protocol = Protocol::IP, timeout = nil) : Array(Addrinfo)

  Resolves a domain that best matches the given options.

- .resolve(domain : String, service, family : Family | Nil = nil, type : Type = nil, protocol : Protocol = Protocol::IP, timeout = nil, &)

  Resolves a domain that best matches the given options.

- .tcp(domain : String, service, family = Family::UNSPEC, timeout = nil) : Array(Addrinfo)

  Resolves domain for the TCP protocol and returns an `Array` of possible `Addrinfo`.

- .tcp(domain : String, service, family = Family::UNSPEC, timeout = nil, &)

  Resolves a domain for the TCP protocol with STREAM type, and yields each possible `Addrinfo`.

- .udp(domain : String, service, family = Family::UNSPEC, timeout = nil) : Array(Addrinfo)

  Resolves domain for the UDP protocol and returns an `Array` of possible `Addrinfo`.

- .udp(domain : String, service, family = Family::UNSPEC, timeout = nil, &)

  Resolves a domain for the UDP protocol with DGRAM type, and yields each possible `Addrinfo`.

##
Instance Method Summary

- #family : Family
- #inspect(io : IO)

  Appends this struct's name and instance variables names and values to the given IO.

- #ip_address : Socket::IPAddress

  Returns an `IPAddress` matching this addrinfo.

- #protocol : Protocol
- #size : Int32
- #type : Type

### Instance methods inherited from module `Crystal::System::Addrinfo`

system_ip_address : ::Socket::IPAddress system_ip_address, to_unsafe to_unsafe

### Class methods inherited from module `Crystal::System::Addrinfo`

free_addrinfo(addrinfo : Handle) free_addrinfo, getaddrinfo(domain, service, family, type, protocol, timeout, & : ::Socket::Addrinfo -> )
getaddrinfo(domain, service, family, type, protocol, timeout) : Handle getaddrinfo, next_addrinfo(addrinfo : Handle) : Handle next_addrinfo

### Instance methods inherited from struct `Struct`

==(other) : Bool ==, hash(hasher) hash, inspect(io : IO) : Nil inspect, pretty_print(pp) : Nil pretty_print, to_s(io : IO) : Nil to_s

### Instance methods inherited from struct `Value`

==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup

### Instance methods inherited from class `Object`

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

### Class methods inherited from class `Object`

from_json(string_or_io, root : String)
from_json(string_or_io) from_json, from_yaml(string_or_io : String | IO) from_yaml

### Macros inherited from class `Object`

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

##
Class Method Detail

def self.resolve(domain : String, service, family : Family | Nil = nil, type : Type = nil, protocol : Protocol = Protocol::IP, timeout = nil) : Array(Addrinfo) #

Resolves a domain that best matches the given options.

- domain may be an IP address or a domain name.
- service may be a port number or a service name. It must be specified, because different servers may handle the `mail` or `http` services for example.
- family is optional and defaults to `Family::UNSPEC`
- type is the intended socket type (e.g. `Type::STREAM`) and must be specified.
- protocol is the intended socket protocol (e.g. `Protocol::TCP`) and should be specified.
- timeout is optional and specifies the maximum time to wait before `IO::TimeoutError` is raised. Currently this is only supported on Windows.

Example:

    require "socket"

    addrinfos = Socket::Addrinfo.resolve("example.org", "http", type: Socket::Type::STREAM, protocol: Socket::Protocol::TCP)

def self.resolve(domain : String, service, family : Family | Nil = nil, type : Type = nil, protocol : Protocol = Protocol::IP, timeout = nil, &) #

Resolves a domain that best matches the given options.

Yields each possible `Addrinfo` resolution since a domain may resolve to many IP. Implementations are supposed to try all the addresses until the socket is connected (or bound) or there are no addresses to try anymore.

Raising is an expensive operation, so instead of raising on a connect or bind error, just to rescue it immediately after, the block is expected to return the error instead, which will be raised once there are no more addresses to try.

The iteration will be stopped once the block returns something that isn't an `Exception` (e.g. a `Socket` or `nil`).

def self.tcp(domain : String, service, family = Family::UNSPEC, timeout = nil) : Array(Addrinfo) #

Resolves domain for the TCP protocol and returns an `Array` of possible `Addrinfo`. See `#resolve` for details.

Example:

    require "socket"

    addrinfos = Socket::Addrinfo.tcp("example.org", 80)

def self.tcp(domain : String, service, family = Family::UNSPEC, timeout = nil, &) #

Resolves a domain for the TCP protocol with STREAM type, and yields each possible `Addrinfo`. See `#resolve` for details.

def self.udp(domain : String, service, family = Family::UNSPEC, timeout = nil) : Array(Addrinfo) #

Resolves domain for the UDP protocol and returns an `Array` of possible `Addrinfo`. See `#resolve` for details.

Example:

    require "socket"

    addrinfos = Socket::Addrinfo.udp("example.org", 53)

def self.udp(domain : String, service, family = Family::UNSPEC, timeout = nil, &) #

Resolves a domain for the UDP protocol with DGRAM type, and yields each possible `Addrinfo`. See `#resolve` for details.

##
Instance Method Detail

def family : Family #
def inspect(io : IO) #
Description copied from struct Struct

Appends this struct's name and instance variables names and values to the given IO.

    struct Point
      def initialize(@x : Int32, @y : Int32)
      end
    end

    p1 = Point.new 1, 2
    p1.to_s    # "Point(@x=1, @y=2)"
    p1.inspect # "Point(@x=1, @y=2)"

def ip_address : Socket::IPAddress #

Returns an `IPAddress` matching this addrinfo.

def protocol : Protocol #
def size : Int32 #
def type : Type #