--- loncom/lonnet/perl/lonnet.pm 2012/05/30 20:29:45 1.1176
+++ loncom/lonnet/perl/lonnet.pm 2012/09/04 20:48:05 1.1190
@@ -1,7 +1,7 @@
# The LearningOnline Network
# TCP networking package
#
-# $Id: lonnet.pm,v 1.1176 2012/05/30 20:29:45 raeburn Exp $
+# $Id: lonnet.pm,v 1.1190 2012/09/04 20:48:05 raeburn Exp $
#
# Copyright Michigan State University Board of Trustees
#
@@ -75,6 +75,7 @@ use LWP::UserAgent();
use HTTP::Date;
use Image::Magick;
+
use Encode;
use vars qw(%perlvar %spareid %pr %prp $memcache %packagetab $tmpdir
@@ -112,30 +113,33 @@ our @ISA = qw (Exporter);
our @EXPORT = qw(%env);
-# --------------------------------------------------------------------- Logging
+# ------------------------------------ Logging (parameters, docs, slots, roles)
{
my $logid;
- sub instructor_log {
- my ($hash_name,$storehash,$delflag,$uname,$udom,$cnum,$cdom)=@_;
- if (($cnum eq '') || ($cdom eq '')) {
- $cnum = $env{'course.'.$env{'request.course.id'}.'.num'};
- $cdom = $env{'course.'.$env{'request.course.id'}.'.domain'};
+ sub write_log {
+ my ($context,$hash_name,$storehash,$delflag,$uname,$udom,$cnum,$cdom)=@_;
+ if ($context eq 'course') {
+ if (($cnum eq '') || ($cdom eq '')) {
+ $cnum = $env{'course.'.$env{'request.course.id'}.'.num'};
+ $cdom = $env{'course.'.$env{'request.course.id'}.'.domain'};
+ }
}
- $logid++;
+ $logid ++;
my $now = time();
my $id=$now.'00000'.$$.'00000'.$logid;
- return &Apache::lonnet::put('nohist_'.$hash_name,
- { $id => {
- 'exe_uname' => $env{'user.name'},
- 'exe_udom' => $env{'user.domain'},
- 'exe_time' => $now,
- 'exe_ip' => $ENV{'REMOTE_ADDR'},
- 'delflag' => $delflag,
- 'logentry' => $storehash,
- 'uname' => $uname,
- 'udom' => $udom,
- }
- },$cdom,$cnum);
+ my $logentry = {
+ $id => {
+ 'exe_uname' => $env{'user.name'},
+ 'exe_udom' => $env{'user.domain'},
+ 'exe_time' => $now,
+ 'exe_ip' => $ENV{'REMOTE_ADDR'},
+ 'delflag' => $delflag,
+ 'logentry' => $storehash,
+ 'uname' => $uname,
+ 'udom' => $udom,
+ }
+ };
+ return &put('nohist_'.$hash_name,$logentry,$cdom,$cnum);
}
}
@@ -1419,7 +1423,7 @@ sub get_loadbalancer_targets {
}
}
} else {
- my %servers = &dom_servers($udom);
+ my %servers = &internet_dom_servers($udom);
my ($remotebalancer,$remotetargets) = &get_lonbalancer_config(\%servers);
if (&hostname($remotebalancer) ne '') {
$offloadto = [$remotebalancer];
@@ -1938,7 +1942,8 @@ sub get_domain_defaults {
my %domconfig =
&Apache::lonnet::get_dom('configuration',['defaults','quotas',
'requestcourses','inststatus',
- 'coursedefaults','usersessions'],$domain);
+ 'coursedefaults','usersessions',
+ 'requestauthor'],$domain);
if (ref($domconfig{'defaults'}) eq 'HASH') {
$domdefaults{'lang_def'} = $domconfig{'defaults'}{'lang_def'};
$domdefaults{'auth_def'} = $domconfig{'defaults'}{'auth_def'};
@@ -1957,7 +1962,7 @@ sub get_domain_defaults {
} else {
$domdefaults{'defaultquota'} = $domconfig{'quotas'};
}
- my @usertools = ('aboutme','blog','portfolio');
+ my @usertools = ('aboutme','blog','webdav','portfolio');
foreach my $item (@usertools) {
if (ref($domconfig{'quotas'}{$item}) eq 'HASH') {
$domdefaults{$item} = $domconfig{'quotas'}{$item};
@@ -1969,6 +1974,9 @@ sub get_domain_defaults {
$domdefaults{$item} = $domconfig{'requestcourses'}{$item};
}
}
+ if (ref($domconfig{'requestauthor'}) eq 'HASH') {
+ $domdefaults{'requestauthor'} = $domconfig{'requestauthor'};
+ }
if (ref($domconfig{'inststatus'}) eq 'HASH') {
foreach my $item ('inststatustypes','inststatusorder') {
$domdefaults{$item} = $domconfig{'inststatus'}{$item};
@@ -2398,7 +2406,7 @@ sub chatsend {
sub getversion {
my $fname=&clutter(shift);
- unless ($fname=~/^\/res\//) { return -1; }
+ unless ($fname=~m{^(/adm/wrapper|)/res/}) { return -1; }
return ¤tversion(&filelocation('',$fname));
}
@@ -2585,7 +2593,9 @@ sub ssi {
$request->header(Cookie => $ENV{'HTTP_COOKIE'});
my $response= $ua->request($request);
- my $content = Encode::decode_utf8($response->content);
+ my $content = $response->content;
+
+
if (wantarray) {
return ($content, $response);
} else {
@@ -3527,38 +3537,70 @@ sub userrolelog {
sub courserolelog {
my ($trole,$username,$domain,$area,$tstart,$tend,$delflag,$selfenroll,$context)=@_;
- if (($trole eq 'cc') || ($trole eq 'in') ||
- ($trole eq 'ep') || ($trole eq 'ad') ||
- ($trole eq 'ta') || ($trole eq 'st') ||
- ($trole=~/^cr/) || ($trole eq 'gr') ||
- ($trole eq 'co')) {
- if ($area =~ m-^/($match_domain)/($match_courseid)/?([^/]*)-) {
- my $cdom = $1;
- my $cnum = $2;
- my $sec = $3;
- my $namespace = 'rolelog';
- my %storehash = (
- role => $trole,
- start => $tstart,
- end => $tend,
- selfenroll => $selfenroll,
- context => $context,
- );
- if ($trole eq 'gr') {
- $namespace = 'groupslog';
- $storehash{'group'} = $sec;
- } else {
- $storehash{'section'} = $sec;
- }
- &instructor_log($namespace,\%storehash,$delflag,$username,$domain,$cnum,$cdom);
- if (($trole ne 'st') || ($sec ne '')) {
- &devalidate_cache_new('getcourseroles',$cdom.'_'.$cnum);
- }
+ if ($area =~ m-^/($match_domain)/($match_courseid)/?([^/]*)-) {
+ my $cdom = $1;
+ my $cnum = $2;
+ my $sec = $3;
+ my $namespace = 'rolelog';
+ my %storehash = (
+ role => $trole,
+ start => $tstart,
+ end => $tend,
+ selfenroll => $selfenroll,
+ context => $context,
+ );
+ if ($trole eq 'gr') {
+ $namespace = 'groupslog';
+ $storehash{'group'} = $sec;
+ } else {
+ $storehash{'section'} = $sec;
+ }
+ &write_log('course',$namespace,\%storehash,$delflag,$username,
+ $domain,$cnum,$cdom);
+ if (($trole ne 'st') || ($sec ne '')) {
+ &devalidate_cache_new('getcourseroles',$cdom.'_'.$cnum);
}
}
return;
}
+sub domainrolelog {
+ my ($trole,$username,$domain,$area,$tstart,$tend,$delflag,$context)=@_;
+ if ($area =~ m{^/($match_domain)/$}) {
+ my $cdom = $1;
+ my $domconfiguser = &Apache::lonnet::get_domainconfiguser($cdom);
+ my $namespace = 'rolelog';
+ my %storehash = (
+ role => $trole,
+ start => $tstart,
+ end => $tend,
+ context => $context,
+ );
+ &write_log('domain',$namespace,\%storehash,$delflag,$username,
+ $domain,$domconfiguser,$cdom);
+ }
+ return;
+
+}
+
+sub coauthorrolelog {
+ my ($trole,$username,$domain,$area,$tstart,$tend,$delflag,$context)=@_;
+ if ($area =~ m{^/($match_domain)/($match_username)$}) {
+ my $audom = $1;
+ my $auname = $2;
+ my $namespace = 'rolelog';
+ my %storehash = (
+ role => $trole,
+ start => $tstart,
+ end => $tend,
+ context => $context,
+ );
+ &write_log('author',$namespace,\%storehash,$delflag,$username,
+ $domain,$auname,$audom);
+ }
+ return;
+}
+
sub get_course_adv_roles {
my ($cid,$codes) = @_;
$cid=$env{'request.course.id'} unless (defined($cid));
@@ -3671,7 +3713,7 @@ sub get_my_roles {
}
my ($rolecode,$username,$domain,$section,$area);
if ($context eq 'userroles') {
- ($area,$rolecode) = split(/_/,$entry);
+ ($area,$rolecode) = ($entry =~ /^(.+)_([^_]+)$/);
(undef,$domain,$username,$section) = split(/\//,$area);
} else {
($role,$username,$domain,$section) = split(/\:/,$entry);
@@ -3822,18 +3864,32 @@ sub courseiddump {
if (($domfilter eq '') ||
(&host_domain($tryserver) eq $domfilter)) {
- my $rep =
- &reply('courseiddump:'.&host_domain($tryserver).':'.
- $sincefilter.':'.&escape($descfilter).':'.
- &escape($instcodefilter).':'.&escape($ownerfilter).
- ':'.&escape($coursefilter).':'.&escape($typefilter).
- ':'.&escape($regexp_ok).':'.$as_hash.':'.
- &escape($selfenrollonly).':'.&escape($catfilter).':'.
- $showhidden.':'.$caller.':'.&escape($cloner).':'.
- &escape($cc_clone).':'.$cloneonly.':'.
- &escape($createdbefore).':'.&escape($createdafter).':'.
- &escape($creationcontext).':'.$domcloner,
- $tryserver);
+ my $rep;
+ if (grep { $_ eq $tryserver } current_machine_ids()) {
+ $rep = LONCAPA::Lond::dump_course_id_handler(
+ join(":", (&host_domain($tryserver), $sincefilter,
+ &escape($descfilter), &escape($instcodefilter),
+ &escape($ownerfilter), &escape($coursefilter),
+ &escape($typefilter), &escape($regexp_ok),
+ $as_hash, &escape($selfenrollonly),
+ &escape($catfilter), $showhidden, $caller,
+ &escape($cloner), &escape($cc_clone), $cloneonly,
+ &escape($createdbefore), &escape($createdafter),
+ &escape($creationcontext), $domcloner)));
+ } else {
+ $rep = &reply('courseiddump:'.&host_domain($tryserver).':'.
+ $sincefilter.':'.&escape($descfilter).':'.
+ &escape($instcodefilter).':'.&escape($ownerfilter).
+ ':'.&escape($coursefilter).':'.&escape($typefilter).
+ ':'.&escape($regexp_ok).':'.$as_hash.':'.
+ &escape($selfenrollonly).':'.&escape($catfilter).':'.
+ $showhidden.':'.$caller.':'.&escape($cloner).':'.
+ &escape($cc_clone).':'.$cloneonly.':'.
+ &escape($createdbefore).':'.&escape($createdafter).':'.
+ &escape($creationcontext).':'.$domcloner,
+ $tryserver);
+ }
+
my @pairs=split(/\&/,$rep);
foreach my $item (@pairs) {
my ($key,$value)=split(/\=/,$item,2);
@@ -4993,15 +5049,19 @@ sub delete_env_groupprivs {
sub check_adhoc_privs {
my ($cdom,$cnum,$update,$refresh,$now,$checkrole,$caller) = @_;
my $cckey = 'user.role.'.$checkrole.'./'.$cdom.'/'.$cnum;
+ my $setprivs;
if ($env{$cckey}) {
my ($role,$where,$trolecode,$tstart,$tend,$tremark,$tstatus,$tpstart,$tpend);
&role_status($cckey,$update,$refresh,$now,\$role,\$where,\$trolecode,\$tstatus,\$tstart,\$tend);
unless (($tstatus eq 'is') || ($tstatus eq 'will_not')) {
&set_adhoc_privileges($cdom,$cnum,$checkrole,$caller);
+ $setprivs = 1;
}
} else {
&set_adhoc_privileges($cdom,$cnum,$checkrole,$caller);
+ $setprivs = 1;
}
+ return $setprivs;
}
sub set_adhoc_privileges {
@@ -5073,12 +5133,37 @@ sub del {
# -------------------------------------------------------------- dump interface
+sub unserialize {
+ my ($rep, $escapedkeys) = @_;
+
+ return {} if $rep =~ /^error/;
+
+ my %returnhash=();
+ foreach my $item (split /\&/, $rep) {
+ my ($key, $value) = split(/=/, $item, 2);
+ $key = unescape($key) unless $escapedkeys;
+ next if $key =~ /^error: 2 /;
+ $returnhash{$key} = Apache::lonnet::thaw_unescape($value);
+ }
+ #return %returnhash;
+ return \%returnhash;
+}
+
+# see Lond::dump_with_regexp
+# if $escapedkeys hash keys won't get unescaped.
sub dump {
- my ($namespace,$udomain,$uname,$regexp,$range)=@_;
+ my ($namespace,$udomain,$uname,$regexp,$range,$escapedkeys)=@_;
if (!$udomain) { $udomain=$env{'user.domain'}; }
if (!$uname) { $uname=$env{'user.name'}; }
my $uhome=&homeserver($uname,$udomain);
+ my $reply;
+ if (grep { $_ eq $uhome } current_machine_ids()) {
+ # user is hosted on this machine
+ $reply = LONCAPA::Lond::dump_with_regexp(join(":", ($udomain,
+ $uname, $namespace, $regexp, $range)), $loncaparevs{$uhome});
+ return %{unserialize($reply, $escapedkeys)};
+ }
if ($regexp) {
$regexp=&escape($regexp);
} else {
@@ -5090,7 +5175,8 @@ sub dump {
if (!($rep =~ /^error/ )) {
foreach my $item (@pairs) {
my ($key,$value)=split(/=/,$item,2);
- $key = &unescape($key);
+ $key = unescape($key) unless $escapedkeys;
+ #$key = &unescape($key);
next if ($key =~ /^error: 2 /);
$returnhash{$key}=&thaw_unescape($value);
}
@@ -5103,23 +5189,9 @@ sub dump {
sub dumpstore {
my ($namespace,$udomain,$uname,$regexp,$range)=@_;
- if (!$udomain) { $udomain=$env{'user.domain'}; }
- if (!$uname) { $uname=$env{'user.name'}; }
- my $uhome=&homeserver($uname,$udomain);
- if ($regexp) {
- $regexp=&escape($regexp);
- } else {
- $regexp='.';
- }
- my $rep=&reply("dump:$udomain:$uname:$namespace:$regexp:$range",$uhome);
- my @pairs=split(/\&/,$rep);
- my %returnhash=();
- foreach my $item (@pairs) {
- my ($key,$value)=split(/=/,$item,2);
- next if ($key =~ /^error: 2 /);
- $returnhash{$key}=&thaw_unescape($value);
- }
- return %returnhash;
+ # same as dump but keys must be escaped. They may contain colon separated
+ # lists of values that may themself contain colons (e.g. symbs).
+ return &dump($namespace, $udomain, $uname, $regexp, $range, 1);
}
# -------------------------------------------------------------- keys interface
@@ -5145,7 +5217,15 @@ sub currentdump {
$sdom = $env{'user.domain'} if (! defined($sdom));
$sname = $env{'user.name'} if (! defined($sname));
my $uhome = &homeserver($sname,$sdom);
- my $rep=reply('currentdump:'.$sdom.':'.$sname.':'.$courseid,$uhome);
+ my $rep;
+
+ if (grep { $_ eq $uhome } current_machine_ids()) {
+ $rep = LONCAPA::Lond::dump_profile_database(join(":", ($sdom, $sname,
+ $courseid)));
+ } else {
+ $rep = reply('currentdump:'.$sdom.':'.$sname.':'.$courseid,$uhome);
+ }
+
return if ($rep =~ /^(error:|no_such_host)/);
#
my %returnhash=();
@@ -5643,10 +5723,15 @@ sub usertools_access {
unofficial => 1,
community => 1,
);
+ } elsif ($context eq 'requestauthor') {
+ %tools = (
+ requestauthor => 1,
+ );
} else {
%tools = (
aboutme => 1,
blog => 1,
+ webdav => 1,
portfolio => 1,
);
}
@@ -5661,25 +5746,32 @@ sub usertools_access {
if ($action ne 'reload') {
if ($context eq 'requestcourses') {
return $env{'environment.canrequest.'.$tool};
+ } elsif ($context eq 'requestauthor') {
+ return $env{'environment.canrequest.author'};
} else {
return $env{'environment.availabletools.'.$tool};
}
}
}
- my ($toolstatus,$inststatus);
+ my ($toolstatus,$inststatus,$envkey);
+ if ($context eq 'requestauthor') {
+ $envkey = $context;
+ } else {
+ $envkey = $context.'.'.$tool;
+ }
if (($udom eq $env{'user.domain'}) && ($uname eq $env{'user.name'}) &&
($action ne 'reload')) {
- $toolstatus = $env{'environment.'.$context.'.'.$tool};
+ $toolstatus = $env{'environment.'.$envkey};
$inststatus = $env{'environment.inststatus'};
} else {
if (ref($userenvref) eq 'HASH') {
- $toolstatus = $userenvref->{$context.'.'.$tool};
+ $toolstatus = $userenvref->{$envkey};
$inststatus = $userenvref->{'inststatus'};
} else {
- my %userenv = &userenvironment($udom,$uname,$context.'.'.$tool,'inststatus');
- $toolstatus = $userenv{$context.'.'.$tool};
+ my %userenv = &userenvironment($udom,$uname,$envkey,'inststatus');
+ $toolstatus = $userenv{$envkey};
$inststatus = $userenv{'inststatus'};
}
}
@@ -5745,7 +5837,7 @@ sub usertools_access {
}
}
} else {
- if ($context eq 'tools') {
+ if (($context eq 'tools') && ($tool ne 'webdav')) {
$access = 1;
} else {
$access = 0;
@@ -7466,6 +7558,41 @@ sub assignrole {
}
}
}
+ } elsif ($context eq 'requestauthor') {
+ if (($udom eq $env{'user.domain'}) && ($uname eq $env{'user.name'}) &&
+ ($url eq '/'.$udom.'/') && ($role eq 'au')) {
+ if ($env{'environment.requestauthor'} eq 'automatic') {
+ $refused = '';
+ } else {
+ my %domdefaults = &get_domain_defaults($udom);
+ if (ref($domdefaults{'requestauthor'}) eq 'HASH') {
+ my $checkbystatus;
+ if ($env{'user.adv'}) {
+ my $disposition = $domdefaults{'requestauthor'}{'_LC_adv'};
+ if ($disposition eq 'automatic') {
+ $refused = '';
+ } elsif ($disposition eq '') {
+ $checkbystatus = 1;
+ }
+ } else {
+ $checkbystatus = 1;
+ }
+ if ($checkbystatus) {
+ if ($env{'environment.inststatus'}) {
+ my @inststatuses = split(/,/,$env{'environment.inststatus'});
+ foreach my $type (@inststatuses) {
+ if (($type ne '') &&
+ ($domdefaults{'requestauthor'}{$type} eq 'automatic')) {
+ $refused = '';
+ }
+ }
+ } elsif ($domdefaults{'requestauthor'}{'default'} eq 'automatic') {
+ $refused = '';
+ }
+ }
+ }
+ }
+ }
}
if ($refused) {
&logthis('Refused assignrole: '.$udom.' '.$uname.' '.$url.
@@ -7516,11 +7643,25 @@ sub assignrole {
if ($answer eq 'ok') {
&userrolelog($role,$uname,$udom,$url,$start,$end);
# for course roles, perform group memberships changes triggered by role change.
- &courserolelog($role,$uname,$udom,$url,$origstart,$origend,$delflag,$selfenroll,$context);
unless ($role =~ /^gr/) {
&Apache::longroup::group_changes($udom,$uname,$url,$role,$origend,
$origstart,$selfenroll,$context);
}
+ if (($role eq 'cc') || ($role eq 'in') ||
+ ($role eq 'ep') || ($role eq 'ad') ||
+ ($role eq 'ta') || ($role eq 'st') ||
+ ($role=~/^cr/) || ($role eq 'gr') ||
+ ($role eq 'co')) {
+ &courserolelog($role,$uname,$udom,$url,$origstart,$origend,$delflag,
+ $selfenroll,$context);
+ } elsif (($role eq 'li') || ($role eq 'dg') || ($role eq 'sc') ||
+ ($role eq 'au') || ($role eq 'dc')) {
+ &domainrolelog($role,$uname,$udom,$url,$origstart,$origend,$delflag,
+ $context);
+ } elsif (($role eq 'ca') || ($role eq 'aa')) {
+ &coauthorrolelog($role,$uname,$udom,$url,$origstart,$origend,$delflag,
+ $context);
+ }
if ($role eq 'cc') {
&autoupdate_coowners($url,$end,$start,$uname,$udom);
}
@@ -9815,6 +9956,41 @@ sub devalidate_slots_cache {
&devalidate_cache_new('allslots',$hashid);
}
+sub get_coursechange {
+ my ($cdom,$cnum) = @_;
+ if ($cdom eq '' || $cnum eq '') {
+ return unless ($env{'request.course.id'});
+ $cnum = $env{'course.'.$env{'request.course.id'}.'.num'};
+ $cdom = $env{'course.'.$env{'request.course.id'}.'.domain'};
+ }
+ my $hashid=$cdom.'_'.$cnum;
+ my ($change,$cached)=&is_cached_new('crschange',$hashid);
+ if ((defined($cached)) && ($change ne '')) {
+ return $change;
+ } else {
+ my %crshash;
+ %crshash = &get('environment',['internal.contentchange'],$cdom,$cnum);
+ if ($crshash{'internal.contentchange'} eq '') {
+ $change = $env{'course.'.$cdom.'_'.$cnum.'.internal.created'};
+ if ($change eq '') {
+ %crshash = &get('environment',['internal.created'],$cdom,$cnum);
+ $change = $crshash{'internal.created'};
+ }
+ } else {
+ $change = $crshash{'internal.contentchange'};
+ }
+ my $cachetime = 600;
+ &do_cache_new('crschange',$hashid,$change,$cachetime);
+ }
+ return $change;
+}
+
+sub devalidate_coursechange_cache {
+ my ($cnum,$cdom)=@_;
+ my $hashid=$cnum.':'.$cdom;
+ &devalidate_cache_new('crschange',$hashid);
+}
+
# ------------------------------------------------- Update symbolic store links
sub symblist {
@@ -9842,7 +10018,7 @@ sub symblist {
# --------------------------------------------------------------- Verify a symb
sub symbverify {
- my ($symb,$thisurl)=@_;
+ my ($symb,$thisurl,$encstate)=@_;
my $thisfn=$thisurl;
$thisfn=&declutter($thisfn);
# direct jump to resource in page or to a sequence - will construct own symbs
@@ -9878,11 +10054,14 @@ sub symbverify {
}
if (
&symbclean(&declutter($bighash{'map_id_'.$mapid}).'___'.$resid.'___'.$thisfn)
- eq $symb) {
+ eq $symb) {
+ if (ref($encstate)) {
+ $$encstate = $bighash{'encrypted_'.$id};
+ }
if (($env{'request.role.adv'}) ||
($bighash{'encrypted_'.$id} eq $env{'request.enc'}) ||
($thisurl eq '/adm/navmaps')) {
- $okay=1;
+ $okay=1;
}
}
}
@@ -9959,7 +10138,11 @@ sub deversion {
sub symbread {
my ($thisfn,$donotrecurse)=@_;
my $cache_str='request.symbread.cached.'.$thisfn;
- if (defined($env{$cache_str})) { return $env{$cache_str}; }
+ if (defined($env{$cache_str})) {
+ if (($thisfn) || ($env{$cache_str} ne '')) {
+ return $env{$cache_str};
+ }
+ }
# no filename provided? try from environment
unless ($thisfn) {
if ($env{'request.symb'}) {
@@ -12075,12 +12258,14 @@ returns the data handle
=item *
-symbverify($symb,$thisfn) : verifies that $symb actually exists and is
-a possible symb for the URL in $thisfn, and if is an encryypted
+symbverify($symb,$thisfn,$encstate) : verifies that $symb actually exists
+and is a possible symb for the URL in $thisfn, and if is an encrypted
resource that the user accessed using /enc/ returns a 1 on success, 0
-on failure, user must be in a course, as it assumes the existance of
-the course initial hash, and uses $env('request.course.id'}
-
+on failure, user must be in a course, as it assumes the existence of
+the course initial hash, and uses $env('request.course.id'}. The third
+arg is an optional reference to a scalar. If this arg is passed in the
+call to symbverify, it will be set to 1 if the symb has been set to be
+encrypted; otherwise it will be null.
=item *