data/TWiki/TWikiUserMappingDotPm.txt
changeset 1 e2915a7cbdfa
parent 0 414e01d06fd5
equal deleted inserted replaced
0:414e01d06fd5 1:e2915a7cbdfa
    19 and a unique user id that the mapper uses to identify the user.
    19 and a unique user id that the mapper uses to identify the user.
    20 
    20 
    21 The null prefix is reserver for the TWikiUserMapping for compatibility
    21 The null prefix is reserver for the TWikiUserMapping for compatibility
    22 with old TWiki releases.
    22 with old TWiki releases.
    23 
    23 
    24 __Note:__ in all the following documentation, =$user= refers to a
    24 __Note:__ in all the following documentation, =$cUID= refers to a
    25 *canonical user id*.
    25 *canonical user id*.
    26 
    26 
    27 
    27 
    28 %TOC%
    28 %TOC%
    29 
    29 
    57 ---++ ObjectMethod *handlesUser* <tt>($cUID,$login,$wikiname) -> $boolean</tt>
    57 ---++ ObjectMethod *handlesUser* <tt>($cUID,$login,$wikiname) -> $boolean</tt>
    58 
    58 
    59 Called by the TWiki::Users object to determine which loaded mapping
    59 Called by the TWiki::Users object to determine which loaded mapping
    60 to use for a given user (must be fast).
    60 to use for a given user (must be fast).
    61 
    61 
    62 Default is *false*
    62 The user can be identified by any of $cUID, $login or $wikiname. Any of
    63 
    63 these parameters may be undef, and they should be tested in order; cUID
    64 
    64 first, then login, then wikiname.
    65 
    65 
    66 ---++ ObjectMethod *getCanonicalUserID* <tt>($login,$dontcheck) -> cUID</tt>
    66 
       
    67 
       
    68 ---++ ObjectMethod *login2cUID* <tt>($login,$dontcheck) -> cUID</tt>
    67 
    69 
    68 Convert a login name to the corresponding canonical user name. The
    70 Convert a login name to the corresponding canonical user name. The
    69 canonical name can be any string of 7-bit alphanumeric and underscore
    71 canonical name can be any string of 7-bit alphanumeric and underscore
    70 characters, and must correspond 1:1 to the login name.
    72 characters, and must map 1:1 to the login name.
    71 (undef on failure)
    73 (undef on failure)
    72 
    74 
    73 (if dontcheck is true, return a cUID for a nonexistant user too - used for registration)
    75 (if $dontcheck is true, return a cUID for a nonexistant user too.
    74 
    76 This is used for registration)
    75 Subclasses *must* implement this method.
    77 
    76 
    78 Subclasses *must* implement this method.
       
    79 
       
    80 Note: This method was previously (in TWiki 4.2.0) known as getCanonicalUserID.
       
    81 The name was changed to avoid confusion with TWiki::Users::getCanonicalUserID,
       
    82 which has a more generic function. However to support older user mappers,
       
    83 getCanonicalUserID will still be called if login2cUID is not defined.
    77 
    84 
    78 
    85 
    79 
    86 
    80 ---++ ObjectMethod *getLoginName* <tt>($cUID) -> login</tt>
    87 ---++ ObjectMethod *getLoginName* <tt>($cUID) -> login</tt>
    81 
    88 
    84 
    91 
    85 Subclasses *must* implement this method.
    92 Subclasses *must* implement this method.
    86 
    93 
    87 
    94 
    88 
    95 
    89 ---++ ObjectMethod *addUser* <tt>($login,$wikiname,$password,$emails) -> cUID</tt>
    96 ---++ ObjectMethod *addUser* <tt>($login,$wikiname,$password,$emails) -> $cUID</tt>
    90 
    97 
    91 Add a user to the persistant mapping that maps from usernames to wikinames
    98 Add a user to the persistant mapping that maps from usernames to wikinames
    92 and vice-versa, via a *canonical user id* (cUID).
    99 and vice-versa.
    93 
   100 
    94 $login and $wikiname must be acceptable to $TWiki::cfg{NameFilter}.
   101 $login and $wikiname must be acceptable to $TWiki::cfg{NameFilter}.
    95 $login must *always* be specified. $wikiname may be undef, in which case
   102 $login must *always* be specified. $wikiname may be undef, in which case
    96 the user mapper should make one up.
   103 the user mapper should make one up.
    97 
   104 
   108 
   115 
   109 Throws an Error::Simple if user adding is not supported (the default).
   116 Throws an Error::Simple if user adding is not supported (the default).
   110 
   117 
   111 
   118 
   112 
   119 
   113 ---++ ObjectMethod *removeUser* <tt>($user) -> $boolean</tt>
   120 ---++ ObjectMethod *removeUser* <tt>($cUID) -> $boolean</tt>
   114 
   121 
   115 Delete the users entry from this mapper. Throws an Error::Simple if
   122 Delete the users entry from this mapper. Throws an Error::Simple if
   116 user removal is not supported (the default).
   123 user removal is not supported (the default).
   117 
   124 
   118 
   125 
   119 
   126 
   120 ---++ ObjectMethod *getWikiName* <tt>($cUID) -> wikiname</tt>
   127 ---++ ObjectMethod *getWikiName* <tt>($cUID) -> $wikiname</tt>
   121 
   128 
   122 Map a canonical user name to a wikiname.
   129 Map a canonical user name to a wikiname.
   123 
   130 
   124 Returns the $cUID by default.
   131 Returns the $cUID by default.
   125 
   132 
   132 
   139 
   133 Subclasses *must* implement this method.
   140 Subclasses *must* implement this method.
   134 
   141 
   135 
   142 
   136 
   143 
   137 ---++ ObjectMethod *eachUser* <tt>() -> listIteratorofcUIDs</tt>
   144 ---++ ObjectMethod *eachUser* <tt>() -> TWiki::ListIteratorofcUIDs</tt>
   138 
   145 
   139 Called from TWiki::Users. See the documentation of the corresponding
   146 Get an iterator over the list of all the registered users *not* including
   140 method in that module for details.
   147 groups.
   141 
   148 
   142 Subclasses *must* implement this method.
   149 Subclasses *must* implement this method.
   143 
   150 
   144 
   151 
   145 
   152 
   146 ---++ ObjectMethod *eachGroupMember* <tt>($group) -> TWiki::ListIteratorofcUIDs</tt>
   153 ---++ ObjectMethod *eachGroupMember* <tt>($group) -> TWiki::ListIteratorofcUIDs</tt>
   147 
   154 
   148 Called from TWiki::Users. See the documentation of the corresponding
   155 Return a iterator over the canonical user ids of users that are members
   149 method in that module for details.
   156 of this group. Should only be called on groups.
   150 
   157 
   151 Subclasses *must* implement this method.
   158 Note that groups may be defined recursively, so a group may contain other
   152 
   159 groups. This method should *only* return users i.e. all contained groups
   153 
   160 should be fully expanded.
   154 
   161 
   155 ---++ ObjectMethod *isGroup* <tt>($user) -> boolean</tt>
   162 Subclasses *must* implement this method.
   156 
   163 
   157 Called from TWiki::Users. See the documentation of the corresponding
   164 
   158 method in that module for details.
   165 
   159 
   166 ---++ ObjectMethod *isGroup* <tt>($name) -> boolean</tt>
   160 Subclasses *must* implement this method.
   167 
   161 
   168 Establish if a user refers to a group or not. If $name is not
   162 
   169 a group name it will probably be a canonical user id, though that
   163 
   170 should not be assumed.
   164 ---++ ObjectMethod *eachGroup* <tt>() -> ListIteratorofgroupnames</tt>
   171 
   165 
   172 Subclasses *must* implement this method.
   166 Called from TWiki::Users. See the documentation of the corresponding
   173 
   167 method in that module for details.
   174 
   168 
   175 
   169 Subclasses *must* implement this method.
   176 ---++ ObjectMethod *eachGroup* <tt>() -> TWiki::ListIteratorofgroupnames</tt>
   170 
   177 
   171 
   178 Get an iterator over the list of all the groups.
   172 
   179 
   173 ---++ ObjectMethod *eachMembership* <tt>($cUID) -> ListIteratorofgroupsthisuserisin</tt>
   180 Subclasses *must* implement this method.
   174 
   181 
   175 Called from TWiki::Users. See the documentation of the corresponding
   182 
   176 method in that module for details.
   183 
   177 
   184 ---++ ObjectMethod *eachMembership* <tt>($cUID) -> TWiki::ListIteratorofgroupsthisuserisin</tt>
   178 Subclasses *must* implement this method.
   185 
   179 
   186 Return an iterator over the names of groups that $cUID is a member of.
   180 
   187 
   181 
   188 Subclasses *must* implement this method.
   182 ---++ ObjectMethod *isAdmin* <tt>($user) -> $boolean</tt>
   189 
   183 
   190 
   184 True if the user is an administrator. Default is *false*
   191 
   185 
   192 ---++ ObjectMethod *isAdmin* <tt>($cUID) -> $boolean</tt>
   186 
   193 
   187 
   194 True if the user is an administrator.
   188 ---++ ObjectMethod *isInGroup* <tt>($user,$group,$scanning) -> bool</tt>
   195 
   189 
   196 
   190 Called from TWiki::Users. See the documentation of the corresponding
   197 
   191 method in that module for details.
   198 ---++ ObjectMethod *isInGroup* <tt>($cUID,$group) -> $bool</tt>
   192 
   199 
   193 Default is *false*
   200 Test if the user identified by $cUID is in the given group. The default
       
   201 implementation iterates over all the members of $group, which is rather
       
   202 inefficient.
   194 
   203 
   195 
   204 
   196 
   205 
   197 ---++ ObjectMethod *findUserByEmail* <tt>($email) -> \@users</tt>
   206 ---++ ObjectMethod *findUserByEmail* <tt>($email) -> \@users</tt>
   198    * =$email= - email address to look up
   207    * =$email= - email address to look up
   199 Return a list of canonical user names for the users that have this email
   208 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.
   209 registered with the password manager or the user mapping manager.
   201 
   210 
   202 Returns an empty list by default.
   211 
   203 
   212 
   204 
   213 ---++ ObjectMethod *getEmails* <tt>($name) -> @emailAddress</tt>
   205 
   214 
   206 ---++ ObjectMethod *getEmails* <tt>($user) -> @emailAddress</tt>
   215 If $name is a cUID, return that user's email addresses. If it is a group,
   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.
   216 return the addresses of everyone in the group.
   210 
   217 
   211 Duplicates should be removed from the list.
   218 Duplicates should be removed from the list.
   212 
   219 
   213 By default, returns the empty list.
   220 
   214 
   221 
   215 
   222 ---++ ObjectMethod *setEmails* <tt>($cUID,@emails)</tt>
   216 
   223 
   217 ---++ ObjectMethod *setEmails* <tt>($user,@emails)</tt>
   224 Set the email address(es) for the given user.
   218 
       
   219 Set the email address(es) for the given user. Does nothing by default.
       
   220 
   225 
   221 
   226 
   222 
   227 
   223 ---++ ObjectMethod *findUserByWikiName* <tt>($wikiname) -> listofcUIDsassociatedwiththatwikiname</tt>
   228 ---++ ObjectMethod *findUserByWikiName* <tt>($wikiname) -> listofcUIDsassociatedwiththatwikiname</tt>
   224 
   229    * =$wikiname= - wikiname to look up
   225 Called from TWiki::Users. See the documentation of the corresponding
   230 Return a list of canonical user names for the users that have this wikiname.
   226 method in that module for details.
   231 Since a single wikiname might be used by multiple login ids, we need a list.
   227 
   232 
   228 Subclasses *must* implement this method.
   233 Note that if $wikiname is the name of a group, the group will *not* be
   229 
   234 expanded.
   230 
   235 
   231 
   236 Subclasses *must* implement this method.
   232 ---++ ObjectMethod *checkPassword* <tt>($userName,$passwordU) -> $boolean</tt>
   237 
   233 
   238 
   234 Finds if the password is valid for the given user.
   239 
       
   240 ---++ ObjectMethod *checkPassword* <tt>($login,$passwordU) -> $boolean</tt>
       
   241 
       
   242 Finds if the password is valid for the given login. This is called using
       
   243 a login name rather than a cUID because the user may not have been mapped
       
   244 at the time it is called.
   235 
   245 
   236 Returns 1 on success, undef on failure.
   246 Returns 1 on success, undef on failure.
   237 
   247 
   238 Default behaviour is to return 1.
   248 Default behaviour is to return 1.
   239 
   249 
   240 
   250 
   241 
   251 
   242 ---++ ObjectMethod *setPassword* <tt>($user,$newPassU,$oldPassU) -> $boolean</tt>
   252 ---++ ObjectMethod *setPassword* <tt>($cUID,$newPassU,$oldPassU) -> $boolean</tt>
   243 
   253 
   244 If the $oldPassU matches matches the user's password, then it will
   254 If the $oldPassU matches matches the user's password, then it will
   245 replace it with $newPassU.
   255 replace it with $newPassU.
   246 
   256 
   247 If $oldPassU is not correct and not 1, will return 0.
   257 If $oldPassU is not correct and not 1, will return 0.
   258 ---++ ObjectMethod *passwordError* <tt>() -> $string</tt>
   268 ---++ ObjectMethod *passwordError* <tt>() -> $string</tt>
   259 
   269 
   260 Returns a string indicating the error that happened in the password handlers
   270 Returns a string indicating the error that happened in the password handlers
   261 TODO: these delayed errors should be replaced with Exceptions.
   271 TODO: these delayed errors should be replaced with Exceptions.
   262 
   272 
   263 returns undef if no error 9the default)
   273 returns undef if no error (the default)
   264 
   274 
   265 
   275 
   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