dns

The DNS interface is for DNS lookups. Note that this class is - while be used asynchrounosly - internal using a thread for the look up stuff.

File information

File	common/interface/dns.h
Classes	IDns UDns IDnsQueryResult IDnsQueryEntry IDnsQueryEntryA IDnsQueryEntryAAAA IDnsQueryEntryCNAME IDnsQueryEntryMX IDnsQueryEntryNS IDnsQueryEntrySRV IDnsQueryEntryTXT IDnsQueryEntrySOA IDnsQueryEntryPTR IDnsQueryEntryNAPTR
Data types	DNS_DEFAULT_TIMEOUT dns_query_type_sdk
Examples	Code Example

Classes

IDns

class IDns {
public:
    static IDns * Create(class IIoMux * const iomux);
    virtual ~IDns() {};
    virtual void GetHostByName(const char * host, class UDns * const user, class IInstanceLog * const log, dword timeout = DNS_DEFAULT_TIMEOUT, bool all = false);
    virtual void Query(const char * hostName, class UDns * const user, class IInstanceLog * const log, dns_query_type_sdk queryType);
};

Public functions

Create (static)

Creates an instance of IDns. iomux has to be a iomux instance IDns can use. The returned instance needs to be deleted after it is no longer used. Note that the IDns uses a thread to make the DNS lookup to not block the application. Generally this won't be a problem for the application, because the result of the lookup will be send to the mainthread of the application (or at least to the thread of the given iomux) in an synchronized way.

Parameters

class IIoMux * const iomux

The IIoMux instance used by IDns.

Return value

The IDns instance the application can use for for DNS lookups. Note that this instance must be released by the application, if no longer used.

GetHostByName

Starts the lookup of the given host. The lookup requests will be cached internally and handled in a fifo order. The interface uses the DNS servers defined in the local network settings of the AppPlatform.

Parameters

const char * host	The hostname (e. g. "innovaphone.com").
class UDns * user	The UDns instance callback after the name has been resolved (or an error occurred).
class IInstanceLog * const log	The IInstanceLog instance to write logging messages to. Only used, if LOG_DNS is enabled.
dword timeout	(Default: DNS_DEFAULT_TIMEOUT) The timeout in milliseconds to wait until the request will be canceled if the DNS server won't answer.
bool all	(Default: false) If that flag is set, all IP addresses found for the hostname will be reported, else only the first one.

Callbacks

UDns::DnsGetHostByNameResult() will be called, passing the IP address for the given hostname. If all is set to true, the function can be called multiple times. If an error occures, the addr parameter of the callback function will be nullptr. See UDns.

Query

Starts the lookup of the given host. The interface uses the DNS servers defined in the local network settings of the AppPlatform and uses the res_query functionality.

Parameters

const char * host	The hostname (e. g. "innovaphone.com").
class UDns * user	The UDns instance callback after the name has been resolved (or an error occurred).
class IInstanceLog * const log	The IInstanceLog instance to write logging messages to. Only used, if LOG_DNS is enabled.
dns_query_type_sdk queryType	A value of enum dns_query_type_sdk to indicate the type of search.

Callbacks

UDns::DnsQueryResult() will be called, passing the raw bytes of the server answer. See UDns.

UDns

class UDns {
public:
    virtual void DnsGetHostByNameResult(const char * addr, bool isIPv6);
    virtual void DnsQueryResult(const byte * answer, unsigned length);
};

DnsGetHostByNameResult

When calling IDns::GetHostByName(), an instance of UDns must be passed as user. So the application must provide a class instance that implements UDns. After a DNS lookup, this function will be called. If the flag all of IDnsGetHostByName() has ben set to true, DnsGetHostByNameResult() can be called multiple times, one time for each DNS entry found.

Parameters

const char * addr	The TCP/IP address of the hostname given to IDns::GetHostByName(). If an error occured, addr will be nullptr.
bool isIPv6	True, if the address given in addr is an IPv6 address, or false, if it is IPv4.

DnsQueryResult

When calling IDns::DnsQuery(), an instance of UDns must be passed as user. So the application must provide a class instance that implements UDns. After a DNS lookup, this function will be called.

Parameters

const byte * answer	The binary answer.
unsigned length	The length of the binary data.

Remarks

You can parse the answer with IDnsQueryResult::Parse.

IDnsQueryResult

class IDnsQueryResult {
public:
    static IDnsQueryResult * Parse(const byte * answer, unsigned length);

    virtual ~IDnsQueryResult() {};

