MDL-31863 Web Service : get_files() optional $modified timestamp returns files change...
[moodle.git] / files / externallib.php
CommitLineData
249c4f60 1<?php
249c4f60
DC
2// This file is part of Moodle - http://moodle.org/
3//
4// Moodle is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// Moodle is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
16
4615817d 17
249c4f60
DC
18/**
19 * External files API
20 *
4615817d
JM
21 * @package core_files
22 * @category external
23 * @copyright 2010 Dongsheng Cai
249c4f60
DC
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
27require_once("$CFG->libdir/externallib.php");
28require_once("$CFG->libdir/filelib.php");
29
5d1017e1 30/**
4615817d
JM
31 * Files external functions
32 *
33 * @package core_files
34 * @category external
35 * @copyright 2011 Jerome Mouneyrac
36 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
37 * @since Moodle 2.2
5d1017e1
JM
38 */
39class core_files_external extends external_api {
249c4f60
DC
40
41 /**
42 * Returns description of get_files parameters
4615817d 43 *
249c4f60 44 * @return external_function_parameters
4615817d 45 * @since Moodle 2.2
249c4f60
DC
46 */
47 public static function get_files_parameters() {
48 return new external_function_parameters(
49 array(
218a7c5f
DC
50 'contextid' => new external_value(PARAM_INT, 'context id'),
51 'component' => new external_value(PARAM_TEXT, 'component'),
52 'filearea' => new external_value(PARAM_TEXT, 'file area'),
53 'itemid' => new external_value(PARAM_INT, 'associated id'),
54 'filepath' => new external_value(PARAM_PATH, 'file path'),
25ccaf54 55 'filename' => new external_value(PARAM_FILE, 'file name'),
130d3fbf 56 'modified' => new external_value(PARAM_INT, 'timestamp to return files changed after this time.', VALUE_DEFAULT, null)
249c4f60
DC
57 )
58 );
59 }
60
61 /**
62 * Return moodle files listing
4615817d
JM
63 *
64 * @param int $contextid context id
65 * @param int $component component
66 * @param int $filearea file aera
67 * @param int $itemid item id
68 * @param string $filepath file path
69 * @param string $filename file name
130d3fbf 70 * @param int $modified timestamp to return files changed after this time.
249c4f60 71 * @return array
4615817d 72 * @since Moodle 2.2
249c4f60 73 */
25ccaf54 74 public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename, $modified = null) {
218a7c5f 75 global $CFG, $USER, $OUTPUT;
25ccaf54
YY
76 $fileinfo = self::validate_parameters(self::get_files_parameters(), array(
77 'contextid'=>$contextid, 'component'=>$component, 'filearea'=>$filearea,
78 'itemid'=>$itemid, 'filepath'=>$filepath, 'filename'=>$filename, 'modified'=>$modified));
64f93798 79
218a7c5f 80 $browser = get_file_browser();
64f93798 81
64f93798
PS
82 if (empty($fileinfo['contextid'])) {
83 $context = get_system_context();
84 } else {
85 $context = get_context_instance_by_id($fileinfo['contextid']);
86 }
87 if (empty($fileinfo['component'])) {
88 $fileinfo['component'] = null;
89 }
90 if (empty($fileinfo['filearea'])) {
91 $fileinfo['filearea'] = null;
92 }
249c4f60
DC
93 if (empty($fileinfo['itemid'])) {
94 $fileinfo['itemid'] = null;
95 }
96 if (empty($fileinfo['filename'])) {
97 $fileinfo['filename'] = null;
98 }
99 if (empty($fileinfo['filepath'])) {
100 $fileinfo['filepath'] = null;
101 }
249c4f60 102
218a7c5f
DC
103 $return = array();
104 $return['parents'] = array();
105 $return['files'] = array();
25ccaf54
YY
106 if ($file = $browser->get_file_info(
107 $context, $fileinfo['component'], $fileinfo['filearea'], $fileinfo['itemid'],
108 $fileinfo['filepath'], $fileinfo['filename'])) {
218a7c5f
DC
109 $level = $file->get_parent();
110 while ($level) {
111 $params = $level->get_params();
112 $params['filename'] = $level->get_visible_name();
113 array_unshift($return['parents'], $params);
114 $level = $level->get_parent();
115 }
116 $list = array();
117 $children = $file->get_children();
118 foreach ($children as $child) {
119
120 $params = $child->get_params();
25ccaf54 121 $timemodified = $child->get_timemodified();
218a7c5f
DC
122
123 if ($child->is_directory()) {
130d3fbf 124 if ((is_null($modified)) or ($modified < $timemodified)) {
25ccaf54
YY
125 $node = array(
126 'contextid' => $params['contextid'],
127 'component' => $params['component'],
128 'filearea' => $params['filearea'],
129 'itemid' => $params['itemid'],
130 'filepath' => $params['filepath'],
131 'filename' => $child->get_visible_name(),
132 'url' => null,
133 'isdir' => true,
134 'timemodified' => $timemodified
135 );
136 $list[] = $node;
137 }
218a7c5f 138 } else {
130d3fbf 139 if ((is_null($modified)) or ($modified < $timemodified)) {
25ccaf54
YY
140 $node = array(
141 'contextid' => $params['contextid'],
142 'component' => $params['component'],
143 'filearea' => $params['filearea'],
144 'itemid' => $params['itemid'],
145 'filepath' => $params['filepath'],
146 'filename' => $child->get_visible_name(),
147 'url' => $child->get_url(),
148 'isdir' => false,
149 'timemodified' => $timemodified
150 );
151 $list[] = $node;
152 }
249c4f60
DC
153 }
154 }
249c4f60 155 }
218a7c5f 156 $return['files'] = $list;
249c4f60
DC
157 return $return;
158 }
159
160 /**
161 * Returns description of get_files returns
4615817d
JM
162 *
163 * @return external_single_structure
164 * @since Moodle 2.2
249c4f60
DC
165 */
166 public static function get_files_returns() {
167 return new external_single_structure(
168 array(
169 'parents' => new external_multiple_structure(
170 new external_single_structure(
171 array(
172 'contextid' => new external_value(PARAM_INT, ''),
aff24313
PS
173 'component' => new external_value(PARAM_COMPONENT, ''),
174 'filearea' => new external_value(PARAM_AREA, ''),
64f93798
PS
175 'itemid' => new external_value(PARAM_INT, ''),
176 'filepath' => new external_value(PARAM_TEXT, ''),
177 'filename' => new external_value(PARAM_TEXT, ''),
249c4f60
DC
178 )
179 )
180 ),
181 'files' => new external_multiple_structure(
182 new external_single_structure(
183 array(
64f93798 184 'contextid' => new external_value(PARAM_INT, ''),
aff24313
PS
185 'component' => new external_value(PARAM_COMPONENT, ''),
186 'filearea' => new external_value(PARAM_AREA, ''),
249c4f60 187 'itemid' => new external_value(PARAM_INT, ''),
64f93798 188 'filepath' => new external_value(PARAM_TEXT, ''),
218a7c5f 189 'filename' => new external_value(PARAM_FILE, ''),
249c4f60
DC
190 'isdir' => new external_value(PARAM_BOOL, ''),
191 'url' => new external_value(PARAM_TEXT, ''),
25ccaf54 192 'timemodified' => new external_value(PARAM_INT, ''),
249c4f60
DC
193 )
194 )
195 )
196 )
197 );
198 }
199
200 /**
201 * Returns description of upload parameters
4615817d 202 *
249c4f60 203 * @return external_function_parameters
4615817d 204 * @since Moodle 2.2
249c4f60
DC
205 */
206 public static function upload_parameters() {
207 return new external_function_parameters(
208 array(
218a7c5f 209 'contextid' => new external_value(PARAM_INT, 'context id'),
aff24313
PS
210 'component' => new external_value(PARAM_COMPONENT, 'component'),
211 'filearea' => new external_value(PARAM_AREA, 'file area'),
218a7c5f
DC
212 'itemid' => new external_value(PARAM_INT, 'associated id'),
213 'filepath' => new external_value(PARAM_PATH, 'file path'),
214 'filename' => new external_value(PARAM_FILE, 'file name'),
215 'filecontent' => new external_value(PARAM_TEXT, 'file content')
249c4f60
DC
216 )
217 );
218 }
219
220 /**
221 * Uploading a file to moodle
222 *
4615817d
JM
223 * @param int $contextid context id
224 * @param string $component component
225 * @param string $filearea file aera
226 * @param int $itemid item id
227 * @param string $filepath file path
228 * @param string $filename file name
229 * @param string $filecontent file content
249c4f60 230 * @return array
4615817d 231 * @since Moodle 2.2
249c4f60 232 */
218a7c5f 233 public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
249c4f60 234 global $USER, $CFG;
218a7c5f 235
25ccaf54
YY
236 $fileinfo = self::validate_parameters(self::upload_parameters(), array(
237 'contextid'=>$contextid, 'component'=>$component, 'filearea'=>$filearea, 'itemid'=>$itemid,
238 'filepath'=>$filepath, 'filename'=>$filename, 'filecontent'=>$filecontent));
249c4f60
DC
239
240 if (!isset($fileinfo['filecontent'])) {
241 throw new moodle_exception('nofile');
242 }
25ccaf54 243 // Saving file.
af9b1444 244 $dir = make_temp_directory('wsupload');
882efc3c 245
249c4f60 246 if (empty($fileinfo['filename'])) {
af08a48b 247 $filename = uniqid('wsupload', true).'_'.time().'.tmp';
249c4f60
DC
248 } else {
249 $filename = $fileinfo['filename'];
250 }
251
252 if (file_exists($dir.$filename)) {
218a7c5f
DC
253 $savedfilepath = $dir.uniqid('m').$filename;
254 } else {
255 $savedfilepath = $dir.$filename;
249c4f60
DC
256 }
257
249c4f60
DC
258 file_put_contents($savedfilepath, base64_decode($fileinfo['filecontent']));
259 unset($fileinfo['filecontent']);
260
249c4f60
DC
261 if (!empty($fileinfo['filepath'])) {
262 $filepath = $fileinfo['filepath'];
263 } else {
218a7c5f 264 $filepath = '/';
249c4f60 265 }
64f93798 266
249c4f60 267 if (isset($fileinfo['itemid'])) {
25ccaf54 268 // TODO MDL-31116 in user private area, itemid is always 0.
218a7c5f 269 $itemid = 0;
249c4f60 270 } else {
218a7c5f 271 throw new coding_exception('itemid cannot be empty');
249c4f60 272 }
218a7c5f 273
249c4f60
DC
274 if (!empty($fileinfo['contextid'])) {
275 $context = get_context_instance_by_id($fileinfo['contextid']);
276 } else {
277 $context = get_system_context();
278 }
279
218a7c5f
DC
280 if (!($fileinfo['component'] == 'user' and $fileinfo['filearea'] == 'private')) {
281 throw new coding_exception('File can be uploaded to user private area only');
282 } else {
25ccaf54 283 // TODO MDL-31116 hard-coded to use user_private area.
218a7c5f
DC
284 $component = 'user';
285 $filearea = 'private';
286 }
64f93798 287
249c4f60
DC
288 $browser = get_file_browser();
289
25ccaf54 290 // Check existing file.
218a7c5f 291 if ($file = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, $filename)) {
249c4f60
DC
292 throw new moodle_exception('fileexist');
293 }
294
25ccaf54 295 // Move file to filepool.
218a7c5f
DC
296 if ($dir = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, '.')) {
297 $info = $dir->create_file_from_pathname($filename, $savedfilepath);
298 $params = $info->get_params();
249c4f60 299 unlink($savedfilepath);
218a7c5f
DC
300 return array(
301 'contextid'=>$params['contextid'],
302 'component'=>$params['component'],
303 'filearea'=>$params['filearea'],
304 'itemid'=>$params['itemid'],
305 'filepath'=>$params['filepath'],
306 'filename'=>$params['filename'],
307 'url'=>$info->get_url()
308 );
309 } else {
310 throw new moodle_exception('nofile');
249c4f60 311 }
249c4f60
DC
312 }
313
314 /**
315 * Returns description of upload returns
4615817d
JM
316 *
317 * @return external_single_structure
318 * @since Moodle 2.2
249c4f60
DC
319 */
320 public static function upload_returns() {
321 return new external_single_structure(
322 array(
218a7c5f 323 'contextid' => new external_value(PARAM_INT, ''),
aff24313
PS
324 'component' => new external_value(PARAM_COMPONENT, ''),
325 'filearea' => new external_value(PARAM_AREA, ''),
218a7c5f 326 'itemid' => new external_value(PARAM_INT, ''),
249c4f60 327 'filepath' => new external_value(PARAM_TEXT, ''),
218a7c5f
DC
328 'filename' => new external_value(PARAM_FILE, ''),
329 'url' => new external_value(PARAM_TEXT, ''),
249c4f60
DC
330 )
331 );
332 }
249c4f60 333}
5d1017e1
JM
334
335/**
4615817d
JM
336 * Deprecated files external functions
337 *
338 * @package core_files
339 * @copyright 2010 Dongsheng Cai
340 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
341 * @since Moodle 2.0
342 * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
343 * @todo MDL-31194 This will be deleted in Moodle 2.5.
344 * @see core_files_external
5d1017e1
JM
345 */
346class moodle_file_external extends external_api {
347
348 /**
349 * Returns description of get_files parameters
4615817d 350 *
5d1017e1 351 * @return external_function_parameters
4615817d
JM
352 * @since Moodle 2.0
353 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
354 * @todo MDL-31194 This will be deleted in Moodle 2.5.
355 * @see core_files_external::get_files_parameters()
5d1017e1
JM
356 */
357 public static function get_files_parameters() {
358 return core_files_external::get_files_parameters();
359 }
360
361 /**
362 * Return moodle files listing
4615817d 363 *
5d1017e1
JM
364 * @param int $contextid
365 * @param int $component
366 * @param int $filearea
367 * @param int $itemid
368 * @param string $filepath
369 * @param string $filename
370 * @return array
4615817d
JM
371 * @since Moodle 2.0
372 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
373 * @todo MDL-31194 This will be deleted in Moodle 2.5.
374 * @see core_files_external::get_files()
5d1017e1
JM
375 */
376 public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename) {
377 return core_files_external::get_files($contextid, $component, $filearea, $itemid, $filepath, $filename);
378 }
379
380 /**
381 * Returns description of get_files returns
4615817d
JM
382 *
383 * @return external_single_structure
384 * @since Moodle 2.0
385 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
386 * @todo MDL-31194 This will be deleted in Moodle 2.5.
387 * @see core_files_external::get_files_returns()
5d1017e1
JM
388 */
389 public static function get_files_returns() {
390 return core_files_external::get_files_returns();
391 }
392
393 /**
394 * Returns description of upload parameters
4615817d 395 *
5d1017e1 396 * @return external_function_parameters
4615817d
JM
397 * @since Moodle 2.0
398 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
399 * @todo MDL-31194 This will be deleted in Moodle 2.5.
400 * @see core_files_external::upload_parameters()
5d1017e1
JM
401 */
402 public static function upload_parameters() {
403 return core_files_external::upload_parameters();
404 }
405
406 /**
407 * Uploading a file to moodle
4615817d 408 *
5d1017e1
JM
409 * @param int $contextid
410 * @param string $component
411 * @param string $filearea
412 * @param int $itemid
413 * @param string $filepath
414 * @param string $filename
415 * @param string $filecontent
416 * @return array
4615817d
JM
417 * @since Moodle 2.0
418 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
419 * @todo MDL-31194 This will be deleted in Moodle 2.5.
420 * @see core_files_external::upload()
5d1017e1
JM
421 */
422 public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
423 return core_files_external::upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent);
424 }
425
426 /**
427 * Returns description of upload returns
4615817d
JM
428 *
429 * @return external_single_structure
430 * @since Moodle 2.0
431 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
432 * @todo MDL-31194 This will be deleted in Moodle 2.5.
433 * @see core_files_external::upload_returns()
5d1017e1
JM
434 */
435 public static function upload_returns() {
436 return core_files_external::upload_returns();
437 }
438}