data/TWiki/TWikiUserMappingDotPm.txt
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
permissions -rw-r--r--
RELEASE 4.2.0 freetown
     1 ---+ Package =TWiki::UserMapping=
     2 
     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
     5 behaviour.
     6 
     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.
     9 
    10 See TWiki::Users::BaseUserMapping and TWiki::Users::TWikiUserMapping for
    11 the default implementations of this interface.
    12 
    13 If you want to write a user mapper, you will need to implement the methods
    14 described in this class.
    15 
    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.
    20 
    21 The null prefix is reserver for the TWikiUserMapping for compatibility
    22 with old TWiki releases.
    23 
    24 __Note:__ in all the following documentation, =$user= refers to a
    25 *canonical user id*.
    26 
    27 
    28 %TOC%
    29 
    30 ---++ PROTECTED ClassMethod new ($session, $mapping_id)
    31 
    32 Construct a user mapping object, using the given mapping id.
    33 
    34 
    35 ---++ ObjectMethod *finish* <tt>()</tt>
    36 Break circular references.
    37 
    38 
    39 
    40 ---++ ObjectMethod *loginTemplateName* <tt>() -> $templateFile</tt>
    41 
    42 Allows UserMappings to come with customised login screens - that should
    43 preferably only over-ride the UI function
    44 
    45 Default is "login"
    46 
    47 
    48 
    49 ---++ ObjectMethod *supportsRegistration* <tt>() -> $boolean</tt>
    50 
    51 Return true if the UserMapper supports registration (ie can create new users)
    52 
    53 Default is *false*
    54 
    55 
    56 
    57 ---++ ObjectMethod *handlesUser* <tt>($cUID,$login,$wikiname) -> $boolean</tt>
    58 
    59 Called by the TWiki::Users object to determine which loaded mapping
    60 to use for a given user (must be fast).
    61 
    62 Default is *false*
    63 
    64 
    65 
    66 ---++ ObjectMethod *getCanonicalUserID* <tt>($login,$dontcheck) -> cUID</tt>
    67 
    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.
    71 (undef on failure)
    72 
    73 (if dontcheck is true, return a cUID for a nonexistant user too - used for registration)
    74 
    75 Subclasses *must* implement this method.
    76 
    77 
    78 
    79 
    80 ---++ ObjectMethod *getLoginName* <tt>($cUID) -> login</tt>
    81 
    82 Converts an internal cUID to that user's login
    83 (undef on failure)
    84 
    85 Subclasses *must* implement this method.
    86 
    87 
    88 
    89 ---++ ObjectMethod *addUser* <tt>($login,$wikiname,$password,$emails) -> cUID</tt>
    90 
    91 Add a user to the persistant mapping that maps from usernames to wikinames
    92 and vice-versa, via a *canonical user id* (cUID).
    93 
    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.
    97 
    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.
   102 
   103 If you fail to create a new user (for eg your Mapper has read only access),
   104 <pre>
   105     throw Error::Simple('Failed to add user: '.$error);
   106 </pre>
   107 where $error is a descriptive string.
   108 
   109 Throws an Error::Simple if user adding is not supported (the default).
   110 
   111 
   112 
   113 ---++ ObjectMethod *removeUser* <tt>($user) -> $boolean</tt>
   114 
   115 Delete the users entry from this mapper. Throws an Error::Simple if
   116 user removal is not supported (the default).
   117 
   118 
   119 
   120 ---++ ObjectMethod *getWikiName* <tt>($cUID) -> wikiname</tt>
   121 
   122 Map a canonical user name to a wikiname.
   123 
   124 Returns the $cUID by default.
   125 
   126 
   127 
   128 ---++ ObjectMethod *userExists* <tt>($cUID) -> $boolean</tt>
   129 
   130 Determine if the user already exists or not. Whether a user exists
   131 or not is determined by the password manager.
   132 
   133 Subclasses *must* implement this method.
   134 
   135 
   136 
   137 ---++ ObjectMethod *eachUser* <tt>() -> listIteratorofcUIDs</tt>
   138 
   139 Called from TWiki::Users. See the documentation of the corresponding
   140 method in that module for details.
   141 
   142 Subclasses *must* implement this method.
   143 
   144 
   145 
   146 ---++ ObjectMethod *eachGroupMember* <tt>($group) -> TWiki::ListIteratorofcUIDs</tt>
   147 
   148 Called from TWiki::Users. See the documentation of the corresponding
   149 method in that module for details.
   150 
   151 Subclasses *must* implement this method.
   152 
   153 
   154 
   155 ---++ ObjectMethod *isGroup* <tt>($user) -> boolean</tt>
   156 
   157 Called from TWiki::Users. See the documentation of the corresponding
   158 method in that module for details.
   159 
   160 Subclasses *must* implement this method.
   161 
   162 
   163 
   164 ---++ ObjectMethod *eachGroup* <tt>() -> ListIteratorofgroupnames</tt>
   165 
   166 Called from TWiki::Users. See the documentation of the corresponding
   167 method in that module for details.
   168 
   169 Subclasses *must* implement this method.
   170 
   171 
   172 
   173 ---++ ObjectMethod *eachMembership* <tt>($cUID) -> ListIteratorofgroupsthisuserisin</tt>
   174 
   175 Called from TWiki::Users. See the documentation of the corresponding
   176 method in that module for details.
   177 
   178 Subclasses *must* implement this method.
   179 
   180 
   181 
   182 ---++ ObjectMethod *isAdmin* <tt>($user) -> $boolean</tt>
   183 
   184 True if the user is an administrator. Default is *false*
   185 
   186 
   187 
   188 ---++ ObjectMethod *isInGroup* <tt>($user,$group,$scanning) -> bool</tt>
   189 
   190 Called from TWiki::Users. See the documentation of the corresponding
   191 method in that module for details.
   192 
   193 Default is *false*
   194 
   195 
   196 
   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.
   201 
   202 Returns an empty list by default.
   203 
   204 
   205 
   206 ---++ ObjectMethod *getEmails* <tt>($user) -> @emailAddress</tt>
   207 
   208 If this is a user, return their email addresses. If it is a group,
   209 return the addresses of everyone in the group.
   210 
   211 Duplicates should be removed from the list.
   212 
   213 By default, returns the empty list.
   214 
   215 
   216 
   217 ---++ ObjectMethod *setEmails* <tt>($user,@emails)</tt>
   218 
   219 Set the email address(es) for the given user. Does nothing by default.
   220 
   221 
   222 
   223 ---++ ObjectMethod *findUserByWikiName* <tt>($wikiname) -> listofcUIDsassociatedwiththatwikiname</tt>
   224 
   225 Called from TWiki::Users. See the documentation of the corresponding
   226 method in that module for details.
   227 
   228 Subclasses *must* implement this method.
   229 
   230 
   231 
   232 ---++ ObjectMethod *checkPassword* <tt>($userName,$passwordU) -> $boolean</tt>
   233 
   234 Finds if the password is valid for the given user.
   235 
   236 Returns 1 on success, undef on failure.
   237 
   238 Default behaviour is to return 1.
   239 
   240 
   241 
   242 ---++ ObjectMethod *setPassword* <tt>($user,$newPassU,$oldPassU) -> $boolean</tt>
   243 
   244 If the $oldPassU matches matches the user's password, then it will
   245 replace it with $newPassU.
   246 
   247 If $oldPassU is not correct and not 1, will return 0.
   248 
   249 If $oldPassU is 1, will force the change irrespective of
   250 the existing password, adding the user if necessary.
   251 
   252 Otherwise returns 1 on success, undef on failure.
   253 
   254 Default behaviour is to fail.
   255 
   256 
   257 
   258 ---++ ObjectMethod *passwordError* <tt>() -> $string</tt>
   259 
   260 Returns a string indicating the error that happened in the password handlers
   261 TODO: these delayed errors should be replaced with Exceptions.
   262 
   263 returns undef if no error 9the default)
   264 
   265 
   266 
   267 ---++ ObjectMethod *ASSERT_IS_CANONICAL_USER_ID* <tt>($user_id) -> $boolean</tt>
   268 
   269 Used for debugging to ensure we are actually passing a canonical_id
   270 
   271 
   272 
   273 ---++ ObjectMethod *ASSERT_IS_USER_LOGIN_ID* <tt>($user_login) -> $boolean</tt>
   274 
   275 Used for debugging to ensure we are actually passing a user login
   276 
   277 
   278 
   279 ---++ ObjectMethod *ASSERT_IS_USER_DISPLAY_NAME* <tt>($user_display) -> $boolean</tt>
   280 
   281 Used for debugging to ensure we are actually passing a user display_name
   282 (commonly a WikiWord Name)
   283 
   284 Returns true by default.
   285 
   286