EXPERTS ONLY Proposed API for user access, for use with TWiki-4.0.x
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