3 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
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
27 require_once("$CFG->libdir/externallib.php");
28 require_once("$CFG->libdir/filelib.php");
33 class core_files_external
extends external_api
{
36 * Returns description of get_files parameters
37 * @return external_function_parameters
39 public static function get_files_parameters() {
40 return new external_function_parameters(
42 'contextid' => new external_value(PARAM_INT
, 'context id'),
43 'component' => new external_value(PARAM_TEXT
, 'component'),
44 'filearea' => new external_value(PARAM_TEXT
, 'file area'),
45 'itemid' => new external_value(PARAM_INT
, 'associated id'),
46 'filepath' => new external_value(PARAM_PATH
, 'file path'),
47 'filename' => new external_value(PARAM_FILE
, 'file name')
53 * Return moodle files listing
54 * @param int $contextid
55 * @param int $component
56 * @param int $filearea
58 * @param string $filepath
59 * @param string $filename
62 public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename) {
63 global $CFG, $USER, $OUTPUT;
64 $fileinfo = self
::validate_parameters(self
::get_files_parameters(), array('contextid'=>$contextid, 'component'=>$component, 'filearea'=>$filearea, 'itemid'=>$itemid, 'filepath'=>$filepath, 'filename'=>$filename));
66 $browser = get_file_browser();
68 if (empty($fileinfo['contextid'])) {
69 $context = get_system_context();
71 $context = get_context_instance_by_id($fileinfo['contextid']);
73 if (empty($fileinfo['component'])) {
74 $fileinfo['component'] = null;
76 if (empty($fileinfo['filearea'])) {
77 $fileinfo['filearea'] = null;
79 if (empty($fileinfo['itemid'])) {
80 $fileinfo['itemid'] = null;
82 if (empty($fileinfo['filename'])) {
83 $fileinfo['filename'] = null;
85 if (empty($fileinfo['filepath'])) {
86 $fileinfo['filepath'] = null;
90 $return['parents'] = array();
91 $return['files'] = array();
92 if ($file = $browser->get_file_info($context, $fileinfo['component'], $fileinfo['filearea'], $fileinfo['itemid'], $fileinfo['filepath'], $fileinfo['filename'])) {
93 $level = $file->get_parent();
95 $params = $level->get_params();
96 $params['filename'] = $level->get_visible_name();
97 array_unshift($return['parents'], $params);
98 $level = $level->get_parent();
101 $children = $file->get_children();
102 foreach ($children as $child) {
104 $params = $child->get_params();
106 if ($child->is_directory()) {
108 'contextid' => $params['contextid'],
109 'component' => $params['component'],
110 'filearea' => $params['filearea'],
111 'itemid' => $params['itemid'],
112 'filepath' => $params['filepath'],
113 'filename' => $child->get_visible_name(),
120 'contextid' => $params['contextid'],
121 'component' => $params['component'],
122 'filearea' => $params['filearea'],
123 'itemid' => $params['itemid'],
124 'filepath' => $params['filepath'],
125 'filename' => $child->get_visible_name(),
126 'url' => $child->get_url(),
133 $return['files'] = $list;
138 * Returns description of get_files returns
139 * @return external_multiple_structure
141 public static function get_files_returns() {
142 return new external_single_structure(
144 'parents' => new external_multiple_structure(
145 new external_single_structure(
147 'contextid' => new external_value(PARAM_INT
, ''),
148 'component' => new external_value(PARAM_COMPONENT
, ''),
149 'filearea' => new external_value(PARAM_AREA
, ''),
150 'itemid' => new external_value(PARAM_INT
, ''),
151 'filepath' => new external_value(PARAM_TEXT
, ''),
152 'filename' => new external_value(PARAM_TEXT
, ''),
156 'files' => new external_multiple_structure(
157 new external_single_structure(
159 'contextid' => new external_value(PARAM_INT
, ''),
160 'component' => new external_value(PARAM_COMPONENT
, ''),
161 'filearea' => new external_value(PARAM_AREA
, ''),
162 'itemid' => new external_value(PARAM_INT
, ''),
163 'filepath' => new external_value(PARAM_TEXT
, ''),
164 'filename' => new external_value(PARAM_FILE
, ''),
165 'isdir' => new external_value(PARAM_BOOL
, ''),
166 'url' => new external_value(PARAM_TEXT
, ''),
175 * Returns description of upload parameters
176 * @return external_function_parameters
178 public static function upload_parameters() {
179 return new external_function_parameters(
181 'contextid' => new external_value(PARAM_INT
, 'context id'),
182 'component' => new external_value(PARAM_COMPONENT
, 'component'),
183 'filearea' => new external_value(PARAM_AREA
, 'file area'),
184 'itemid' => new external_value(PARAM_INT
, 'associated id'),
185 'filepath' => new external_value(PARAM_PATH
, 'file path'),
186 'filename' => new external_value(PARAM_FILE
, 'file name'),
187 'filecontent' => new external_value(PARAM_TEXT
, 'file content')
193 * Uploading a file to moodle
195 * @param int $contextid
196 * @param string $component
197 * @param string $filearea
199 * @param string $filepath
200 * @param string $filename
201 * @param string $filecontent
204 public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
207 $fileinfo = self
::validate_parameters(self
::upload_parameters(), array('contextid'=>$contextid, 'component'=>$component, 'filearea'=>$filearea, 'itemid'=>$itemid, 'filepath'=>$filepath, 'filename'=>$filename, 'filecontent'=>$filecontent));
209 if (!isset($fileinfo['filecontent'])) {
210 throw new moodle_exception('nofile');
213 $dir = make_temp_directory('wsupload');
215 if (empty($fileinfo['filename'])) {
216 $filename = uniqid('wsupload', true).'_'.time().'.tmp';
218 $filename = $fileinfo['filename'];
221 if (file_exists($dir.$filename)) {
222 $savedfilepath = $dir.uniqid('m').$filename;
224 $savedfilepath = $dir.$filename;
228 file_put_contents($savedfilepath, base64_decode($fileinfo['filecontent']));
229 unset($fileinfo['filecontent']);
231 if (!empty($fileinfo['filepath'])) {
232 $filepath = $fileinfo['filepath'];
237 if (isset($fileinfo['itemid'])) {
238 // TODO: in user private area, itemid is always 0
241 throw new coding_exception('itemid cannot be empty');
244 if (!empty($fileinfo['contextid'])) {
245 $context = get_context_instance_by_id($fileinfo['contextid']);
247 $context = get_system_context();
250 if (!($fileinfo['component'] == 'user' and $fileinfo['filearea'] == 'private')) {
251 throw new coding_exception('File can be uploaded to user private area only');
253 // TODO: hard-coded to use user_private area
255 $filearea = 'private';
258 $browser = get_file_browser();
260 // check existing file
261 if ($file = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, $filename)) {
262 throw new moodle_exception('fileexist');
265 // move file to filepool
266 if ($dir = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, '.')) {
267 $info = $dir->create_file_from_pathname($filename, $savedfilepath);
268 $params = $info->get_params();
269 unlink($savedfilepath);
271 'contextid'=>$params['contextid'],
272 'component'=>$params['component'],
273 'filearea'=>$params['filearea'],
274 'itemid'=>$params['itemid'],
275 'filepath'=>$params['filepath'],
276 'filename'=>$params['filename'],
277 'url'=>$info->get_url()
280 throw new moodle_exception('nofile');
285 * Returns description of upload returns
286 * @return external_multiple_structure
288 public static function upload_returns() {
289 return new external_single_structure(
291 'contextid' => new external_value(PARAM_INT
, ''),
292 'component' => new external_value(PARAM_COMPONENT
, ''),
293 'filearea' => new external_value(PARAM_AREA
, ''),
294 'itemid' => new external_value(PARAM_INT
, ''),
295 'filepath' => new external_value(PARAM_TEXT
, ''),
296 'filename' => new external_value(PARAM_FILE
, ''),
297 'url' => new external_value(PARAM_TEXT
, ''),
304 * Deprecated files functions
305 * @deprecated since Moodle 2.2 please use core_files_external instead
307 class moodle_file_external
extends external_api
{
310 * Returns description of get_files parameters
311 * @deprecated since Moodle 2.2 please use core_files_external::get_files_parameters instead
312 * @return external_function_parameters
314 public static function get_files_parameters() {
315 return core_files_external
::get_files_parameters();
319 * Return moodle files listing
320 * @deprecated since Moodle 2.2 please use core_files_external::get_files instead
321 * @param int $contextid
322 * @param int $component
323 * @param int $filearea
325 * @param string $filepath
326 * @param string $filename
329 public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename) {
330 return core_files_external
::get_files($contextid, $component, $filearea, $itemid, $filepath, $filename);
334 * Returns description of get_files returns
335 * @deprecated since Moodle 2.2 please use core_files_external::get_files_returns instead
336 * @return external_multiple_structure
338 public static function get_files_returns() {
339 return core_files_external
::get_files_returns();
343 * Returns description of upload parameters
344 * @deprecated since Moodle 2.2 please use core_files_external::upload_parameters instead
345 * @return external_function_parameters
347 public static function upload_parameters() {
348 return core_files_external
::upload_parameters();
352 * Uploading a file to moodle
353 * @deprecated since Moodle 2.2 please use core_files_external::upload instead
354 * @param int $contextid
355 * @param string $component
356 * @param string $filearea
358 * @param string $filepath
359 * @param string $filename
360 * @param string $filecontent
363 public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
364 return core_files_external
::upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent);
368 * Returns description of upload returns
369 * @deprecated since Moodle 2.2 please use core_files_external::upload_returns instead
370 * @return external_multiple_structure
372 public static function upload_returns() {
373 return core_files_external
::upload_returns();