Difference: TWikiUserMappingDotPm (1 vs. 3)

Revision 32011-08-21 - TWikiContributor

Line: 93 to 93
 
Changed:
<
<

ObjectMethod addUser ($login,$wikiname,$password,$emails) -> $cUID

>
>

ObjectMethod addUser ($login,$wikiname,$password,$emails,$mcp) -> $cUID

  Add a user to the persistant mapping that maps from usernames to wikinames and vice-versa.
Line: 225 to 225
 
Added:
>
>

ObjectMethod *getMustChangePassword ($cUID) -> $flag

Returns 1 if the $cUID must change the password, else 0. Returns undef if $cUID not found.

ObjectMethod getUserData ($cUID) -> $dataRef

Return a reference to an array of hashes with user data, used to manage users. Each item is a hash with:

  • {name} - name of field, such as "email"
  • {title} - title of field, such as "E-mail"
  • {value} - value of field, such as "jimmy@example.com"
  • {type} - type of field: text, password, checkbox, label
  • {size} - size of field, such as 40
  • {note} - comment note, if any

User management forms can be build dynamically from this data structure. Each password manager may return a different set of fields.

ObjectMethod setUserData ($cUID,$dataRef)

Set the user data of a user. Same array of hashes as getUserData is assumed, although only {name} and {value} are used.

 

ObjectMethod *findUserByWikiName ($wikiname) -> listofcUIDsassociatedwiththatwikiname

  • $wikiname - wikiname to look up
Return a list of canonical user names for the users that have this wikiname.

Revision 22008-08-03 - TWikiContributor

Line: 21 to 21
 The null prefix is reserver for the TWikiUserMapping for compatibility with old TWiki releases.
Changed:
<
<
Note: in all the following documentation, $user refers to a
>
>
Note: in all the following documentation, $cUID refers to a
 canonical user id.
Line: 59 to 59
 Called by the TWiki::Users object to determine which loaded mapping to use for a given user (must be fast).
Changed:
<
<
Default is false
>
>
The user can be identified by any of $cUID, $login or $wikiname. Any of these parameters may be undef, and they should be tested in order; cUID first, then login, then wikiname.
 
Changed:
<
<

ObjectMethod *getCanonicalUserID ($login,$dontcheck) -> cUID

>
>

ObjectMethod login2cUID ($login,$dontcheck) -> cUID

  Convert a login name to the corresponding canonical user name. The canonical name can be any string of 7-bit alphanumeric and underscore
Changed:
<
<
characters, and must correspond 1:1 to the login name.
>
>
characters, and must map 1:1 to the login name.
 (undef on failure)
Changed:
<
<
(if dontcheck is true, return a cUID for a nonexistant user too - used for registration)
>
>
(if $dontcheck is true, return a cUID for a nonexistant user too. This is used for registration)
  Subclasses must implement this method.
Added:
>
>
Note: This method was previously (in TWiki 4.2.0) known as getCanonicalUserID. The name was changed to avoid confusion with TWiki::Users::getCanonicalUserID, which has a more generic function. However to support older user mappers, getCanonicalUserID will still be called if login2cUID is not defined.
 
Line: 86 to 93
 
Changed:
<
<

ObjectMethod addUser ($login,$wikiname,$password,$emails) -> cUID

>
>

ObjectMethod addUser ($login,$wikiname,$password,$emails) -> $cUID

  Add a user to the persistant mapping that maps from usernames to wikinames
Changed:
<
<
and vice-versa, via a canonical user id (cUID).
>
>
and vice-versa.
  $login and $wikiname must be acceptable to $TWiki::cfg{NameFilter}. $login must always be specified. $wikiname may be undef, in which case
Line: 110 to 117
 
Changed:
<
<

ObjectMethod removeUser ($user) -> $boolean

>
>

ObjectMethod removeUser ($cUID) -> $boolean

  Delete the users entry from this mapper. Throws an Error::Simple if user removal is not supported (the default).

Changed:
<
<

ObjectMethod getWikiName ($cUID) -> wikiname

>
>

ObjectMethod getWikiName ($cUID) -> $wikiname

  Map a canonical user name to a wikiname.
Line: 134 to 141
 
Changed:
<
<

ObjectMethod eachUser () -> listIteratorofcUIDs

>
>

