TWiki/TWikiUsersBaseUserMappingDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki::Users::_BaseUser"></a> Package =TWiki::Users::BaseUserMapping
   2
   3 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.
   4
   5 The [[BaseMapper]] provides support for a small number of predefined users. No registration - this is a read only usermapper. It uses the mapper prefix 'BaseUserMapping\_'.
   6
   7 ## <a name="Users"></a> Users
   8
   9 - [[TWikiAdmin]] - uses the password that was set in Configure (IF its not null)
  10 - [[TWikiGuest]]
  11 - [[UnknownUser]]
  12 - [[TWikiContributor]] - 1 Jan 2005
  13 - [[TWikiRegistrationAgent]] - 1 Jan 2005
  14
  15 ### <a name="Groups"></a> Groups
  16
  17 - $TWiki::cfg\{SuperAdminGroup\}
  18 - [[TWikiBaseGroup]]
  19
  20 <div>
  21   <ul>
  22     <li><a href="#Package =TWiki::Users::_BaseUser"> Package TWiki::Users::BaseUserMapping</a><ul>
  23         <li><a href="#Users"> Users</a><ul>
  24             <li><a href="#Groups"> Groups</a></li>
  25           </ul>
  26         </li>
  27         <li><a href="#ClassMethod <strong>new</strong> ($session)"> ClassMethod new <tt>($session)</tt></a></li>
  28         <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
  29         <li><a href="#ObjectMethod *login_TemplateName"> ObjectMethod loginTemplateName <tt>() -&gt; templateFile</tt></a></li>
  30         <li><a href="#ObjectMethod <strong>handlesUser</strong> ($cUI"> ObjectMethod handlesUser <tt>($cUID,$login,$wikiname) -&gt; $boolean</tt></a></li>
  31         <li><a href="#ObjectMethod <strong>login2cUID</strong> ($logi"> ObjectMethod login2cUID <tt>($login) -&gt; $cUID</tt></a></li>
  32         <li><a href="#ObjectMethod <strong>get_LoginName</strong> ($c"> ObjectMethod getLoginName <tt>($cUID) -&gt; login</tt></a></li>
  33         <li><a href="#ObjectMethod <strong>get_WikiName</strong> ($cU"> ObjectMethod getWikiName <tt>($cUID) -&gt; wikiname</tt></a></li>
  34         <li><a href="#ObjectMethod <strong>userExists</strong> ($user"> ObjectMethod userExists <tt>($user) -&gt; $boolean</tt></a></li>
  35         <li><a href="#ObjectMethod <strong>eachUser</strong> () -> li"> ObjectMethod eachUser <tt>() -&gt; listIteratorofcUIDs</tt></a></li>
  36         <li><a href="#ObjectMethod *each_GroupMember*"> ObjectMethod eachGroupMember <tt>($group) -&gt; listIteratorofcUIDs</tt></a></li>
  37         <li><a href="#ObjectMethod <strong>isGroup</strong> ($name) -"> ObjectMethod isGroup <tt>($name) -&gt; boolean</tt></a></li>
  38         <li><a href="#ObjectMethod <strong>eachGroup</strong> () ->"> ObjectMethod eachGroup <tt>() -&gt; ListIteratorofgroupnames</tt></a></li>
  39         <li><a href="#ObjectMethod <strong>eachMembership</strong> ($"> ObjectMethod eachMembership <tt>($cUID) -&gt; ListIteratorofgroupsthisuserisin</tt></a></li>
  40         <li><a href="#ObjectMethod <strong>isAdmin</strong> ($cUID) -"> ObjectMethod isAdmin <tt>($cUID) -&gt; $boolean</tt></a></li>
  41         <li><a href="#ObjectMethod <strong>getEmails</strong> ($name)"> ObjectMethod getEmails <tt>($name) -&gt; @emailAddress</tt></a></li>
  42         <li><a href="#ObjectMethod *find_UserByWikiNam"> ObjectMethod findUserByWikiName <tt>($wikiname) -&gt; listofcUIDsassociatedwiththatwikiname</tt></a></li>
  43         <li><a href="#ObjectMethod <strong>checkPassword</strong> ($l"> ObjectMethod checkPassword <tt>($login,$passwordU) -&gt; $boolean</tt></a></li>
  44         <li><a href="#ObjectMethod <strong>setPassword</strong> ($cUI"> ObjectMethod setPassword <tt>($cUID,$newPassU,$oldPassU) -&gt; $boolean</tt></a></li>
  45         <li><a href="#ObjectMethod <strong>passwordError</strong> ()"> ObjectMethod passwordError <tt>() -&gt; $string</tt></a></li>
  46       </ul>
  47     </li>
  48   </ul>
  49 </div>
  50
  51 ## <a name="ClassMethod &lt;strong&gt;new&lt;/strong&gt; ($session)"></a> [[ClassMethod]] **new** `($session)`
  52
  53 Construct the [[BaseUserMapping]] object
  54
  55 ## <a name="ObjectMethod &lt;strong&gt;finish&lt;/strong&gt; ()"></a> [[ObjectMethod]] **finish** `()`
  56
  57 Break circular references.
  58
  59 ## <a name="ObjectMethod &lt;strong&gt;login_TemplateName"></a> [[ObjectMethod]] \*loginTemplateName `() -> templateFile`
  60
  61 allows [[UserMappings]] to come with customised login screens - that should preffereably only over-ride the UI function
  62
  63 ## <a name="ObjectMethod &lt;strong&gt;handlesUser&lt;/strong&gt; ($cUI"></a> [[ObjectMethod]] **handlesUser** `($cUID,$login,$wikiname) -> $boolean`
  64
  65 See baseclass for documentation.
  66
  67 In the [[BaseUserMapping]] case, we know all the details of the users we specialise in.
  68
  69 ## <a name="ObjectMethod &lt;strong&gt;login2cUID&lt;/strong&gt; ($logi"></a> [[ObjectMethod]] **login2cUID** `($login) -> $cUID`
  70
  71 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)
  72
  73 ## <a name="ObjectMethod &lt;strong&gt;get_LoginName&lt;/strong&gt; ($c"></a> [[ObjectMethod]] **getLoginName** `($cUID) -> login`
  74
  75 converts an internal cUID to that user's login (undef on failure)
  76
  77 ## <a name="ObjectMethod &lt;strong&gt;get_WikiName&lt;/strong&gt; ($cU"></a> [[ObjectMethod]] **getWikiName** `($cUID) -> wikiname`
  78
  79 Map a canonical user name to a wikiname
  80
  81 ## <a name="ObjectMethod &lt;strong&gt;userExists&lt;/strong&gt; ($user"></a> [[ObjectMethod]] **userExists** `($user) -> $boolean`
  82
  83 Determine if the user already exists or not.
  84
  85 ## <a name="ObjectMethod &lt;strong&gt;eachUser&lt;/strong&gt; () - lis"></a> [[ObjectMethod]] **eachUser** `() -> listIteratorofcUIDs`
  86
  87 See baseclass for documentation.
  88
  89 ## <a name="ObjectMethod &lt;strong&gt;each_GroupMember*"></a><a name="ObjectMethod *each_GroupMember&lt;/strong&gt; "></a> [[ObjectMethod]] **eachGroupMember** `($group) -> listIteratorofcUIDs`
  90
  91 See baseclass for documentation.
  92
  93 The basemapper implementation assumes that there are no nested groups in the basemapper.
  94
  95 ## <a name="ObjectMethod &lt;strong&gt;isGroup&lt;/strong&gt; ($name) -"></a> [[ObjectMethod]] **isGroup** `($name) -> boolean`
  96
  97 See baseclass for documentation.
  98
  99 ## <a name="ObjectMethod &lt;strong&gt;eachGroup&lt;/strong&gt; () - _L"></a> [[ObjectMethod]] **eachGroup** <tt>() -&gt; [[ListIteratorofgroupnames]]</tt>
 100
 101 See baseclass for documentation.
 102
 103 ## <a name="ObjectMethod &lt;strong&gt;eachMembership&lt;/strong&gt; ($"></a> [[ObjectMethod]] **eachMembership** <tt>($cUID) -&gt; [[ListIteratorofgroupsthisuserisin]]</tt>
 104
 105 See baseclass for documentation.
 106
 107 ## <a name="ObjectMethod &lt;strong&gt;isAdmin&lt;/strong&gt; ($cUID) -"></a> [[ObjectMethod]] **isAdmin** `($cUID) -> $boolean`
 108
 109 True if the user is an admin
 110
 111 - is a member of the $TWiki::cfg\{SuperAdminGroup\}
 112
 113 ## <a name="ObjectMethod &lt;strong&gt;getEmails&lt;/strong&gt; ($name)"></a> [[ObjectMethod]] **getEmails** `($name) -> @emailAddress`
 114
 115 If $name is a cUID, return their email addresses. If it is a group, return the addresses of everyone in the group.
 116
 117 ## <a name="ObjectMethod &lt;strong&gt;find_UserByWikiNam"></a> [[ObjectMethod]] \*findUserByWikiName `($wikiname) -> listofcUIDsassociatedwiththatwikiname`
 118
 119 See baseclass for documentation.
 120
 121 ## <a name="ObjectMethod &lt;strong&gt;checkPassword&lt;/strong&gt; ($l"></a> [[ObjectMethod]] **checkPassword** `($login,$passwordU) -> $boolean`
 122
 123 Finds if the password is valid for the given user.
 124
 125 Returns 1 on success, undef on failure.
 126
 127 ## <a name="ObjectMethod &lt;strong&gt;setPassword&lt;/strong&gt; ($cUI"></a> [[ObjectMethod]] **setPassword** `($cUID,$newPassU,$oldPassU) -> $boolean`
 128
 129 If the $oldPassU matches matches the user's password, then it will replace it with $newPassU.
 130
 131 If $oldPassU is not correct and not 1, will return 0.
 132
 133 If $oldPassU is 1, will force the change irrespective of the existing password, adding the user if necessary.
 134
 135 Otherwise returns 1 on success, undef on failure.
 136
 137 ## <a name="ObjectMethod &lt;strong&gt;passwordError&lt;/strong&gt; ()"></a><a name="ObjectMethod &lt;strong&gt;passwordError&lt;/strong&gt; () "></a> [[ObjectMethod]] **passwordError** `() -> $string`
 138
 139 returns a string indicating the error that happened in the password handlers TODO: these delayed error's should be replaced with Exceptions.
 140
 141 returns undef if no error