data/TWiki/TWikiUserMappingDotPm.txt
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
equal deleted inserted replaced
-1:000000000000 0:414e01d06fd5
       
     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