INT GetUrlHostName(
	LPCTSTR lpszUrl,
	LPTSTR lpszHostName,
	INT nMaxLength,
	UINT *lpnHostPort,
	UINT *lpnProtocol,
	DWORD *lpdwOptions
);

INT GetUrlHostName(
	LPCTSTR lpszUrl,
	CString& strHostName,
	UINT *lpnHostPort,
	UINT *lpnProtocol,
	DWORD *lpdwOptions
);

The GetUrlHostName method returns the host name and port number specified in a URL.

Parameters

lpszUrl

A null-terminated string which specifies a URL. This parameter cannot be NULL or point to an empty string. If a non-standard URI scheme is used, the port number must be explicitly specified or the method will fail. See the remarks below for more information on the format supported by this method.

lpszHostName

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 and must be large enough to store the complete host name. An alternate version of this method accepts a reference to a CString object if MFC or ATL is used with the project.

nMaxLength

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

lpnHostPort

Pointer to an optional unsigned integer value which will contain the port number specified in the URL. This parameter value will always be initialized by the method with a value of zero. If this parameter is omitted or NULL, it will be ignored and no port information will be returned.

lpnProtocol

Pointer to an optional unsigned integer value which will contain the protocol associated with the URI scheme. This parameter value will always be initialized by the method with a value of zero. If this parameter is omitted or NULL, it will be ignored and no protocol information will be returned.

lpdwOptions

Pointer to an optional unsigned integer value which will contain any socket options required to establish a connection based on the URI scheme or specified port. This parameter value will always be initialized by the method with a value of zero. If this parameter is omitted or NULL, it will be ignored.

Return Value

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

Remarks

The GetUrlHostName method will extract the host name and port number from a URL and return the canonical form of the host name. If the lpnHostPort, lpnProtocol and lpdwOptions parameters have been specified, they will contain the port number, protocol and additional connection options associated with the URL scheme.

The general format of the URL should look like this:

[scheme]:// [[username : password] @] hostname [:port] / [path;parameters ...]

This method recognizes most standard URI schemes which use this format. The host name and port number specified in the URL will be used to establish a connection and the remaining information will be discarded. If the URL does not explicitly specify a port number, the default port number associated with the scheme will be used as the default value. For example, consider the following:

https://www.example.com/

In this example, there is no port number specified; instead, the default port for the https:// scheme would be used, which is port 443. This method will also recognize a simpler format which only includes the host name and port number without a URI scheme, such as:

www.example.com:443

If the lpszUrl parameter only specifies a host name without a URI scheme or port number, this method will ignore the lpnHostPort, lpnProtocol and lpdwOptions parameters and return the canonical form of the host name in the lpszHostName string argument.

The host name portion of the URL can be specified as either a domain name or an IP address. Because an IPv6 address can contain colon characters, you must enclose the entire address in bracket [] characters. If this is not done, the method will return an error indicating the port number is invalid. For example, the URL https://[2001:db8:0:0:1::128]/ uses an IPv6 host address and this would be considered valid. Without the brackets, this URL would not be accepted.

If the URL uses an IP address instead of a host name, this method will return a copy of that IP address in the lpszHostName string provided by the caller. The method will not attempt to resolve the IP address into a host name, however you can use the GetHostName method to perform a reverse DNS lookup if required.

The only URI schemes currently supported by this method use TCP stream connections. In practical terms, this means the lpnProtocol parameter will always return with the value INET_PROTOCOL_TCP when the method is successful. If the method fails, this value will be INET_PROTOCOL_NONE.

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

Requirements

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

See Also

ConnectUrl, GetHostAddress, GetHostName, HostNameToUnicode, NormalizeHostName

Copyright © 2026 Catalyst Development Corporation. All rights reserved.