ObjectMethod eachUser () -> TWiki::ListIteratorofcUIDs

 
Changed:
<
<
Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
>
>
Get an iterator over the list of all the registered users not including groups.
  Subclasses must implement this method.
Line: 145 to 152
 

ObjectMethod *eachGroupMember ($group) -> TWiki::ListIteratorofcUIDs

Changed:
<
<
Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
>
>
Return a iterator over the canonical user ids of users that are members of this group. Should only be called on groups.

Note that groups may be defined recursively, so a group may contain other groups. This method should only return users i.e. all contained groups should be fully expanded.

  Subclasses must implement this method.

Changed:
<
<

ObjectMethod isGroup ($user) -> boolean

>
>

ObjectMethod isGroup ($name) -> boolean

 
Changed:
<
<
Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
>
>
Establish if a user refers to a group or not. If $name is not a group name it will probably be a canonical user id, though that should not be assumed.
  Subclasses must implement this method.

Changed:
<
<

ObjectMethod eachGroup () -> ListIteratorofgroupnames

>
>

ObjectMethod eachGroup () -> TWiki::ListIteratorofgroupnames

 
Changed:
<
<
Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
>
>
Get an iterator over the list of all the groups.
  Subclasses must implement this method.

Changed:
<
<

ObjectMethod eachMembership ($cUID) -> ListIteratorofgroupsthisuserisin

>
>

ObjectMethod eachMembership ($cUID) -> TWiki::ListIteratorofgroupsthisuserisin

 
Changed:
<
<
Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
>
>
Return an iterator over the names of groups that $cUID is a member of.
  Subclasses must implement this method.

Changed:
<
<

ObjectMethod isAdmin ($user) -> $boolean

>
>

ObjectMethod isAdmin ($cUID) -> $boolean

 
Changed:
<
<
True if the user is an administrator. Default is false
>
>
True if the user is an administrator.
 
Changed:
<
<

ObjectMethod isInGroup ($user,$group,$scanning) -> bool

>
>

ObjectMethod isInGroup ($cUID,$group) -> $bool

 
Changed:
<
<
Called from TWiki::Users. See the documentation of the corresponding method in that module for details.

Default is false

>
>
Test if the user identified by $cUID is in the given group. The default implementation iterates over all the members of $group, which is rather inefficient.
 
Line: 199 to 208
 Return a list of canonical user names for the users that have this email registered with the password manager or the user mapping manager.
Deleted:
<
<
Returns an empty list by default.
 
Changed:
<
<

ObjectMethod getEmails ($user) -> @emailAddress

>
>

ObjectMethod getEmails ($name) -> @emailAddress

 
Changed:
<
<
If this is a user, return their email addresses. If it is a group,
>
>
If $name is a cUID, return that user's email addresses. If it is a group,
 return the addresses of everyone in the group.

Duplicates should be removed from the list.

Deleted:
<
<
By default, returns the empty list.
 
Added:
>
>

ObjectMethod setEmails ($cUID,@emails)

 
Changed:
<
<

ObjectMethod setEmails ($user,@emails)

Set the email address(es) for the given user. Does nothing by default.

>
>
Set the email address(es) for the given user.
 

ObjectMethod *findUserByWikiName ($wikiname) -> listofcUIDsassociatedwiththatwikiname

Added:
>
>
  • $wikiname - wikiname to look up
Return a list of canonical user names for the users that have this wikiname. Since a single wikiname might be used by multiple login ids, we need a list.
 
Changed:
<
<
Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
>
>
Note that if $wikiname is the name of a group, the group will not be expanded.
  Subclasses must implement this method.

Changed:
<
<

ObjectMethod checkPassword ($userName,$passwordU) -> $boolean

>
>

ObjectMethod checkPassword ($login,$passwordU) -> $boolean

 
Changed:
<
<
Finds if the password is valid for the given user.
>
>
Finds if the password is valid for the given login. This is called using a login name rather than a cUID because the user may not have been mapped at the time it is called.
  Returns 1 on success, undef on failure.
Line: 239 to 249
 
Changed:
<
<

ObjectMethod setPassword ($user,$newPassU,$oldPassU) -> $boolean

>
>

ObjectMethod setPassword ($cUID,$newPassU,$oldPassU) -> $boolean

  If the $oldPassU matches matches the user's password, then it will replace it with $newPassU.
