--- loncom/lonnet/perl/lonnet.pm	2002/06/24 14:16:58	1.242
+++ loncom/lonnet/perl/lonnet.pm	2002/06/24 19:41:41	1.243
@@ -1,7 +1,7 @@
 # The LearningOnline Network
 # TCP networking package
 #
-# $Id: lonnet.pm,v 1.242 2002/06/24 14:16:58 www Exp $
+# $Id: lonnet.pm,v 1.243 2002/06/24 19:41:41 albertel Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -3015,75 +3015,105 @@ $readit=1;
 1;
 __END__
 
+=pod
+
 =head1 NAME
 
-Apache::lonnet - TCP networking package
+Apache::lonnet - Subroutines to ask questions about things in the network.
 
 =head1 SYNOPSIS
 
-Invoked by other LON-CAPA modules.
+Invoked by other LON-CAPA modules, when they need to talk to or about objects in the network.
 
  &Apache::lonnet::SUBROUTINENAME(ARGUMENTS);
 
+Common parameters:
+
+=over 4
+
+=item *
+
+$uname : an internal username (if $cname expecting a course Id specifically)
+
+=item *
+
+$udom : a domain (if $cdom expecting a course's domain specifically)
+
+=item *
+
+$symb : a resource instance identifier
+
+=item *
+
+$namespace : the name of a .db file that contains the data needed or
+being set.
+
+=back
+
 =head1 INTRODUCTION
 
 This module provides subroutines which interact with the
-lonc/lond (TCP) network layer of LON-CAPA.
+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.
 
-=head1 HANDLER SUBROUTINE
-
-There is no handler routine for this module.
-
-=head1 OTHER SUBROUTINES
+=head1 RETURN MESSAGES
 
 =over 4
 
 =item *
 
-logtouch() : make sure the logfile, lonnet.log, exists
+con_lost : unable to contact remote host
 
 =item *
 
-logthis() : append message to lonnet.log
+con_delayed : unable to contact remote host, message will be delivered
+when the connection is brought back up
 
 =item *
 
-logperm() : append a permanent message to lonnet.perm.log
+con_failed : unable to contact remote host and unable to save message
+for later delivery
 
 =item *
 
-subreply() : non-critical communication, called by &reply
+error: : an error a occured, a description of the error follows the :
 
 =item *
 
-reply() : makes two attempts to pass message; logs refusals and rejections
+no_such_host : unable to fund a host associated with the user/domain
+that was requested
 
-=item *
+=back
 
-reconlonc() : tries to reconnect lonc client processes.
+=head1 PUBLIC SUBROUTINES
 
-=item *
+=head2 Session Environment Functions
 
-critical() : passes a critical message to another server; if cannot get
-through then place message in connection buffer
+=over 4
 
 =item *
 
-appenv(%hash) : read in current user environment, append new environment
-values to make new user environment
+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
 
 =item *
 
-delenv($varname) : read in current user environment, remove all values
-beginning with $varname, write new user environment (note: flock is used
-to prevent conflicting shared read/writes with file)
+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.
 
-=item *
+=back
 
-spareserver() : find server with least workload from spare.tab
+=head2 User Information
+
+=over 4
 
 =item *
 
@@ -3093,16 +3123,19 @@ authentication scheme
 =item *
 
 authenticate($uname,$upass,$udom) : try to authenticate user from domain's lib
-servers (first use the current one)
+servers (first use the current one), $upass should be the users password
 
 =item *
 
-homeserver($uname,$udom) : find the homebase for a user from domain's lib
-servers
+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.
 
 =item *
 
-idget($udom,@ids) : find the usernames behind a list of IDs (returns hash:
+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)
 
 =item *
@@ -3116,226 +3149,332 @@ idput($udom,%ids) : store away a list of
 
 =item *
 
-usection($domain,$user,$courseid) : output of section name/number or '' for
-"not in course" and '-1' for "no section"
+rolesinit($udom,$username,$authhost) : get user privileges
 
 =item *
 
-userenvironment($domain,$user,$what) : puts out any environment parameter 
-for a user
+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"
 
 =item *
 
-subscribe($fname) : subscribe to a resource, return URL if possible
+userenvironment($udom,$uname,@what) : gets the values of the keys
+passed in @what from the requested user's environment, returns a hash
+
+=back
+
+=head2 User Roles
+
+=over 4
 
 =item *
 
-repcopy($filename) : replicate file
+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
 
 =item *
 
-ssi($url,%hash) : server side include, does a complete request cycle on url to
-localhost, posts hash
+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
 
 =item *
 
-log($domain,$name,$home,$message) : write to permanent log for user; use
-critical subroutine
+plaintext($short) : return value in %prp hash (rolesplain.tab); plain text
+explanation of a user role term
+
+=back
+
+=head2 User Modification
+
+=over 4
 
 =item *
 
-flushcourselogs() : flush (save) buffer logs and access logs
+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")
 
 =item *
 
-courselog($what) : save message for course in hash
+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
 
 =item *
 
-courseacclog($what) : save message for course using &courselog().  Perform
-special processing for specific resource types (problems, exams, quizzes, etc).
+modifyuserauth($udom,$uname,$umode,$upass) : modify user authentication
 
 =item *
 
-countacc($url) : count the number of accesses to a given URL
+modifyuser($udom,$uname,$uid,$umode,$upass,$first,$middle,$last,$gene) : 
+modify user
 
 =item *
 
-sub checkout($symb,$tuname,$tudom,$tcrsid) : check out an item
+modifystudent($udom,$uname,$uid,$umode,$upass,$first,$middle,$last,$gene,$usec,$end,$start) : modify student
 
 =item *
 
-sub checkin($token) : check in an item
+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
 
 =item *
 
-sub expirespread($uname,$udom,$stype,$usymb) : set expire date for spreadsheet
+revokerole($udom,$uname,$url,$role) : revoke a role for url
 
 =item *
 
-devalidate($symb) : devalidate spreadsheets
+revokecustomrole($udom,$uname,$url,$role) : revoke a custom role
+
+=back
+
+=head2 Course Infomation
+
+=over 4
 
 =item *
 
-hash2str(%hash) : convert a hash into a string complete with escaping and '='
-and '&' separators, supports elements that are arrayrefs and hashrefs
+coursedescription($courseid) : course description
 
 =item *
 
-hashref2str($hashref) : convert a hashref into a string complete with
-escaping and '=' and '&' separators, supports elements that are
-arrayrefs and hashrefs
+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.
+
+=back
+
+=head2 Course Modification
+
+=over 4
 
 =item *
 
-arrayref2str($arrayref) : convert an arrayref into a string complete
-with escaping and '&' separators, supports elements that are arrayrefs
-and hashrefs
+writecoursepref($courseid,%prefs) : write preferences (environment
+database) for a course
 
 =item *
 
-str2hash($string) : convert string to hash using unescaping and
-splitting on '=' and '&', supports elements that are arrayrefs and
-hashrefs
+createcourse($udom,$description,$url) : make/modify course
+
+=back
+
+=head2 Resource Subroutines
+
+=over 4
 
 =item *
 
-str2array($string) : convert string to hash using unescaping and
-splitting on '&', supports elements that are arrayrefs and hashrefs
+subscribe($fname) : subscribe to a resource, returns URL if possible (probably should use repcopy instead)
 
 =item *
 
-tmpreset($symb,$namespace,$domain,$stuname) : temporary storage
+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/....)
+
+=back
+
+=head2 Resource Information
+
+=over 4
 
 =item *
 