    virtual size_t GetAnswerCount() = 0;
    virtual size_t GetAuthorityCount() = 0;
    virtual size_t GetAdditionalCount() = 0;
    virtual IDnsQueryEntry * GetAnswer(size_t index) = 0;
    virtual IDnsQueryEntry * GetAuthority(size_t index) = 0;
    virtual IDnsQueryEntry * GetAdditional(size_t index) = 0;
};

Public functions

Parse (static)

Parses a DNS query response from the provided binary data.

Parameters

const byte * answer	The binary data of the DNS query response.
unsigned length	The length of the binary data.

Return value

An instance of IDnsQueryResult representing the parsed DNS query response. The caller is responsible to delete the object.
A nullptr is returned if the answer couldn't be parsed.

GetAnswerCount

Retrieves the number of answer records in the DNS query response.

Return value

The number of answer records.

GetAuthorityCount

Retrieves the number of authority records in the DNS query response.

Return value

The number of authority records.

GetAdditionalCount

Retrieves the number of additional records in the DNS query response.

Return value

The number of additional records.

GetAnswer

Retrieves the answer record at the specified index.

Parameters

size_t index

The index of the answer record.

Return value

An instance of IDnsQueryEntry representing the answer record. A nullptr is returned if the index is out of bound.

GetAuthority

Retrieves the authority record at the specified index.

Parameters

size_t index

The index of the authority record.

Return value

An instance of IDnsQueryEntry representing the authority record. A nullptr is returned if the index is out of bound.

GetAdditional

Retrieves the additional record at the specified index.

Parameters

size_t index

The index of the additional record.

Return value

An instance of IDnsQueryEntry representing the additional record. A nullptr is returned if the index is out of bound.

IDnsQueryEntry

class IDnsQueryEntry {
public:
    virtual ~IDnsQueryEntry() {};

    virtual const char * GetName() { return nullptr; }
    virtual dns_query_type_sdk GetType() { return DNS_QUERY_TYPE_NONE; }
    virtual dword GetTTL() { return 0; }
};

Public functions

GetName

Retrieves the name associated with this DNS query entry.

Return value

The name as a string.

GetType

Retrieves the type of this DNS query entry.

Return value

A value from the dns_query_type_sdk enum indicating the type.

GetTTL

Retrieves the Time-To-Live (TTL) of this DNS query entry.

Return value

The TTL as a dword.

IDnsQueryEntryA

class IDnsQueryEntryA : public virtual IDnsQueryEntry {
public:
    virtual ~IDnsQueryEntryA() {};

    virtual const char * GetAddress() = 0;
};

Public functions

GetAddress

Retrieves the IPv4 address associated with this DNS A record entry.

Return value

The IPv4 address as a string.

IDnsQueryEntryAAAA

class IDnsQueryEntryAAAA : public virtual IDnsQueryEntry {
public:
    virtual ~IDnsQueryEntryAAAA() {};

    virtual const char * GetAddress() = 0;
};

Public functions

GetAddress

Retrieves the IPv6 address associated with this DNS AAAA record entry.

Return value

The IPv6 address as a string.

IDnsQueryEntryCNAME

class IDnsQueryEntryCNAME : public virtual IDnsQueryEntry {
public:
    virtual ~IDnsQueryEntryCNAME() {};

    virtual const char * GetCanonicalName() = 0;
};

Public functions

GetCanonicalName

Retrieves the canonical name associated with this DNS CNAME record entry.

Return value

The canonical name as a string.

IDnsQueryEntryMX

class IDnsQueryEntryMX : public virtual IDnsQueryEntry {
public:
    virtual ~IDnsQueryEntryMX() {};

    virtual word GetPreference() = 0;
    virtual const char * GetMailServer() = 0;
};

Public functions

GetPreference

Retrieves the preference value associated with this DNS MX record entry.

Return value

The preference value as a word.

GetMailServer

Retrieves the mail server associated with this DNS MX record entry.

Return value

The mail server as a string.

IDnsQueryEntryNS

class IDnsQueryEntryNS : public virtual IDnsQueryEntry {
public:
    virtual ~IDnsQueryEntryNS() {};

    virtual const char * GetNameServer() = 0;
};

Public functions

GetNameServer

Retrieves the name server associated with this DNS NS record entry.

Return value

The name server as a string.

IDnsQueryEntrySRV

class IDnsQueryEntrySRV : public virtual IDnsQueryEntry {
public:
    virtual ~IDnsQueryEntrySRV() {};

    virtual word GetPriority() = 0;
    virtual word GetWeight() = 0;
    virtual word GetPort() = 0;
    virtual const char * GetTarget() = 0;
};

