| EXPERTS ONLY Proposed API for user access, for use with TWiki-4.0.x
<--
PLEASE DO NOT EDIT THIS TOPIC
It is automatically generated from the subversion repository, and any changes
you make will simply be overwritten the next time a release is generated.
Instead, you could check your fix in, raise a bug in the Bugs web, or mail the author.
-->
This module will only work with TWiki versions 4.0.0 and above.
Intended for use with any other plugin that urgently needs access to user data.
The module implements a set of functions for access to TWiki internal user data, to support functions such as getting a list of users, getting a list of groups, and mapping emails to users.
Summary of contents
A single perl module that implements the proposed user access API.
The API is packaged this way so it can be used with TWiki-4.0
- Set STUB = TWiki::Contrib::FuncUsersContrib
- Set SHORTDESCRIPTION = EXPERTS ONLY Proposed API for user access, for use with TWiki-4.0.x
Details
getListOfUsers() -> \@list
Get a list of the registered users not including groups. The returned
list is a list of TWiki::User objects.
To get a combined list of users and groups, you can do this:
@usersandgroups = ( @{TWiki::Func::getListOfUsers()}, TWiki::Func::getListOfGroups() );
getListOfGroups() -> \@list
Get a list of groups. The returned list is a list of TWiki::User objects.
lookupUser( %spec ) -> \$user
Find the TWiki::User object for a named user.
-
%spec - the identifying marks of the user. The following options are supported:
-
wikiname - the wikiname of the user (web name optional, also supports Main)
-
login - login name of the user
-
email - email address of the user *returns an array of users*
For example,
my @pa = TWiki::Func::lookupUser( email => "pa@addams.org" );
my $ma = TWiki::Func::lookupUser( wikiname => "%MAINWEB%.MorticiaAddams" );
getACLs( \@modes, $web, $topic ) -> \%acls
Get the Access Control Lists controlling which registered users and groups are allowed to access the topic (web).
-
\@modes - list of access modes you are interested in; e.g. [ "VIEW","CHANGE" ]
-
$web - the web
-
$topic - if undef then the setting is taken as a web setting e.g. WEBVIEW. Otherwise it is taken as a topic setting e.g. TOPICCHANGE
\%acls is a hash indexed by user name (web.wikiname). This maps to a hash indexed by access mode e.g. VIEW , CHANGE etc. This in turn maps to a boolean; 0 for access denied, non-zero for access permitted.
my $acls = TWiki::Func::getACLs( [ 'VIEW', 'CHANGE', 'RENAME' ], $web, $topic );
foreach my $user ( keys %$acls ) {
if( $acls->{$user}->{VIEW} ) {
print STDERR "$user can view $web.$topic\n";
}
}
The \%acls object may safely be written to e.g. for subsequent use with setACLs .
Note topic ACLs are not the final permissions used to control access to a topic. Web level restrictions may apply that prevent certain access modes for individual topics.
WARNING when you use setACLs to set the ACLs of a web or topic, the change is not committed to the database until the current session exist. After setACLs has been called on a web or topic, the results of getACLS for that web/topic are undefined.
setACLs( \@modes, \%acls, $web, $topic, $plainText )
Set the access controls on the named topic.
-
\@modes - list of access modes you want to set; e.g. [ "VIEW","CHANGE" ]
-
$web - the web
-
$topic - if undef , then this is the ACL for the web. otherwise it's for the topic.
-
\%acls - must be a hash indexed by user name (web.wikiname). This maps to a hash indexed by access mode e.g. VIEW , CHANGE etc. This in turn maps to a boolean value; 1 for allowed, and 0 for denied. See getACLs for an example of this kind of object.
- =$plainText - if set, permissions will be written using plain text (* Set) in the topic body rather than being stored in meta-data (the default)
Access modes used in \%acls that do not appear in \@modes are simply ignored.
If there are any errors, then an Error::Simple will be thrown.
WARNING when you use setACLs to set the ACLs of a web or topic, the change is not committed to the database until the current session exist. After setACLs has been called on a web or topic, the results of getACLS for that web/topic are undefined.
isAdmin() -> $boolean
Find out if the currently logged-in user is an admin or not.
isInGroup( $group ) -> $boolean
Find out if the currently logged-in user is in the named group. e.g.
if( TWiki::Func::isInGroup( "PopGroup" )) {
...
}
Contrib Info
Related Topics: TWikiPreferences
-- TWiki:Main/CrawfordCurrie - 21:30:35 01 August 2006 |