|
The Domain Name Service (DNS) protocol is what applications use to
resolve domain names into Internet addresses, as well as provide other
information about a domain, such as the name of the mail servers which
are responsible for receiving email for users in that domain. All of
the SocketTools libraries provide basic domain name resolution
functionality, but the Domain Name Services library gives an
application direct control over what servers are queried, the amount of
time spent waiting for a response and the type of information that is
returned.
The first step that your application must take is to initialize the
library and then create a handle for the client session. Unlike many of
the other libraries, there are no connection related functions because
DNS uses UDP datagrams rather than TCP streams. The following functions
are available for use by your application:
DnsInitialize
Initialize the library and load the Windows Sockets library for the
current process. This must be the first function call that the
application makes before calling the other DNS API functions.
DnsCreateHandle
Create a handle that is used by the library to reference the client
session. There are two arguments, a timeout period and a retry count.
These values are used together to determine the total amount of time
that the library will take in an attempt to resolve a hostname or IP
address. The default values of 15 seconds and 4 retries are
recommended for most applications.
DnsCloseHandle
Release the handle that was previously created by the call to
DnsCreateHandle. Any memory allocated by the library on behalf of the
application is released and the datagram socket that was created is
closed.
DnsRegisterServer
Specify a nameserver that the library should use to resolve queries.
By default, the library will use the nameservers that the local host
was configured to use. This function enables you to override that
default and specify your own servers, independent of the system's
configuration.
DnsUninitialize
Unload the Windows Sockets library and release any resources that
have been allocated for the current process. This is the last
function call that the application should make prior to
terminating.
Address Conversion
Internet Protocol (IP) addresses can be represented in one of two
ways, either as unsigned 32-bit integer value or as string where each
byte of the address is written as an integer value and separated by
periods. For example, the local loopback IP address can either be
specified as the string "127.0.0.1" or as the integer value
16777343. In most cases, using the string form of the address is
easier; however, some functions require that the numeric value be used.
The following functions are provided to enable you to convert between
the two formats.
DnsGetAddress
Convert an IP address string in dotted notation into a 32-bit integer
value.
DnsFormatAddress
Convert a numeric IP address into a string in dotted notation,
copying the result into a buffer that you provide to the
function.
Host Tables
When resolving a host name or IP address, the library will first
search the local system's host table, a file that is used to map host
names to addresses. On Windows 95/98 and Windows Me, if the file exists
it is usually found in C:\Windows\hosts. On Windows NT and later
versions, it is found in C:\Windows\system32\drivers\etc\hosts. Note
that the file does not have an extension.
DnsGetDefaultHostFile
Return the full path of the file that contains the default host table
for the local system. This can be useful if you wish to temporarily
switch between the default host file and another host file specific
to your application.
DnsGetHostFile
Return the full path of the host table that is currently being used
by the library. Initially this is the same as the default host table
for the local system.
DnsSetHostFile
Specify a new host table which the library should use to resolve host
names and IP addresses. This can be used by an application to provide
its own local cache of host names and addresses in order to speed up
the process of host name resolution.
Host Name Resolution
The library can be used to resolve host names into IP addresses, as
well as perform reverse DNS lookups converting IP addresses into the
host names that are assigned to them. The library will search the local
system's host table first, and then perform a nameserver query if
required.
DnsGetHostAddress
Resolve a host name into an IP address, returned as a string in
dotted notation. The library first checks the system's local host
table, and if the name is not found there, it will perform a
nameserver query for the A (address) record for that host.
DnsGetHostName
Resolve an IP address into a host name. The address is passed as a
string in dotted notation, and the fully qualified host name is
returned in a string buffer you provide to the function. The library
first checks the system's local host table, and if the address is not
found there, it will perform a nameserver query for the PTR (pointer)
record for that address.
Mail Exchange Records
When a system needs to deliver a mail message to someone, it needs
to determine what server is responsible for accepting mail for that
user. This is done by looking up the mail exchange (MX) record for the
domain. For example, if a message was addressed to joe@example.com, to
determine the name of the mail server that would accept mail for that
recipient, you would perform an MX record query against the domain
example.com. A domain may have more than one mail server, in which case
multiple MX records will be returned.
DnsEnumMailExchanges
Enumerate all of the mail exchanges for the specified domain. If
there are multiple servers, they may be prioritized so that certain
servers are given precedence over the others. This function will
return the highest priority servers first in the list. Refer to the
Technical Reference for an example of how this function can be
used.
Advanced Queries
In addition to providing host name and IP address resolution, the
library can be used to perform advanced queries for other types of
records.
DnsGetHostInfo
Return additional information about the specified host name. If the
name server has been configured to provide host information for the
domain, this function will return that data. Typically it is used to
indicate what hardware and operating system the host uses.
DnsGetHostServices
Return information about the UDP and TCP based services that the host
provides. If defined, this will return a list of service names such
as "ftp" and "http". Note that your application
should not depend on this information to be a definitive list of what
services a server provides.
DnsGetRecord
Perform a general nameserver query for a specific record type. This
function can be used to perform queries for the common record types
such as A and PTR records, as well as for other record types such as
TXT (text) records. Refer to the Technical Reference for more
information about the specific types of records that can be
returned.
|