diff -r 000000000000 -r 414e01d06fd5 data/TWiki/TWikiUserMappingDotPm.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/data/TWiki/TWikiUserMappingDotPm.txt	Sat Jan 26 15:50:53 2008 +0100
@@ -0,0 +1,286 @@
+---+ Package =TWiki::UserMapping=
+
+This is a virtual base class (a.k.a an interface) for all user mappers. It is
+*not* useable as a mapping in TWiki - use the BaseUserMapping for default
+behaviour.
+
+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.
+
+See TWiki::Users::BaseUserMapping and TWiki::Users::TWikiUserMapping for
+the default implementations of this interface.
+
+If you want to write a user mapper, you will need to implement the methods
+described in this class.
+
+User mappings work by mapping both login names and display names to a
+_canonical user id_. This user id is composed from a prefix that defines
+the mapper in use (something like 'BaseUserMapping_' or 'LdapUserMapping_')
+and a unique user id that the mapper uses to identify the user.
+
+The null prefix is reserver for the TWikiUserMapping for compatibility
+with old TWiki releases.
+
+__Note:__ in all the following documentation, =$user= refers to a
+*canonical user id*.
+
+
+%TOC%
+
+---++ PROTECTED ClassMethod new ($session, $mapping_id)
+
+Construct a user mapping object, using the given mapping id.
+
+
+---++ ObjectMethod *finish* <tt>()</tt>
+Break circular references.
+
+
+
+---++ ObjectMethod *loginTemplateName* <tt>() -> $templateFile</tt>
+
+Allows UserMappings to come with customised login screens - that should
+preferably only over-ride the UI function
+
+Default is "login"
+
+
+
+---++ ObjectMethod *supportsRegistration* <tt>() -> $boolean</tt>
+
+Return true if the UserMapper supports registration (ie can create new users)
+
+Default is *false*
+
+
+
+---++ ObjectMethod *handlesUser* <tt>($cUID,$login,$wikiname) -> $boolean</tt>
+
+Called by the TWiki::Users object to determine which loaded mapping
+to use for a given user (must be fast).
+
+Default is *false*
+
+
+
+---++ ObjectMethod *getCanonicalUserID* <tt>($login,$dontcheck) -> cUID</tt>
+
+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)
+
+(if dontcheck is true, return a cUID for a nonexistant user too - used for registration)
+
+Subclasses *must* implement this method.
+
+
+
+
+---++ ObjectMethod *getLoginName* <tt>($cUID) -> login</tt>
+
+Converts an internal cUID to that user's login
+(undef on failure)
+
+Subclasses *must* implement this method.
+
+
+
+---++ ObjectMethod *addUser* <tt>($login,$wikiname,$password,$emails) -> cUID</tt>
+
+Add a user to the persistant mapping that maps from usernames to wikinames
+and vice-versa, via a *canonical user id* (cUID).
+
+$login and $wikiname must be acceptable to $TWiki::cfg{NameFilter}.
+$login must *always* be specified. $wikiname may be undef, in which case
+the user mapper should make one up.
+
+This function must return a canonical user id that it uses to uniquely
+identify the user. This can be the login name, or the wikiname if they
+are all guaranteed unigue, or some other string consisting only of 7-bit
+alphanumerics and underscores.
+
+If you fail to create a new user (for eg your Mapper has read only access),
+<pre>
+    throw Error::Simple('Failed to add user: '.$error);
+</pre>
+where $error is a descriptive string.
+
+Throws an Error::Simple if user adding is not supported (the default).
+
+
+
+---++ ObjectMethod *removeUser* <tt>($user) -> $boolean</tt>
+
+Delete the users entry from this mapper. Throws an Error::Simple if
+user removal is not supported (the default).
+
+
+
+---++ ObjectMethod *getWikiName* <tt>($cUID) -> wikiname</tt>
+
+Map a canonical user name to a wikiname.
+
+Returns the $cUID by default.
+
+
+
+---++ ObjectMethod *userExists* <tt>($cUID) -> $boolean</tt>
+
+Determine if the user already exists or not. Whether a user exists
+or not is determined by the password manager.
+
+Subclasses *must* implement this method.
+
+
+
+---++ ObjectMethod *eachUser* <tt>() -> listIteratorofcUIDs</tt>
+
+Called from TWiki::Users. See the documentation of the corresponding
+method in that module for details.
+
+Subclasses *must* implement this method.
+
+
+
+---++ ObjectMethod *eachGroupMember* <tt>($group) -> TWiki::ListIteratorofcUIDs</tt>
+
+Called from TWiki::Users. See the documentation of the corresponding
+method in that module for details.
+
+Subclasses *must* implement this method.
+
+
+
+---++ ObjectMethod *isGroup* <tt>($user) -> boolean</tt>
+
+Called from TWiki::Users. See the documentation of the corresponding
+method in that module for details.
+
+Subclasses *must* implement this method.
+
+
+
+---++ ObjectMethod *eachGroup* <tt>() -> ListIteratorofgroupnames</tt>
+
+Called from TWiki::Users. See the documentation of the corresponding
+method in that module for details.
+
+Subclasses *must* implement this method.
+
+
+
+---++ ObjectMethod *eachMembership* <tt>($cUID) -> ListIteratorofgroupsthisuserisin</tt>
+
+Called from TWiki::Users. See the documentation of the corresponding
+method in that module for details.
+
+Subclasses *must* implement this method.
+
+
+
+---++ ObjectMethod *isAdmin* <tt>($user) -> $boolean</tt>
+
+True if the user is an administrator. Default is *false*
+
+
+
+---++ ObjectMethod *isInGroup* <tt>($user,$group,$scanning) -> bool</tt>
+
+Called from TWiki::Users. See the documentation of the corresponding
+method in that module for details.
+
+Default is *false*
+
+
+
+---++ ObjectMethod *findUserByEmail* <tt>($email) -> \@users</tt>
+   * =$email= - email address to look up
+Return a list of canonical user names for the users that have this email
+registered with the password manager or the user mapping manager.
+
+Returns an empty list by default.
+
+
+
+---++ ObjectMethod *getEmails* <tt>($user) -> @emailAddress</tt>
+
+If this is a user, return their email addresses. If it is a group,
+return the addresses of everyone in the group.
+
+Duplicates should be removed from the list.
+
+By default, returns the empty list.
+
+
+
+---++ ObjectMethod *setEmails* <tt>($user,@emails)</tt>
+
+Set the email address(es) for the given user. Does nothing by default.
+
+
+
+---++ ObjectMethod *findUserByWikiName* <tt>($wikiname) -> listofcUIDsassociatedwiththatwikiname</tt>
+
+Called from TWiki::Users. See the documentation of the corresponding
+method in that module for details.
+
+Subclasses *must* implement this method.
+
+
+
+---++ ObjectMethod *checkPassword* <tt>($userName,$passwordU) -> $boolean</tt>
+
+Finds if the password is valid for the given user.
+
+Returns 1 on success, undef on failure.
+
+Default behaviour is to return 1.
+
+
+
+---++ ObjectMethod *setPassword* <tt>($user,$newPassU,$oldPassU) -> $boolean</tt>
+
+If the $oldPassU matches matches the user's password, then it will
+replace it with $newPassU.
+
+If $oldPassU is not correct and not 1, will return 0.
+
+If $oldPassU is 1, will force the change irrespective of
+the existing password, adding the user if necessary.
+
+Otherwise returns 1 on success, undef on failure.
+
+Default behaviour is to fail.
+
+
+
+---++ ObjectMethod *passwordError* <tt>() -> $string</tt>
+
+Returns a string indicating the error that happened in the password handlers
+TODO: these delayed errors should be replaced with Exceptions.
+
+returns undef if no error 9the default)
+
+
+
+---++ ObjectMethod *ASSERT_IS_CANONICAL_USER_ID* <tt>($user_id) -> $boolean</tt>
+
+Used for debugging to ensure we are actually passing a canonical_id
+
+
+
+---++ ObjectMethod *ASSERT_IS_USER_LOGIN_ID* <tt>($user_login) -> $boolean</tt>
+
+Used for debugging to ensure we are actually passing a user login
+
+
+
+---++ ObjectMethod *ASSERT_IS_USER_DISPLAY_NAME* <tt>($user_display) -> $boolean</tt>
+
+Used for debugging to ensure we are actually passing a user display_name
+(commonly a WikiWord Name)
+
+Returns true by default.
+
+