Line: 260 to 270
 Returns a string indicating the error that happened in the password handlers TODO: these delayed errors should be replaced with Exceptions.
Changed:
<
<
returns undef if no error 9the default)

ObjectMethod *ASSERT_IS_CANONICAL_USER_ID ($user_id) -> $boolean

Used for debugging to ensure we are actually passing a canonical_id

ObjectMethod *ASSERT_IS_USER_LOGIN_ID ($user_login) -> $boolean

Used for debugging to ensure we are actually passing a user login

ObjectMethod *ASSERT_IS_USER_DISPLAY_NAME ($user_display) -> $boolean

Used for debugging to ensure we are actually passing a user display_name (commonly a WikiWord Name)

Returns true by default.

>
>
returns undef if no error (the default)
 

Revision 12008-01-22 - TWikiContributor

Line: 1 to 1
Added:
>
>

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.

PROTECTED ClassMethod new ($session, $mapping_id)

Construct a user mapping object, using the given mapping id.

ObjectMethod finish ()

Break circular references.

ObjectMethod *loginTemplateName () -> $templateFile

Allows UserMappings to come with customised login screens - that should preferably only over-ride the UI function

Default is "login"

ObjectMethod *supportsRegistration () -> $boolean

Return true if the UserMapper supports registration (ie can create new users)

Default is false

ObjectMethod handlesUser ($cUID,$login,$wikiname) -> $boolean

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 ($login,$dontcheck) -> cUID

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 ($cUID) -> login

Converts an internal cUID to that user's login (undef on failure)

Subclasses must implement this method.

ObjectMethod addUser ($login,$wikiname,$password,$emails) -> cUID

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),

    throw Error::Simple('Failed to add user: '.$error);
where $error is a descriptive string.

Throws an Error::Simple if user adding is not supported (the default).

ObjectMethod removeUser ($user) -> $boolean

Delete the users entry from this mapper. Throws an Error::Simple if user removal is not supported (the default).

ObjectMethod getWikiName ($cUID) -> wikiname

Map a canonical user name to a wikiname.

Returns the $cUID by default.

ObjectMethod userExists ($cUID) -> $boolean

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 () -> listIteratorofcUIDs

Called from TWiki::Users. See the documentation of the corresponding method in that module for details.

Subclasses must implement this method.

ObjectMethod *eachGroupMember ($group) -> TWiki::ListIteratorofcUIDs

Called from TWiki::Users. See the documentation of the corresponding method in that module for details.

Subclasses must implement this method.

ObjectMethod isGroup ($user) -> boolean

Called from TWiki::Users. See the documentation of the corresponding method in that module for details.

Subclasses must implement this method.

ObjectMethod eachGroup () -> ListIteratorofgroupnames

Called from TWiki::Users. See the documentation of the corresponding method in that module for details.

Subclasses must implement this method.

ObjectMethod eachMembership ($cUID) -> ListIteratorofgroupsthisuserisin

Called from TWiki::Users. See the documentation of the corresponding method in that module for details.

Subclasses must implement this method.

ObjectMethod isAdmin ($user) -> $boolean

True if the user is an administrator. Default is false

ObjectMethod isInGroup ($user,$group,$scanning) -> bool

Called from TWiki::Users. See the documentation of the corresponding method in that module for details.

Default is false

ObjectMethod *findUserByEmail ($email) -> \@users

  • $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 ($user) -> @emailAddress

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 ($user,@emails)

Set the email address(es) for the given user. Does nothing by default.

ObjectMethod *findUserByWikiName ($wikiname) -> listofcUIDsassociatedwiththatwikiname

Called from TWiki::Users. See the documentation of the corresponding method in that module for details.

Subclasses must implement this method.

ObjectMethod checkPassword ($userName,$passwordU) -> $boolean

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 ($user,$newPassU,$oldPassU) -> $boolean

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 () -> $string

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 ($user_id) -> $boolean

Used for debugging to ensure we are actually passing a canonical_id

ObjectMethod *ASSERT_IS_USER_LOGIN_ID ($user_login) -> $boolean

Used for debugging to ensure we are actually passing a user login

ObjectMethod *ASSERT_IS_USER_DISPLAY_NAME ($user_display) -> $boolean

Used for debugging to ensure we are actually passing a user display_name (commonly a WikiWord Name)

Returns true by default.

 
Copyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiUserMappingDotPm.