Apache::lonnet - Subroutines to ask questions about things in the network.
Invoked by other LON-CAPA modules, when they need to talk to or about objects in the network.
&Apache::lonnet::SUBROUTINENAME(ARGUMENTS);
Common parameters:
lonnet provides subroutines which interact with the lonc/lond (TCP) network layer of LON-CAPA. They can be used to ask about classes, users, and resources.
For many of these objects you can also use this to store data about them or modify them in various ways.
To identify a specific instance of a resource, LON-CAPA uses symbols or ``symbs''. These identifiers are built from the URL of the map, the resource number of the resource in the map, and the URL of the resource itself. The latter is somewhat redundant, but might help if maps change.
An example is
msu/korte/parts/part1.sequence___19___msu/korte/tests/part12.problem
The respective map entry is
<resource id="19" src="/res/msu/korte/tests/part12.problem" title="Problem 2"> </resource>
Symbs are used by the random number generator, as well as to store and restore data specific to a certain instance of for example a problem.
Three of the most important functions
in lonnet.pm
are &Apache::lonnet::cstore()
,
&Apache::lonnet:restore()
, and &Apache::lonnet::store()
, which
is is the non-critical message twin of cstore. These functions are for
handlers to store a perl hash to a user's permanent data space in an
easy manner, and to retrieve it again on another call. It is expected
that a handler would use this once at the beginning to retrieve data,
and then again once at the end to send only the new data back.
The data is stored in the user's data directory on the user's homeserver under the ID of the course.
The hash that is returned by restore will have all of the previous value for all of the elements of the hash.
Example:
#creating a hash my %hash; $hash{'foo'}='bar';
#storing it &Apache::lonnet::cstore(\%hash);
#changing a value $hash{'foo'}='notbar';
#adding a new value $hash{'bar'}='foo'; &Apache::lonnet::cstore(\%hash);
#retrieving the hash my %history=&Apache::lonnet::restore();
#print the hash foreach my $key (sort(keys(%history))) { print("\%history{$key} = $history{$key}"); }
Will print out:
%history{1:foo} = bar %history{1:keys} = foo:timestamp %history{1:timestamp} = 990455579 %history{2:bar} = foo %history{2:foo} = notbar %history{2:keys} = foo:bar:timestamp %history{2:timestamp} = 990455580 %history{bar} = foo %history{foo} = notbar %history{timestamp} = 990455580 %history{version} = 2
Note that the special hash entries keys
, version
and
timestamp
were added to the hash. version
will be equal to the
total number of versions of the data that have been stored. The
timestamp
attribute will be the UNIX time the hash was
stored. keys
is available in every historical section to list which
keys were added or changed at a specific historical revision of a
hash.
Warning: do not store the hash that restore returns directly. This will cause a mess since it will restore the historical keys as if the were new keys. I.E. 1:foo will become 1:1:foo etc.
Calling convention:
my %record=&Apache::lonnet::restore($symb,$courseid,$domain,$uname,$home); &Apache::lonnet::cstore(\%newrecord,$symb,$courseid,$domain,$uname,$home);
For more detailed information, see lonnet specific documentation.
$upass
should be the users password.
allowed($priv,$uri)
: check for a user privilege; returns codes for allowed
actions
F: full access
U,I,K: authentication modes (cxx only)
'': forbidden
1: user needs to choose course
2: browse allowed
definerole($rolename,$sysrole,$domrole,$courole)
: define role; define a custom
role rolename set privileges in format of lonTabs/roles.tab for system, domain,
and course level
plaintext($short)
: return value in %prp hash (rolesplain.tab); plain text
explanation of a user role term
assignrole($udom,$uname,$url,$role,$end,$start)
: assign role; give a role to a
user for the level given by URL. Optional start and end dates (leave empty
string or zero for ``no date'')
changepass($uname,$udom,$currentpass,$newpass,$server)
: attempts to
change a users, password, possible return values are: ok,
pwchange_failure, non_authorized, auth_mode_error, unknown_user,
refused
modifyuserauth($udom,$uname,$umode,$upass)
: modify user authentication
modifyuser($udom,$uname,$uid,$umode,$upass,$first,$middle,$last,$gene)
:
modify user
modify a students enrollment and identification information. The course id is resolved based on the current users environment. This means the envoking user must be a course coordinator or otherwise associated with a course.
This call is essentially a wrapper for lonnet::modifyuser and lonnet::modify_student_enrollment
Inputs:
Change a students enrollment status in a class. The environment variable 'role.request.course' must be defined for this function to proceed.
Inputs:
assigncustomrole($udom,$uname,$url,$rdom,$rnam,$rolename,$end,$start)
: assign
custom role; give a custom role to a user for the level given by URL. Specify
name and domain of role author, and role name
revokerole($udom,$uname,$url,$role)
: revoke a role for url
revokecustomrole($udom,$uname,$url,$role)
: revoke a custom role
coursedescription($courseid)
: course description
courseresdata($coursenum,$coursedomain,@which)
: request for current
parameter setting for a specific course, @what should be a list of
parameters to ask about. This routine caches answers for 5 minutes.
writecoursepref($courseid,%prefs)
: write preferences (environment
database) for a course
createcourse($udom,$description,$url)
: make/modify course
subscribe($fname)
: subscribe to a resource, returns URL if possible (probably should use repcopy instead)
repcopy($filename)
: subscribes to the requested file, and attempts to
replicate from the owning library server, Might return
HTTP_SERVICE_UNAVAILABLE, HTTP_NOT_FOUND, FORBIDDEN, OK, or
HTTP_BAD_REQUEST, also attempts to grab the metadata for the
resource. Expects the local filesystem pathname
(/home/httpd/html/res/....)
EXT($varname,$symb,$udom,$uname)
: evaluates and returns the value of
a vairety of different possible values, $varname should be a request
string, and the other parameters can be used to specify who and what
one is asking about.
Possible values for $varname are environment.lastname (or other item from the envirnment hash), user.name (or someother aspect about the user), resource.0.maxtries (or some other part and parameter of a resource)
directcondval($number)
: get current value of a condition; reads from a state
string
condval($condidx)
: value of condition index based on state
metadata($uri,$what,$liburi,$prefix,$depthcount)
: request a
resource's metadata, $what should be either a specific key, or either
'keys' (to get a list of possible keys) or 'packages' to get a list of
packages that this resource currently uses, the last 3 arguments are only used internally for recursive metadata.
this function automatically caches all requests
metadata_query($query,$custom,$customshow)
: make a metadata query against the
network of library servers; returns file handle of where SQL and regex results
will be stored for query
symbread($filename)
: return symbolic list entry (filename argument optional);
returns the data handle
symbverify($symb,$thisfn)
: verifies that $symb actually exists and is
a possible symb for the URL in $thisfn, returns a 1 on success, 0 on
failure, user must be in a course, as it assumes the existance of the
course initi hash, and uses $ENV('request.course.id'}
symbclean($symb)
: removes versions numbers from a symb, returns the
cleaned symb
is_on_map($uri)
: checks if the $uri is somewhere on the current
course map, user must be in a course for it to work.
numval($salt)
: return random seed value (addend for rndseed)
rndseed($symb,$courseid,$udom,$uname)
: create a random sum; returns
a random seed, all arguments are optional, if they aren't sent it uses the
environment to derive them. Note: if symb isn't sent and it can't get one
from &symbread it will use the current time as its return value
ireceipt($funame,$fudom,$fucourseid,$fusymb)
: return unique,
unfakeable, receipt
receipt()
: API to ireceipt working off of ENV values; given out to users
countacc($url)
: count the number of accesses to a given URL
checkout($symb,$tuname,$tudom,$tcrsid)
: creates a record of a user having looked at an item, most likely printed out or otherwise using a resource
checkin($token)
: updates that a resource has beeen returned (a hard copy version for instance) and returns the data that $token was Checkout with ($symb, $tuname, $tudom, and $tcrsid)
expirespread($uname,$udom,$stype,$usymb)
: set expire date for spreadsheet
devalidate($symb)
: devalidate temporary spreadsheet calculations,
forcing spreadsheet to reevaluate the resource scores next time.
store($storehash,$symb,$namespace,$udom,$uname)
: stores hash permanently
for this url; hashref needs to be given and should be a \%hashname; the
remaining args aren't required and if they aren't passed or are '' they will
be derived from the ENV
cstore($storehash,$symb,$namespace,$udom,$uname)
: same as store but
uses critical subroutine
restore($symb,$namespace,$udom,$uname)
: returns hash for this symb;
all args are optional
tmpstore($storehash,$symb,$namespace,$udom,$uname)
: storage that
works very similar to store/cstore, but all data is stored in a
temporary location and can be reset using tmpreset, $storehash should
be a hash reference, returns nothing on success
tmprestore($symb,$namespace,$udom,$uname)
: storage that works very
similar to restore, but all data is stored in a temporary location and
can be reset using tmpreset. Returns a hash of values on success,
error string otherwise.
tmpreset($symb,$namespace,$udom,$uname)
: temporary storage reset,
deltes all keys for $symb form the temporary storage hash.
get($namespace,$storearr,$udom,$uname)
: returns hash with keys from array
reference filled in from namesp ($udom and $uname are optional)
del($namespace,$storearr,$udom,$uname)
: deletes keys out of array from
namesp ($udom and $uname are optional)
dump($namespace,$udom,$uname,$regexp)
:
dumps the complete (or key matching regexp) namespace into a hash
($udom, $uname and $regexp are optional)
put($namespace,$storehash,$udom,$uname)
: stores hash in namesp
($udom and $uname are optional)
cput($namespace,$storehash,$udom,$uname)
: critical put
($udom and $uname are optional)
eget($namespace,$storearr,$udom,$uname)
: returns hash with keys from array
reference filled in from namesp (encrypts the return communication)
($udom and $uname are optional)
log($udom,$name,$home,$message)
: write to permanent log for user; use
critical subroutine
dirlist($uri)
: return directory list based on URI
spareserver()
: find server with least workload from spare.tab
ssi($url,%hash)
: server side include, does a complete request cycle on url to
localhost, posts hash
hash2str(%hash)
: convert a hash into a string complete with escaping and '='
and '&' separators, supports elements that are arrayrefs and hashrefs
hashref2str($hashref)
: convert a hashref into a string complete with
escaping and '=' and '&' separators, supports elements that are
arrayrefs and hashrefs
arrayref2str($arrayref)
: convert an arrayref into a string complete
with escaping and '&' separators, supports elements that are arrayrefs
and hashrefs
str2hash($string)
: convert string to hash using unescaping and
splitting on '=' and '&', supports elements that are arrayrefs and
hashrefs
str2array($string)
: convert string to hash using unescaping and
splitting on '&', supports elements that are arrayrefs and hashrefs
These routines allow one to make log messages in the lonnet.log and lonnet.perm logfiles.
logtouch()
: make sure the logfile, lonnet.log, exists
logthis()
: append message to the normal lonnet.log file, it gets
preiodically rolled over and deleted.
logperm()
: append a permanent message to lonnet.perm.log, this log
file never gets deleted by any automated portion of the system, only
messages of critical importance should go in here.
getfile($file)
: returns the entire contents of a file or -1; it
properly subscribes to and replicates the file if neccessary.
filelocation($dir,$file)
: returns file system location of a file
based on URI; meant to be ``fairly clean'' absolute reference, $dir is a
directory that relative $file lookups are to looked in ($dir of /a/dir
and a file of ../bob will become /a/bob)
hreflocation($dir,$file)
: returns file system location or a URL; same as
filelocation except for hrefs
declutter()
: declutters URLs (remove docroot, beginning slashes, 'res' etc)
escape()
: unpack non-word characters into CGI-compatible hex codes
unescape()
: pack CGI-compatible hex codes into actual non-word ASCII character
subreply()
: tries to pass a message to lonc, returns con_lost if incapable
reply()
: uses subreply to send a message to remote machine, logs all failures
critical()
: passes a critical message to another server; if cannot
get through then place message in connection buffer directory and
returns con_delayed, if incapable of saving message, returns
con_failed
reconlonc()
: tries to reconnect lonc client processes.
flushcourselogs()
: flush (save) buffer logs and access logs
courselog($what)
: save message for course in hash
courseacclog($what)
: save message for course using &courselog(). Perform
special processing for specific resource types (problems, exams, quizzes, etc).
goodbye()
: flush course logs and log shutting down; it is called in srm.conf
as a PerlChildExitHandler
symblist($mapname,%newhash)
: update symbolic storage links