data/TWiki/TWikiUserMappingDotPm.txt
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
     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 +