If the method succeeds, the return value is non-zero. If the virtual
host ID does not specify a valid host, the method will return zero. If
the method fails, the last error code will be updated to indicate the
cause of the failure.
The AddVirtualPath method maps a virtual path name to a directory or file name
on the local system. Virtual paths are assigned to specific hosts and
if multiple virtual hosts are created for the server, each can have
its own virtual paths which map to different files. To create a
virtual path for the default server, the nHostId parameter
should be specified as VIRTUAL_HOST_DEFAULT.
It is recommended that the lpszLocalPath parameter always
specify the full path to the local file or directory. If the path is
relative, it will be considered relative to the current working
directory for the process and expanded to its full path name. The
local path can include environment variables surrounded by % symbols.
For example, if the value %ProgramData% is included in the path, it
will be expanded to the full path for the common application data
folder. The local path cannot specify a Windows system folder or the root
directory of a mounted drive volume.
The local file or directory does not need to located in the
document root directory for the server or virtual host. It can specify
any valid local path that the server process has the appropriate
permissions to access. You should exercise caution when creating
virtual paths to files or directories outside of the server root
directory. If the lpszLocalPath parameter specifies a
directory, clients will have access to that directory and all
subdirectories using its virtual path.
If you wish to password protect the virtual file or directory,
include the HTTP_ACCESS_PROTECTED flag in the file permissions. The
default command handlers will recognize this flag and require that the
client authenticate itself to grant access to the resource. If the
server application implements a custom command handler, it is responsible for
checking for the presence of this flag and perform the appropriate
checks to ensure that the client session has been authenticated.
If the server was started in restricted mode, the client will be
unable to access documents outside of the server root directory and its
subdirectories. This restriction also applies to virtual paths that
reference documents or other resources outside of the root directory.
To allow a client to access a document outside of the server root
directory, the SetClientAccess method should be used to grant
the client HTTP_ACCESS_READ permission.
The GetClientVirtualPath method will return the
virtual path that is associated with a local file or directory. The
GetClientLocalPath method will return the full path to a
local file or directory that is mapped to a virtual path.