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

Author:	TWiki:Main/CrawfordCurrie http://www.c-dot.co.uk
Version:	11231
Change History:
10558	Now supports ACL stored in META:PREFERENCE
9060	Removed NOSEARCHALL handling from setACLs
9046	Was not deleting the old setting out of the file, just writing the new setting at the end. Not a killer, just untidy.
8877	Item1701 getting install right
8856	Item1682 Further improvements to the user access, include access to ACL lists (read and write)
8847	Item1670 didn't realise getAllGroups wasn't in TWiki4
8837	Item1670 proof-of-concept demonstrator for functions for user data access from plugins, long overdue.
Copyright ©:	Crawford Currie http://c-dot.co.uk 2006
License:	GNU LGPL
Dependencies:	None
Home:	http://TWiki.org/cgi-bin/view/Plugins/FuncUsersContrib
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/FuncUsersContribDev

Related Topics: TWikiPreferences

-- TWiki:Main/CrawfordCurrie - 21:30:35 01 August 2006