INT NormalizeHostName(
	LPCTSTR lpszHostName,
	LPTSTR lpszNormalized,
	INT nMaxLength
);

INT NormalizeHostName(
	LPCTSTR lpszHostName,
	CString& strNormalized
);

The NormalizeHostName method returns the canonical form of a host name in the specified buffer.

Parameters

lpszHostName

Pointer to the host name as a null-terminated string. This parameter cannot be a NULL pointer or a zero length string.

lpszNormalized

Pointer to the string buffer that will contain the canonical form of the host name, including the terminating null character. It is recommended that this buffer be at least 256 characters in size. This parameter cannot be a NULL pointer. An alternate version of this method accepts a reference to a CString object.

nMaxLength

The maximum number of characters that can be copied to the lpszNormalized string buffer. This parameter cannot be zero, and must include the terminating null character.

Return Value

If the method succeeds, the return value is the number of characters copied into the string buffer. If the method fails, the return value is INET_ERROR. To get extended error information, call GetLastError.

Remarks

The NormalizeHostName method will remove all leading and trailing whitespace characters from the host name and fold all upper-case characters to lower-case. If an internationalized domain name (IDN) containing Unicode characters is passed to this method, it will be converted to an ASCII compatible format for domain names.

If the application is compiled using the Unicode character set, the host name will be converted from UTF-16 to UTF-8 and then processed. If you are unsure if an internationalized domain name will be specified as the host name, it is recommended that you use Unicode.

Although this method performs checks to ensure that the lpszHostName parameter is in the correct format and does not contain any illegal characters or malformed encoding, it does not validate the existence of the domain name. To check if the host name exists and has a valid IP address, use the GetHostAddress method.

It is recommended that you use this method if your application needs to store the host name, and if accepts a host name as user input. It is not necessary to call this method prior to calling the other methods that accept a host name as a parameter. They already normalize the host name and perform checks to ensure it is in the correct format.

If the lpszHostName parameter specifies a valid IPv4 or IPv6 address string instead of a host name, this method will return a copy of that IP address in the buffer provided by the caller. This allows the method to be used in cases where a user may input either a host name or IP address. To determine if the IP address has a corresponding host name, use the GetHostName method.

Requirements

Minimum Desktop Platform: Windows 7 (Service Pack 1)
Minimum Server Platform: Windows Server 2008 R2 (Service Pack 1)
Header File: cswsock10.h
Import Library: cswskv10.lib
Unicode: Implemented as Unicode and ANSI versions.

See Also

GetHostAddress, GetHostName, HostNameToUnicode

Copyright © 2023 Catalyst Development Corporation. All rights reserved.