emergency release 2.2dev
[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
30class 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(
218a7c5f
DC
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')
249c4f60
DC
45 )
46 );
47 }
48
49 /**
50 * Return moodle files listing
218a7c5f
DC
51 * @param int $contextid
52 * @param int $component
53 * @param int $filearea
54 * @param int $itemid
55 * @param string $filepath
56 * @param string $filename
249c4f60
DC
57 * @return array
58 */
218a7c5f
DC
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));
64f93798 62
218a7c5f 63 $browser = get_file_browser();
64f93798 64
64f93798
PS
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 }
249c4f60
DC
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 }
249c4f60 85
218a7c5f
DC
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;
249c4f60
DC
127 }
128 }
249c4f60 129 }
218a7c5f 130 $return['files'] = $list;
249c4f60
DC
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, ''),
aff24313
PS
145 'component' => new external_value(PARAM_COMPONENT, ''),
146 'filearea' => new external_value(PARAM_AREA, ''),
64f93798
PS
147 'itemid' => new external_value(PARAM_INT, ''),
148 'filepath' => new external_value(PARAM_TEXT, ''),
149 'filename' => new external_value(PARAM_TEXT, ''),
249c4f60
DC
150 )
151 )
152 ),
153 'files' => new external_multiple_structure(
154 new external_single_structure(
155 array(
64f93798 156 'contextid' => new external_value(PARAM_INT, ''),
aff24313
PS
157 'component' => new external_value(PARAM_COMPONENT, ''),
158 'filearea' => new external_value(PARAM_AREA, ''),
249c4f60 159 'itemid' => new external_value(PARAM_INT, ''),
64f93798 160 'filepath' => new external_value(PARAM_TEXT, ''),
218a7c5f 161 'filename' => new external_value(PARAM_FILE, ''),
249c4f60
DC
162 'isdir' => new external_value(PARAM_BOOL, ''),
163 'url' => new external_value(PARAM_TEXT, ''),
249c4f60
DC
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(
218a7c5f 178 'contextid' => new external_value(PARAM_INT, 'context id'),
aff24313
PS
179 'component' => new external_value(PARAM_COMPONENT, 'component'),
180 'filearea' => new external_value(PARAM_AREA, 'file area'),
218a7c5f
DC
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')
249c4f60
DC
185 )
186 );
187 }
188
189 /**
190 * Uploading a file to moodle
191 *
218a7c5f
DC
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
249c4f60
DC
199 * @return array
200 */
218a7c5f 201 public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
249c4f60 202 global $USER, $CFG;
218a7c5f
DC
203
204 $fileinfo = self::validate_parameters(self::upload_parameters(), array('contextid'=>$contextid, 'component'=>$component, 'filearea'=>$filearea, 'itemid'=>$itemid, 'filepath'=>$filepath, 'filename'=>$filename, 'filecontent'=>$filecontent));
249c4f60
DC
205
206 if (!isset($fileinfo['filecontent'])) {
207 throw new moodle_exception('nofile');
208 }
209 // saving file
af9b1444 210 $dir = make_temp_directory('wsupload');
882efc3c 211
249c4f60 212 if (empty($fileinfo['filename'])) {
af08a48b 213 $filename = uniqid('wsupload', true).'_'.time().'.tmp';
249c4f60
DC
214 } else {
215 $filename = $fileinfo['filename'];
216 }
217
218 if (file_exists($dir.$filename)) {
218a7c5f
DC
219 $savedfilepath = $dir.uniqid('m').$filename;
220 } else {
221 $savedfilepath = $dir.$filename;
249c4f60
DC
222 }
223
249c4f60
DC
224
225 file_put_contents($savedfilepath, base64_decode($fileinfo['filecontent']));
226 unset($fileinfo['filecontent']);
227
249c4f60
DC
228 if (!empty($fileinfo['filepath'])) {
229 $filepath = $fileinfo['filepath'];
230 } else {
218a7c5f 231 $filepath = '/';
249c4f60 232 }
64f93798 233
249c4f60 234 if (isset($fileinfo['itemid'])) {
218a7c5f
DC
235 // TODO: in user private area, itemid is always 0
236 $itemid = 0;
249c4f60 237 } else {
218a7c5f 238 throw new coding_exception('itemid cannot be empty');
249c4f60 239 }
218a7c5f 240
249c4f60
DC
241 if (!empty($fileinfo['contextid'])) {
242 $context = get_context_instance_by_id($fileinfo['contextid']);
243 } else {
244 $context = get_system_context();
245 }
246
218a7c5f
DC
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 }
64f93798 254
249c4f60
DC
255 $browser = get_file_browser();
256
257 // check existing file
218a7c5f 258 if ($file = $browser->get_file_info($context, $component, $filearea, $itemid, $filepath, $filename)) {
249c4f60
DC
259 throw new moodle_exception('fileexist');
260 }
261
249c4f60 262 // move file to filepool
218a7c5f
DC
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();
249c4f60 266 unlink($savedfilepath);
218a7c5f
DC
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');
249c4f60 278 }
249c4f60
DC
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(
218a7c5f 288 'contextid' => new external_value(PARAM_INT, ''),
aff24313
PS
289 'component' => new external_value(PARAM_COMPONENT, ''),
290 'filearea' => new external_value(PARAM_AREA, ''),
218a7c5f 291 'itemid' => new external_value(PARAM_INT, ''),
249c4f60 292 'filepath' => new external_value(PARAM_TEXT, ''),
218a7c5f
DC
293 'filename' => new external_value(PARAM_FILE, ''),
294 'url' => new external_value(PARAM_TEXT, ''),
249c4f60
DC
295 )
296 );
297 }
249c4f60 298}