-tmprestore($symb,$namespace,$domain,$stuname) : temporary restore
+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)
 
 =item *
 
-store($storehash,$symb,$namespace,$domain,$stuname) : 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
+directcondval($number) : get current value of a condition; reads from a state
+string
 
 =item *
 
-cstore($storehash,$symb,$namespace,$domain,$stuname) : same as store but
-uses critical subroutine
+condval($condidx) : value of condition index based on state
 
 =item *
 
-restore($symb,$namespace,$domain,$stuname) : returns hash for this symb;
-all args are optional
+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
 
 =item *
 
-coursedescription($courseid) : course description
+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
 
 =item *
 
-rolesinit($domain,$username,$authhost) : get user privileges
+symbread($filename) : return symbolic list entry (filename argument optional);
+returns the data handle
 
 =item *
 
-get($namespace,$storearr,$udomain,$uname) : returns hash with keys from array
-reference filled in from namesp ($udomain and $uname are optional)
+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'}
+
 
 =item *
 
-del($namespace,$storearr,$udomain,$uname) : deletes keys out of array from
-namesp ($udomain and $uname are optional)
+symbclean($symb) : removes versions numbers from a symb, returns the
+cleaned symb
 
 =item *
 
-dump($namespace,$udomain,$uname,$regexp) : 
-dumps the complete (or key matching regexp) namespace into a hash
-($udomain, $uname and $regexp are optional)
+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.
 
 =item *
 