Public functions

GetPriority

Retrieves the priority value associated with this DNS SRV record entry.

Return value

The priority value as a word.

GetWeight

Retrieves the weight value associated with this DNS SRV record entry.

Return value

The weight value as a word.

GetPort

Retrieves the port value associated with this DNS SRV record entry.

Return value

The port value as a word.

GetTarget

Retrieves the target associated with this DNS SRV record entry.

Return value

The target as a string.

IDnsQueryEntryTXT

class IDnsQueryEntryTXT : public virtual IDnsQueryEntry {
public:
    virtual ~IDnsQueryEntryTXT() {};

    virtual size_t GetTextCount() = 0;
    virtual const char * GetTxt(size_t index) = 0;
};

Public functions

GetTextCount

Retrieves the number of text strings associated with this DNS TXT record entry.

Return value

The number of text strings.

GetTxt

Retrieves the text string at the specified index associated with this DNS TXT record entry.

Parameters

size_t index

The index of the text string.

Return value

The text string as a string.

IDnsQueryEntrySOA

class IDnsQueryEntrySOA : public virtual IDnsQueryEntry {
public:
    virtual ~IDnsQueryEntrySOA() {};

    virtual const char * GetPrimaryNS() = 0;
    virtual const char * GetResponsibleMailbox() = 0;
    virtual dword GetSerialNumber() = 0;
    virtual dword GetRefreshInterval() = 0;
    virtual dword GetRetryInterval() = 0;
    virtual dword GetExpireLimit() = 0;
    virtual dword GetMinimumTTL() = 0;
};

Public functions

GetPrimaryNS

Retrieves the primary name server associated with this DNS SOA record entry.

Return value

The primary name server as a string.

GetResponsibleMailbox

Retrieves the responsible mailbox associated with this DNS SOA record entry.

Return value

The responsible mailbox as a string.

GetSerialNumber

Retrieves the serial number associated with this DNS SOA record entry.

Return value

The serial number as a dword.

GetRefreshInterval

Retrieves the refresh interval associated with this DNS SOA record entry.

Return value

The refresh interval as a dword.

GetRetryInterval

Retrieves the retry interval associated with this DNS SOA record entry.

Return value

The retry interval as a dword.

GetExpireLimit

Retrieves the expire limit associated with this DNS SOA record entry.

Return value

The expire limit as a dword.

GetMinimumTTL

Retrieves the minimum TTL associated with this DNS SOA record entry.

Return value

The minimum TTL as a dword.

IDnsQueryEntryPTR

class IDnsQueryEntryPTR : public virtual IDnsQueryEntry {
public:
    virtual ~IDnsQueryEntryPTR() {};

    virtual const char * GetDomainName() = 0;
};

Public functions

GetDomainName

Retrieves the domain name associated with this DNS PTR record entry.

Return value

The domain name as a string.

IDnsQueryEntryNAPTR

class IDnsQueryEntryNAPTR : public virtual IDnsQueryEntry {
public:
    virtual ~IDnsQueryEntryNAPTR() {};

    virtual word GetOrder() = 0;
    virtual word GetPreference() = 0;
    virtual const char * GetFlags() = 0;
    virtual const char * GetServices() = 0;
    virtual const char * GetRegexp() = 0;
    virtual const char * GetReplacement() = 0;
};

Public functions

GetOrder

Retrieves the order in which the NAPTR records must be processed when multiple records are returned. Lower values indicate higher priority.

Return value

The order as a word.

GetPreference

Retrieves the preference in which NAPTR records with the same Order value should be processed. Lower values indicate higher preference.

Return value

The preference as a word.

GetFlags

Indicates how the next DNS lookup should be performed. Common values include "U" (indicating URI) or "S" (indicating service).

Return value

The flags as a string.

GetServices

Indicates the service(s) available, such as "E2U+sip" (indicating ENUM service for SIP).

Return value

The services as a string.

GetRegexp

A substitution expression (regular expression) used to rewrite the original string. This can be used to transform the requested domain name into another domain name or URI.

Return value

The regexp as a string.

GetReplacement

Specifies the domain name to query next, after applying the regular expression. If the regular expression field is empty, this field is used directly.

Return value

The replacement as a string.

Data types

Defines / Statics

DNS_DEFAULT_TIMEOUT

The default timeout for DNS lookup requests (5000ms).

dns_query_type_sdk


