**NOTE:**
-- wherever the code references $user, its a canonical\_id
+- wherever the code references $cUID, its a canonical\_id
- wherever the code references $group, its a group\_name
+- $name may be a group or a cUID
<div>
<ul>
<li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
<li><a href="#ObjectMethod *login_TemplateName"> ObjectMethod loginTemplateName <tt>() -> templateFile</tt></a></li>
<li><a href="#ObjectMethod *supportsRegistrati"> ObjectMethod supportsRegistration <tt>() -> boolean</tt></a></li>
- <li><a href="#ObjectMethod <strong>initialiseUser</strong> ($"> ObjectMethod initialiseUser <tt>($login) -> cUID</tt></a></li>
+ <li><a href="#ObjectMethod <strong>initialiseUser</strong> ($"> ObjectMethod initialiseUser <tt>($login) -> $cUID</tt></a></li>
<li><a href="#randomPassword()"> randomPassword()</a></li>
<li><a href="#ObjectMethod <strong>addUser</strong> ($login,$"> ObjectMethod addUser <tt>($login,$wikiname,$password,$emails) -> $cUID</tt></a></li>
- <li><a href="#StaticMethod <strong>forceCUID</strong> ($cUID)"> StaticMethod forceCUID <tt>($cUID) -> $cUID</tt></a></li>
- <li><a href="#ObjectMethod *get_CanonicalUserI"> ObjectMethod getCanonicalUserID <tt>($login) -> $user</tt></a></li>
+ <li><a href="#StaticMethod <strong>map_Login2cUID</strong> ($"> StaticMethod mapLogin2cUID <tt>($login) -> $cUID</tt></a></li>
+ <li><a href="#ObjectMethod *get_CanonicalUserI"> ObjectMethod getCanonicalUserID <tt>($identifier) -> $cUID</tt></a></li>
<li><a href="#ObjectMethod *find_UserByWikiNam"> ObjectMethod findUserByWikiName <tt>($wn) -> \@users</tt></a></li>
<li><a href="#ObjectMethod *find_UserByEmail*"> ObjectMethod findUserByEmail <tt>($email) -> \@users</tt></a></li>
- <li><a href="#ObjectMethod <strong>getEmails</strong> ($user)"> ObjectMethod getEmails <tt>($user) -> @emailAddress</tt></a></li>
- <li><a href="#ObjectMethod <strong>setEmails</strong> ($user,"> ObjectMethod setEmails <tt>($user,@emails)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>getEmails</strong> ($name)"> ObjectMethod getEmails <tt>($name) -> @emailAddress</tt></a></li>
+ <li><a href="#ObjectMethod <strong>setEmails</strong> ($cUID,"> ObjectMethod setEmails <tt>($cUID,@emails)</tt></a></li>
<li><a href="#ObjectMethod <strong>isAdmin</strong> ($cUID) -"> ObjectMethod isAdmin <tt>($cUID) -> $boolean</tt></a></li>
- <li><a href="#ObjectMethod <strong>is_InList</strong> ($user,"> ObjectMethod isInList <tt>($user,$list) -> $boolean</tt></a></li>
- <li><a href="#ObjectMethod <strong>get_LoginName</strong> ($c"> ObjectMethod getLoginName <tt>($cUID) -> $string</tt></a></li>
+ <li><a href="#ObjectMethod <strong>is_InList</strong> ($cUID,"> ObjectMethod isInList <tt>($cUID,$list) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>get_LoginName</strong> ($c"> ObjectMethod getLoginName <tt>($cUID) -> $login</tt></a></li>
<li><a href="#ObjectMethod <strong>get_WikiName</strong> ($cU"> ObjectMethod getWikiName <tt>($cUID) -> $wikiName</tt></a></li>
- <li><a href="#ObjectMethod <strong>web_DotWikiName</strong> ("> ObjectMethod webDotWikiName <tt>($user) -> $webDotWiki</tt></a></li>
+ <li><a href="#ObjectMethod <strong>web_DotWikiName</strong> ("> ObjectMethod webDotWikiName <tt>($cUID) -> $webDotWiki</tt></a></li>
<li><a href="#ObjectMethod <strong>userExists</strong> ($cUID"> ObjectMethod userExists <tt>($cUID) -> $boolean</tt></a></li>
- <li><a href="#ObjectMethod <strong>eachUser</strong> () -> $i"> ObjectMethod eachUser <tt>() -> $iterator</tt></a></li>
- <li><a href="#ObjectMethod <strong>eachGroup</strong> () -> $"> ObjectMethod eachGroup <tt>() -> $iterator</tt></a></li>
+ <li><a href="#ObjectMethod <strong>eachUser</strong> () -> TW"> ObjectMethod eachUser <tt>() -> TWiki::IteratorofcUIDs</tt></a></li>
+ <li><a href="#ObjectMethod <strong>eachGroup</strong> () -> T"> ObjectMethod eachGroup <tt>() -> TWiki::ListIteratorofgroupnames</tt></a></li>
<li><a href="#ObjectMethod *each_GroupMember*"> ObjectMethod eachGroupMember <tt>($group) -> $iterator</tt></a></li>
- <li><a href="#ObjectMethod <strong>isGroup</strong> ($user) -"> ObjectMethod isGroup <tt>($user) -> boolean</tt></a></li>
- <li><a href="#ObjectMethod <strong>is_InGroup</strong> ($user"> ObjectMethod isInGroup <tt>($user,$group) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>isGroup</strong> ($name) -"> ObjectMethod isGroup <tt>($name) -> boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>is_InGroup</strong> ($cUID"> ObjectMethod isInGroup <tt>($cUID,$group) -> $boolean</tt></a></li>
<li><a href="#ObjectMethod <strong>eachMembership</strong> ($"> ObjectMethod eachMembership <tt>($cUID) -> $iterator</tt></a></li>
- <li><a href="#ObjectMethod <strong>checkPassword</strong> ($u"> ObjectMethod checkPassword <tt>($userName,$passwordU) -> $boolean</tt></a></li>
- <li><a href="#ObjectMethod <strong>setPassword</strong> ($use"> ObjectMethod setPassword <tt>($user,$newPassU,$oldPassU) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>checkLogin</strong> ($logi"> ObjectMethod checkLogin <tt>($login,$passwordU) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>setPassword</strong> ($cUI"> ObjectMethod setPassword <tt>($cUID,$newPassU,$oldPassU) -> $boolean</tt></a></li>
<li><a href="#ObjectMethod <strong>passwordError</strong> ()"> ObjectMethod passwordError <tt>() -> $string</tt></a></li>
- <li><a href="#ObjectMethod <strong>removeUser</strong> ($user"> ObjectMethod removeUser <tt>($user) -> $boolean</tt></a></li>
- <li><a href="#ObjectMethod *ASSERT_IS_CANONICA"> ObjectMethod ASSERT_IS_CANONICAL_USER_ID <tt>($user_id) -> $boolean</tt></a></li>
- <li><a href="#ObjectMethod *ASSERT_IS_USER_LOG"> ObjectMethod ASSERT_IS_USER_LOGIN_ID <tt>($user_login) -> $boolean</tt></a></li>
- <li><a href="#ObjectMethod *ASSERT_IS_USER_DIS"> ObjectMethod ASSERT_IS_USER_DISPLAY_NAME <tt>($user_display) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>removeUser</strong> ($cUID"> ObjectMethod removeUser <tt>($cUID) -> $boolean</tt></a></li>
</ul>
</li>
</ul>
#return 1 if the main [[UserMapper]] supports registration (ie can create new users)
-## <a name="ObjectMethod <strong>initialiseUser</strong> ($"></a> [[ObjectMethod]] **initialiseUser** `($login) -> cUID`
+## <a name="ObjectMethod <strong>initialiseUser</strong> ($"></a> [[ObjectMethod]] **initialiseUser** `($login) -> $cUID`
+
+Given a login (which must have been authenticated) determine the cUID that corresponds to that user. This method is used from TWiki.pm to map the $REMOTE\_USER to a cUID.
## <a name="randomPassword()"></a> randomPassword()
-Static function that returns a random password
+Static function that returns a random password. This function is not used in this module; it is provided as a service for other modules, such as custom mappers and registration modules.
## <a name="ObjectMethod <strong>addUser</strong> ($login,$"></a> [[ObjectMethod]] **addUser** `($login,$wikiname,$password,$emails) -> $cUID`
The return value is the canonical user id that is used by TWiki to identify the user.
-## <a name="StaticMethod <strong>forceCUID</strong> ($cUID)"></a> [[StaticMethod]] **forceCUID** `($cUID) -> $cUID`
+## <a name="StaticMethod <strong>map_Login2cUID</strong> ($"></a> [[StaticMethod]] **mapLogin2cUID** `($login) -> $cUID`
+
+This function maps an arbitrary string into a valid cUID. The transformation is reversible, but the function is not idempotent (a cUID passed to this function will NOT be returned unchanged). The generated cUID will be unique for the given login name.
-This function ensures that any cUID's are able to be used for rcs, and other internals not capable of coping with user identifications that contain more than 7 bit ascii.
+This static function is designed to be called from custom user mappers that support 1:1 login-to-cUID mappings.
-repeated calls must result in the same result (sorry, can't spell the word for it)so the '\_' must not be re-encoded
+## <a name="ObjectMethod <strong>get_CanonicalUserI"></a> [[ObjectMethod]] \*getCanonicalUserID `($identifier) -> $cUID`
-Please, call this function in any custom Usermapper to simplifyyour mapping code.
+Works out the TWiki canonical user identifier for the user who either (1) logs in with the login name $identifier or (2) has the wikiname $identifier.
-## <a name="ObjectMethod <strong>get_CanonicalUserI"></a> [[ObjectMethod]] \*getCanonicalUserID `($login) -> $user`
+The canonical user ID is an alphanumeric string that is unique to the login name, and can be mapped back to a login name and the corresponding wiki name using the methods of this class.
-Works out the unique TWiki identifier for the user who logs in with the given login. The canonical user ID is an alphanumeric string that is unique to the login name, and can be mapped back to a login name and the corresponding wiki name using the methods of this class.
+Note that if the login name to wiki name mapping is not 1:1, this method will map a wikiname to one of the login names that corresponds to the wiki name, but there is no guarantee which one.
-returns undef if the user does not exist.
+Returns undef if the user does not exist.
## <a name="ObjectMethod <strong>find_UserByWikiNam"></a> [[ObjectMethod]] \*findUserByWikiName `($wn) -> \@users`
Return a list of canonical user names for the users that have this email registered with the user mapping managers.
-## <a name="ObjectMethod <strong>getEmails</strong> ($user)"></a> [[ObjectMethod]] **getEmails** `($user) -> @emailAddress`
+## <a name="ObjectMethod <strong>getEmails</strong> ($name)"></a> [[ObjectMethod]] **getEmails** `($name) -> @emailAddress`
-If this is a user, return their email addresses. If it is a group, return the addresses of everyone in the group.
+If $name is a cUID, return their email addresses. If it is a group, return the addresses of everyone in the group.
The password manager and user mapping manager are both consulted for emails for each user (where they are actually found is implementation defined).
Duplicates are removed from the list.
-## <a name="ObjectMethod <strong>setEmails</strong> ($user,"></a> [[ObjectMethod]] **setEmails** `($user,@emails)`
+## <a name="ObjectMethod <strong>setEmails</strong> ($cUID,"></a> [[ObjectMethod]] **setEmails** `($cUID,@emails)`
Set the email address(es) for the given user. The password manager is tried first, and if it doesn't want to know the user mapping manager is tried.
- is $TWiki::cfg\{SuperAdminGroup\}
- is a member of the $TWiki::cfg\{SuperAdminGroup\}
-## <a name="ObjectMethod <strong>is_InList</strong> ($user,"></a> [[ObjectMethod]] **isInList** `($user,$list) -> $boolean`
+## <a name="ObjectMethod <strong>is_InList</strong> ($cUID,"></a> [[ObjectMethod]] **isInList** `($cUID,$list) -> $boolean`
-Return true if $user is in a list of user **wikinames** and group ids.
+Return true if $cUID is in a list of user **wikinames**, **logins** and group ids.
-$list is a comma-separated wikiname and group list. The list may contain the conventional web specifiers (which are ignored).
+The list may contain the conventional web specifiers (which are ignored).
-## <a name="ObjectMethod <strong>get_LoginName</strong> ($c"></a> [[ObjectMethod]] **getLoginName** `($cUID) -> $string`
+## <a name="ObjectMethod <strong>get_LoginName</strong> ($c"></a> [[ObjectMethod]] **getLoginName** `($cUID) -> $login`
-Get the login name of a user.
+Get the login name of a user. Returns undef if the user is not known.
## <a name="ObjectMethod <strong>get_WikiName</strong> ($cU"></a> [[ObjectMethod]] **getWikiName** `($cUID) -> $wikiName`
Get the wikiname to display for a canonical user identifier.
-can return undef if the user is not in the mapping system (or the special case from initialiseUser)
+Can return undef if the user is not in the mapping system (or the special case from initialiseUser)
-## <a name="ObjectMethod <strong>web_DotWikiName</strong> ("></a> [[ObjectMethod]] **webDotWikiName** `($user) -> $webDotWiki`
+## <a name="ObjectMethod <strong>web_DotWikiName</strong> ("></a> [[ObjectMethod]] **webDotWikiName** `($cUID) -> $webDotWiki`
Return the fully qualified wikiname of the user
Determine if the user already exists or not. A user exists if they are known to to the user mapper.
-## <a name="ObjectMethod <strong>eachUser</strong> () - $it"></a> [[ObjectMethod]] **eachUser** `() -> $iterator`
+## <a name="ObjectMethod <strong>eachUser</strong> () - TWi"></a> [[ObjectMethod]] **eachUser** `() -> TWiki::IteratorofcUIDs`
Get an iterator over the list of all the registered users **not** including groups.
...
}
-## <a name="ObjectMethod <strong>eachGroup</strong> () - $i"></a> [[ObjectMethod]] **eachGroup** `() -> $iterator`
+## <a name="ObjectMethod <strong>eachGroup</strong> () - TW"></a> [[ObjectMethod]] **eachGroup** `() -> TWiki::ListIteratorofgroupnames`
Get an iterator over the list of all the groups.
Note that groups may be defined recursively, so a group may contain other groups. This method should **only** return users i.e. all contained groups should be fully expanded.
-## <a name="ObjectMethod <strong>isGroup</strong> ($user) -"></a> [[ObjectMethod]] **isGroup** `($user) -> boolean`
-
-Establish if a user refers to a group or not.
-
-The default implementation is to check if the wikiname of the user ends with 'Group'. Subclasses may override this behaviour to provide alternative interpretations. The $TWiki::cfg\{SuperAdminGroup\} is recognized as a group no matter what it's name is.
+## <a name="ObjectMethod <strong>isGroup</strong> ($name) -"></a> [[ObjectMethod]] **isGroup** `($name) -> boolean`
-QUESTION: is the $user parameter here a string, or a canonical\_id??
+Establish if a $name refers to a group or not. If $name is not a group name it will probably be a canonical user id, though that should not be assumed.
-## <a name="ObjectMethod <strong>is_InGroup</strong> ($user"></a> [[ObjectMethod]] **isInGroup** `($user,$group) -> $boolean`
+## <a name="ObjectMethod <strong>is_InGroup</strong> ($cUID"></a> [[ObjectMethod]] **isInGroup** `($cUID,$group) -> $boolean`
-Test if user is in the given group.
+Test if the user identified by $cUID is in the given group.
## <a name="ObjectMethod <strong>eachMembership</strong> ($"></a> [[ObjectMethod]] **eachMembership** `($cUID) -> $iterator`
Return an iterator over the groups that $cUID is a member of.
-## <a name="ObjectMethod <strong>checkPassword</strong> ($u"></a> [[ObjectMethod]] **checkPassword** `($userName,$passwordU) -> $boolean`
+## <a name="ObjectMethod <strong>checkLogin</strong> ($logi"></a> [[ObjectMethod]] **checkLogin** `($login,$passwordU) -> $boolean`
-Finds if the password is valid for the given user.
+Finds if the password is valid for the given user. This method is called using the login name rather than the $cUID so that it can be called with a user who can be authenticated, but may not be mappable to a cUID (yet).
Returns 1 on success, undef on failure.
TODO: add special check for [[BaseMapping]] admin user's login, and if its there (and we're in sudo\_context?) use that..
-## <a name="ObjectMethod <strong>setPassword</strong> ($use"></a> [[ObjectMethod]] **setPassword** `($user,$newPassU,$oldPassU) -> $boolean`
+## <a name="ObjectMethod <strong>setPassword</strong> ($cUI"></a> [[ObjectMethod]] **setPassword** `($cUID,$newPassU,$oldPassU) -> $boolean`
If the $oldPassU matches matches the user's password, then it will replace it with $newPassU.
## <a name="ObjectMethod <strong>passwordError</strong> ()"></a><a name="ObjectMethod <strong>passwordError</strong> () "></a> [[ObjectMethod]] **passwordError** `() -> $string`
-returns a string indicating the error that happened in the password handlers TODO: these delayed error's should be replaced with Exceptions.
+Returns a string indicating the error that happened in the password handlers TODO: these delayed error's should be replaced with Exceptions.
returns undef if no error
-## <a name="ObjectMethod <strong>removeUser</strong> ($user"></a> [[ObjectMethod]] **removeUser** `($user) -> $boolean`
+## <a name="ObjectMethod <strong>removeUser</strong> ($cUID"></a> [[ObjectMethod]] **removeUser** `($cUID) -> $boolean`
Delete the users entry. Removes the user from the password manager and user mapping manager. Does **not** remove their personal topics, which may still be linked.
-
-## <a name="ObjectMethod <strong>ASSERT_IS_CANONICA"></a> [[ObjectMethod]] \*ASSERT\_IS\_CANONICAL\_USER\_ID `($user_id) -> $boolean`
-
-used for debugging to ensure we are actually passing a canonical\_id
-
-These ASSERTS have been disabled, as they have been made dangerous and misleading due to the legacy cUID code
-
-## <a name="ObjectMethod <strong>ASSERT_IS_USER_LOG"></a> [[ObjectMethod]] \*ASSERT\_IS\_USER\_LOGIN\_ID `($user_login) -> $boolean`
-
-used for debugging to ensure we are actually passing a user login
-
-These ASSERTS have been disabled, as they have been made dangerous and misleading due to the legacy cUID code
-
-## <a name="ObjectMethod <strong>ASSERT_IS_USER_DIS"></a> [[ObjectMethod]] \*ASSERT\_IS\_USER\_DISPLAY\_NAME `($user_display) -> $boolean`
-
-used for debugging to ensure we are actually passing a user display\_name (commonly a [[WikiWord]] Name)
-
-These ASSERTS have been disabled, as they have been made dangerous and misleading due to the legacy cUID code
git://git.openafs.org / openafs-wiki.git / blobdiff