DnsQuery (Compact 2013)

3/26/2014

This function is the generic query interface to the DNS namespace and provides developers with a DNS query resolution interface. The DnsQuery function type supports multiple forms to facilitate different character encoding. Based on the character encoding involved, use one of the following functions:

• DnsQuery_A (for ANSI encoding)
• DnsQuery_W (for Unicode encoding)
• DnsQuery_UTF8 (for UTF-8 encoding)

Windows Embedded Compact 2013 supports only the Unicode encoding.

Syntax

DNS_STATUS WINAPI DnsQuery (
    IN      PCWSTR          pszName,
    IN      WORD            wType,
    IN      DWORD           Options,                         
    IN      PIP4_ARRAY      aipServers            OPTIONAL,
    IN OUT  PDNS_RECORD *   ppQueryResults        OPTIONAL,
    IN OUT  PVOID *         pReserved             OPTIONAL
    ); 

Parameters

• pszName
  [in] A pointer to a string that represents the name of the owner of the record set being queried.

• wType
  [in] A value that represents the Resource Record (RR) DNS Record Type that is queried. wType determines the format of data pointed to by ppQueryResultsSet. For example, if the value of wType is DNS_TYPE_A, the format of data pointed to by ppQueryResultsSet is DNS_A_DATA.

• Options
  [in] A value that contains a bitmap of DNS Query Options. Options can be combined and all options override DNS_QUERY_STANDARD.

• aipServers
  [in] Specifies the DNS servers to which the query should be sent. If this is NULL, default DNS servers for the local computer are used. This parameter is optional. Compact 2013 supports a maximum of one server listed in this parameter. Attempts to specify multiple DNS servers result in failure.

• ppQueryResultsSet
  [in, out] Pointer to the pointer to the list of RRs that comprise the response. This parameter is optional.

• pReserved
  This parameter is reserved for future use and must be set to NULL. This parameter is optional.

Return Value

Returns ERROR_SUCCESS upon successful completion. Otherwise, it returns the appropriate DNS-specific error code as defined in Winerror.h.

Remarks

Callers of this function build a query by using a fully qualified DNS name and Resource Record (RR) type, and set query options depending on the kind of service desired. When the DNS_QUERY_STANDARD option is set, DNS uses the resolver cache, queries first with UDP, then retries with TCP if the response is truncated, and requests that the server to perform recursive resolution on behalf of the client resolve the query. The DNS_QUERY_BYPASS_CACHE bypasses the resolver cache on the lookup.

Callers are responsible for freeing any returned RR sets with DnsRecordListFree. See DNS Functionsfor more information.

A DNS server can return multiple records in response to a query. A computer that is multi-homed, for example, receives multiple A records for the same IP address. The caller must use as many of the returned records as necessary.

Consider the following scenario, in which multiple returned records require additional activity on behalf of the application. A DnsQuery function call is made for a multi-homed computer and the application finds that the address associated with the first A record is not responding. The application should then try to use other IP addresses specified in the (additional) A records returned from the DnsQuery function call.

Requirements

See Also

Reference

DNS Functions
DNS_RECORD