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:
This module provides subroutines which interact with the lonc/lond (TCP) network layer of LON-CAPA. And Can be used to ask about - classes - users - resources
For many of these objects you can also use this to store data about them or modify them in various ways.
This is part of the LearningOnline Network with CAPA project described at http://www.lon-capa.org.
appenv(%hash) : the value of %hash is written to the
user envirnoment file, and will be restored for each access this user makes
during this session, also modifies the %ENV for the current process delenv($regexp) : removes all items from the session
environment file that matches the regular expression in $regexp. The values
are also delted from the current processes %ENV. queryauthenticate($uname,$udom) : try to determine
user's current authentication scheme authenticate($uname,$upass,$udom) : try to authenticate
user from domain's lib servers (first use the current one), $upass should
be the users password homeserver($uname,$udom) : find the server which has
the user's directory and files (there must be only one) . This caches the
answer and also caches if there is an error.idget($udom,@ids) : find the usernames behind a list
of IDs (IDs are a unique resource in a domain, there must be only 1 ID per
username, and only 1 username per ID in a specific domain) (returns hash:
id=>name,id=>name) idrget($udom,@unames) : find the IDs behind a list
of usernames (returns hash: name=>id,name=>id) idput($udom,%ids) : store away a list of names and
associated IDs rolesinit($udom,$username,$authhost) : get user privileges
usection($udom,$uname,$cname) : finds the section
of student in the course $cname, return section name/number or '' for ``not
in course'' and '-1' for ``no section'' userenvironment($udom,$uname,@what) : gets the values
of the keys passed in @what from the requested user's environment, returns
a hash 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'') modifyuserauth($udom,$uname,$umode,$upass)
: modify user authentication modifyuser($udom,$uname,$uid,$umode,$upass,$first,$middle,$last,$gene)
: modify user 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
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/....)
Possible values for $varname are environment.lastname (or other item from the environment 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 requestsmetadata_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 querysymbread($filename) : return symbolic
list entry (filename argument optional); returns the data handle numval($salt) : return random seed
value (addend for rndseed) rndseed($symb,$courseid,$udom,$username)
: 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 ($udomain
and $uname are optional) del($namespace,$storearr,$udom,$uname)
: deletes keys out of array from namesp ($udomain and $uname are optional)
dump($namespace,$udom,$uname,$regexp)
: dumps the complete (or key matching regexp) namespace into a hash ($udomain,
$uname and $regexp are optional) put($namespace,$storehash,$udomain,$uname)
: stores hash in namesp ($udomain and $uname are optional) cput($namespace,$storehash,$udomain,$uname)
: critical put ($udomain and $uname are optional) eget($namespace,$storearr,$udomain,$uname)
: returns hash with keys from array reference filled in from namesp (encrypts
the return communication) ($udomain 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) : serves up a file,
returns the contents of a file or -1; replicates and subscribes to the file
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
Things to keep in mind while coding handlers for LON-CAPA
1. DON'T write to Access machine disks with permanent data, use store/restore
2. DON'T use print(), use $request->print()
3. DON'T launch children
4. DO use $Apache::lonnet::perlvar{'lonDaemons'}/tmp for temporary data.
5. DO query the return value of every file operation.
6. DO use strict;
7. DO use strict;
8. DO familiarize your self with the functions in lonnet.pm and use them to communicate with other servers and when you handler needs to ask questions.
9. DON'T use &Apache::lonnet::reply()
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:
+This module provides subroutines which interact with the lonc/lond (TCP) + network layer of LON-CAPA. And Can be used to ask about - classes - users + - resources
+For many of these objects you can also use this to store data about them + or modify them in various ways.
+This is part of the LearningOnline Network with CAPA project described at + http://www.lon-capa.org.
+appenv(%hash) : the value of %hash is written to the
+ user envirnoment file, and will be restored for each access this user makes
+ during this session, also modifies the %ENV for the current process delenv($regexp) : removes all items from the session
+ environment file that matches the regular expression in $regexp. The values
+ are also delted from the current processes %ENV. queryauthenticate($uname,$udom) : try to determine
+ user's current authentication scheme authenticate($uname,$upass,$udom) : try to authenticate
+ user from domain's lib servers (first use the current one), $upass should
+ be the users password homeserver($uname,$udom) : find the server which has
+ the user's directory and files (there must be only one) . This caches the
+ answer and also caches if there is an error.idget($udom,@ids) : find the usernames behind a list
+ of IDs (IDs are a unique resource in a domain, there must be only 1 ID per
+ username, and only 1 username per ID in a specific domain) (returns hash:
+ id=>name,id=>name) idrget($udom,@unames) : find the IDs behind a list
+ of usernames (returns hash: name=>id,name=>id) idput($udom,%ids) : store away a list of names and
+ associated IDs rolesinit($udom,$username,$authhost) : get user privileges
+ usection($udom,$uname,$cname) : finds the section
+ of student in the course $cname, return section name/number or '' for ``not
+ in course'' and '-1' for ``no section'' userenvironment($udom,$uname,@what) : gets the values
+ of the keys passed in @what from the requested user's environment, returns
+ a hash 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'') modifyuserauth($udom,$uname,$umode,$upass)
+ : modify user authentication modifyuser($udom,$uname,$uid,$umode,$upass,$first,$middle,$last,$gene)
+ : modify user 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
+ 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/....)
+ Possible values for $varname are environment.lastname + (or other item from the environment 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 requestsmetadata_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 querysymbread($filename) : return symbolic
+ list entry (filename argument optional); returns the data handle numval($salt) : return random seed
+ value (addend for rndseed) rndseed($symb,$courseid,$udom,$username)
+ : 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 ($udomain
+ and $uname are optional) del($namespace,$storearr,$udom,$uname)
+ : deletes keys out of array from namesp ($udomain and $uname are optional)
+ dump($namespace,$udom,$uname,$regexp)
+ : dumps the complete (or key matching regexp) namespace into a hash ($udomain,
+ $uname and $regexp are optional) put($namespace,$storehash,$udomain,$uname)
+ : stores hash in namesp ($udomain and $uname are optional) cput($namespace,$storehash,$udomain,$uname)
+ : critical put ($udomain and $uname are optional) eget($namespace,$storearr,$udomain,$uname)
+ : returns hash with keys from array reference filled in from namesp (encrypts
+ the return communication) ($udomain 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) : serves up a file,
+ returns the contents of a file or -1; replicates and subscribes to the file
+ 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
Things to keep in mind while coding handlers for LON-CAPA
+1. + DON'T write to Access machine disks + with permanent data, use store/restore
+2. + DON'T use print(), use $request->print()
+3. + DON'T launch children
+4. + DO use $Apache::lonnet::perlvar{'lonDaemons'}/tmp for temporary data.
+5. + DO query the return value of every + file operation.
+6. + DO use strict;
+7. + DO use strict;
+8. + DO familiarize your self with the + functions in lonnet.pm and use them to communicate with other servers and when + you handler needs to ask questions.
+9. DON'T use &Apache::lonnet::reply()
+