typedef enum {
    DNS_QUERY_TYPE_NONE     = 0,   /* use getaddr_info instead of res_query */
    DNS_QUERY_TYPE_A        = 1,   /* host address */
    DNS_QUERY_TYPE_NS       = 2,   /* authoritative server */
    DNS_QUERY_TYPE_MD       = 3,   /* mail destination */
    DNS_QUERY_TYPE_MF       = 4,   /* mail forwarder */
    DNS_QUERY_TYPE_CNAME    = 5,   /* canonical name */
    DNS_QUERY_TYPE_SOA      = 6,   /* start of authority zone */
    DNS_QUERY_TYPE_MB       = 7,   /* mailbox domain name */
    DNS_QUERY_TYPE_MG       = 8,   /* mail group member */
    DNS_QUERY_TYPE_MR       = 9,   /* mail rename name */
    DNS_QUERY_TYPE_NULL     = 10,  /* null resource record */
    DNS_QUERY_TYPE_WKS      = 11,  /* well known service */
    DNS_QUERY_TYPE_PTR      = 12,  /* domain name pointer */
    DNS_QUERY_TYPE_HINFO    = 13,  /* host information */
    DNS_QUERY_TYPE_MINFO    = 14,  /* mailbox information */
    DNS_QUERY_TYPE_MX       = 15,  /* mail routing information */
    DNS_QUERY_TYPE_TXT      = 16,  /* text strings */
    DNS_QUERY_TYPE_RP       = 17,  /* responsible person */
    DNS_QUERY_TYPE_AFSDB    = 18,  /* AFS cell database */
    DNS_QUERY_TYPE_X25      = 19,  /* X_25 calling address */
    DNS_QUERY_TYPE_ISDN     = 20,  /* ISDN calling address */
    DNS_QUERY_TYPE_RT       = 21,  /* router */
    DNS_QUERY_TYPE_NSAP     = 22,  /* NSAP address */
    DNS_QUERY_TYPE_NSAP_PTR = 23,  /* reverse NSAP lookup (deprecated) */
    DNS_QUERY_TYPE_SIG      = 24,  /* security signature */
    DNS_QUERY_TYPE_KEY      = 25,  /* security key */
    DNS_QUERY_TYPE_PX       = 26,  /* X.400 mail mapping */
    DNS_QUERY_TYPE_GPOS     = 27,  /* geographical position (withdrawn) */
    DNS_QUERY_TYPE_AAAA     = 28,  /* IP6 Address */
    DNS_QUERY_TYPE_LOC      = 29,  /* Location Information */
    DNS_QUERY_TYPE_NXT      = 30,  /* Next Valid Name in Zone */
    DNS_QUERY_TYPE_EID      = 31,  /* Endpoint identifier */
    DNS_QUERY_TYPE_NIMLOC   = 32,  /* Nimrod locator */
    DNS_QUERY_TYPE_SRV      = 33,  /* Server selection */
    DNS_QUERY_TYPE_ATMA     = 34,  /* ATM Address */
    DNS_QUERY_TYPE_NAPTR    = 35,  /* Naming Authority PoinTeR */
    DNS_QUERY_TYPE_KX       = 36,  /* Key Exchanger */
    DNS_QUERY_TYPE_CERT     = 37,  /* CERT */
    DNS_QUERY_TYPE_A6       = 38,  /* A6 */
    DNS_QUERY_TYPE_DNAME    = 39,  /* DNAME */
    DNS_QUERY_TYPE_SINK     = 40,  /* SINK */
    DNS_QUERY_TYPE_OPT      = 41,  /* OPT pseudo-RR, RFC2671 */
    DNS_QUERY_TYPE_APL      = 42,  /* APL */
    DNS_QUERY_TYPE_DS       = 43,  /* Delegation Signer */
    DNS_QUERY_TYPE_SSHFP    = 44,  /* SSH Key Fingerprint */
    DNS_QUERY_TYPE_RRSIG    = 46,  /* RRSIG */
    DNS_QUERY_TYPE_NSEC     = 47,  /* NSEC */
    DNS_QUERY_TYPE_DNSKEY   = 48   /* DNSKEY */
} dns_query_type_sdk;

This enum is used determine the type of the query.

Code Example

app::app(IIoMux * iomux)
    : iomux(iomux)
{
    this->dns = IDns::Create(iomux);
    this->dns->GetHostByName("innovaphone.com", this);
}

void app::DnsGetHostByNameResult(const char * addr, bool isIPv6)

{
    if (addr == nullptr) debug->printf("DNS lookup of innovaphone.com failed\n");
    else debug->printf("ip address of innovaphone.com = %s\n", addr);

    delete this->dns;
    this->dns = nullptr;
}