r1 - 01 Aug 2006 - 07:30:35 - TWikiGuestYou are here: TWiki >  TWiki Web > FuncUsersContrib
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

About This Site

Please note that this site is a content mirror of the BNL USATLAS TWiki. To edit the content of this page, click the Edit this page button at the top of the page and log in with your BNL USATLAS account.


Attachments

 
Powered by TWiki
This site is powered by the TWiki collaboration platformCopyright © 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.FuncUsersContrib