AddPath Method  

Add a new virtual path for the specified host.


object.AddPath( HostId, VirtualPath, LocalPath, [AccessFlags] )


An integer value which identifies the virtual host. A value of zero specifies that the default virtual host should be used.
A string which specifies the virtual path that will be created. This parameter cannot be an empty string and the maximum length of the virtual path is 1024 characters.
A string which specifies the local directory or file name that the virtual path will be mapped to. This path must exist and can be no longer than 260 characters. This parameter cannot be an empty string.
An optional integer value which specifies the access clients will be given to the virtual path. This value created from one or more bitflags. For a list of access permissions, see User and File Access Constants. If this parameter is omitted, the virtual path is assigned default file access permissions based on the server configuration.

Return Value

A value of zero is returned if the virtual path was created. Otherwise, a non-zero error code is returned which indicates the cause of the failure.


The AddPath 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 caller should specify the HostId parameter as httpHostDefault which has a value of zero.

It is recommended that the LocalPath 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 LocalPath 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 httpAccessProtected 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 ClientAccess property should be used to grant the client httpAccessRead permission.

See Also

ClientAccess Property, LocalPath Property, VirtualPath Property, DeletePath Method, ResolvePath Method