data/TWiki/TWikiUserMappingDotPm.txt,v
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
permissions -rw-r--r--
RELEASE 4.2.0 freetown
colas@0
     1
head	1.1;
colas@0
     2
access;
colas@0
     3
symbols;
colas@0
     4
locks; strict;
colas@0
     5
comment	@# @;
colas@0
     6
colas@0
     7
colas@0
     8
1.1
colas@0
     9
date	2008.01.22.03.21.24;	author TWikiContributor;	state Exp;
colas@0
    10
branches;
colas@0
    11
next	;
colas@0
    12
colas@0
    13
colas@0
    14
desc
colas@0
    15
@buildrelease
colas@0
    16
@
colas@0
    17
colas@0
    18
colas@0
    19
1.1
colas@0
    20
log
colas@0
    21
@buildrelease
colas@0
    22
@
colas@0
    23
text
colas@0
    24
@---+ Package =TWiki::UserMapping=
colas@0
    25
colas@0
    26
This is a virtual base class (a.k.a an interface) for all user mappers. It is
colas@0
    27
*not* useable as a mapping in TWiki - use the BaseUserMapping for default
colas@0
    28
behaviour.
colas@0
    29
colas@0
    30
User mapping is the process by which TWiki maps from a username (a login name)
colas@0
    31
to a display name and back. It is also where groups are maintained.
colas@0
    32
colas@0
    33
See TWiki::Users::BaseUserMapping and TWiki::Users::TWikiUserMapping for
colas@0
    34
the default implementations of this interface.
colas@0
    35
colas@0
    36
If you want to write a user mapper, you will need to implement the methods
colas@0
    37
described in this class.
colas@0
    38
colas@0
    39
User mappings work by mapping both login names and display names to a
colas@0
    40
_canonical user id_. This user id is composed from a prefix that defines
colas@0
    41
the mapper in use (something like 'BaseUserMapping_' or 'LdapUserMapping_')
colas@0
    42
and a unique user id that the mapper uses to identify the user.
colas@0
    43
colas@0
    44
The null prefix is reserver for the TWikiUserMapping for compatibility
colas@0
    45
with old TWiki releases.
colas@0
    46
colas@0
    47
__Note:__ in all the following documentation, =$user= refers to a
colas@0
    48
*canonical user id*.
colas@0
    49
colas@0
    50
colas@0
    51
%TOC%
colas@0
    52
colas@0
    53
---++ PROTECTED ClassMethod new ($session, $mapping_id)
colas@0
    54
colas@0
    55
Construct a user mapping object, using the given mapping id.
colas@0
    56
colas@0
    57
colas@0
    58
---++ ObjectMethod *finish* <tt>()</tt>
colas@0
    59
Break circular references.
colas@0
    60
colas@0
    61
colas@0
    62
colas@0
    63
---++ ObjectMethod *loginTemplateName* <tt>() -> $templateFile</tt>
colas@0
    64
colas@0
    65
Allows UserMappings to come with customised login screens - that should
colas@0
    66
preferably only over-ride the UI function
colas@0
    67
colas@0
    68
Default is "login"
colas@0
    69
colas@0
    70
colas@0
    71
colas@0
    72
---++ ObjectMethod *supportsRegistration* <tt>() -> $boolean</tt>
colas@0
    73
colas@0
    74
Return true if the UserMapper supports registration (ie can create new users)
colas@0
    75
colas@0
    76
Default is *false*
colas@0
    77
colas@0
    78
colas@0
    79
colas@0
    80
---++ ObjectMethod *handlesUser* <tt>($cUID,$login,$wikiname) -> $boolean</tt>
colas@0
    81
colas@0
    82
Called by the TWiki::Users object to determine which loaded mapping
colas@0
    83
to use for a given user (must be fast).
colas@0
    84
colas@0
    85
Default is *false*
colas@0
    86
colas@0
    87
colas@0
    88
colas@0
    89
---++ ObjectMethod *getCanonicalUserID* <tt>($login,$dontcheck) -> cUID</tt>
colas@0
    90
colas@0
    91
Convert a login name to the corresponding canonical user name. The
colas@0
    92
canonical name can be any string of 7-bit alphanumeric and underscore
colas@0
    93
characters, and must correspond 1:1 to the login name.
colas@0
    94
(undef on failure)
colas@0
    95
colas@0
    96
(if dontcheck is true, return a cUID for a nonexistant user too - used for registration)
colas@0
    97
colas@0
    98
Subclasses *must* implement this method.
colas@0
    99
colas@0
   100
colas@0
   101
colas@0
   102
colas@0
   103
---++ ObjectMethod *getLoginName* <tt>($cUID) -> login</tt>
colas@0
   104
