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( PCSTR lpstrName, WORD wType, DWORD fOptions, PIP4_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, such as a value of 1 (0x0001) for an A record (DNS_TYPE_A). See the Windns.h header file for a complete listing of record set types and their numeric representations. 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_TRUNCATED_RESPONSE 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_NO_WIRE_QUERY Directs DNS to perform a query on the local cache only. DNS_QUERY_NO_LOCAL_NAME Directs DNS to ignore the local name. DNS_QUERY_NO_HOSTS_FILE Prevents the DNS query from consulting the HOSTS file. DNS_QUERY_NO_NETBT Prevents the DNS query from using NetBT for resolution. DNS_QUERY_TREAT_AS_FQDN Prevents the DNS response from attaching suffixes to the submitted name in a name resolution process. DNS_QUERY_WIRE_ONLY Directs DNS to perform a query using the network only, bypassing local information. DNS_QUERY_RETURN_MESSAGE Directs DNS to return the entire DNS response message. 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] Specifier of 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. Note If one or more DNS servers are specified in this parameter, the DNS_QUERY_BYPASS_CACHE option must be specified in the fOptions parameter. Failure to use the DNS_QUERY_BYPASS_CACHE option when specifying one or more DNS servers results in an error, with the return value of ERROR_INVALID_PARAMETER.ppQueryResultsSet [in, out] Pointer to the pointer that points to the list of RRs comprising the response. This parameter is optional. See the Res section. pReserved [in, out] Returned response in original wire format. This parameter is optional. See the Res section. Return Values Returns success confirmation upon successful completion. Otherwise, returns the appropriate DNS-specific error code as defined in Winerror.h. Res Callers of the DnsQuery function build a query using a fully-qualified DNS name and RR 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 RR sets with the DnsRecordListFree function.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 the 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.If the ppQueryResultsSet and pReserved parameters are set to NULL, the DnsQuery function fails with the error INVALID_PARAMETER.Requirements Client: Requires Windows XP or Windows 2000 Professional. Server: Requires Windows Server 2003 or Windows 2000 Server. Header: Declared in Windns.h. Library: Use Dnsapi.lib.
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(
PCSTR lpstrName,
WORD wType,
DWORD fOptions,
PIP4_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, such as a value of 1 (0x0001) for an A record (DNS_TYPE_A). See the Windns.h header file for a complete listing of record set types and their numeric representations.
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_TRUNCATED_RESPONSE 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_NO_WIRE_QUERY Directs DNS to perform a query on the local cache only.
DNS_QUERY_NO_LOCAL_NAME Directs DNS to ignore the local name.
DNS_QUERY_NO_HOSTS_FILE Prevents the DNS query from consulting the HOSTS file.
DNS_QUERY_NO_NETBT Prevents the DNS query from using NetBT for resolution.
DNS_QUERY_TREAT_AS_FQDN Prevents the DNS response from attaching suffixes to the submitted name in a name resolution process.
DNS_QUERY_WIRE_ONLY Directs DNS to perform a query using the network only, bypassing local information.
DNS_QUERY_RETURN_MESSAGE Directs DNS to return the entire DNS response message.
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] Specifier of 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.
Note If one or more DNS servers are specified in this parameter, the DNS_QUERY_BYPASS_CACHE option must be specified in the fOptions parameter. Failure to use the DNS_QUERY_BYPASS_CACHE option when specifying one or more DNS servers results in an error, with the return value of ERROR_INVALID_PARAMETER.ppQueryResultsSet
[in, out] Pointer to the pointer that points to the list of RRs comprising the response. This parameter is optional. See the Res section.
pReserved
[in, out] Returned response in original wire format. This parameter is optional. See the Res section.
Return Values
Returns success confirmation upon successful completion. Otherwise, returns the appropriate DNS-specific error code as defined in Winerror.h.
Res
Callers of the DnsQuery function build a query using a fully-qualified DNS name and RR 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 RR sets with the DnsRecordListFree function.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 the 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.If the ppQueryResultsSet and pReserved parameters are set to NULL, the DnsQuery function fails with the error INVALID_PARAMETER.Requirements
Client: Requires Windows XP or Windows 2000 Professional.
Server: Requires Windows Server 2003 or Windows 2000 Server.
Header: Declared in Windns.h.
Library: Use Dnsapi.lib.