Merge branch 'MDL-49425-master' of git://github.com/jleyva/moodle
[moodle.git] / webservice / externallib.php
CommitLineData
0bf486a6
JM
1<?php
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
a0a07014 17
0bf486a6
JM
18/**
19 * external API for mobile web services
20 *
a0a07014
JM
21 * @package core_webservice
22 * @category external
23 * @copyright 2011 Jerome Mouneyrac <jerome@moodle.com>
0bf486a6
JM
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
639bc8b2
PC
27defined('MOODLE_INTERNAL') || die;
28
29require_once("$CFG->libdir/externallib.php");
30
5d1017e1
JM
31/**
32 * Web service related functions
a0a07014
JM
33 *
34 * @package core_webservice
35 * @category external
36 * @copyright 2011 Jerome Mouneyrac <jerome@moodle.com>
37 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
38 * @since Moodle 2.2
5d1017e1
JM
39 */
40class core_webservice_external extends external_api {
0bf486a6 41
5d1017e1
JM
42 /**
43 * Returns description of method parameters
a0a07014 44 *
e6acc551 45 * @return external_function_parameters
a0a07014 46 * @since Moodle 2.2
5d1017e1
JM
47 */
48 public static function get_site_info_parameters() {
0bf486a6
JM
49 return new external_function_parameters(
50 array('serviceshortnames' => new external_multiple_structure (
00a33dcb
SH
51 new external_value(
52 PARAM_ALPHANUMEXT,
53 'service shortname'),
639bc8b2
PC
54 'DEPRECATED PARAMETER - it was a design error in the original implementation. \
55 It is ignored now. (parameter kept for backward compatibility)',
00a33dcb
SH
56 VALUE_DEFAULT,
57 array()
58 ),
59 )
0bf486a6
JM
60 );
61 }
62
63 /**
00a33dcb 64 * Return user information including profile picture + basic site information
0bf486a6 65 * Note:
a0a07014
JM
66 * - no capability checking because we return only known information about logged user
67 *
97f6be20 68 * @param array $serviceshortnames - DEPRECATED PARAMETER - values will be ignored -
639bc8b2 69 * it was an original design error, we keep for backward compatibility.
a0a07014
JM
70 * @return array site info
71 * @since Moodle 2.2
0bf486a6 72 */
639bc8b2 73 public static function get_site_info($serviceshortnames = array()) {
af03513f 74 global $USER, $SITE, $CFG, $DB;
0bf486a6 75
5d1017e1 76 $params = self::validate_parameters(self::get_site_info_parameters(),
00a33dcb 77 array('serviceshortnames'=>$serviceshortnames));
0bf486a6 78
11c78c11 79 $context = context_user::instance($USER->id);
0bf486a6 80 $profileimageurl = moodle_url::make_pluginfile_url(
11c78c11 81 $context->id, 'user', 'icon', null, '/', 'f1');
0bf486a6 82
639bc8b2 83 // Site information.
af03513f
JM
84 $siteinfo = array(
85 'sitename' => $SITE->fullname,
86 'siteurl' => $CFG->wwwroot,
87 'username' => $USER->username,
88 'firstname' => $USER->firstname,
89 'lastname' => $USER->lastname,
90 'fullname' => fullname($USER),
92fa81d3 91 'lang' => current_language(),
af03513f
JM
92 'userid' => $USER->id,
93 'userpictureurl' => $profileimageurl->out(false)
94 );
0bf486a6 95
639bc8b2
PC
96 // Retrieve the service and functions from the web service linked to the token
97 // If you call this function directly from external (not a web service call),
98 // then it will still return site info without information about a service
99 // Note: wsusername/wspassword ws authentication is not supported.
af03513f 100 $functions = array();
639bc8b2 101 if ($CFG->enablewebservices) { // No need to check token if web service are disabled and not a ws call.
af03513f 102 $token = optional_param('wstoken', '', PARAM_ALPHANUM);
0bf486a6 103
639bc8b2
PC
104 if (!empty($token)) { // No need to run if not a ws call.
105 // Retrieve service shortname.
af03513f
JM
106 $servicesql = 'SELECT s.*
107 FROM {external_services} s, {external_tokens} t
108 WHERE t.externalserviceid = s.id AND token = ? AND t.userid = ? AND s.enabled = 1';
109 $service = $DB->get_record_sql($servicesql, array($token, $USER->id));
110
111 $siteinfo['downloadfiles'] = $service->downloadfiles;
106c55fb 112 $siteinfo['uploadfiles'] = $service->uploadfiles;
af03513f
JM
113
114 if (!empty($service)) {
639bc8b2
PC
115 // Return the release and version number for web service users only.
116 $siteinfo['release'] = $CFG->release;
117 $siteinfo['version'] = $CFG->version;
118 // Retrieve the functions.
af03513f
JM
119 $functionssql = "SELECT f.*
120 FROM {external_functions} f, {external_services_functions} sf
121 WHERE f.name = sf.functionname AND sf.externalserviceid = ?";
122 $functions = $DB->get_records_sql($functionssql, array($service->id));
123 } else {
639bc8b2
PC
124 throw new coding_exception('No service found in get_site_info: something is buggy, \
125 it should have fail at the ws server authentication layer.');
af03513f
JM
126 }
127 }
128 }
0bf486a6 129
639bc8b2 130 // Build up the returned values of the list of functions.
0bf486a6 131 $componentversions = array();
639bc8b2 132 $availablefunctions = array();
0bf486a6
JM
133 foreach ($functions as $function) {
134 $functioninfo = array();
135 $functioninfo['name'] = $function->name;
639bc8b2
PC
136 if ($function->component == 'moodle' || $function->component == 'core') {
137 $version = $CFG->version; // Moodle version.
0bf486a6 138 } else {
b0d1d941 139 $versionpath = core_component::get_component_directory($function->component).'/version.php';
0bf486a6 140 if (is_readable($versionpath)) {
639bc8b2 141 // We store the component version once retrieved (so we don't load twice the version.php).
0bf486a6
JM
142 if (!isset($componentversions[$function->component])) {
143 include($versionpath);
144 $componentversions[$function->component] = $plugin->version;
145 $version = $plugin->version;
146 } else {
147 $version = $componentversions[$function->component];
148 }
149 } else {
639bc8b2
PC
150 // Function component should always have a version.php,
151 // otherwise the function should have been described with component => 'moodle'.
0bf486a6
JM
152 throw new moodle_exception('missingversionfile', 'webservice', '', $function->component);
153 }
154 }
155 $functioninfo['version'] = $version;
639bc8b2 156 $availablefunctions[] = $functioninfo;
0bf486a6
JM
157 }
158
639bc8b2 159 $siteinfo['functions'] = $availablefunctions;
af03513f 160
9184d44d 161 // Mobile CSS theme and alternative login url.
44b3927b 162 $siteinfo['mobilecssurl'] = $CFG->mobilecssurl;
33af7882 163
cc90f74b
JL
164 // Retrieve some advanced features. Only enable/disable ones (bool).
165 $advancedfeatures = array("usecomments", "usetags", "enablenotes", "messaging", "enableblogs",
166 "enablecompletion", "enablebadges");
167 foreach ($advancedfeatures as $feature) {
168 if (isset($CFG->{$feature})) {
169 $siteinfo['advancedfeatures'][] = array(
170 'name' => $feature,
171 'value' => (int) $CFG->{$feature}
172 );
173 }
174 }
175 // Special case mnet_dispatcher_mode.
176 $siteinfo['advancedfeatures'][] = array(
177 'name' => 'mnet_dispatcher_mode',
178 'value' => ($CFG->mnet_dispatcher_mode == 'strict') ? 1 : 0
179 );
180
11c78c11
JL
181 // User can manage own files.
182 $siteinfo['usercanmanageownfiles'] = has_capability('moodle/user:manageownfiles', $context);
183
184 // User quota. 0 means user can ignore the quota.
185 $siteinfo['userquota'] = 0;
186 if (!has_capability('moodle/user:ignoreuserquota', $context)) {
187 $siteinfo['userquota'] = $CFG->userquota;
188 }
189
190 // User max upload file size. -1 means the user can ignore the upload file size.
191 $siteinfo['usermaxuploadfilesize'] = get_user_max_upload_file_size($context, $CFG->maxbytes);
192
af03513f 193 return $siteinfo;
0bf486a6
JM
194 }
195
5d1017e1
JM
196 /**
197 * Returns description of method result value
a0a07014 198 *
e6acc551 199 * @return external_single_structure
a0a07014 200 * @since Moodle 2.2
5d1017e1
JM
201 */
202 public static function get_site_info_returns() {
0bf486a6
JM
203 return new external_single_structure(
204 array(
205 'sitename' => new external_value(PARAM_RAW, 'site name'),
206 'username' => new external_value(PARAM_RAW, 'username'),
207 'firstname' => new external_value(PARAM_TEXT, 'first name'),
208 'lastname' => new external_value(PARAM_TEXT, 'last name'),
209 'fullname' => new external_value(PARAM_TEXT, 'user full name'),
92fa81d3 210 'lang' => new external_value(PARAM_LANG, 'user language'),
0bf486a6
JM
211 'userid' => new external_value(PARAM_INT, 'user id'),
212 'siteurl' => new external_value(PARAM_RAW, 'site url'),
e1f97020
JM
213 'userpictureurl' => new external_value(PARAM_URL, 'the user profile picture.
214 Warning: this url is the public URL that only works when forcelogin is set to NO and guestaccess is set to YES.
215 In order to retrieve user profile pictures independently of the Moodle config, replace "pluginfile.php" by
639bc8b2
PC
216 "webservice/pluginfile.php?token=WSTOKEN&file="
217 Of course the user can only see profile picture depending
218 on his/her permissions. Moreover it is recommended to use HTTPS too.'),
0bf486a6
JM
219 'functions' => new external_multiple_structure(
220 new external_single_structure(
221 array(
222 'name' => new external_value(PARAM_RAW, 'function name'),
87ede25c 223 'version' => new external_value(PARAM_TEXT,
639bc8b2 224 'The version number of the component to which the function belongs')
00a33dcb 225 ), 'functions that are available')
0bf486a6 226 ),
639bc8b2
PC
227 'downloadfiles' => new external_value(PARAM_INT, '1 if users are allowed to download files, 0 if not',
228 VALUE_OPTIONAL),
106c55fb
DW
229 'uploadfiles' => new external_value(PARAM_INT, '1 if users are allowed to upload files, 0 if not',
230 VALUE_OPTIONAL),
639bc8b2 231 'release' => new external_value(PARAM_TEXT, 'Moodle release number', VALUE_OPTIONAL),
33af7882 232 'version' => new external_value(PARAM_TEXT, 'Moodle version number', VALUE_OPTIONAL),
cc90f74b
JL
233 'mobilecssurl' => new external_value(PARAM_URL, 'Mobile custom CSS theme', VALUE_OPTIONAL),
234 'advancedfeatures' => new external_multiple_structure(
235 new external_single_structure(
236 array(
237 'name' => new external_value(PARAM_ALPHANUMEXT, 'feature name'),
238 'value' => new external_value(PARAM_INT, 'feature value. Usually 1 means enabled.')
239 ),
240 'Advanced features availability'
241 ),
242 'Advanced features availability',
243 VALUE_OPTIONAL
11c78c11
JL
244 ),
245 'usercanmanageownfiles' => new external_value(PARAM_BOOL,
246 'true if the user can manage his own files', VALUE_OPTIONAL),
247 'userquota' => new external_value(PARAM_INT,
248 'user quota (bytes). 0 means user can ignore the quota', VALUE_OPTIONAL),
249 'usermaxuploadfilesize' => new external_value(PARAM_INT,
250 'user max upload file size (bytes). -1 means the user can ignore the upload file size',
251 VALUE_OPTIONAL)
0bf486a6
JM
252 )
253 );
254 }
5d1017e1
JM
255}
256
257/**
258 * Deprecated web service related functions
a0a07014
JM
259 *
260 * @package core_webservice
261 * @category external
262 * @copyright 2011 Jerome Mouneyrac <jerome@moodle.com>
263 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
264 * @deprecated Moodle 2.2 MDL-29106 - please do not use this class any more.
a0a07014
JM
265 * @see core_webservice_external
266 * @since Moodle 2.1
5d1017e1
JM
267 */
268class moodle_webservice_external extends external_api {
269
270 /**
271 * Returns description of method parameters
a0a07014 272 *
e6acc551 273 * @return external_function_parameters
a0a07014 274 * @deprecated Moodle 2.2 - please do not use this function any more.
a0a07014
JM
275 * @see core_webservice_external::get_site_info_parameters
276 * @since Moodle 2.1
5d1017e1
JM
277 */
278 public static function get_siteinfo_parameters() {
279 return core_webservice_external::get_site_info_parameters();
280 }
281
282 /**
283 * Return user information including profile picture + basic site information
284 * Note:
285 * - no capability checking because we return just known information by logged user
a0a07014 286 *
5d1017e1
JM
287 * @param array $serviceshortnames of service shortnames - the functions of these services will be returned
288 * @return array
a0a07014 289 * @deprecated Moodle 2.2 - please do not use this function any more.
a0a07014
JM
290 * @see core_webservice_external::get_site_info
291 * @since Moodle 2.1
5d1017e1 292 */
2336a843 293 public function get_siteinfo($serviceshortnames = array()) {
5d1017e1
JM
294 return core_webservice_external::get_site_info($serviceshortnames);
295 }
296
297 /**
298 * Returns description of method result value
a0a07014 299 *
e6acc551 300 * @return external_single_structure
a0a07014 301 * @deprecated Moodle 2.2 - please do not use this function any more.
a0a07014
JM
302 * @see core_webservice_external::get_site_info_returns
303 * @since Moodle 2.1
5d1017e1
JM
304 */
305 public static function get_siteinfo_returns() {
306 return core_webservice_external::get_site_info_returns();
307 }
3c1aa6fd
DM
308
309 /**
310 * Marking the method as deprecated.
311 *
312 * @return bool
313 */
314 public static function get_siteinfo_is_deprecated() {
315 return true;
316 }
97f6be20 317}