| |
Add a new virtual user to the server.
Syntax
object.AddUser(
HostId,
UserName,
Password,
[AccessFlags],
[Directory] )
Parameters
- HostId
- An integer value which identifies the virtual host. A value of
zero specifies that the default virtual host should be used.
- UserName
- A string which specifies the user name. The maximum length of a
username is 63 characters and it is recommended that names be
limited to alphanumeric characters. Whitespace, control characters
and certain symbols such as path delimiters and wildcard characters
are not permitted. If an invalid character is included in the name,
the method will fail with an error indicating the username is
invalid. The username must be at least three characters in length.
Usernames are not case sensitive.
- Password
- A string which specifies the user password. The maximum length
of a password is 63 characters and is limited to printable
characters. Whitespace and control characters are not permitted. If
an invalid character is included in the password, the method will
fail with an error indicating the password is invalid. The password
must be at least one character in length. Passwords are case
sensitive.
- AccessFlags
- An optional integer value which specifies the access clients
will be given when authenticated as this user. This value created
from one or more bit flags. For a list of user access permissions,
see User and File Access
Constants. If this parameter is omitted, the user is
assigned default access permissions based on the server
configuration.
- Directory
- An optional string which specifies the directory that will be
the virtual user's home directory. If the server was started in
multi-user mode, this directory will be relative to the user
directory created by the server, otherwise it will be relative to
the server root directory. If the directory does not exist, it will
be created the first time that the virtual user successfully logs in
to the server. If this parameter is omitted or is an empty string, a
default home directory will be created for the virtual user.
Return Value
A value of zero is returned if the virtual user was created. Otherwise, a non-zero error code is returned which
indicates the cause of the failure.
Remarks
The AddUser method creates a virtual user that is associated
with the server. When a client connects with the server and provides
authentication credentials, the server will check if the username has
been created using this method. If a match is found, the client access
rights will be updated.
If you wish to modify the information for an existing 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.
See Also
Authenticate Method,
DeleteUser Method,
RequireAuthentication Method,
OnAuthenticate Event
|
|