weekly release 2.3dev
[moodle.git] / files / externallib.php
CommitLineData
249c4f60
DC
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
27require_once("$CFG->libdir/externallib.php");
28require_once("$CFG->libdir/filelib.php");
29
5d1017e1
JM
30/**
31 * Files functions
32 */
33class core_files_external extends external_api {
249c4f60
DC
34
35 /**
36 * Returns description of get_files parameters
37 * @return external_function_parameters
38 */
39 public static function get_files_parameters() {
40 return new external_function_parameters(
41 array(
218a7c5f
DC
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')
249c4f60
DC
48 )
49 );
50 }
51
52 /**
53 * Return moodle files listing
218a7c5f
DC
54 * @param int $contextid
55 * @param int $component
56 * @param int $filearea
57 * @param int $itemid
58 * @param string $filepath
59 * @param string $filename
249c4f60
DC
60 * @return array
61 */
218a7c5f
DC
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));
64f93798 65
218a7c5f 66 $browser = get_file_browser();
64f93798 67
64f93798
PS
68 if (empty($fileinfo['contextid'])) {
69 $context = get_system_context();
70 } else {
71 $context = get_context_instance_by_id($fileinfo['contextid']);
72 }
73 if (empty($fileinfo['component'])) {
74 $fileinfo['component'] = null;
75 }
76 if (empty($fileinfo['filearea'])) {
77 $fileinfo['filearea'] = null;
78 }
249c4f60
DC
79 if (empty($fileinfo['itemid'])) {
80 $fileinfo['itemid'] = null;
81 }
82 if (empty($fileinfo['filename'])) {
83 $fileinfo['filename'] = null;
84 }
85 if (empty($fileinfo['filepath'])) {
86 $fileinfo['filepath'] = null;
87 }
249c4f60 88
218a7c5f
DC
89 $return = array();
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();
94 while ($level) {
95 $params = $level->get_params();
96 $params['filename'] = $level->get_visible_name();
97 array_unshift($return['parents'], $params);
98 $level = $level->get_parent();
99 }
100 $list = array();
101 $children = $file->get_children();
102 foreach ($children as $child) {
103
104 $params = $child->get_params();
105
106 if ($child->is_directory()) {
107 $node = array(
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(),
114 'url' => null,
115 'isdir' => true
116 );
117 $list[] = $node;
118 } else {
119 $node = array(
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(),
127 'isdir' => false
128 );
129 $list[] = $node;
249c4f60
DC
130 }
131 }
249c4f60 132 }
218a7c5f 133 $return['files'] = $list;
249c4f60
DC
134 return $return;
135 }
136
137 /**
138 * Returns description of get_files returns
139 * @return external_multiple_structure
140 */
141 public static function get_files_returns() {
142 return new external_single_structure(
143 array(
144 'parents' => new external_multiple_structure(
145 new external_single_structure(
146 array(
147 'contextid' => new external_value(PARAM_INT, ''),
aff24313
PS
148 'component' => new external_value(PARAM_COMPONENT, ''),
149 'filearea' => new external_value(PARAM_AREA, ''),
64f93798
PS
150 'itemid' => new external_value(PARAM_INT, ''),
151 'filepath' => new external_value(PARAM_TEXT, ''),
152 'filename' => new external_value(PARAM_TEXT, ''),
249c4f60
DC
153 )
154 )
155 ),
156 'files' => new external_multiple_structure(
157 new external_single_structure(
158 array(
64f93798 159 'contextid' => new external_value(PARAM_INT, ''),
aff24313
PS
160 'component' => new external_value(PARAM_COMPONENT, ''),
161 'filearea' => new external_value(PARAM_AREA, ''),
249c4f60 162 'itemid' => new external_value(PARAM_INT, ''),
64f93798 163 'filepath' => new external_value(PARAM_TEXT, ''),
218a7c5f 164 'filename' => new external_value(PARAM_FILE, ''),
249c4f60
DC
165 'isdir' => new external_value(PARAM_BOOL, ''),
166 'url' => new external_value(PARAM_TEXT, ''),
249c4f60
DC
167 )
168 )
169 )
170 )
171 );
172 }
173
174 /**
175 * Returns description of upload parameters
176 * @return external_function_parameters
177 */
178 public static function upload_parameters() {
179 return new external_function_parameters(
180 array(
218a7c5f 181 'contextid' => new external_value(PARAM_INT, 'context id'),
aff24313
PS
182 'component' => new external_value(PARAM_COMPONENT, 'component'),
183 'filearea' => new external_value(PARAM_AREA, 'file area'),
218a7c5f
DC
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')
249c4f60
DC
188 )
189 );
190 }
191
192 /**
193 * Uploading a file to moodle
194 *
218a7c5f
DC
195 * @param int $contextid
196 * @param string $component
197 * @param string $filearea
198 * @param int $itemid
199 * @param string $filepath
200 * @param string $filename
201 * @param string $filecontent
249c4f60
DC
202 * @return array
203 */
218a7c5f 204 public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
249c4f60 205 global $USER, $CFG;
218a7c5f
DC
206
207 $fileinfo = self::validate_parameters(self::upload_parameters(), array('contextid'=>$contextid, 'component'=>$component, 'filearea'=>$filearea, 'itemid'=>$itemid, 'filepath'=>$filepath, 'filename'=>$filename, 'filecontent'=>$filecontent));
249c4f60
DC
208
209 if (!isset($fileinfo['filecontent'])) {
210 throw new moodle_exception('nofile');
211 }
212 // saving file
af9b1444 213 $dir = make_temp_directory('wsupload');
882efc3c 214
249c4f60 215 if (empty($fileinfo['filename'])) {
af08a48b 216 $filename = uniqid('wsupload', true).'_'.time().'.tmp';
249c4f60
DC
217 } else {
218 $filename = $fileinfo['filename'];
219 }
220
221 if (file_exists($dir.$filename)) {
218a7c5f
DC
222 $savedfilepath = $dir.uniqid('m').$filename;
223 } else {
224 $savedfilepath = $dir.$filename;
249c4f60
DC
225 }
226
249c4f60
DC
227
228 file_put_contents($savedfilepath, base64_decode($fileinfo['filecontent']));
229 unset($fileinfo['filecontent']);
230
249c4f60
DC
231 if (!empty($fileinfo['filepath'])) {
232 $filepath = $fileinfo['filepath'];
233 } else {
218a7c5f 234 $filepath = '/';
249c4f60 235 }
64f93798 236
249c4f60 237 if (isset($fileinfo['itemid'])) {
218a7c5f
DC
238 // TODO: in user private area, itemid is always 0
239 $itemid = 0;
249c4f60 240 } else {
218a7c5f 241 throw new coding_exception('itemid cannot be empty');
249c4f60 242 }
218a7c5f 243
249c4f60
DC
244 if (!empty($fileinfo['contextid'])) {
245 $context = get_context_instance_by_id($fileinfo['contextid']);
246 } else {
247 $context = get_system_context();
248 }
249
218a7c5f
DC
250 if (!($fileinfo['component'] == 'user' and $fileinfo['filearea'] == 'private')) {
251 throw new coding_exception('File can be uploaded to user private area only');
252 } else {
253 // TODO: hard-coded to use user_private area
254 $component = 'user';
255 $filearea = 'private';
256 }
64f93798 257
249c4f60
DC
258 $browser = get_file_browser();
259
260 // check existing file
218a7c5f 261 if ($file = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, $filename)) {
249c4f60
DC
262 throw new moodle_exception('fileexist');
263 }
264
249c4f60 265 // move file to filepool
218a7c5f
DC
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();
249c4f60 269 unlink($savedfilepath);
218a7c5f
DC
270 return array(
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()
278 );
279 } else {
280 throw new moodle_exception('nofile');
249c4f60 281 }
249c4f60
DC
282 }
283
284 /**
285 * Returns description of upload returns
286 * @return external_multiple_structure
287 */
288 public static function upload_returns() {
289 return new external_single_structure(
290 array(
218a7c5f 291 'contextid' => new external_value(PARAM_INT, ''),
aff24313
PS
292 'component' => new external_value(PARAM_COMPONENT, ''),
293 'filearea' => new external_value(PARAM_AREA, ''),
218a7c5f 294 'itemid' => new external_value(PARAM_INT, ''),
249c4f60 295 'filepath' => new external_value(PARAM_TEXT, ''),
218a7c5f
DC
296 'filename' => new external_value(PARAM_FILE, ''),
297 'url' => new external_value(PARAM_TEXT, ''),
249c4f60
DC
298 )
299 );
300 }
249c4f60 301}
5d1017e1
JM
302
303/**
304 * Deprecated files functions
305 * @deprecated since Moodle 2.2 please use core_files_external instead
306 */
307class moodle_file_external extends external_api {
308
309 /**
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
313 */
314 public static function get_files_parameters() {
315 return core_files_external::get_files_parameters();
316 }
317
318 /**
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
324 * @param int $itemid
325 * @param string $filepath
326 * @param string $filename
327 * @return array
328 */
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);
331 }
332
333 /**
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
337 */
338 public static function get_files_returns() {
339 return core_files_external::get_files_returns();
340 }
341
342 /**
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
346 */
347 public static function upload_parameters() {
348 return core_files_external::upload_parameters();
349 }
350
351 /**
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
357 * @param int $itemid
358 * @param string $filepath
359 * @param string $filename
360 * @param string $filecontent
361 * @return array
362 */
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);
365 }
366
367 /**
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
371 */
372 public static function upload_returns() {
373 return core_files_external::upload_returns();
374 }
375}