1 ---+ Package =TWiki::UserMapping=
3 This is a virtual base class (a.k.a an interface) for all user mappers. It is
4 *not* useable as a mapping in TWiki - use the BaseUserMapping for default
7 User mapping is the process by which TWiki maps from a username (a login name)
8 to a display name and back. It is also where groups are maintained.
10 See TWiki::Users::BaseUserMapping and TWiki::Users::TWikiUserMapping for
11 the default implementations of this interface.
13 If you want to write a user mapper, you will need to implement the methods
14 described in this class.
16 User mappings work by mapping both login names and display names to a
17 _canonical user id_. This user id is composed from a prefix that defines
18 the mapper in use (something like 'BaseUserMapping_' or 'LdapUserMapping_')
19 and a unique user id that the mapper uses to identify the user.
21 The null prefix is reserver for the TWikiUserMapping for compatibility
22 with old TWiki releases.
24 __Note:__ in all the following documentation, =$cUID= refers to a
30 ---++ PROTECTED ClassMethod new ($session, $mapping_id)
32 Construct a user mapping object, using the given mapping id.
35 ---++ ObjectMethod *finish* <tt>()</tt>
36 Break circular references.
40 ---++ ObjectMethod *loginTemplateName* <tt>() -> $templateFile</tt>
42 Allows UserMappings to come with customised login screens - that should
43 preferably only over-ride the UI function
49 ---++ ObjectMethod *supportsRegistration* <tt>() -> $boolean</tt>
51 Return true if the UserMapper supports registration (ie can create new users)
57 ---++ ObjectMethod *handlesUser* <tt>($cUID,$login,$wikiname) -> $boolean</tt>
59 Called by the TWiki::Users object to determine which loaded mapping
60 to use for a given user (must be fast).
62 The user can be identified by any of $cUID, $login or $wikiname. Any of
63 these parameters may be undef, and they should be tested in order; cUID
64 first, then login, then wikiname.
68 ---++ ObjectMethod *login2cUID* <tt>($login,$dontcheck) -> cUID</tt>
70 Convert a login name to the corresponding canonical user name. The
71 canonical name can be any string of 7-bit alphanumeric and underscore
72 characters, and must map 1:1 to the login name.
75 (if $dontcheck is true, return a cUID for a nonexistant user too.
76 This is used for registration)
78 Subclasses *must* implement this method.
80 Note: This method was previously (in TWiki 4.2.0) known as getCanonicalUserID.
81 The name was changed to avoid confusion with TWiki::Users::getCanonicalUserID,
82 which has a more generic function. However to support older user mappers,
83 getCanonicalUserID will still be called if login2cUID is not defined.
87 ---++ ObjectMethod *getLoginName* <tt>($cUID) -> login</tt>
89 Converts an internal cUID to that user's login
92 Subclasses *must* implement this method.
96 ---++ ObjectMethod *addUser* <tt>($login,$wikiname,$password,$emails) -> $cUID</tt>
98 Add a user to the persistant mapping that maps from usernames to wikinames
101 $login and $wikiname must be acceptable to $TWiki::cfg{NameFilter}.
102 $login must *always* be specified. $wikiname may be undef, in which case
103 the user mapper should make one up.
105 This function must return a canonical user id that it uses to uniquely
106 identify the user. This can be the login name, or the wikiname if they
107 are all guaranteed unigue, or some other string consisting only of 7-bit
108 alphanumerics and underscores.
110 If you fail to create a new user (for eg your Mapper has read only access),
112 throw Error::Simple('Failed to add user: '.$error);
114 where $error is a descriptive string.
116 Throws an Error::Simple if user adding is not supported (the default).
120 ---++ ObjectMethod *removeUser* <tt>($cUID) -> $boolean</tt>
122 Delete the users entry from this mapper. Throws an Error::Simple if
123 user removal is not supported (the default).
127 ---++ ObjectMethod *getWikiName* <tt>($cUID) -> $wikiname</tt>
129 Map a canonical user name to a wikiname.
131 Returns the $cUID by default.
135 ---++ ObjectMethod *userExists* <tt>($cUID) -> $boolean</tt>
137 Determine if the user already exists or not. Whether a user exists
138 or not is determined by the password manager.
140 Subclasses *must* implement this method.
144 ---++ ObjectMethod *eachUser* <tt>() -> TWiki::ListIteratorofcUIDs</tt>
146 Get an iterator over the list of all the registered users *not* including
149 Subclasses *must* implement this method.
153 ---++ ObjectMethod *eachGroupMember* <tt>($group) -> TWiki::ListIteratorofcUIDs</tt>
155 Return a iterator over the canonical user ids of users that are members
156 of this group. Should only be called on groups.
158 Note that groups may be defined recursively, so a group may contain other
159 groups. This method should *only* return users i.e. all contained groups
160 should be fully expanded.
162 Subclasses *must* implement this method.
166 ---++ ObjectMethod *isGroup* <tt>($name) -> boolean</tt>
168 Establish if a user refers to a group or not. If $name is not
169 a group name it will probably be a canonical user id, though that
170 should not be assumed.
172 Subclasses *must* implement this method.
176 ---++ ObjectMethod *eachGroup* <tt>() -> TWiki::ListIteratorofgroupnames</tt>
178 Get an iterator over the list of all the groups.
180 Subclasses *must* implement this method.
184 ---++ ObjectMethod *eachMembership* <tt>($cUID) -> TWiki::ListIteratorofgroupsthisuserisin</tt>
186 Return an iterator over the names of groups that $cUID is a member of.
188 Subclasses *must* implement this method.
192 ---++ ObjectMethod *isAdmin* <tt>($cUID) -> $boolean</tt>
194 True if the user is an administrator.
198 ---++ ObjectMethod *isInGroup* <tt>($cUID,$group) -> $bool</tt>
200 Test if the user identified by $cUID is in the given group. The default
201 implementation iterates over all the members of $group, which is rather
206 ---++ ObjectMethod *findUserByEmail* <tt>($email) -> \@users</tt>
207 * =$email= - email address to look up
208 Return a list of canonical user names for the users that have this email
209 registered with the password manager or the user mapping manager.
213 ---++ ObjectMethod *getEmails* <tt>($name) -> @emailAddress</tt>
215 If $name is a cUID, return that user's email addresses. If it is a group,
216 return the addresses of everyone in the group.
218 Duplicates should be removed from the list.
222 ---++ ObjectMethod *setEmails* <tt>($cUID,@emails)</tt>
224 Set the email address(es) for the given user.
228 ---++ ObjectMethod *findUserByWikiName* <tt>($wikiname) -> listofcUIDsassociatedwiththatwikiname</tt>
229 * =$wikiname= - wikiname to look up
230 Return a list of canonical user names for the users that have this wikiname.
231 Since a single wikiname might be used by multiple login ids, we need a list.
233 Note that if $wikiname is the name of a group, the group will *not* be
236 Subclasses *must* implement this method.
240 ---++ ObjectMethod *checkPassword* <tt>($login,$passwordU) -> $boolean</tt>
242 Finds if the password is valid for the given login. This is called using
243 a login name rather than a cUID because the user may not have been mapped
244 at the time it is called.
246 Returns 1 on success, undef on failure.
248 Default behaviour is to return 1.
252 ---++ ObjectMethod *setPassword* <tt>($cUID,$newPassU,$oldPassU) -> $boolean</tt>
254 If the $oldPassU matches matches the user's password, then it will
255 replace it with $newPassU.
257 If $oldPassU is not correct and not 1, will return 0.
259 If $oldPassU is 1, will force the change irrespective of
260 the existing password, adding the user if necessary.
262 Otherwise returns 1 on success, undef on failure.
264 Default behaviour is to fail.
268 ---++ ObjectMethod *passwordError* <tt>() -> $string</tt>
270 Returns a string indicating the error that happened in the password handlers
271 TODO: these delayed errors should be replaced with Exceptions.
273 returns undef if no error (the default)