| INT WINAPI DnsSetHostFile(
|
| |
HCLIENT hClient, |
|
| |
LPCTSTR lpszFileName |
|
| );
|
The DnsSetHostFile function specifies the name of an
alternate file to use when resolving hostnames and IP addresses.
The host file is used as a database that maps an IP address to one
or more hostnames, and is used by the DnsGetHostAddress and
DnsGetHostName functions. The file is a plain text file,
with each line in the file specifying a record, and each field
separated by spaces or tabs. The format of the file must be as
follows:
ipaddress hostname [hostalias ...]
For example, one typical entry maps the name "localhost" to the
local loopback IP address. This would be entered as:
127.0.0.1 localhost
The hash character (#) may be used to specify a comment in the
file, and all characters after it are ignored up to the end of the
line. Blank lines are ignored, as are any lines which do not follow
the required format.
Parameters
- hClient
- Handle to the client session.
- lpszFileName
- Pointer to a null-terminated string that specifies the name of
the file. If the parameter is NULL, then the current host file is
cleared from the cache and only the default host file will be used
to resolve hostnames and addresses.
Return Value
If the function succeeds, the return value is the number of
entries in the host file. A return value of DNS_ERROR indicates
failure. To get extended error information, call
DnsGetLastError.
Remarks
This function loads the file into memory allocated for the
current thread. If the contents of the file have changed after the
function has been called, those changes will not be reflected when
resolving hostnames or addresses. To reload the host file from
disk, call this function again with the same file name. To remove
the alternate host file from memory, specify a NULL pointer as the
parameter.
If a host file has been specified, it is processed before the
default host file when resolving a hostname into an IP address, or
an IP address into a hostname. If the host name or address is not
found, or no host file has been specified, a nameserver lookup is
performed.
To determine if an alternate host file has been specified, use
the DnsGetHostFile function. A return value of zero
indicates that no alternate host file has been cached for the
current thread.
A system may have a default host file, which is used to resolve
hostnames before performing a nameserver lookup. To determine the
name of this file, use the DnsGetDefaultHostFile function.
It is not necessary to specify this default host file, since it is
always used to resolve host names and addresses.
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.
Unicode: Implemented as Unicode and ANSI versions.
See Also
DnsGetDefaultHostFile,
DnsGetHostAddress, DnsGetHostFile, DnsGetHostName
|