# 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;
    }