[LON-CAPA-cvs] cvs: loncom /lonnet/perl lonnet.pm

[albertel]

albertel		Wed Mar 16 18:04:16 2005 EDT

  Modified files:              
    /loncom/lonnet/perl	lonnet.pm 
  Log:
  - adding documentation for the userfile functions
  
  
  
Index: loncom/lonnet/perl/lonnet.pm
diff -u loncom/lonnet/perl/lonnet.pm:1.607 loncom/lonnet/perl/lonnet.pm:1.608
--- loncom/lonnet/perl/lonnet.pm:1.607	Wed Mar 16 16:35:17 2005
+++ loncom/lonnet/perl/lonnet.pm	Wed Mar 16 18:04:16 2005
@@ -1,7 +1,7 @@
 # The LearningOnline Network
 # TCP networking package
 #
-# $Id: lonnet.pm,v 1.607 2005/03/16 21:35:17 raeburn Exp $
+# $Id: lonnet.pm,v 1.608 2005/03/16 23:04:16 albertel Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -1199,10 +1199,6 @@
     return $fetchresult;
 }
 
-# --------------- Take an uploaded file and put it into the userfiles directory
-# input: name of form element, coursedoc=1 means this is for the course
-# output: url of file in userspace
-
 sub clean_filename {
     my ($fname)=@_;
 # Replace Windows backslashes by forward slashes
@@ -1219,6 +1215,11 @@
     return $fname;
 }
 
+# --------------- Take an uploaded file and put it into the userfiles directory
+# input: name of form element, coursedoc=1 means this is for the course
+# output: url of file in userspace
+
+
 sub userfileupload {
     my ($formname,$coursedoc,$subdir)=@_;
     if (!defined($subdir)) { $subdir='unknown'; }
@@ -6476,6 +6477,91 @@
 
 =back
 
+=head2 Usererfile file routines (/uploaded*)
+
+=over 4
+
+=item *
+
+userfileupload(): main rotine for putting a file in a user or course's
+                  filespace, arguments are,
+
+ formname - required - this is the name of the element in $ENV where the
+           filename, and the contents of the file to create/modifed exist
+           the filename is in $ENV{'form.'.$formname.'.filename'} and the
+           contents of the file is located in $ENV{'form.'.$formname}
+ coursedoc - if true, store the file in the course of the active role
+             of the current user
+ subdir - required - subdirectory to put the file in under ../userfiles/
+         if undefined, it will be placed in "unknown"
+
+ (This routine calls clean_filename() to remove any dangerous
+ characters from the filename, and then calls finuserfileupload() to
+ complete the transaction)
+
+ returns either the url of the uploaded file (/uploaded/....) if successful
+ and /adm/notfound.html if unsuccessful
+
+=item *
+
+clean_filename(): routine for cleaing a filename up for storage in
+                 userfile space, argument is:
+
+ filename - proposed filename
+
+returns: the new clean filename
+
+=item *
+
+finishuserfileupload(): routine that creaes and sends the file to
+userspace, probably shouldn't be called directly
+
+  docuname: username or courseid of destination for the file
+  docudom: domain of user/course of destination for the file
+  docuhome: loncapa id of the library server that is getting the file
+  formname: same as for userfileupload()
+  fname: filename (inculding subdirectories) for the file
+
+ returns either the url of the uploaded file (/uploaded/....) if successful
+ and /adm/notfound.html if unsuccessful
+
+=item *
+
+renameuserfile(): renames an existing userfile to a new name
+
+  Args:
+   docuname: username or courseid of destination for the file
+   docudom: domain of user/course of destination for the file
+   old: current file name (including any subdirs under userfiles)
+   new: desired file name (including any subdirs under userfiles)
+
+=item *
+
+mkdiruserfile(): creates a directory is a userfiles dir
+
+  Args:
+   docuname: username or courseid of destination for the file
+   docudom: domain of user/course of destination for the file
+   dir: dir to create (including any subdirs under userfiles)
+
+=item *
+
+removeuserfile(): removes a file that exists in userfiles
+
+  Args:
+   docuname: username or courseid of destination for the file
+   docudom: domain of user/course of destination for the file
+   fname: filname to delete (including any subdirs under userfiles)
+
+=item *
+
+removeuploadedurl(): convience function for removeuserfile()
+
+  Args:
+   url:  a full /uploaded/... url to delete
+
+=back
+
 =head2 HTTP Helper Routines
 
 =over 4