-put($namespace,$storehash,$udomain,$uname) : stores hash in namesp
-($udomain and $uname are optional)
+numval($salt) : return random seed value (addend for rndseed)
 
 =item *
 
-cput($namespace,$storehash,$udomain,$uname) : critical put
-($udomain and $uname are optional)
+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
 
 =item *
 
-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)
+ireceipt($funame,$fudom,$fucourseid,$fusymb) : return unique,
+unfakeable, receipt
 
 =item *
 
-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
+receipt() : API to ireceipt working off of ENV values; given out to users
 
 =item *
 
-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
+countacc($url) : count the number of accesses to a given URL
 
 =item *
 
-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
+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
 
 =item *
 
-plaintext($short) : return value in %prp hash (rolesplain.tab); plain text
-explanation of a user role term
+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)
 
 =item *
 
-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")
+expirespread($uname,$udom,$stype,$usymb) : set expire date for spreadsheet
 
 =item *
 
-modifyuserauth($udom,$uname,$umode,$upass) : modify user authentication
+devalidate($symb) : devalidate temporary spreadsheet calculations,
+forcing spreadsheet to reevaluate the resource scores next time.
+
+=back
+
+=head2 Storing/Retreiving Data
+
+=over 4
 
 =item *
 
-modifyuser($udom,$uname,$uid,$umode,$upass,$first,$middle,$last,$gene) : 
-modify user
+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
 
 =item *
 
-modifystudent($udom,$uname,$uid,$umode,$upass,$first,$middle,$last,$gene,$usec,
-$end,$start) : modify student
+cstore($storehash,$symb,$namespace,$udom,$uname) : same as store but
+uses critical subroutine
 
 =item *
 
-writecoursepref($courseid,%prefs) : write preferences for a course
+restore($symb,$namespace,$udom,$uname) : returns hash for this symb;
+all args are optional
 
 =item *
 
-createcourse($udom,$description,$url) : make/modify course
+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
 
 =item *
 
-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
+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.
 
 =item *
 
-revokerole($udom,$uname,$url,$role) : revoke a role for url
+tmpreset($symb,$namespace,$udom,$uname) : temporary storage reset,
+deltes all keys for $symb form the temporary storage hash.
 
 =item *
 
-revokecustomrole($udom,$uname,$url,$role) : revoke a custom role
+get($namespace,$storearr,$udom,$uname) : returns hash with keys from array
+reference filled in from namesp ($udom and $uname are optional)
+
+=item *
+
+del($namespace,$storearr,$udom,$uname) : deletes keys out of array from
+namesp ($udom and $uname are optional)
+
+=item *
+
+dump($namespace,$udom,$uname,$regexp) : 
+dumps the complete (or key matching regexp) namespace into a hash
+($udom, $uname and $regexp are optional)
+
+=item *
+
+put($namespace,$storehash,$udom,$uname) : stores hash in namesp
+($udom and $uname are optional)
+
+=item *
+
+cput($namespace,$storehash,$udom,$uname) : critical put
+($udom and $uname are optional)
+
+=item *
+
+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)
+
+=item *
+
+log($udom,$name,$home,$message) : write to permanent log for user; use
+critical subroutine
+
+=back
+
+=head2 Network Status Functions
+
+=over 4
 
 =item *
 
@@ -3343,60 +3482,94 @@ dirlist($uri) : return directory list ba
 
 =item *
 
-directcondval($number) : get current value of a condition; reads from a state
-string
+spareserver() : find server with least workload from spare.tab
+
+=back
+
+=head2 Apache Request
+
+=over 4
 
 =item *
 
