files/externallib.php

   1 <?php
   2
   3 // This file is part of Moodle - http://moodle.org/
   4 //
   5 // Moodle is free software: you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation, either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // Moodle is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 /**
  19  * External files API
  20  *
  21  * @package    moodlecore
  22  * @subpackage webservice
  23  * @copyright  2010 Dongsheng Cai <dongsheng@moodle.com>
  24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25  */
  26
  27 require_once("$CFG->libdir/externallib.php");
  28 require_once("$CFG->libdir/filelib.php");
  29
  30 class moodle_file_external extends external_api {
  31
  32     /**
  33      * Returns description of get_files parameters
  34      * @return external_function_parameters
  35      */
  36     public static function get_files_parameters() {
  37         return new external_function_parameters(
  38             array(
  39                 'contextid' => new external_value(PARAM_INT, 'context id'),
  40                 'component' => new external_value(PARAM_TEXT, 'component'),
  41                 'filearea'  => new external_value(PARAM_TEXT, 'file area'),
  42                 'itemid'    => new external_value(PARAM_INT, 'associated id'),
  43                 'filepath'  => new external_value(PARAM_PATH, 'file path'),
  44                 'filename'  => new external_value(PARAM_FILE, 'file name')
  45             )
  46         );
  47     }
  48
  49     /**
  50      * Return moodle files listing
  51      * @param int $contextid
  52      * @param int $component
  53      * @param int $filearea
  54      * @param int $itemid
  55      * @param string $filepath
  56      * @param string $filename
  57      * @return array
  58      */
  59     public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename) {
  60         global $CFG, $USER, $OUTPUT;
  61         $fileinfo = self::validate_parameters(self::get_files_parameters(), array('contextid'=>$contextid, 'component'=>$component, 'filearea'=>$filearea, 'itemid'=>$itemid, 'filepath'=>$filepath, 'filename'=>$filename));
  62
  63         $browser = get_file_browser();
  64
  65         if (empty($fileinfo['contextid'])) {
  66             $context  = get_system_context();
  67         } else {
  68             $context  = get_context_instance_by_id($fileinfo['contextid']);
  69         }
  70         if (empty($fileinfo['component'])) {
  71             $fileinfo['component'] = null;
  72         }
  73         if (empty($fileinfo['filearea'])) {
  74             $fileinfo['filearea'] = null;
  75         }
  76         if (empty($fileinfo['itemid'])) {
  77             $fileinfo['itemid'] = null;
  78         }
  79         if (empty($fileinfo['filename'])) {
  80             $fileinfo['filename'] = null;
  81         }
  82         if (empty($fileinfo['filepath'])) {
  83             $fileinfo['filepath'] = null;
  84         }
  85
  86         $return = array();
  87         $return['parents'] = array();
  88         $return['files'] = array();
  89         if ($file = $browser->get_file_info($context, $fileinfo['component'], $fileinfo['filearea'], $fileinfo['itemid'], $fileinfo['filepath'], $fileinfo['filename'])) {
  90             $level = $file->get_parent();
  91             while ($level) {
  92                 $params = $level->get_params();
  93                 $params['filename'] = $level->get_visible_name();
  94                 array_unshift($return['parents'], $params);
  95                 $level = $level->get_parent();
  96             }
  97             $list = array();
  98             $children = $file->get_children();
  99             foreach ($children as $child) {
 100
 101                 $params = $child->get_params();
 102
 103                 if ($child->is_directory()) {
 104                     $node = array(
 105                         'contextid' => $params['contextid'],
 106                         'component' => $params['component'],
 107                         'filearea'  => $params['filearea'],
 108                         'itemid'    => $params['itemid'],
 109                         'filepath'  => $params['filepath'],
 110                         'filename'  => $child->get_visible_name(),
 111                         'url'       => null,
 112                         'isdir'     => true
 113                     );
 114                     $list[] = $node;
 115                 } else {
 116                     $node = array(
 117                         'contextid' => $params['contextid'],
 118                         'component' => $params['component'],
 119                         'filearea'  => $params['filearea'],
 120                         'itemid'    => $params['itemid'],
 121                         'filepath'  => $params['filepath'],
 122                         'filename'  => $child->get_visible_name(),
 123                         'url'       => $child->get_url(),
 124                         'isdir'     => false
 125                     );
 126                     $list[] = $node;
 127                 }
 128             }
 129         }
 130         $return['files'] = $list;
 131         return $return;
 132     }
 133
 134     /**
 135      * Returns description of get_files returns
 136      * @return external_multiple_structure
 137      */
 138     public static function get_files_returns() {
 139         return new external_single_structure(
 140             array(
 141                 'parents' => new external_multiple_structure(
 142                     new external_single_structure(
 143                         array(
 144                             'contextid' => new external_value(PARAM_INT, ''),
 145                             'component' => new external_value(PARAM_ALPHAEXT, ''),
 146                             'filearea'  => new external_value(PARAM_ALPHAEXT, ''),
 147                             'itemid'    => new external_value(PARAM_INT, ''),
 148                             'filepath'  => new external_value(PARAM_TEXT, ''),
 149                             'filename'  => new external_value(PARAM_TEXT, ''),
 150                         )
 151                     )
 152                 ),
 153                 'files' => new external_multiple_structure(
 154                     new external_single_structure(
 155                         array(
 156                             'contextid' => new external_value(PARAM_INT, ''),
 157                             'component' => new external_value(PARAM_ALPHAEXT, ''),
 158                             'filearea'  => new external_value(PARAM_ALPHAEXT, ''),
 159                             'itemid'   => new external_value(PARAM_INT, ''),
 160                             'filepath' => new external_value(PARAM_TEXT, ''),
 161                             'filename' => new external_value(PARAM_FILE, ''),
 162                             'isdir'    => new external_value(PARAM_BOOL, ''),
 163                             'url'      => new external_value(PARAM_TEXT, ''),
 164                         )
 165                     )
 166                 )
 167             )
 168         );
 169     }
 170
 171     /**
 172      * Returns description of upload parameters
 173      * @return external_function_parameters
 174      */
 175     public static function upload_parameters() {
 176         return new external_function_parameters(
 177             array(
 178                 'contextid' => new external_value(PARAM_INT, 'context id'),
 179                 'component' => new external_value(PARAM_ALPHAEXT, 'component'),
 180                 'filearea'  => new external_value(PARAM_ALPHAEXT, 'file area'),
 181                 'itemid'    => new external_value(PARAM_INT, 'associated id'),
 182                 'filepath'  => new external_value(PARAM_PATH, 'file path'),
 183                 'filename'  => new external_value(PARAM_FILE, 'file name'),
 184                 'filecontent' => new external_value(PARAM_TEXT, 'file content')
 185             )
 186         );
 187     }
 188
 189     /**
 190      * Uploading a file to moodle
 191      *
 192      * @param int $contextid
 193      * @param string $component
 194      * @param string $filearea
 195      * @param int $itemid
 196      * @param string $filepath
 197      * @param string $filename
 198      * @param string $filecontent
 199      * @return array
 200      */
 201     public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
 202         global $USER, $CFG;
 203
 204         $fileinfo = self::validate_parameters(self::upload_parameters(), array('contextid'=>$contextid, 'component'=>$component, 'filearea'=>$filearea, 'itemid'=>$itemid, 'filepath'=>$filepath, 'filename'=>$filename, 'filecontent'=>$filecontent));
 205
 206         if (!isset($fileinfo['filecontent'])) {
 207             throw new moodle_exception('nofile');
 208         }
 209         // saving file
 210         $dir = make_upload_directory('temp/wsupload');
 211
 212         if (empty($fileinfo['filename'])) {
 213             $filename = uniqid('wsupload').'_'.time().'.tmp';
 214         } else {
 215             $filename = $fileinfo['filename'];
 216         }
 217
 218         if (file_exists($dir.$filename)) {
 219             $savedfilepath = $dir.uniqid('m').$filename;
 220         } else {
 221             $savedfilepath = $dir.$filename;
 222         }
 223
 224
 225         file_put_contents($savedfilepath, base64_decode($fileinfo['filecontent']));
 226         unset($fileinfo['filecontent']);
 227
 228         if (!empty($fileinfo['filepath'])) {
 229             $filepath = $fileinfo['filepath'];
 230         } else {
 231             $filepath = '/';
 232         }
 233
 234         if (isset($fileinfo['itemid'])) {
 235             // TODO: in user private area, itemid is always 0
 236             $itemid = 0;
 237         } else {
 238             throw new coding_exception('itemid cannot be empty');
 239         }
 240
 241         if (!empty($fileinfo['contextid'])) {
 242             $context = get_context_instance_by_id($fileinfo['contextid']);
 243         } else {
 244             $context = get_system_context();
 245         }
 246
 247         if (!($fileinfo['component'] == 'user' and $fileinfo['filearea'] == 'private')) {
 248             throw new coding_exception('File can be uploaded to user private area only');
 249         } else {
 250             // TODO: hard-coded to use user_private area
 251             $component = 'user';
 252             $filearea = 'private';
 253         }
 254
 255         $browser = get_file_browser();
 256
 257         // check existing file
 258         if ($file = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, $filename)) {
 259             throw new moodle_exception('fileexist');
 260         }
 261
 262         // move file to filepool
 263         if ($dir = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, '.')) {
 264             $info = $dir->create_file_from_pathname($filename, $savedfilepath);
 265             $params = $info->get_params();
 266             unlink($savedfilepath);
 267             return array(
 268                 'contextid'=>$params['contextid'],
 269                 'component'=>$params['component'],
 270                 'filearea'=>$params['filearea'],
 271                 'itemid'=>$params['itemid'],
 272                 'filepath'=>$params['filepath'],
 273                 'filename'=>$params['filename'],
 274                 'url'=>$info->get_url()
 275                 );
 276         } else {
 277             throw new moodle_exception('nofile');
 278         }
 279     }
 280
 281     /**
 282      * Returns description of upload returns
 283      * @return external_multiple_structure
 284      */
 285     public static function upload_returns() {
 286         return new external_single_structure(
 287              array(
 288                  'contextid' => new external_value(PARAM_INT, ''),
 289                  'component' => new external_value(PARAM_ALPHAEXT, ''),
 290                  'filearea'  => new external_value(PARAM_ALPHAEXT, ''),
 291                  'itemid'   => new external_value(PARAM_INT, ''),
 292                  'filepath' => new external_value(PARAM_TEXT, ''),
 293                  'filename' => new external_value(PARAM_FILE, ''),
 294                  'url'      => new external_value(PARAM_TEXT, ''),
 295              )
 296         );
 297     }
 298 }