1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/data/TWiki/TWikiUserMappingDotPm.txt Sat Jan 26 15:50:53 2008 +0100
1.3 @@ -0,0 +1,286 @@
1.4 +---+ Package =TWiki::UserMapping=
1.5 +
1.6 +This is a virtual base class (a.k.a an interface) for all user mappers. It is
1.7 +*not* useable as a mapping in TWiki - use the BaseUserMapping for default
1.8 +behaviour.
1.9 +
1.10 +User mapping is the process by which TWiki maps from a username (a login name)
1.11 +to a display name and back. It is also where groups are maintained.
1.12 +
1.13 +See TWiki::Users::BaseUserMapping and TWiki::Users::TWikiUserMapping for
1.14 +the default implementations of this interface.
1.15 +
1.16 +If you want to write a user mapper, you will need to implement the methods
1.17 +described in this class.
1.18 +
1.19 +User mappings work by mapping both login names and display names to a
1.20 +_canonical user id_. This user id is composed from a prefix that defines
1.21 +the mapper in use (something like 'BaseUserMapping_' or 'LdapUserMapping_')
1.22 +and a unique user id that the mapper uses to identify the user.
1.23 +
1.24 +The null prefix is reserver for the TWikiUserMapping for compatibility
1.25 +with old TWiki releases.
1.26 +
1.27 +__Note:__ in all the following documentation, =$user= refers to a
1.28 +*canonical user id*.
1.29 +
1.30 +
1.31 +%TOC%
1.32 +
1.33 +---++ PROTECTED ClassMethod new ($session, $mapping_id)
1.34 +
1.35 +Construct a user mapping object, using the given mapping id.
1.36 +
1.37 +
1.38 +---++ ObjectMethod *finish* <tt>()</tt>
1.39 +Break circular references.
1.40 +
1.41 +
1.42 +
1.43 +---++ ObjectMethod *loginTemplateName* <tt>() -> $templateFile</tt>
1.44 +
1.45 +Allows UserMappings to come with customised login screens - that should
1.46 +preferably only over-ride the UI function
1.47 +
1.48 +Default is "login"
1.49 +
1.50 +
1.51 +
1.52 +---++ ObjectMethod *supportsRegistration* <tt>() -> $boolean</tt>
1.53 +
1.54 +Return true if the UserMapper supports registration (ie can create new users)
1.55 +
1.56 +Default is *false*
1.57 +
1.58 +
1.59 +
1.60 +---++ ObjectMethod *handlesUser* <tt>($cUID,$login,$wikiname) -> $boolean</tt>
1.61 +
1.62 +Called by the TWiki::Users object to determine which loaded mapping
1.63 +to use for a given user (must be fast).
1.64 +
1.65 +Default is *false*
1.66 +
1.67 +
1.68 +
1.69 +---++ ObjectMethod *getCanonicalUserID* <tt>($login,$dontcheck) -> cUID</tt>
1.70 +
1.71 +Convert a login name to the corresponding canonical user name. The
1.72 +canonical name can be any string of 7-bit alphanumeric and underscore
1.73 +characters, and must correspond 1:1 to the login name.
1.74 +(undef on failure)
1.75 +
1.76 +(if dontcheck is true, return a cUID for a nonexistant user too - used for registration)
1.77 +
1.78 +Subclasses *must* implement this method.
1.79 +
1.80 +
1.81 +
1.82 +
1.83 +---++ ObjectMethod *getLoginName* <tt>($cUID) -> login</tt>
1.84 +
1.85 +Converts an internal cUID to that user's login
1.86 +(undef on failure)
1.87 +
1.88 +Subclasses *must* implement this method.
1.89 +
1.90 +
1.91 +
1.92 +---++ ObjectMethod *addUser* <tt>($login,$wikiname,$password,$emails) -> cUID</tt>
1.93 +
1.94 +Add a user to the persistant mapping that maps from usernames to wikinames
1.95 +and vice-versa, via a *canonical user id* (cUID).
1.96 +
1.97 +$login and $wikiname must be acceptable to $TWiki::cfg{NameFilter}.
1.98 +$login must *always* be specified. $wikiname may be undef, in which case
1.99 +the user mapper should make one up.
1.100 +
1.101 +This function must return a canonical user id that it uses to uniquely
1.102 +identify the user. This can be the login name, or the wikiname if they
1.103 +are all guaranteed unigue, or some other string consisting only of 7-bit
1.104 +alphanumerics and underscores.
1.105 +
1.106 +If you fail to create a new user (for eg your Mapper has read only access),
1.107 +<pre>
1.108 + throw Error::Simple('Failed to add user: '.$error);
1.109 +</pre>
1.110 +where $error is a descriptive string.
1.111 +
1.112 +Throws an Error::Simple if user adding is not supported (the default).
1.113 +
1.114 +
1.115 +
1.116 +---++ ObjectMethod *removeUser* <tt>($user) -> $boolean</tt>
1.117 +
1.118 +Delete the users entry from this mapper. Throws an Error::Simple if
1.119 +user removal is not supported (the default).
1.120 +
1.121 +
1.122 +
1.123 +---++ ObjectMethod *getWikiName* <tt>($cUID) -> wikiname</tt>
1.124 +
1.125 +Map a canonical user name to a wikiname.
1.126 +
1.127 +Returns the $cUID by default.
1.128 +
1.129 +
1.130 +
1.131 +---++ ObjectMethod *userExists* <tt>($cUID) -> $boolean</tt>
1.132 +
1.133 +Determine if the user already exists or not. Whether a user exists
1.134 +or not is determined by the password manager.
1.135 +
1.136 +Subclasses *must* implement this method.
1.137 +
1.138 +
1.139 +
1.140 +---++ ObjectMethod *eachUser* <tt>() -> listIteratorofcUIDs</tt>
1.141 +
1.142 +Called from TWiki::Users. See the documentation of the corresponding
1.143 +method in that module for details.
1.144 +
1.145 +Subclasses *must* implement this method.
1.146 +
1.147 +
1.148 +
1.149 +---++ ObjectMethod *eachGroupMember* <tt>($group) -> TWiki::ListIteratorofcUIDs</tt>
1.150 +
1.151 +Called from TWiki::Users. See the documentation of the corresponding
1.152 +method in that module for details.
1.153 +
1.154 +Subclasses *must* implement this method.
1.155 +
1.156 +
1.157 +
1.158 +---++ ObjectMethod *isGroup* <tt>($user) -> boolean</tt>
1.159 +
1.160 +Called from TWiki::Users. See the documentation of the corresponding
1.161 +method in that module for details.
1.162 +
1.163 +Subclasses *must* implement this method.
1.164 +
1.165 +
1.166 +
1.167 +---++ ObjectMethod *eachGroup* <tt>() -> ListIteratorofgroupnames</tt>
1.168 +
1.169 +Called from TWiki::Users. See the documentation of the corresponding
1.170 +method in that module for details.
1.171 +
1.172 +Subclasses *must* implement this method.
1.173 +
1.174 +
1.175 +
1.176 +---++ ObjectMethod *eachMembership* <tt>($cUID) -> ListIteratorofgroupsthisuserisin</tt>
1.177 +
1.178 +Called from TWiki::Users. See the documentation of the corresponding
1.179 +method in that module for details.
1.180 +
1.181 +Subclasses *must* implement this method.
1.182 +
1.183 +
1.184 +
1.185 +---++ ObjectMethod *isAdmin* <tt>($user) -> $boolean</tt>
1.186 +
1.187 +True if the user is an administrator. Default is *false*
1.188 +
1.189 +
1.190 +
1.191 +---++ ObjectMethod *isInGroup* <tt>($user,$group,$scanning) -> bool</tt>
1.192 +
1.193 +Called from TWiki::Users. See the documentation of the corresponding
1.194 +method in that module for details.
1.195 +
1.196 +Default is *false*
1.197 +
1.198 +
1.199 +
1.200 +---++ ObjectMethod *findUserByEmail* <tt>($email) -> \@users</tt>
1.201 + * =$email= - email address to look up
1.202 +Return a list of canonical user names for the users that have this email
1.203 +registered with the password manager or the user mapping manager.
1.204 +
1.205 +Returns an empty list by default.
1.206 +
1.207 +
1.208 +
1.209 +---++ ObjectMethod *getEmails* <tt>($user) -> @emailAddress</tt>
1.210 +
1.211 +If this is a user, return their email addresses. If it is a group,
1.212 +return the addresses of everyone in the group.
1.213 +
1.214 +Duplicates should be removed from the list.
1.215 +
1.216 +By default, returns the empty list.
1.217 +
1.218 +
1.219 +
1.220 +---++ ObjectMethod *setEmails* <tt>($user,@emails)</tt>
1.221 +
1.222 +Set the email address(es) for the given user. Does nothing by default.
1.223 +
1.224 +
1.225 +
1.226 +---++ ObjectMethod *findUserByWikiName* <tt>($wikiname) -> listofcUIDsassociatedwiththatwikiname</tt>
1.227 +
1.228 +Called from TWiki::Users. See the documentation of the corresponding
1.229 +method in that module for details.
1.230 +
1.231 +Subclasses *must* implement this method.
1.232 +
1.233 +
1.234 +
1.235 +---++ ObjectMethod *checkPassword* <tt>($userName,$passwordU) -> $boolean</tt>
1.236 +
1.237 +Finds if the password is valid for the given user.
1.238 +
1.239 +Returns 1 on success, undef on failure.
1.240 +
1.241 +Default behaviour is to return 1.
1.242 +
1.243 +
1.244 +
1.245 +---++ ObjectMethod *setPassword* <tt>($user,$newPassU,$oldPassU) -> $boolean</tt>
1.246 +
1.247 +If the $oldPassU matches matches the user's password, then it will
1.248 +replace it with $newPassU.
1.249 +
1.250 +If $oldPassU is not correct and not 1, will return 0.
1.251 +
1.252 +If $oldPassU is 1, will force the change irrespective of
1.253 +the existing password, adding the user if necessary.
1.254 +
1.255 +Otherwise returns 1 on success, undef on failure.
1.256 +
1.257 +Default behaviour is to fail.
1.258 +
1.259 +
1.260 +
1.261 +---++ ObjectMethod *passwordError* <tt>() -> $string</tt>
1.262 +
1.263 +Returns a string indicating the error that happened in the password handlers
1.264 +TODO: these delayed errors should be replaced with Exceptions.
1.265 +
1.266 +returns undef if no error 9the default)
1.267 +
1.268 +
1.269 +
1.270 +---++ ObjectMethod *ASSERT_IS_CANONICAL_USER_ID* <tt>($user_id) -> $boolean</tt>
1.271 +
1.272 +Used for debugging to ensure we are actually passing a canonical_id
1.273 +
1.274 +
1.275 +
1.276 +---++ ObjectMethod *ASSERT_IS_USER_LOGIN_ID* <tt>($user_login) -> $boolean</tt>
1.277 +
1.278 +Used for debugging to ensure we are actually passing a user login
1.279 +
1.280 +
1.281 +
1.282 +---++ ObjectMethod *ASSERT_IS_USER_DISPLAY_NAME* <tt>($user_display) -> $boolean</tt>
1.283 +
1.284 +Used for debugging to ensure we are actually passing a user display_name
1.285 +(commonly a WikiWord Name)
1.286 +
1.287 +Returns true by default.
1.288 +
1.289 +