-condval($condidx) : value of condition index based on state
+ssi($url,%hash) : server side include, does a complete request cycle on url to
+localhost, posts hash
+
+=back
+
+=head2 Data to String to Data
+
+=over 4
 
 =item *
 
-EXT($varname,$symbparm) : value of a variable
+hash2str(%hash) : convert a hash into a string complete with escaping and '='
+and '&' separators, supports elements that are arrayrefs and hashrefs
 
 =item *
 
-metadata($uri,$what,$liburi,$prefix,$depthcount) : get metadata; returns the
-metadata entry for a file; entry='keys', returns a comma separated list of keys
+hashref2str($hashref) : convert a hashref into a string complete with
+escaping and '=' and '&' separators, supports elements that are
+arrayrefs and hashrefs
 
 =item *
 
-symblist($mapname,%newhash) : update symbolic storage links
+arrayref2str($arrayref) : convert an arrayref into a string complete
+with escaping and '&' separators, supports elements that are arrayrefs
+and hashrefs
 
 =item *
 
-symbread($filename) : return symbolic list entry (filename argument optional);
-returns the data handle
+str2hash($string) : convert string to hash using unescaping and
+splitting on '=' and '&', supports elements that are arrayrefs and
+hashrefs
 
 =item *
 
-numval($salt) : return random seed value (addend for rndseed)
+str2array($string) : convert string to hash using unescaping and
+splitting on '&', supports elements that are arrayrefs and hashrefs
+
+=back
+
+=head2 Logging Routines
+
+=over 4
+
+These routines allow one to make log messages in the lonnet.log and
+lonnet.perm logfiles.
 
 =item *
 
-rndseed($symb,$courseid,$domain,$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
+logtouch() : make sure the logfile, lonnet.log, exists
 
 =item *
 
-ireceipt($funame,$fudom,$fucourseid,$fusymb) : return unique,
-unfakeable, receipt
+logthis() : append message to the normal lonnet.log file, it gets
+preiodically rolled over and deleted.
 
 =item *
 
-receipt() : API to ireceipt working off of ENV values; given out to users
+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.
+
+=back
+
+=head2 General File Helper Routines
+
+=over 4
 
 =item *
 
-getfile($file) : serves up a file, returns the contents of a file or -1;
-replicates and subscribes to the file
+getfile($file) : returns the entire contents of a file or -1; it
+properly subscribes to and replicates the file if neccessary.
 
 =item *
 
-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)
+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)
 
 =item *
 
@@ -3407,6 +3580,12 @@ filelocation except for hrefs
 
 declutter() : declutters URLs (remove docroot, beginning slashes, 'res' etc)
 
+=back
+
+=head2 HTTP Helper Routines
+
+=over 4
+
 =item *
 
 escape() : unpack non-word characters into CGI-compatible hex codes
@@ -3415,6 +3594,52 @@ escape() : unpack non-word characters in
 
 unescape() : pack CGI-compatible hex codes into actual non-word ASCII character
 
+=back
+
+=head1 PRIVATE SUBROUTINES
+
+=head2 Underlying communication routines (Shouldn't call)
+
+=over 4
+
+=item *
+
+subreply() : tries to pass a message to lonc, returns con_lost if incapable
+
+=item *
+
+reply() : uses subreply to send a message to remote machine, logs all failures
+
+=item *
+
+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
+
+=item *
+
+reconlonc() : tries to reconnect lonc client processes.
+
+=back
+
+=head2 Resource Access Logging
+
+=over 4
+
+=item *
+
+flushcourselogs() : flush (save) buffer logs and access logs
+
+=item *
+
+courselog($what) : save message for course in hash
+
+=item *
+
+courseacclog($what) : save message for course using &courselog().  Perform
+special processing for specific resource types (problems, exams, quizzes, etc).
+
 =item *
 
 goodbye() : flush course logs and log shutting down; it is called in srm.conf
@@ -3422,4 +3647,14 @@ as a PerlChildExitHandler
 
 =back
 
+=head2 Other
+
+=over 4
+
+=item *
+
+symblist($mapname,%newhash) : update symbolic storage links
+
+=back
+
 =cut