UINT HttpAddVirtualHost(
	LPCTSTR lpszHostName,
	UINT nHostPort,
	LPCTSTR lpszDirectory
);

Add a new virtual host to the server virtual host table.

Parameters

lpszHostName

A null-terminated string which specifies the hostname that will be added to the virtual host table. This parameter must specify a valid hostname and cannot be a NULL pointer or a zero-length string.

nHostPort

An integer value which specifies the port number for the virtual host. This value must be zero or the same value as the original port number that the server was configured to use.

lpszDirectory

A null-terminated string which specifies the root document directory for the virtual host. If this parameter is NULL or a zero-length string, the virtual host will use the same root directory that was specified when the server was started. This parameter may contain environment variables enclosed in % symbols.

Return Value

If the method is successful, it will return a non-zero integer value that identifies the virtual host. If the method fails, it will return INVALID_VIRTUAL_HOST and the last error code will be updated to indicate the cause of the failure.

Remarks

Virtual hosting is a method for sharing multiple domain names on a single instance of a server. The client provides the server with the hostname that it has used to establish the connection, and that name is compared against a table of virtual hosts configured for the server. If the hostname matches a virtual host, the client will use the root directory and any virtual paths that have been assigned to that host.

When the server is first started, a default virtual host with an ID of zero is automatically created and is identified as VIRTUAL_HOST_DEFAULT. This virtual host uses the same hostname, port number and root directory that the server instance was created with. The application should treat all other host IDs as opaque values and never make assumptions about how they are allocated.

The nHostPort parameter should always be specified with a value of zero, or the same port number that the server was configured to use. Port-based virtual hosting is currently not supported and this parameter is included for future use.

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: cshtsv11.lib
Unicode: Implemented as Unicode and ANSI versions

See Also

AddVirtualHostAlias, AddVirtualPath, DeleteVirtualHost, GetVirtualHostId, GetVirtualHostName

Copyright © 2025 Catalyst Development Corporation. All rights reserved.