DnsQuery

The DnsQuery function type is the generic query interface to the DNS name space, and provides application programmers with a DNS query resolution interface. Like many DNS functions, the DnsQuery function type is implemented in 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)

If the DnsQuery function type is called without its suffix (_A, _W, or _UTF8), a compiler error will occur.

DNS_STATUS WINAPI DnsQuery (
  LPSTR lpstrName,
  WORD wType,
  DWORD fOptions,
  PIP_ARRAY aipServers,
  PDNS_RECORD *ppQueryResultsSet,
  PVOID *pReserved 
);

Parameters

lpstrName

[in] Name of the owner of the record set being queried.

wType

[in] Numeric representation of the type of record set queried.

fOptions

[in] Query options. Options can be combined, and all options override DNS_QUERY_STANDARD. The following table lists the available query options.

Query	Meaning
DNS_QUERY_STANDARD	Standard query.
DNS_QUERY_ACCEPT_PARTIAL_UDP	Returns truncated results—does not retry under TCP.
DNS_QUERY_USE_TCP_ONLY	Uses TCP only for the query.
DNS_QUERY_NO_RECURSION	Directs the DNS server to perform an iterative query (specifically directs the DNS server not to perform recursive resolution to resolve the query).
DNS_QUERY_BYPASS_CACHE	Bypasses the resolver cache on the lookup.
DNS_QUERY_CACHE_ONLY	Attempts to resolve the query using locally cached data only.
DNS_QUERY_SOCKET_KEEPALIVE	Prevents the DNS query socket from closing after the response is received.
DNS_QUERY_TREAT_AS_FQDN	Prevents the DNS response from attaching suffixes to the submitted name in a name resolution process.
DNS_QUERY_ALLOW_EMPTY_AUTH_RESP	Accepts the response with an empty authority section.
DNS_QUERY_DONT_RESET_TTL_VALUES	If set, and if the response contains multiple records, records are stored with the TTL corresponding to the minimum value TTL from among all records. When this option is set, "Do not change the TTL of individual records" in the returned record set is not modified.
DNS_QUERY_RESERVED	Reserved.

aipServers

[in] Specifies DNS servers to which the query should be sent. If aipServers is NULL, default DNS servers for the local computer are used. This parameter is optional.

ppQueryResultsSet

[in, out] Pointer to the pointer that points to the list of resource records comprising the response. This parameter is optional.

pReserved

[in, out] Returns the response in original wire format. This parameter is optional.

Remarks

Callers of the DnsQuery function build a query using a fully-qualified DNS name and resource record type, and set query options depending on the type 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 asks the server to perform recursive resolution on behalf of the client to resolve the query.

Callers are responsible for freeing any returned resource record sets.

Note  When calling one of the DnsQuery function types, it is important to realize that a DNS server may return multiple records in response to a query. A computer that is multihomed, for example, will receive multiple A records for the same IP address. It is the caller's responsibility to 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_A function call is made for a multihomed computer and the application finds that the address associated with first A record is not responding. The application should then attempt to use other IP addresses specified in the (additional) A records returned from the DnsQuery_A function call.

Return Values

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

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Windns.h.
  Library: Use Dnsapi.lib.