INT WINAPI InetGetHostAddress(
	LPCTSTR lpszHostName,
	INT nAddressFamily,
	LPINTERNET_ADDRESS lpAddress
);

The InetGetHostAddress function resolves the specified host name into an IP address in binary format.

Parameters

lpszHostName

A pointer to the name of the host to resolve; this may be a fully-qualified domain name or an IP address. This function recognizes the format for both IPv4 and IPv6 format addresses.

nAddressFamily

An integer which identifies the type of IP address to return. It may be one of the following values:

Constant	Description
INET_ADDRESS_UNKNOWN	Return the IP address for the specified host in either IPv4 or IPv6 format, depending on how the host name can be resolved. By default, a preference will be given for returning an IPv4 address. However, if the host only has an IPv6 address, that value will be returned.
INET_ADDRESS_DEFAULT	Return the IP address for the specified host in the default format. This is currently the same as specifying INET_ADDRESS_IPV4, however an application should not depend on this behavior and for future compatibility should be designed to handle either IPv4 or IPv6 addresses.
INET_ADDRESS_IPV4	Specifies that the address should be returned in IPv4 format. The first four bytes of the ipNumber array are significant and contains the IP address. The remaining bytes are not significant and an application should not depend on them having any particular value, including zero.
INET_ADDRESS_IPV6	Specifies that the address should be returned in IPv6 format. All bytes in the ipNumber array are significant. Note that it is possible for an IPv6 address to actually represent an IPv4 address. This is indicated by the first 10 bytes of the address being zero.

lpAddress

A pointer to an INTERNET_ADDRESS structure that will contain the IP address of the specified host.

Return Value

If the function succeeds, the return value is zero. If the function fails, the return value is INET_ERROR. To get extended error information, call InetGetLastError.

Remarks

This function can also be used to convert an address in dot notation to a binary format. If the function must perform a DNS lookup to resolve the hostname, the calling thread will block. To ensure future compatibility with IPv6 networks, it is important that the application does not make any assumptions about the format of the address. If the function returns successfully, the ipFamily member of the INTERNET_ADDRESS structure should always be checked to determine the type of address.

The nAddressFamily parameter is used to specify a preference for the type of address returned, however it is possible that a host may not have an IPv4 or IPv6 address record, in which case this function will fail. Although IPv4 is still the most common address used at this time, an application should not assume that because a given host name does not have an IPv4 address, that the host name is invalid.

If the nAddressFamily parameter is specified as INET_ADDRESS_UNKNOWN, the application must be prepared to handle IPv6 addresses because it is possible for a host name to have an IPv6 address assigned to it and no IPv4 address. For legacy applications that only recognize IPv4 addresses, the nAddressFamily member should always be specified as INET_ADDRESS_IPV4 to ensure that only IPv4 addresses are returned.

To determine if the local system has an IPv6 TCP/IP stack installed and configured on the local system, use the InetIsProtocolAvailable function. If an IPv6 stack is not installed, this function will fail if the lpszHostName parameter specifies an host that only has an IPv6 (AAAA) DNS record.

Requirements

Client: Requires Windows 7, Windows Vista or Windows XP.
Server: Requires Windows Server 2008 or Windows Server 2003.
Header: Include cswsock7.h.
Library: Use cswskav7.lib.
Unicode: Implemented as Unicode and ANSI versions.

See Also

InetGetHostName, InetGetLocalAddress, InetGetLocalName, InetGetPeerAddress, InetIsProtocolAvailable, INTERNET_ADDRESS

Copyright © 2012 Catalyst Development Corporation. All rights reserved.