200 lines
6.4 KiB
C++
200 lines
6.4 KiB
C++
//
|
|
// DNS.h
|
|
//
|
|
// Library: Net
|
|
// Package: NetCore
|
|
// Module: DNS
|
|
//
|
|
// Definition of the DNS class.
|
|
//
|
|
// Copyright (c) 2005-2006, Applied Informatics Software Engineering GmbH.
|
|
// and Contributors.
|
|
//
|
|
// SPDX-License-Identifier: BSL-1.0
|
|
//
|
|
|
|
|
|
#ifndef Net_DNS_INCLUDED
|
|
#define Net_DNS_INCLUDED
|
|
|
|
|
|
#include "Poco/Net/Net.h"
|
|
#include "Poco/Net/SocketDefs.h"
|
|
#include "Poco/Net/IPAddress.h"
|
|
#include "Poco/Net/HostEntry.h"
|
|
|
|
|
|
namespace Poco {
|
|
namespace Net {
|
|
|
|
|
|
class Net_API DNS
|
|
/// 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()).
|
|
{
|
|
public:
|
|
enum HintFlag
|
|
{
|
|
DNS_HINT_NONE = 0,
|
|
#ifdef POCO_HAVE_ADDRINFO
|
|
DNS_HINT_AI_PASSIVE = AI_PASSIVE, /// Socket address will be used in bind() call
|
|
DNS_HINT_AI_CANONNAME = AI_CANONNAME, /// Return canonical name in first ai_canonname
|
|
DNS_HINT_AI_NUMERICHOST = AI_NUMERICHOST, /// Nodename must be a numeric address string
|
|
DNS_HINT_AI_NUMERICSERV = AI_NUMERICSERV, /// Servicename must be a numeric port number
|
|
DNS_HINT_AI_ALL = AI_ALL, /// Query both IP6 and IP4 with AI_V4MAPPED
|
|
DNS_HINT_AI_ADDRCONFIG = AI_ADDRCONFIG, /// Resolution only if global address configured
|
|
DNS_HINT_AI_V4MAPPED = AI_V4MAPPED /// On v6 failure, query v4 and convert to V4MAPPED format
|
|
#endif
|
|
};
|
|
|
|
static HostEntry hostByName(const std::string& hostname, unsigned hintFlags =
|
|
#ifdef POCO_HAVE_ADDRINFO
|
|
DNS_HINT_AI_CANONNAME | DNS_HINT_AI_ADDRCONFIG
|
|
#else
|
|
DNS_HINT_NONE
|
|
#endif
|
|
);
|
|
/// 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.
|
|
|
|
static HostEntry hostByAddress(const IPAddress& address, unsigned hintFlags =
|
|
#ifdef POCO_HAVE_ADDRINFO
|
|
DNS_HINT_AI_CANONNAME | DNS_HINT_AI_ADDRCONFIG
|
|
#else
|
|
DNS_HINT_NONE
|
|
#endif
|
|
);
|
|
/// 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.
|
|
|
|
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.
|
|
|
|
static IPAddress resolveOne(const std::string& address);
|
|
/// Convenience method that calls resolve(address) and returns
|
|
/// the first address from the HostInfo.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
static std::string hostName();
|
|
/// Returns the host name of this host.
|
|
|
|
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.
|
|
|
|
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--".
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
protected:
|
|
static int lastError();
|
|
/// Returns the code of the last error.
|
|
|
|
static void error(int code, const std::string& arg);
|
|
/// Throws an exception according to the error code.
|
|
|
|
static void aierror(int code, const std::string& arg);
|
|
/// Throws an exception according to the getaddrinfo() error code.
|
|
|
|
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.
|
|
|
|
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.
|
|
};
|
|
|
|
|
|
} } // namespace Poco::Net
|
|
|
|
|
|
#endif // Net_DNS_INCLUDED
|