If the method succeeds, the return value is non-zero. If the the virtual host ID does not specify a
valid host, or the username or password contain invalid characters, the method will return zero. If the method fails, the
last error code will be updated to indicate the cause of the failure.
The AddVirtualUser method adds a virtual user that is
associated with the specified virtual host. If a client attempts to
access a protected document and provides credentials, the server will
attempt to automatically authenticate the session by searching for
virtual user with the same username and password. If a match is found,
then the client session is assigned the same access permissions as the
virtual user.
If the server is started with the HTTP_SERVER_MULTIUSER option,
then documents in the virtual user's home directory can be accessed by
specifying their username using a specially formatted request URL. For
example, if a virtual user named "Thomas" is created, the
documents in that user's home directory could be accessed as
http://servername/~thomas/document.html
All files and subdirectories in the user's home directory are
considered to be read-only. A client cannot create files in a user's
home directory, even if they are authenticated as that user. In
addition, CGI programs and scripts cannot be executed from a user's
home directory.
If you wish to modify the information for a user, it is not
necessary to delete the username first. If this method is called
with a username that already exists, that record is replaced with the
values passed to this method.
The virtual users created by this method exist only as long as
the server is active. If you wish to maintain a persistent database of
users and passwords, you are responsible for its implementation based
on the requirements of your specific application. For example, a
simple implementation would be to store the user information in a
local XML or INI file and then read that configuration file after the
server has started, calling this method for each user that is
listed.