6.89. kink/socket/IP¶
Provides ip addresses and hostname resolution of both IPv4 and IPv6.
6.89.1. type ip¶
`ip` represents an IPv4 or IPv6 address in the binary form.
6.89.1.1. Ip.bin¶
`bin` method returns the ip address in type `bin`.
When `Ip` represents an IPv4 address, `bin` returns a `bin` of size 4.
When `Ip` represents an IPv6 address, `bin` returns a `bin` of size 16.
6.89.1.2. Ip.protocol_family¶
`protocol_family` returns the protocol family of the ip address in type `protocol_family`. The result is either PROTOCOL_FAMILY.ipv4 or PROTOCOL_FAMILY.ipv6.
6.89.1.3. Ip.text¶
`text` returns a text representation of the ip address `Ip` in type `str`.
When `Ip` is an IPv4 address, `text` returns a `str` of the dotted decimal format.
When `Ip` is an IPv6 address, `text` returns a `str` of the format defined in RFC 2732. The result uses small case letters, and performs no zero hextet omission.
Example
:IP.require_from('kink/socket/')
stdout.print_line(IP.for_hostname('127.0.0.1').text)
# => 127.0.0.1
stdout.print_line(IP.for_hostname('ff02::1').text)
# => ff02:0000:0000:0000:0000:0000:0000:0001
6.89.1.4. Ip.repr¶
`repr` returns a `str` representation of `Ip` for debugging purposes, like "(ip 127.0.0.1)" or "(ip ff02:0000:0000:0000:0000:0000:0000:0001)".
6.89.1.5. X == Y¶
`==` operator, or `op_eq` method, returns whether two `ip` values represent the same ip address.
6.89.2. IP.new(Bin)¶
`new` makes an `ip` value of the IPv4 or IPv6 address .
When the size of `Bin` is 4, the created `ip` is an IPv4 address. When the size of `Bin` is 16, the created `ip` is an IPv6 address.
Precondition
`Bin` must be a `bin` of size 4 or 16.
6.89.3. IP.is?(Val)¶
`is?` returns whether `Val` is an `ip` value.
6.89.4. IP.for_hostname(Hostname ...[$config={}])¶
`for_hostname` resolves the `Hostname` to an ip address.
Config methods:
• C.on_success($success): default = VAL.identity
• C.on_error($error): default = {(:Exc) Exc.raise }
If `Hostname` is resolved to an ip address, `for_hostname` tail-calls $success with an `ip` value.
If `Hostname` is not resolved to an ip address, `for_hostname` tail-calls $error with an `exception`.
Name resolution
`Hostname` is resolved in the following ways.
• IPv4 address in dotted decimal format. Ex. 127.0.0.1
• IPv6 address in the Text Representation specified in RFC 2373. Ex. ff06::c3
• IPv6 address in the IPv6 literal address format specified in RFC 3986. Ex. [ff06::c3]
• Host name. Ex. localhost, www.example.org
In general, a single host name can be resolved to multipe ip addresses. For example, DNS servers might return multiple A or AAAA records. `for_hostname` uses one of those ip addresses as the result.
Preconditions
`Hostname` must be a `str`.
$success must be a fun which takes an `ip` value.
$error must be a fun which takes an `exception` value.
Examples
:IP.require_from('kink/socket/')
# IPv4 address
stdout.print_line(IP.for_hostname('127.0.0.1').repr)
# => (ip 127.0.0.1)
# IPv6 address
stdout.print_line(IP.for_hostname('ff06::c3').repr)
# => (ip ff06:0000:0000:0000:0000:0000:0000:00c3)
# IPv6 literal address format
stdout.print_line(IP.for_hostname('[ff06::c3]').repr)
# => (ip ff06:0000:0000:0000:0000:0000:0000:00c3)
# Host name
stdout.print_line(IP.for_hostname('www.example.com').repr)
# => (ip 93.184.215.14)
6.89.5. IP.all_for_hostname(Hostname)¶
`all_for_hostname` returns a `vec` of `ip` values corresponding to `Hostname`, using the same name resolution mechanism with `for_hostname`.
Result
If `Hostname` is resolved to no ip address, `all_for_hostname` returns an empty `vec`.
If `Hostname` is resolved to a single ip address, `all_for_hostname` returns a `vec` of size 1 which contains an `ip` value.
If `Hostname` is resolved to multiple ip addresses, `all_for_hostname` returns a `vec` of multiple `ip` values.
Precondition
`Hostname` must be a `str`.
Example
:IP.require_from('kink/socket/')
stdout.print_line(IP.all_for_hostname('127.0.0.1').repr)
# => [(ip 127.0.0.1)]
stdout.print_line(IP.all_for_hostname('www.example.com').repr)
# => [(ip 93.184.215.14) (ip 2606:2800:021f:cb07:6820:80da:af6b:8b2c)]
6.89.6. IP.any¶
`any` returns in6addr_any address, which is the IPv6 address `[::]`.
This address can be used to accept connections, or receive datagram packets, from any IPv4 or IPv6 hosts.
6.89.7. IP.any_ipv4¶
`any_ipv4` returns INADDR_ANY address, which is the IPv4 address `0.0.0.0`.
This address can be used to accept connections, or receive datagram packets, from any IPv4 hosts.