|
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 e-mail 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@bigcorp.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 bigcorp.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 remote host 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.
|