colas@0
   105
Converts an internal cUID to that user's login
colas@0
   106
(undef on failure)
colas@0
   107
colas@0
   108
Subclasses *must* implement this method.
colas@0
   109
colas@0
   110
colas@0
   111
colas@0
   112
---++ ObjectMethod *addUser* <tt>($login,$wikiname,$password,$emails) -> cUID</tt>
colas@0
   113
colas@0
   114
Add a user to the persistant mapping that maps from usernames to wikinames
colas@0
   115
and vice-versa, via a *canonical user id* (cUID).
colas@0
   116
colas@0
   117
$login and $wikiname must be acceptable to $TWiki::cfg{NameFilter}.
colas@0
   118
$login must *always* be specified. $wikiname may be undef, in which case
colas@0
   119
the user mapper should make one up.
colas@0
   120
colas@0
   121
This function must return a canonical user id that it uses to uniquely
colas@0
   122
identify the user. This can be the login name, or the wikiname if they
colas@0
   123
are all guaranteed unigue, or some other string consisting only of 7-bit
colas@0
   124
alphanumerics and underscores.
colas@0
   125
colas@0
   126
If you fail to create a new user (for eg your Mapper has read only access),
colas@0
   127
<pre>
colas@0
   128
    throw Error::Simple('Failed to add user: '.$error);
colas@0
   129
</pre>
colas@0
   130
where $error is a descriptive string.
colas@0
   131
colas@0
   132
Throws an Error::Simple if user adding is not supported (the default).
colas@0
   133
colas@0
   134
colas@0
   135
colas@0
   136
---++ ObjectMethod *removeUser* <tt>($user) -> $boolean</tt>
colas@0
   137
colas@0
   138
Delete the users entry from this mapper. Throws an Error::Simple if
colas@0
   139
user removal is not supported (the default).
colas@0
   140
colas@0
   141
colas@0
   142
colas@0
   143
---++ ObjectMethod *getWikiName* <tt>($cUID) -> wikiname</tt>
colas@0
   144
colas@0
   145
Map a canonical user name to a wikiname.
colas@0
   146
colas@0
   147
Returns the $cUID by default.
colas@0
   148
colas@0
   149
colas@0
   150
colas@0
   151
---++ ObjectMethod *userExists* <tt>($cUID) -> $boolean</tt>
colas@0
   152
colas@0
   153
Determine if the user already exists or not. Whether a user exists
colas@0
   154
or not is determined by the password manager.
colas@0
   155
colas@0
   156
Subclasses *must* implement this method.
colas@0
   157
colas@0
   158
colas@0
   159
colas@0
   160
---++ ObjectMethod *eachUser* <tt>() -> listIteratorofcUIDs</tt>
colas@0
   161
colas@0
   162
Called from TWiki::Users. See the documentation of the corresponding
colas@0
   163
method in that module for details.
colas@0
   164
colas@0
   165
Subclasses *must* implement this method.
colas@0
   166
colas@0
   167
colas@0
   168
colas@0
   169
---++ ObjectMethod *eachGroupMember* <tt>($group) -> TWiki::ListIteratorofcUIDs</tt>
colas@0
   170
colas@0
   171
Called from TWiki::Users. See the documentation of the corresponding
colas@0
   172
method in that module for details.
colas@0
   173
colas@0
   174
Subclasses *must* implement this method.
colas@0
   175
colas@0
   176
colas@0
   177
colas@0
   178
---++ ObjectMethod *isGroup* <tt>($user) -> boolean</tt>
colas@0
   179
colas@0
   180
Called from TWiki::Users. See the documentation of the corresponding
colas@0
   181
method in that module for details.
colas@0
   182
colas@0
   183
Subclasses *must* implement this method.
colas@0
   184
colas@0
   185
colas@0
   186
colas@0
   187
---++ ObjectMethod *eachGroup* <tt>() -> ListIteratorofgroupnames</tt>
colas@0
   188
colas@0
   189
Called from TWiki::Users. See the documentation of the corresponding
colas@0
   190
method in that module for details.
colas@0
   191
colas@0
   192
Subclasses *must* implement this method.
colas@0
   193
colas@0
   194
colas@0
   195
colas@0
   196
---++ ObjectMethod *eachMembership* <tt>($cUID) -> ListIteratorofgroupsthisuserisin</tt>
colas@0
   197
colas@0
   198
Called from TWiki::Users. See the documentation of the corresponding
colas@0
   199
method in that module for details.
colas@0
   200
colas@0
   201
Subclasses *must* implement this method.
colas@0
   202
colas@0
   203
colas@0
   204
colas@0
   205
---++ ObjectMethod *isAdmin* <tt>($user) -> $boolean</tt>
colas@0
   206
