1 # <a name="Package <code>TWiki::_UserMapping="></a> Package =TWiki::UserMapping
3 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.
5 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.
7 See TWiki::Users::BaseUserMapping and TWiki::Users::TWikiUserMapping for the default implementations of this interface.
9 If you want to write a user mapper, you will need to implement the methods described in this class.
11 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.
13 The null prefix is reserver for the [[TWikiUserMapping]] for compatibility with old TWiki releases.
15 **_Note:_** in all the following documentation, `$user` refers to a **canonical user id**.
19 <li><a href="#Package =TWiki::_UserMapping="> Package TWiki::UserMapping</a><ul>
20 <li><a href="#PROTECTED _ClassMethod new ($ses"> PROTECTED ClassMethod new ($session, $mapping_id)</a></li>
21 <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
22 <li><a href="#ObjectMethod *login_TemplateName"> ObjectMethod loginTemplateName <tt>() -> $templateFile</tt></a></li>
23 <li><a href="#ObjectMethod *supportsRegistrati"> ObjectMethod supportsRegistration <tt>() -> $boolean</tt></a></li>
24 <li><a href="#ObjectMethod <strong>handlesUser</strong> ($cUI"> ObjectMethod handlesUser <tt>($cUID,$login,$wikiname) -> $boolean</tt></a></li>
25 <li><a href="#ObjectMethod *get_CanonicalUserI"> ObjectMethod getCanonicalUserID <tt>($login,$dontcheck) -> cUID</tt></a></li>
26 <li><a href="#ObjectMethod <strong>get_LoginName</strong> ($c"> ObjectMethod getLoginName <tt>($cUID) -> login</tt></a></li>
27 <li><a href="#ObjectMethod <strong>addUser</strong> ($login,$"> ObjectMethod addUser <tt>($login,$wikiname,$password,$emails) -> cUID</tt></a></li>
28 <li><a href="#ObjectMethod <strong>removeUser</strong> ($user"> ObjectMethod removeUser <tt>($user) -> $boolean</tt></a></li>
29 <li><a href="#ObjectMethod <strong>get_WikiName</strong> ($cU"> ObjectMethod getWikiName <tt>($cUID) -> wikiname</tt></a></li>
30 <li><a href="#ObjectMethod <strong>userExists</strong> ($cUID"> ObjectMethod userExists <tt>($cUID) -> $boolean</tt></a></li>
31 <li><a href="#ObjectMethod <strong>eachUser</strong> () -> li"> ObjectMethod eachUser <tt>() -> listIteratorofcUIDs</tt></a></li>
32 <li><a href="#ObjectMethod *each_GroupMember*"> ObjectMethod eachGroupMember <tt>($group) -> TWiki::ListIteratorofcUIDs</tt></a></li>
33 <li><a href="#ObjectMethod <strong>isGroup</strong> ($user) -"> ObjectMethod isGroup <tt>($user) -> boolean</tt></a></li>
34 <li><a href="#ObjectMethod <strong>eachGroup</strong> () ->"> ObjectMethod eachGroup <tt>() -> ListIteratorofgroupnames</tt></a></li>
35 <li><a href="#ObjectMethod <strong>eachMembership</strong> ($"> ObjectMethod eachMembership <tt>($cUID) -> ListIteratorofgroupsthisuserisin</tt></a></li>
36 <li><a href="#ObjectMethod <strong>isAdmin</strong> ($user) -"> ObjectMethod isAdmin <tt>($user) -> $boolean</tt></a></li>
37 <li><a href="#ObjectMethod <strong>is_InGroup</strong> ($user"> ObjectMethod isInGroup <tt>($user,$group,$scanning) -> bool</tt></a></li>
38 <li><a href="#ObjectMethod *find_UserByEmail*"> ObjectMethod findUserByEmail <tt>($email) -> \@users</tt></a></li>
39 <li><a href="#ObjectMethod <strong>getEmails</strong> ($user)"> ObjectMethod getEmails <tt>($user) -> @emailAddress</tt></a></li>
40 <li><a href="#ObjectMethod <strong>setEmails</strong> ($user,"> ObjectMethod setEmails <tt>($user,@emails)</tt></a></li>
41 <li><a href="#ObjectMethod *find_UserByWikiNam"> ObjectMethod findUserByWikiName <tt>($wikiname) -> listofcUIDsassociatedwiththatwikiname</tt></a></li>
42 <li><a href="#ObjectMethod <strong>checkPassword</strong> ($u"> ObjectMethod checkPassword <tt>($userName,$passwordU) -> $boolean</tt></a></li>
43 <li><a href="#ObjectMethod <strong>setPassword</strong> ($use"> ObjectMethod setPassword <tt>($user,$newPassU,$oldPassU) -> $boolean</tt></a></li>
44 <li><a href="#ObjectMethod <strong>passwordError</strong> ()"> ObjectMethod passwordError <tt>() -> $string</tt></a></li>
45 <li><a href="#ObjectMethod *ASSERT_IS_CANONICA"> ObjectMethod ASSERT_IS_CANONICAL_USER_ID <tt>($user_id) -> $boolean</tt></a></li>
46 <li><a href="#ObjectMethod *ASSERT_IS_USER_LOG"> ObjectMethod ASSERT_IS_USER_LOGIN_ID <tt>($user_login) -> $boolean</tt></a></li>
47 <li><a href="#ObjectMethod *ASSERT_IS_USER_DIS"> ObjectMethod ASSERT_IS_USER_DISPLAY_NAME <tt>($user_display) -> $boolean</tt></a></li>
53 ## <a name="PROTECTED _ClassMethod new ($ses"></a> PROTECTED [[ClassMethod]] new ($session, $mapping\_id)
55 Construct a user mapping object, using the given mapping id.
57 ## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
59 Break circular references.
61 ## <a name="ObjectMethod <strong>login_TemplateName"></a> [[ObjectMethod]] \*loginTemplateName `() -> $templateFile`
63 Allows [[UserMappings]] to come with customised login screens - that should preferably only over-ride the UI function
67 ## <a name="ObjectMethod <strong>supportsRegistrati"></a> [[ObjectMethod]] \*supportsRegistration `() -> $boolean`
69 Return true if the [[UserMapper]] supports registration (ie can create new users)
73 ## <a name="ObjectMethod <strong>handlesUser</strong> ($cUI"></a> [[ObjectMethod]] **handlesUser** `($cUID,$login,$wikiname) -> $boolean`
75 Called by the TWiki::Users object to determine which loaded mapping to use for a given user (must be fast).
79 ## <a name="ObjectMethod <strong>get_CanonicalUserI"></a> [[ObjectMethod]] \*getCanonicalUserID `($login,$dontcheck) -> cUID`
81 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)
83 (if dontcheck is true, return a cUID for a nonexistant user too - used for registration)
85 Subclasses **must** implement this method.
87 ## <a name="ObjectMethod <strong>get_LoginName</strong> ($c"></a> [[ObjectMethod]] **getLoginName** `($cUID) -> login`
89 Converts an internal cUID to that user's login (undef on failure)
91 Subclasses **must** implement this method.
93 ## <a name="ObjectMethod <strong>addUser</strong> ($login,$"></a> [[ObjectMethod]] **addUser** `($login,$wikiname,$password,$emails) -> cUID`
95 Add a user to the persistant mapping that maps from usernames to wikinames and vice-versa, via a **canonical user id** (cUID).
97 $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.
99 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.
101 If you fail to create a new user (for eg your Mapper has read only access),
103 throw Error::Simple('Failed to add user: '.$error);
105 where $error is a descriptive string.
107 Throws an Error::Simple if user adding is not supported (the default).
109 ## <a name="ObjectMethod <strong>removeUser</strong> ($user"></a> [[ObjectMethod]] **removeUser** `($user) -> $boolean`
111 Delete the users entry from this mapper. Throws an Error::Simple if user removal is not supported (the default).
113 ## <a name="ObjectMethod <strong>get_WikiName</strong> ($cU"></a> [[ObjectMethod]] **getWikiName** `($cUID) -> wikiname`
115 Map a canonical user name to a wikiname.
117 Returns the $cUID by default.
119 ## <a name="ObjectMethod <strong>userExists</strong> ($cUID"></a> [[ObjectMethod]] **userExists** `($cUID) -> $boolean`
121 Determine if the user already exists or not. Whether a user exists or not is determined by the password manager.
123 Subclasses **must** implement this method.
125 ## <a name="ObjectMethod <strong>eachUser</strong> () - lis"></a> [[ObjectMethod]] **eachUser** `() -> listIteratorofcUIDs`
127 Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
129 Subclasses **must** implement this method.
131 ## <a name="ObjectMethod <strong>each_GroupMember*"></a><a name="ObjectMethod *each_GroupMember</strong> "></a> [[ObjectMethod]] **eachGroupMember** `($group) -> TWiki::ListIteratorofcUIDs`
133 Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
135 Subclasses **must** implement this method.
137 ## <a name="ObjectMethod <strong>isGroup</strong> ($user) -"></a> [[ObjectMethod]] **isGroup** `($user) -> boolean`
139 Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
141 Subclasses **must** implement this method.
143 ## <a name="ObjectMethod <strong>eachGroup</strong> () - _L"></a> [[ObjectMethod]] **eachGroup** <tt>() -> [[ListIteratorofgroupnames]]</tt>
145 Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
147 Subclasses **must** implement this method.
149 ## <a name="ObjectMethod <strong>eachMembership</strong> ($"></a> [[ObjectMethod]] **eachMembership** <tt>($cUID) -> [[ListIteratorofgroupsthisuserisin]]</tt>
151 Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
153 Subclasses **must** implement this method.
155 ## <a name="ObjectMethod <strong>isAdmin</strong> ($user) -"></a> [[ObjectMethod]] **isAdmin** `($user) -> $boolean`
157 True if the user is an administrator. Default is **false**
159 ## <a name="ObjectMethod <strong>is_InGroup</strong> ($user"></a> [[ObjectMethod]] **isInGroup** `($user,$group,$scanning) -> bool`
161 Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
165 ## <a name="ObjectMethod <strong>find_UserByEmail*"></a><a name="ObjectMethod *find_UserByEmail</strong> "></a> [[ObjectMethod]] **findUserByEmail** `($email) -> \@users`
167 - `$email` - email address to look up
169 Return a list of canonical user names for the users that have this email registered with the password manager or the user mapping manager.
171 Returns an empty list by default.
173 ## <a name="ObjectMethod <strong>getEmails</strong> ($user)"></a> [[ObjectMethod]] **getEmails** `($user) -> @emailAddress`
175 If this is a user, return their email addresses. If it is a group, return the addresses of everyone in the group.
177 Duplicates should be removed from the list.
179 By default, returns the empty list.
181 ## <a name="ObjectMethod <strong>setEmails</strong> ($user,"></a> [[ObjectMethod]] **setEmails** `($user,@emails)`
183 Set the email address(es) for the given user. Does nothing by default.
185 ## <a name="ObjectMethod <strong>find_UserByWikiNam"></a> [[ObjectMethod]] \*findUserByWikiName `($wikiname) -> listofcUIDsassociatedwiththatwikiname`
187 Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
189 Subclasses **must** implement this method.
191 ## <a name="ObjectMethod <strong>checkPassword</strong> ($u"></a> [[ObjectMethod]] **checkPassword** `($userName,$passwordU) -> $boolean`
193 Finds if the password is valid for the given user.
195 Returns 1 on success, undef on failure.
197 Default behaviour is to return 1.
199 ## <a name="ObjectMethod <strong>setPassword</strong> ($use"></a> [[ObjectMethod]] **setPassword** `($user,$newPassU,$oldPassU) -> $boolean`
201 If the $oldPassU matches matches the user's password, then it will replace it with $newPassU.
203 If $oldPassU is not correct and not 1, will return 0.
205 If $oldPassU is 1, will force the change irrespective of the existing password, adding the user if necessary.
207 Otherwise returns 1 on success, undef on failure.
209 Default behaviour is to fail.
211 ## <a name="ObjectMethod <strong>passwordError</strong> ()"></a><a name="ObjectMethod <strong>passwordError</strong> () "></a> [[ObjectMethod]] **passwordError** `() -> $string`
213 Returns a string indicating the error that happened in the password handlers TODO: these delayed errors should be replaced with Exceptions.
215 returns undef if no error 9the default)
217 ## <a name="ObjectMethod <strong>ASSERT_IS_CANONICA"></a> [[ObjectMethod]] \*ASSERT\_IS\_CANONICAL\_USER\_ID `($user_id) -> $boolean`
219 Used for debugging to ensure we are actually passing a canonical\_id
221 ## <a name="ObjectMethod <strong>ASSERT_IS_USER_LOG"></a> [[ObjectMethod]] \*ASSERT\_IS\_USER\_LOGIN\_ID `($user_login) -> $boolean`
223 Used for debugging to ensure we are actually passing a user login
225 ## <a name="ObjectMethod <strong>ASSERT_IS_USER_DIS"></a> [[ObjectMethod]] \*ASSERT\_IS\_USER\_DISPLAY\_NAME `($user_display) -> $boolean`
227 Used for debugging to ensure we are actually passing a user display\_name (commonly a [[WikiWord]] Name)
229 Returns true by default.