The
DnsQuery function type is the generic query interface to the DNS namespace, and provides application developers 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)
Syntax
DNS_STATUS WINAPI DnsQuery(
__in PCTSTR lpstrName,
__in WORD wType,
__in DWORD Options,
__inout_opt PVOID pExtra,
__out_opt PDNS_RECORD *ppQueryResultsSet,
__out_opt PVOID *pReserved
);
Parameters
- lpstrName [in]
-
A pointer to a string that represents the name of the owner of the record set that is queried.
- wType [in]
-
A value that represents the 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.
- pExtra [in, out, optional]
-
This parameter is reserved for future use and must be set to NULL.
- ppQueryResultsSet [out, optional]
-
Optional. A pointer to a pointer that points to the list of RRs that comprise the response. For more information, see the Remarks section.
- pReserved [out, optional]
-
This parameter is reserved for future use and must be set to NULL.
Return Value
Returns success confirmation upon successful completion. Otherwise, returns the appropriate DNS-specific error code as defined in Winerror.h.
Remarks
Applications that call the
DnsQuery function build a query using a fully-qualified DNS name and Resource Record (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 requests that the server to perform recursive resolution on behalf of the client to resolve the query.
Callers must free returned RR sets with the DnsRecordListFree function.
Note When calling one of the
DnsQuery function types, be aware 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. 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_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
| Minimum supported client | Windows 2000 Professional |
| Minimum supported server | Windows 2000 Server |
| Header | Windns.h |
| Library | Dnsapi.lib |
| DLL | Dnsapi.dll |
| Unicode and ANSI names | DnsQuery_W (Unicode) and DnsQuery_A (ANSI) |
See Also
- DNS_RECORD
- DnsRecordListFree
Send comments about this topic to Microsoft
Build date: 11/12/2009