colas@0
   207
True if the user is an administrator. Default is *false*
colas@0
   208
colas@0
   209
colas@0
   210
colas@0
   211
---++ ObjectMethod *isInGroup* <tt>($user,$group,$scanning) -> bool</tt>
colas@0
   212
colas@0
   213
Called from TWiki::Users. See the documentation of the corresponding
colas@0
   214
method in that module for details.
colas@0
   215
colas@0
   216
Default is *false*
colas@0
   217
colas@0
   218
colas@0
   219
colas@0
   220
---++ ObjectMethod *findUserByEmail* <tt>($email) -> \@@users</tt>
colas@0
   221
   * =$email= - email address to look up
colas@0
   222
Return a list of canonical user names for the users that have this email
colas@0
   223
registered with the password manager or the user mapping manager.
colas@0
   224
colas@0
   225
Returns an empty list by default.
colas@0
   226
colas@0
   227
colas@0
   228
colas@0
   229
---++ ObjectMethod *getEmails* <tt>($user) -> @@emailAddress</tt>
colas@0
   230
colas@0
   231
If this is a user, return their email addresses. If it is a group,
colas@0
   232
return the addresses of everyone in the group.
colas@0
   233
colas@0
   234
Duplicates should be removed from the list.
colas@0
   235
colas@0
   236
By default, returns the empty list.
colas@0
   237
colas@0
   238
colas@0
   239
colas@0
   240
---++ ObjectMethod *setEmails* <tt>($user,@@emails)</tt>
colas@0
   241
colas@0
   242
Set the email address(es) for the given user. Does nothing by default.
colas@0
   243
colas@0
   244
colas@0
   245
colas@0
   246
---++ ObjectMethod *findUserByWikiName* <tt>($wikiname) -> listofcUIDsassociatedwiththatwikiname</tt>
colas@0
   247
colas@0
   248
Called from TWiki::Users. See the documentation of the corresponding
colas@0
   249
method in that module for details.
colas@0
   250
colas@0
   251
Subclasses *must* implement this method.
colas@0
   252
colas@0
   253
colas@0
   254
colas@0
   255
---++ ObjectMethod *checkPassword* <tt>($userName,$passwordU) -> $boolean</tt>
colas@0
   256
colas@0
   257
Finds if the password is valid for the given user.
colas@0
   258
colas@0
   259
Returns 1 on success, undef on failure.
colas@0
   260
colas@0
   261
Default behaviour is to return 1.
colas@0
   262
colas@0
   263
colas@0
   264
colas@0
   265
---++ ObjectMethod *setPassword* <tt>($user,$newPassU,$oldPassU) -> $boolean</tt>
colas@0
   266
colas@0
   267
If the $oldPassU matches matches the user's password, then it will
colas@0
   268
replace it with $newPassU.
colas@0
   269
colas@0
   270
If $oldPassU is not correct and not 1, will return 0.
colas@0
   271
colas@0
   272
If $oldPassU is 1, will force the change irrespective of
colas@0
   273
the existing password, adding the user if necessary.
colas@0
   274
colas@0
   275
Otherwise returns 1 on success, undef on failure.
colas@0
   276
colas@0
   277
Default behaviour is to fail.
colas@0
   278
colas@0
   279
colas@0
   280
colas@0
   281
---++ ObjectMethod *passwordError* <tt>() -> $string</tt>
colas@0
   282
colas@0
   283
Returns a string indicating the error that happened in the password handlers
colas@0
   284
TODO: these delayed errors should be replaced with Exceptions.
colas@0
   285
colas@0
   286
returns undef if no error 9the default)
colas@0
   287
colas@0
   288
colas@0
   289
colas@0
   290
---++ ObjectMethod *ASSERT_IS_CANONICAL_USER_ID* <tt>($user_id) -> $boolean</tt>
colas@0
   291
colas@0
   292
Used for debugging to ensure we are actually passing a canonical_id
colas@0
   293
colas@0
   294
colas@0
   295
colas@0
   296
---++ ObjectMethod *ASSERT_IS_USER_LOGIN_ID* <tt>($user_login) -> $boolean</tt>
colas@0
   297
colas@0
   298
Used for debugging to ensure we are actually passing a user login
colas@0
   299
colas@0
   300
colas@0
   301
colas@0
   302
---++ ObjectMethod *ASSERT_IS_USER_DISPLAY_NAME* <tt>($user_display) -> $boolean</tt>
colas@0
   303
colas@0
   304
Used for debugging to ensure we are actually passing a user display_name
colas@0
   305
(commonly a WikiWord Name)
colas@0
   306
colas@0
   307
Returns true by default.
colas@0
   308
colas@0
   309
colas@0
   310
@