| |
| HCLIENT WINAPI DnsCreateHandle(
|
| |
INT nTimeout, |
|
| |
INT nRetries, |
|
| |
DWORD dwOptions |
|
| );
|
The DnsCreateHandle function creates a new handle which
can be used to query the default nameservers configured for the
local host.
Parameters
- nTimeout
- The number of seconds that the client will wait for a response
before failing the query. The constant DNS_TIMEOUT can be used to
specify the default timeout period of 15 seconds.
- nRetries
- The number of attempts the client will make to resolve a query
after a timeout. The constant DNS_RETRIES can be used to specify
the default retry count of 4.
- dwOptions
- An unsigned integer that specifies one or more resolver
options. This parameter is constructed by using a bitwise operator
with any of the following values:
| Constant |
Description |
| DNS_OPTION_NONE |
No additional resolver options specified. This is the default
value, and it is recommended that most applications do not specify
additional options unless the implications of doing so are
understood. |
| DNS_OPTION_PROMOTE |
Promotes the server that successfully completed the last query
to the first server that will be used to resolve subsequent
queries. This option can improve performance in some cases where
one or more of the registered servers are non-responsive. This
option takes precedence over the DNS_OPTION_ROTATE option. |
| DNS_OPTION_ROTATE |
Enables a round-robin selection of nameservers when performing
queries. Normally each nameserver is queried in the same order.
This option rotates the available nameservers so a different server
is used with each query. |
| DNS_OPTION_AUTHONLY |
Require the answer from the nameserver to be authoritative, not
from the server's cache. This option is included for future
expansion as most servers do not support this feature and will
ignore it. |
| DNS_OPTION_PRIMARY |
Queries are only accepted from the primary nameserver. This
option is included for future expansion as most servers do not
support this feature and will ignore it. |
| DNS_OPTION_NORECURSE |
Disable the sending of recursive queries to the nameserver.
Specifying this option will disable the bit in the DNS request
header that specifies recursion is desired. |
| DNS_OPTION_NOSEARCH |
Disable additional queries of higher domains in the search list
if the host name cannot be resolved. If this option is specified,
and the host name cannot be resolved using the local domain name an
error is returned immediately. This option is ignored if no local
domain has been specified or if the DNS_OPTION_NOSUFFIX option has
been specified. |
| DNS_OPTION_NOSUFFIX |
Disable additional queries using the local domain name if the
host name is not a fully qualified domain name and cannot be
resolved. This option is ignored if no local domain has been
specified. |
| DNS_OPTION_NONAMECHECK |
Disable checking the host name for invalid characters, such as
the underscore and control characters. By default, host names are
checked to ensure they're valid before submitting a query to the
nameserver. |
| DNS_OPTION_FREETHREAD |
This option specifies that the handle returned by this function
may be used by any thread, and is not limited to the thread which
created it. The application is responsible for ensuring that access
to the handle is synchronized across multiple threads. |
Return Value
If the function succeeds, the return value is a handle to a
client session. If the function fails, the return value is
INVALID_CLIENT. To get extended error information, call
DnsGetLastError.
Remarks
The DnsCreateHandle function returns a handle to the
application which can be used to perform nameserver queries. By
default, the library will use the nameservers which are configured
for the local host. To determine the IP addresses of those
nameservers, use the DnsGetServerAddress function.
To specify alternate nameservers, either as replacements for or
additions to the default nameservers, use the
DnsRegisterServer function.
It is recommended that most applications do not specify any
resolver options and use the default behavior. Specifying these
options without understanding how they can affect standard queries
can result in unexpected failures. In particular, caution should be
used when specifying the DNS_OPTION_NORECURSE and
DNS_OPTION_NOSEARCH options as they change the normal process of
resolving a host name.
Specifying the DNS_OPTION_FREETHREAD option enables any thread
to call any function using the handle, regardless of which thread
created it. It is important to note that this option disables
certain internal safety checks which are performed by the library
and may result in unexpected behavior unless access to the handle
is synchronized. If one thread calls a function in the library, it
must ensure that no other thread will call another function at the
same time using the same handle.
Requirements
Client: Requires Windows 7, Windows Vista or Windows
XP.
Server: Requires Windows Server 2008 or Windows Server
2003.
Header: Include cstools7.h.
Library: Use csdnsav7.lib.
See Also
DnsCloseHandle, DnsGetResolverOptions, DnsGetServerAddress, DnsInitialize, DnsRegisterServer, DnsSetLocalDomain, DnsSetResolverOptions
|
|