Chapter 4.12:  Groups of People

[TOP] [UP] [PREV] [NEXT]

People (users) are often collected in "groups", which are then in turn used (primarily) to control access to different objects, such as conferences, filesafes, etc.  In Caucus 4, groups were simple text files, containing one userid per line.  In Caucus 5, groups are sets of rules that define which users have which access permissions to the relevant object.  See Caucus Groups in C5 for a more general description.

$group_access (userid gtype gname)

Evaluates to the (numeric) access level granted to user userid in group gtype gname.  If the user has no access, or the group does not exist, the access level is 0.  Group_access() is very fast due to an internal cache, but its information may be out of date by a maximum of 100 seconds.

Groups are defined by a type (e.g. "MGR", "CONF", "Filesafe", "Caucus4", or a specific userid) and by a name.  Thus, for example, group "MGR systemShutdown" defines the list of users who are allowed to shutdown Caucus, and "CONF 12" defines the list of users with access to conference number 12.

The access levels are:

Primary organizer:	100
Organizer	40
Instructor	30
Member ("include")	20
Readonly	10
Exclude	0

$group_update ($quote(grouptype groupname))

Updates all of the 'groups' table entries for "grouptype groupname".  Either $group_update() or $group_update_rule() must be called after any changes to the rules for a particular group (in the grouprules table).  Group_update() is slow but thorough, since it completely rebuilds the groups table entries for a particular group.

$group_update_rule (changeentry $quote(grouptype groupname))

Updates the 'groups' table entries for group "grouptype groupname", but only updates rows for users that match changeentry.  Changeentry can be a userid, a wildcard, or a $quote()'d group name.

This function is much faster (and thus preferable) if we know (which we almost always do) which entries have been changed.  E.g. if we add a grouprules row for a specific userid, then call $group_update_rule() with that userid, etc. etc.

$peo_members(cnum)

Evaluates to a list of userids that are members of conference cnum.  The userids are sorted by "last name" of the actual users.

$userids_byid(match)

Evaluates to a list of all of the userids registered with Caucus that begin with the initial substring match.  If match is empty, evaluates to list of all of the Caucus userids.  (Even on a site with thousands of users, this function evaluates quickly.)

$peo_names(cnum word1 [word2])

Evaluates to a list of userids of people who match word1 (and word2, if specified).  A person matches if the word(s) are an initial substring of their first or last name.  If cnum is non-zero, matching people must also be a member of conference cnum.

$userids_byname(x names...)

Evaluates to a list of userids of people who match names.  A person matches if every word in names is an initial substring of some part of their name (including their userid as if it were part of their name).  The x argument is ignored (for now).

Note:  Caucus 5 implements this function with a brute-force LIKE match and a set of JOINs of user_info against itself.  On a large site, this may be slow; if so, it can be reimplemented as a separate table, with one row per word in the users' names.

Caucus 4.x functions

$in_group(userid gfile)

The In_group function, in combination with the Caucus "groups" files, acts as a simple kind of ACL (access control list) mechanism.  It evaluates to a number (the "match value") >= 1 if userid is found or matched in group file gfile, or any group file that gfile in turn includes.  Otherwise "0".

If userid is found by itself on a line, the match value is 1.  If userid is followed on the same line by a number or numbers, the match value is the bitwise "OR" of those numbers.  If userid is followed on the same line by one or more words, those words are translated into numbers (from the GroupPermNames parameter in swebd.conf), and then likewise "OR"ed together.

If the swebd.conf parameter GroupSearch is "ALL", $in_group() searches for all possible matches for userid, and similarly "OR"s them all together.  Otherwise, $in_group() just returns the first match. 

If you are using $in_group() simply to check if a user is in a group, then GroupSearch does not need to be set to "ALL", and in fact Caucus will run somewhat faster that way.  If, however, you use $in_group() for ACLs, and there's any chance at all that a userid will be listed more than once, you should definitely make sure that GroupSearch is set to "ALL".

$groupperm(permname...)

Translates group permission names (as in the groups files used by $in_group(), above) into their numerical equivalents.  Evaluates to the bitwise "OR" of the numeric values (from the swebd.conf parameter GroupPermNames) of the word(s) in permname.