Convert a login name to the corresponding canonical user name. The
canonical name can be any string of 7-bit alphanumeric and underscore

Changed:

<<

characters, and must correspond 1:1 to the login name.

>>

characters, and must map 1:1 to the login name.

(undef on failure)

Changed:

<<

(if dontcheck is true, return a cUID for a nonexistant user too - used for registration)

>>

(if $dontcheck is true, return a cUID for a nonexistant user too.
This is used for registration)

Subclasses must implement this method.

Added:

>>

Note: This method was previously (in TWiki 4.2.0) known as getCanonicalUserID.
The name was changed to avoid confusion with TWiki::Users::getCanonicalUserID,
which has a more generic function. However to support older user mappers,
getCanonicalUserID will still be called if login2cUID is not defined.

Package TWiki::UserMapping

This is a virtual base class (a.k.a an interface) for all user mappers. It is
not useable as a mapping in TWiki - use the BaseUserMapping for default
behaviour.

User mapping is the process by which TWiki maps from a username (a login name)
to a display name and back. It is also where groups are maintained.

See TWiki::Users::BaseUserMapping and TWiki::Users::TWikiUserMapping for
the default implementations of this interface.

If you want to write a user mapper, you will need to implement the methods
described in this class.

User mappings work by mapping both login names and display names to a
canonical user id. This user id is composed from a prefix that defines
the mapper in use (something like 'BaseUserMapping_' or 'LdapUserMapping_')
and a unique user id that the mapper uses to identify the user.

The null prefix is reserver for the TWikiUserMapping for compatibility
with old TWiki releases.

Note: in all the following documentation, $user refers to a
canonical user id.

Convert a login name to the corresponding canonical user name. The
canonical name can be any string of 7-bit alphanumeric and underscore
characters, and must correspond 1:1 to the login name.
(undef on failure)

(if dontcheck is true, return a cUID for a nonexistant user too - used for registration)

Add a user to the persistant mapping that maps from usernames to wikinames
and vice-versa, via a canonical user id (cUID).

$login and $wikiname must be acceptable to $TWiki::cfg{NameFilter}.
$login must always be specified. $wikiname may be undef, in which case
the user mapper should make one up.

This function must return a canonical user id that it uses to uniquely
identify the user. This can be the login name, or the wikiname if they
are all guaranteed unigue, or some other string consisting only of 7-bit
alphanumerics and underscores.

If you fail to create a new user (for eg your Mapper has read only access),

throw Error::Simple('Failed to add user: '.$error);

where $error is a descriptive string.

Throws an Error::Simple if user adding is not supported (the default).