Library: Net
Package: NetCore
Header: Poco/Net/DNS.h
Description
This class provides an interface to the domain name service.
Starting with POCO C++ Libraries release 1.9.0, this class also supports Internationalized Domain Names (IDNs).
Regarding IDNs, the following rules apply:
- An IDN passed to hostByName() must be encoded manually, by calling encodeIDN() (after testing with isIDN() first).
- An UTF-8 IDN passed to resolve() or resolveOne() is automatically encoded.
- IDNs returned in HostEntry objects are never decoded. They can be decoded by calling decodeIDN() (after testing for an encoded IDN by calling isEncodedIDN()).
Member Summary
Member Functions: aierror, decodeIDN, decodeIDNLabel, encodeIDN, encodeIDNLabel, error, hostByAddress, hostByName, hostName, isEncodedIDN, isIDN, lastError, reload, resolve, resolveOne, thisHost
Enumerations
HintFlag
DNS_HINT_NONE = 0
DNS_HINT_AI_PASSIVE = 0x0001
Socket address will be used in bind() call
DNS_HINT_AI_CANONNAME = 0x0002
Return canonical name in first ai_canonname
DNS_HINT_AI_NUMERICHOST = 0x0004
Nodename must be a numeric address string
DNS_HINT_AI_NUMERICSERV = 0x0400
Servicename must be a numeric port number
DNS_HINT_AI_ALL = 0x0010
Query both IP6 and IP4 with AI_V4MAPPED
DNS_HINT_AI_ADDRCONFIG = 0x0020
Resolution only if global address configured
DNS_HINT_AI_V4MAPPED = 0x0008
On v6 failure, query v4 and convert to V4MAPPED format
Member Functions
decodeIDN 
static std::string decodeIDN(
const std::string & encodedIDN
);
Decodes the given Punycode-encoded IDN (internationalized domain name).
The resulting string will be UTF-8 encoded.
encodeIDN
static std::string encodeIDN(
const std::string & idn
);
Encodes the given IDN (internationalized domain name), which must be in UTF-8 encoding.
The resulting string will be encoded according to Punycode.
hostByAddress
static HostEntry hostByAddress(
const IPAddress & address,
unsigned hintFlags = DNS_HINT_AI_CANONNAME | DNS_HINT_AI_ADDRCONFIG
);
Returns a HostEntry object containing the DNS information for the host with the given IP address. HintFlag argument is only used on platforms that have getaddrinfo().
Throws a HostNotFoundException if a host with the given name cannot be found.
Throws a DNSException in case of a general DNS error.
Throws an IOException in case of any other error.
hostByName
static HostEntry hostByName(
const std::string & hostname,
unsigned hintFlags = DNS_HINT_AI_CANONNAME | DNS_HINT_AI_ADDRCONFIG
);
Returns a HostEntry object containing the DNS information for the host with the given name. HintFlag argument is only used on platforms that have getaddrinfo().
Note that Internationalized Domain Names must be encoded using Punycode (see encodeIDN()) before calling this method.
Throws a HostNotFoundException if a host with the given name cannot be found.
Throws a NoAddressFoundException if no address can be found for the hostname.
Throws a DNSException in case of a general DNS error.
Throws an IOException in case of any other error.
hostName
static std::string hostName();
Returns the host name of this host.
isEncodedIDN
static bool isEncodedIDN(
const std::string & hostname
);
Returns true if the given hostname is an Punycode-encoded internationalized domain name (IDN), otherwise false.
An encoded IDN starts with the character sequence "xn—".
isIDN
static bool isIDN(
const std::string & hostname
);
Returns true if the given hostname is an internationalized domain name (IDN) containing non-ASCII characters, otherwise false.
The IDN must be UTF-8 encoded.
reload
static void reload();
Reloads the resolver configuration.
This method will call res_init() if the Net library has been compiled with -DPOCO_HAVE_LIBRESOLV. Otherwise it will do nothing.
resolve
static HostEntry resolve(
const std::string & address
);
Returns a HostEntry object containing the DNS information for the host with the given IP address or host name.
If address contains a UTF-8 encoded IDN (internationalized domain name), the domain name will be encoded first using Punycode.
Throws a HostNotFoundException if a host with the given name cannot be found.
Throws a NoAddressFoundException if no address can be found for the hostname.
Throws a DNSException in case of a general DNS error.
Throws an IOException in case of any other error.
resolveOne
static IPAddress resolveOne(
const std::string & address
);
Convenience method that calls resolve(address) and returns the first address from the HostInfo.
thisHost
static HostEntry thisHost();
Returns a HostEntry object containing the DNS information for this host.
Throws a HostNotFoundException if DNS information for this host cannot be found.
Throws a NoAddressFoundException if no address can be found for this host.
Throws a DNSException in case of a general DNS error.
Throws an IOException in case of any other error.
aierror 
static void aierror(
int code,
const std::string & arg
);
Throws an exception according to the getaddrinfo() error code.
decodeIDNLabel
static std::string decodeIDNLabel(
const std::string & encodedIDN
);
Decodes the given Punycode-encoded IDN (internationalized domain name) label.
The resulting string will be UTF-8 encoded.
encodeIDNLabel
static std::string encodeIDNLabel(
const std::string & idn
);
Encodes the given IDN (internationalized domain name) label, which must be in UTF-8 encoding.
The resulting string will be encoded according to Punycode.
error
static void error(
int code,
const std::string & arg
);
Throws an exception according to the error code.
lastError
static int lastError();
Returns the code of the last error.