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 a borken connection.
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'')
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
modifystudent($udom,$uname,$uid,$umode,$upass,$first,$middle,$last,$gene,$usec,$end,$start)
: modify student
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