| INT SetHostFile( |
| |
LPCTSTR lpszFileName |
|
| ); |
The SetHostFile method 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 GetHostAddress and
GetHostName methods. 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
- lpszFileName
- Pointer to a 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 method 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 GetLastError.
Remarks
This method loads the file into memory allocated for the current
thread. If the contents of the file have changed after the method has
been called, those changes will not be reflected when resolving
hostnames or addresses. To reload the host file from disk, call this
method 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
GetHostFile method. 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 GetDefaultHostFile method. It is
not necessary to specify this default host file, since it is always
used to resolve host names and addresses.
Requirements
Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools11.h
Import Library: csdnsv11.lib
Unicode: Implemented as Unicode and ANSI versions
See Also
GetDefaultHostFile,
GetHostAddress,
GetHostFile,
GetHostName
|