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, =$user= 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).
66 ---++ ObjectMethod *getCanonicalUserID* <tt>($login,$dontcheck) -> cUID</tt>
68 Convert a login name to the corresponding canonical user name. The
69 canonical name can be any string of 7-bit alphanumeric and underscore
70 characters, and must correspond 1:1 to the login name.
73 (if dontcheck is true, return a cUID for a nonexistant user too - used for registration)
75 Subclasses *must* implement this method.
80 ---++ ObjectMethod *getLoginName* <tt>($cUID) -> login</tt>
82 Converts an internal cUID to that user's login
85 Subclasses *must* implement this method.
89 ---++ ObjectMethod *addUser* <tt>($login,$wikiname,$password,$emails) -> cUID</tt>
91 Add a user to the persistant mapping that maps from usernames to wikinames
92 and vice-versa, via a *canonical user id* (cUID).
94 $login and $wikiname must be acceptable to $TWiki::cfg{NameFilter}.
95 $login must *always* be specified. $wikiname may be undef, in which case
96 the user mapper should make one up.
98 This function must return a canonical user id that it uses to uniquely
99 identify the user. This can be the login name, or the wikiname if they
100 are all guaranteed unigue, or some other string consisting only of 7-bit
101 alphanumerics and underscores.
103 If you fail to create a new user (for eg your Mapper has read only access),
105 throw Error::Simple('Failed to add user: '.$error);
107 where $error is a descriptive string.
109 Throws an Error::Simple if user adding is not supported (the default).
113 ---++ ObjectMethod *removeUser* <tt>($user) -> $boolean</tt>
115 Delete the users entry from this mapper. Throws an Error::Simple if
116 user removal is not supported (the default).
120 ---++ ObjectMethod *getWikiName* <tt>($cUID) -> wikiname</tt>
122 Map a canonical user name to a wikiname.
124 Returns the $cUID by default.
128 ---++ ObjectMethod *userExists* <tt>($cUID) -> $boolean</tt>
130 Determine if the user already exists or not. Whether a user exists
131 or not is determined by the password manager.
133 Subclasses *must* implement this method.
137 ---++ ObjectMethod *eachUser* <tt>() -> listIteratorofcUIDs</tt>
139 Called from TWiki::Users. See the documentation of the corresponding
140 method in that module for details.
142 Subclasses *must* implement this method.
146 ---++ ObjectMethod *eachGroupMember* <tt>($group) -> TWiki::ListIteratorofcUIDs</tt>
148 Called from TWiki::Users. See the documentation of the corresponding
149 method in that module for details.
151 Subclasses *must* implement this method.
155 ---++ ObjectMethod *isGroup* <tt>($user) -> boolean</tt>
157 Called from TWiki::Users. See the documentation of the corresponding
158 method in that module for details.
160 Subclasses *must* implement this method.
164 ---++ ObjectMethod *eachGroup* <tt>() -> ListIteratorofgroupnames</tt>
166 Called from TWiki::Users. See the documentation of the corresponding
167 method in that module for details.
169 Subclasses *must* implement this method.
173 ---++ ObjectMethod *eachMembership* <tt>($cUID) -> ListIteratorofgroupsthisuserisin</tt>
175 Called from TWiki::Users. See the documentation of the corresponding
176 method in that module for details.
178 Subclasses *must* implement this method.
182 ---++ ObjectMethod *isAdmin* <tt>($user) -> $boolean</tt>
184 True if the user is an administrator. Default is *false*
188 ---++ ObjectMethod *isInGroup* <tt>($user,$group,$scanning) -> bool</tt>
190 Called from TWiki::Users. See the documentation of the corresponding
191 method in that module for details.
197 ---++ ObjectMethod *findUserByEmail* <tt>($email) -> \@users</tt>
198 * =$email= - email address to look up
199 Return a list of canonical user names for the users that have this email
200 registered with the password manager or the user mapping manager.
202 Returns an empty list by default.
206 ---++ ObjectMethod *getEmails* <tt>($user) -> @emailAddress</tt>
208 If this is a user, return their email addresses. If it is a group,
209 return the addresses of everyone in the group.
211 Duplicates should be removed from the list.
213 By default, returns the empty list.
217 ---++ ObjectMethod *setEmails* <tt>($user,@emails)</tt>
219 Set the email address(es) for the given user. Does nothing by default.
223 ---++ ObjectMethod *findUserByWikiName* <tt>($wikiname) -> listofcUIDsassociatedwiththatwikiname</tt>
225 Called from TWiki::Users. See the documentation of the corresponding
226 method in that module for details.
228 Subclasses *must* implement this method.
232 ---++ ObjectMethod *checkPassword* <tt>($userName,$passwordU) -> $boolean</tt>
234 Finds if the password is valid for the given user.
236 Returns 1 on success, undef on failure.
238 Default behaviour is to return 1.
242 ---++ ObjectMethod *setPassword* <tt>($user,$newPassU,$oldPassU) -> $boolean</tt>
244 If the $oldPassU matches matches the user's password, then it will
245 replace it with $newPassU.
247 If $oldPassU is not correct and not 1, will return 0.
249 If $oldPassU is 1, will force the change irrespective of
250 the existing password, adding the user if necessary.
252 Otherwise returns 1 on success, undef on failure.
254 Default behaviour is to fail.
258 ---++ ObjectMethod *passwordError* <tt>() -> $string</tt>
260 Returns a string indicating the error that happened in the password handlers
261 TODO: these delayed errors should be replaced with Exceptions.
263 returns undef if no error 9the default)
267 ---++ ObjectMethod *ASSERT_IS_CANONICAL_USER_ID* <tt>($user_id) -> $boolean</tt>
269 Used for debugging to ensure we are actually passing a canonical_id
273 ---++ ObjectMethod *ASSERT_IS_USER_LOGIN_ID* <tt>($user_login) -> $boolean</tt>
275 Used for debugging to ensure we are actually passing a user login
279 ---++ ObjectMethod *ASSERT_IS_USER_DISPLAY_NAME* <tt>($user_display) -> $boolean</tt>
281 Used for debugging to ensure we are actually passing a user display_name
282 (commonly a WikiWord Name)
284 Returns true by default.