---+ 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*.

%TOC%

---++ PROTECTED ClassMethod new ($session, $mapping_id)

Construct a user mapping object, using the given mapping id.

---++ ObjectMethod *finish* <tt>()</tt>

Break circular references.

---++ ObjectMethod *loginTemplateName* <tt>() -> $templateFile</tt>

Allows UserMappings to come with customised login screens - that should

preferably only over-ride the UI function

Default is "login"

---++ ObjectMethod *supportsRegistration* <tt>() -> $boolean</tt>

Return true if the UserMapper supports registration (ie can create new users)

Default is *false*

---++ ObjectMethod *handlesUser* <tt>($cUID,$login,$wikiname) -> $boolean</tt>

Called by the TWiki::Users object to determine which loaded mapping

to use for a given user (must be fast).

Default is *false*

---++ ObjectMethod *getCanonicalUserID* <tt>($login,$dontcheck) -> cUID</tt>

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)

Subclasses *must* implement this method.

---++ ObjectMethod *getLoginName* <tt>($cUID) -> login</tt>

Converts an internal cUID to that user's login

(undef on failure)

Subclasses *must* implement this method.

---++ ObjectMethod *addUser* <tt>($login,$wikiname,$password,$emails) -> cUID</tt>

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),

<pre>

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

</pre>

where $error is a descriptive string.

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

---++ ObjectMethod *removeUser* <tt>($user) -> $boolean</tt>

Delete the users entry from this mapper. Throws an Error::Simple if

user removal is not supported (the default).

---++ ObjectMethod *getWikiName* <tt>($cUID) -> wikiname</tt>

Map a canonical user name to a wikiname.

Returns the $cUID by default.

---++ ObjectMethod *userExists* <tt>($cUID) -> $boolean</tt>

Determine if the user already exists or not. Whether a user exists

or not is determined by the password manager.

Subclasses *must* implement this method.

---++ ObjectMethod *eachUser* <tt>() -> listIteratorofcUIDs</tt>

Called from TWiki::Users. See the documentation of the corresponding

method in that module for details.

Subclasses *must* implement this method.

---++ ObjectMethod *eachGroupMember* <tt>($group) -> TWiki::ListIteratorofcUIDs</tt>

Called from TWiki::Users. See the documentation of the corresponding

method in that module for details.

Subclasses *must* implement this method.

---++ ObjectMethod *isGroup* <tt>($user) -> boolean</tt>

Called from TWiki::Users. See the documentation of the corresponding

method in that module for details.

Subclasses *must* implement this method.

---++ ObjectMethod *eachGroup* <tt>() -> ListIteratorofgroupnames</tt>

Called from TWiki::Users. See the documentation of the corresponding

method in that module for details.

Subclasses *must* implement this method.

---++ ObjectMethod *eachMembership* <tt>($cUID) -> ListIteratorofgroupsthisuserisin</tt>

Called from TWiki::Users. See the documentation of the corresponding

method in that module for details.

Subclasses *must* implement this method.

---++ ObjectMethod *isAdmin* <tt>($user) -> $boolean</tt>

True if the user is an administrator. Default is *false*

---++ ObjectMethod *isInGroup* <tt>($user,$group,$scanning) -> bool</tt>

Called from TWiki::Users. See the documentation of the corresponding

method in that module for details.

Default is *false*

---++ ObjectMethod *findUserByEmail* <tt>($email) -> \@users</tt>

   * =$email= - email address to look up

Return a list of canonical user names for the users that have this email

registered with the password manager or the user mapping manager.

Returns an empty list by default.

---++ ObjectMethod *getEmails* <tt>($user) -> @emailAddress</tt>

If this is a user, return their email addresses. If it is a group,

return the addresses of everyone in the group.

Duplicates should be removed from the list.

By default, returns the empty list.

---++ ObjectMethod *setEmails* <tt>($user,@emails)</tt>

Set the email address(es) for the given user. Does nothing by default.

---++ ObjectMethod *findUserByWikiName* <tt>($wikiname) -> listofcUIDsassociatedwiththatwikiname</tt>

Called from TWiki::Users. See the documentation of the corresponding

method in that module for details.

Subclasses *must* implement this method.

---++ ObjectMethod *checkPassword* <tt>($userName,$passwordU) -> $boolean</tt>

Finds if the password is valid for the given user.

Returns 1 on success, undef on failure.

Default behaviour is to return 1.

---++ ObjectMethod *setPassword* <tt>($user,$newPassU,$oldPassU) -> $boolean</tt>

If the $oldPassU matches matches the user's password, then it will

replace it with $newPassU.

If $oldPassU is not correct and not 1, will return 0.

If $oldPassU is 1, will force the change irrespective of

the existing password, adding the user if necessary.

Otherwise returns 1 on success, undef on failure.

Default behaviour is to fail.

---++ ObjectMethod *passwordError* <tt>() -> $string</tt>

Returns a string indicating the error that happened in the password handlers

TODO: these delayed errors should be replaced with Exceptions.

returns undef if no error 9the default)

---++ ObjectMethod *ASSERT_IS_CANONICAL_USER_ID* <tt>($user_id) -> $boolean</tt>

Used for debugging to ensure we are actually passing a canonical_id

---++ ObjectMethod *ASSERT_IS_USER_LOGIN_ID* <tt>($user_login) -> $boolean</tt>

Used for debugging to ensure we are actually passing a user login

---++ ObjectMethod *ASSERT_IS_USER_DISPLAY_NAME* <tt>($user_display) -> $boolean</tt>

Used for debugging to ensure we are actually passing a user display_name

(commonly a WikiWord Name)

Returns true by default.