MDL-15919 support for archive fixing & fixed inline docs a bit

lib/file/stored_file.php

@@ -109,7 +109,17 @@ class stored_file {
     }
 
     /**
-     * Unzip file to given file path (real OS filesystem), existing files are overwrited
+     * List contents of archive
+     * @param object $file_packer
+     * @return array of file infos
+     */
+    public function list_files(file_packer $packer) {
+        $archivefile = $this->get_content_file_location();
+        return $packer->list_files($archivefile);
+    }
+
+    /**
+     * Extract file to given file path (real OS filesystem), existing files are overwrited
      * @param object $file_packer
      * @param string $pathname target directory
      * @return mixed list of processed files; false if error
@@ -120,7 +130,7 @@ class stored_file {
     }
 
     /**
-     * Unzip file to given file path (real OS filesystem), existing files are overwrited
+     * Extract file to given file path (real OS filesystem), existing files are overwrited
      * @param object $file_packer
      * @param int $contextid
      * @param string $filearea
@@ -135,9 +145,9 @@ class stored_file {
     }
 
     /**
-     * Add file/directory into zip archive
-     * @param object $ziparchive
-     * @param string $archivepath pathname in zip archive
+     * Add file/directory into archive
+     * @param object $filearch
+     * @param string $archivepath pathname in archive
      * @return bool success
      */
     public function archive_file(file_archive $filearch, $archivepath) {

lib/packer/file_packer.php

@@ -44,4 +44,9 @@ abstract class file_packer {
      */
     public abstract function extract_to_storage($archivefile, $contextid, $filearea, $itemid, $pathbase, $userid=null);
 
+    /**
+     * Returns array of info about all files in archive
+     * @return array of file infos
+     */
+    public abstract function list_files($archivefile);
 }

lib/packer/zip_packer.php

@@ -371,4 +371,23 @@ class zip_packer extends file_packer {
         $ziparch->close();
         return $processed;
     }
+
+    /**
+     * Returns array of info about all files in archive
+     * @return array of file infos
+     */
+    public function list_files($archivefile) {
+        if (!is_string($archivefile)) {
+            return $archivefile->list_files();
+        }
+
+        $ziparch = new zip_archive();
+        if (!$ziparch->open($archivefile, file_archive::OPEN)) {
+            return false;
+        }
+        $list = $ziparch->list_files();
+        $ziparch->close();
+        return $list;
+    }
+
 }