Dns¶
| Spice | |
|---|---|
DnsServer struct¶
Name server to send queries to
Fields¶
| Name | Type | Description |
|---|---|---|
address |
IpAddress |
Address of the name server |
port |
unsigned short |
Port of the name server, usually DNS_PORT |
DnsConfig struct¶
Configuration of the resolver, usually read from /etc/resolv.conf (see resolv.conf(5)) or, on Windows, taken from the network adapters
Fields¶
| Name | Type | Description |
|---|---|---|
servers |
Vector<DnsServer> |
Name servers, asked in this order |
searchDomains |
Vector<String> |
Domains to append to names with less than ndots dots |
ndots |
unsigned int |
Number of dots, from which on a name is tried as absolute name first |
timeoutMs |
unsigned long |
Time to wait for the answer of a name server |
attempts |
unsigned int |
Number of rounds over all name servers |
DnsResponse struct¶
Answer of a name server to a single query
Fields¶
| Name | Type | Description |
|---|---|---|
responseCode |
int |
Response code (RCODE), e.g. DNS_RCODE_NO_ERROR or DNS_RCODE_NAME_ERROR |
truncated |
bool |
The answer did not fit into the datagram and has to be asked for over TCP |
addresses |
Vector<IpAddress> |
Addresses of the queried name, with CNAME records followed |
DnsResolver struct¶
Resolves host names to IPv4 and IPv6 addresses via the hosts file and DNS
Constructors¶
ctor¶
| Spice | |
|---|---|
Creates a resolver with the system configuration (see loadDnsConfig) and the hosts file of the system (see getSystemHostsFilePath). The configuration is only loaded, once a name server has to be asked, so that IP address literals and names from the hosts file do not pay for it.
ctor¶
| Spice | |
|---|---|
Creates a resolver with the given configuration
Parameters
| Name | Type | Description |
|---|---|---|
config |
const DnsConfig& |
Name servers and search rules |
hostsFilePath |
const String& |
Path of the hosts file, empty to skip the hosts file |
Methods¶
resolve¶
| Spice | |
|---|---|
Resolves a host name to its addresses. An IP address literal (IPv6 optionally in brackets, like in URLs) resolves to itself. Otherwise the name is looked up in the hosts file first and, if it is not listed there, asked for at the name servers, with the search domains applied like described in resolv.conf(5). The names "localhost" and "*.localhost" resolve to the loopback addresses, unless the hosts file lists them (it takes precedence, like with the C library). Names, whose last label is a decimal or hexadecimal number (like "127.1" or "0x7f000001"), are rejected instead of being sent to the name servers. IPv4 addresses come first in the result, IPv6 addresses second.
Parameters
| Name | Type | Description |
|---|---|---|
host |
const String& |
Host name or IP address literal |
includeIpv4 |
bool |
Look for IPv4 addresses (default: true) |
includeIpv6 |
bool |
Look for IPv6 addresses (default: true) |
Returns: Result<Vector<IpAddress>> — Addresses of the host, never empty
connectTcp¶
| Spice | |
|---|---|
Opens a TCP connection to the given host and port. A host may have several IPv4 and IPv6 addresses,
which are tried one after the other, until a connection is established:
- Addresses, that need no name server (IP address literals, the hosts file, the localhost names),
are tried first, IPv4 ones before IPv6 ones.
- Otherwise the candidate names (see resolve) are asked for one after the other. For each one, the
IPv4 addresses are looked up and tried first; the IPv6 addresses are only looked up, if none of
them works, so that a slow or missing answer for them never delays a connection. The first
candidate, that has any addresses, is the last one to be asked for, like with resolve.
Parameters
| Name | Type | Description |
|---|---|---|
host |
const String& |
Host name or IP address literal (IPv6 optionally in brackets) |
port |
unsigned short |
Port to connect to |
Returns: Result<int> — File descriptor (socket handle on Windows) of the connected socket
query¶
| Spice | |
|---|---|
Asks the name servers for the records of the given type of exactly the given name. The name servers are asked one after the other, until one gives a definite answer (the name exists or does not exist), for the configured number of rounds.
Parameters
| Name | Type | Description |
|---|---|---|
name |
const String& |
Absolute name to ask for, with or without trailing dot |
recordType |
unsigned short |
DNS_TYPE_A or DNS_TYPE_AAAA |
Returns: Result<DnsResponse> — Definite answer of a name server
Functions¶
loadDnsConfig¶
| Spice | |
|---|---|
Reads the DNS configuration of the system: on Linux and macOS from /etc/resolv.conf, on Windows from the name servers and DNS suffixes of the network adapters. If there is none, the defaults apply, i.e. the name server on the local host is asked.
Returns: DnsConfig — DNS configuration
parseResolvConf¶
| Spice | |
|---|---|
Parses the content of a resolv.conf file (see resolv.conf(5)). Understood are the keywords 'nameserver' (up to three), 'search', 'domain' and 'options' with the options 'ndots:n', 'timeout:n' and 'attempts:n'. Anything else is ignored. Without any name server, the name server on the local host is used.
Parameters
| Name | Type | Description |
|---|---|---|
content |
const String& |
Content of the resolv.conf file |
Returns: DnsConfig — DNS configuration
lookupHostsFile¶
| Spice | |
|---|---|
Looks up a name in the content of a hosts file (see hosts(5)). Each line holds an address, followed by the canonical name and the aliases of the host.
Parameters
| Name | Type | Description |
|---|---|---|
content |
const String& |
Content of the hosts file |
name |
const String& |
Name to look up, in lowercase and without trailing dot |
Returns: Vector<IpAddress> — Addresses of all lines, that list the name, in the order of the lines
buildDnsQuery¶
| Spice | |
|---|---|
Encodes a query for the records of the given type of the given name, with recursion desired
Parameters
| Name | Type | Description |
|---|---|---|
id |
unsigned short |
ID of the query, that the answer has to carry |
name |
const String& |
Absolute name to ask for, without trailing dot |
recordType |
unsigned short |
Record type to ask for |
Returns: Result<Vector<unsigned byte>> — Encoded query
parseDnsResponse¶
| Spice | |
|---|---|
Decodes the answer of a name server to a query. The answer is only accepted, if it carries the ID of the query and repeats its question. The addresses are taken from the records of the queried name or, if it is an alias, from the records of the name that the CNAME records lead to.
Parameters
| Name | Type | Description |
|---|---|---|
message |
const Vector<unsigned byte>& |
Encoded answer |
id |
unsigned short |
ID of the query |
name |
const String& |
Name, that the query asked for, in lowercase and without trailing dot |
recordType |
unsigned short |
Record type, that the query asked for |
Returns: Result<DnsResponse> — Decoded answer
getSystemHostsFilePath¶
| Spice | |
|---|---|
Returns the path of the hosts file of the system: /etc/hosts on Linux and macOS, %SystemRoot%\System32\drivers\etc\hosts on Windows
Returns: String — Path of the hosts file
resolveHostAddresses¶
| Spice | |
|---|---|
Resolves a host name to its addresses with the system configuration (see loadDnsConfig) and the hosts file of the system. See DnsResolver.resolve for the details.
Parameters
| Name | Type | Description |
|---|---|---|
host |
const String& |
Host name or IP address literal |
includeIpv4 |
bool |
Look for IPv4 addresses (default: true) |
includeIpv6 |
bool |
Look for IPv6 addresses (default: true) |
Returns: Result<Vector<IpAddress>> — Addresses of the host, IPv4 ones first, never empty