MDL-29938 Remove tabs (Grrr!)
[moodle.git] / user / externallib.php
CommitLineData
ef22c1b6 1<?php
ef22c1b6 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
ef22c1b6 18/**
19 * External user API
20 *
4615817d
JM
21 * @package core_user
22 * @category external
23 * @copyright 2009 Petr Skodak
ef22c1b6 24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
27require_once("$CFG->libdir/externallib.php");
28
5d1017e1 29/**
4615817d
JM
30 * User external functions
31 *
32 * @package core_user
33 * @category external
34 * @copyright 2011 Jerome Mouneyrac
35 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36 * @since Moodle 2.2
5d1017e1
JM
37 */
38class core_user_external extends external_api {
ef22c1b6 39
7b472b32
PS
40 /**
41 * Returns description of method parameters
4615817d 42 *
7b472b32 43 * @return external_function_parameters
4615817d 44 * @since Moodle 2.2
7b472b32 45 */
d4e13355 46 public static function create_users_parameters() {
667b496a
PS
47 global $CFG;
48
35b9a80a 49 return new external_function_parameters(
50 array(
51 'users' => new external_multiple_structure(
52 new external_single_structure(
53 array(
ec80bc6b 54 'username' => new external_value(PARAM_USERNAME, 'Username policy is defined in Moodle security config.'),
667b496a 55 'password' => new external_value(PARAM_RAW, 'Plain text password consisting of any characters'),
7b472b32
PS
56 'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user'),
57 'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user'),
58 'email' => new external_value(PARAM_EMAIL, 'A valid and unique email address'),
aff24313 59 'auth' => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_DEFAULT, 'manual', NULL_NOT_ALLOWED),
610a447e 60 'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_DEFAULT, ''),
3a915b06 61 'lang' => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_DEFAULT, $CFG->lang, NULL_NOT_ALLOWED),
aff24313 62 'theme' => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
ccc77f91 63 'timezone' => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
1e12c120 64 'mailformat' => new external_value(PARAM_INT, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
d9ad0103 65 'description' => new external_value(PARAM_TEXT, 'User profile description, no HTML', VALUE_OPTIONAL),
fb79269b 66 'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
67 'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
35b9a80a 68 'preferences' => new external_multiple_structure(
69 new external_single_structure(
70 array(
7b472b32 71 'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preference'),
35b9a80a 72 'value' => new external_value(PARAM_RAW, 'The value of the preference')
73 )
fb79269b 74 ), 'User preferences', VALUE_OPTIONAL),
35b9a80a 75 'customfields' => new external_multiple_structure(
76 new external_single_structure(
77 array(
7b472b32 78 'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
35b9a80a 79 'value' => new external_value(PARAM_RAW, 'The value of the custom field')
80 )
6bb31e40 81 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL)
35b9a80a 82 )
83 )
84 )
85 )
86 );
625f0a24 87 }
88
d4e13355 89 /**
5de592b1 90 * Create one or more users
91 *
4615817d 92 * @param array $users An array of users to create.
71864f15 93 * @return array An array of arrays
4615817d 94 * @since Moodle 2.2
5de592b1 95 */
7b472b32 96 public static function create_users($users) {
ef22c1b6 97 global $CFG, $DB;
25eb9090 98 require_once($CFG->dirroot."/lib/weblib.php");
fb79269b 99 require_once($CFG->dirroot."/user/lib.php");
30a4fb1b 100 require_once($CFG->dirroot."/user/profile/lib.php"); //required for customfields related function
109b453b 101
5de592b1 102 // Ensure the current user is allowed to run this function
43731030 103 $context = context_system::instance();
ef22c1b6 104 self::validate_context($context);
fb79269b 105 require_capability('moodle/user:create', $context);
d9ad0103 106
5de592b1 107 // Do basic automatic PARAM checks on incoming data, using params description
5de592b1 108 // If any problems are found then exceptions are thrown with helpful error messages
7b472b32 109 $params = self::validate_parameters(self::create_users_parameters(), array('users'=>$users));
109b453b 110
667b496a
PS
111 $availableauths = get_plugin_list('auth');
112 unset($availableauths['mnet']); // these would need mnethostid too
113 unset($availableauths['webservice']); // we do not want new webservice users for now
114
115 $availablethemes = get_plugin_list('theme');
1f96e907 116 $availablelangs = get_string_manager()->get_list_of_translations();
5de592b1 117
38b76f3c 118 $transaction = $DB->start_delegated_transaction();
5de592b1 119
fb79269b 120 $userids = array();
7b472b32 121 foreach ($params['users'] as $user) {
667b496a
PS
122 // Make sure that the username doesn't already exist
123 if ($DB->record_exists('user', array('username'=>$user['username'], 'mnethostid'=>$CFG->mnet_localhost_id))) {
124 throw new invalid_parameter_exception('Username already exists: '.$user['username']);
ef22c1b6 125 }
ef22c1b6 126
667b496a
PS
127 // Make sure auth is valid
128 if (empty($availableauths[$user['auth']])) {
129 throw new invalid_parameter_exception('Invalid authentication type: '.$user['auth']);
ef22c1b6 130 }
131
667b496a
PS
132 // Make sure lang is valid
133 if (empty($availablelangs[$user['lang']])) {
134 throw new invalid_parameter_exception('Invalid language code: '.$user['lang']);
ef22c1b6 135 }
136
667b496a 137 // Make sure lang is valid
fb79269b 138 if (!empty($user['theme']) && empty($availablethemes[$user['theme']])) { //theme is VALUE_OPTIONAL,
139 // so no default value.
140 // We need to test if the client sent it
141 // => !empty($user['theme'])
667b496a 142 throw new invalid_parameter_exception('Invalid theme: '.$user['theme']);
ef22c1b6 143 }
5de592b1 144
fb79269b 145 $user['confirmed'] = true;
a1988186 146 $user['mnethostid'] = $CFG->mnet_localhost_id;
30a4fb1b 147
25eb9090
AB
148 // Start of user info validation.
149 // Lets make sure we validate current user info as handled by current GUI. see user/editadvanced_form.php function validation()
150 if (!validate_email($user['email'])) {
151 throw new invalid_parameter_exception('Email address is invalid: '.$user['email']);
152 } else if ($DB->record_exists('user', array('email'=>$user['email'], 'mnethostid'=>$user['mnethostid']))) {
153 throw new invalid_parameter_exception('Email address already exists: '.$user['email']);
154 }
155 // End of user info validation.
156
615abdda
AB
157 // create the user data now!
158 $user['id'] = user_create_user($user);
25eb9090 159
30a4fb1b 160 // custom fields
161 if(!empty($user['customfields'])) {
162 foreach($user['customfields'] as $customfield) {
163 $user["profile_field_".$customfield['type']] = $customfield['value']; //profile_save_data() saves profile file
164 //it's expecting a user with the correct id,
165 //and custom field to be named profile_field_"shortname"
166 }
167 profile_save_data((object) $user);
168 }
667b496a 169
d9ad0103 170 //preferences
171 if (!empty($user['preferences'])) {
172 foreach($user['preferences'] as $preference) {
173 set_user_preference($preference['type'], $preference['value'],$user['id']);
174 }
175 }
d4e13355 176
c4c352dd 177 $userids[] = array('id'=>$user['id'], 'username'=>$user['username']);
ef22c1b6 178 }
179
38b76f3c 180 $transaction->allow_commit();
667b496a 181
fb79269b 182 return $userids;
ef22c1b6 183 }
184
7b472b32
PS
185 /**
186 * Returns description of method result value
4615817d 187 *
7b472b32 188 * @return external_description
4615817d 189 * @since Moodle 2.2
7b472b32
PS
190 */
191 public static function create_users_returns() {
192 return new external_multiple_structure(
193 new external_single_structure(
194 array(
195 'id' => new external_value(PARAM_INT, 'user id'),
45b4464c 196 'username' => new external_value(PARAM_USERNAME, 'user name'),
7b472b32
PS
197 )
198 )
199 );
d4e13355 200 }
201
202
930680cb
PS
203 /**
204 * Returns description of method parameters
4615817d 205 *
930680cb 206 * @return external_function_parameters
4615817d 207 * @since Moodle 2.2
930680cb 208 */
d4e13355 209 public static function delete_users_parameters() {
930680cb
PS
210 return new external_function_parameters(
211 array(
212 'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
213 )
214 );
d4e13355 215 }
930680cb 216
5d1017e1
JM
217 /**
218 * Delete users
4615817d 219 *
5d1017e1 220 * @param array $userids
e6acc551 221 * @return null
4615817d 222 * @since Moodle 2.2
5d1017e1 223 */
38b76f3c 224 public static function delete_users($userids) {
b73a28be 225 global $CFG, $DB, $USER;
fb79269b 226 require_once($CFG->dirroot."/user/lib.php");
38b76f3c
PS
227
228 // Ensure the current user is allowed to run this function
43731030 229 $context = context_system::instance();
38b76f3c
PS
230 require_capability('moodle/user:delete', $context);
231 self::validate_context($context);
232
fb79269b 233 $params = self::validate_parameters(self::delete_users_parameters(), array('userids'=>$userids));
38b76f3c
PS
234
235 $transaction = $DB->start_delegated_transaction();
38b76f3c
PS
236
237 foreach ($params['userids'] as $userid) {
238 $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0), '*', MUST_EXIST);
b73a28be 239 // must not allow deleting of admins or self!!!
4f622c38
PS
240 if (is_siteadmin($user)) {
241 throw new moodle_exception('useradminodelete', 'error');
242 }
243 if ($USER->id == $user->id) {
244 throw new moodle_exception('usernotdeletederror', 'error');
b73a28be 245 }
fb79269b 246 user_delete_user($user);
38b76f3c
PS
247 }
248
249 $transaction->allow_commit();
250
251 return null;
ef22c1b6 252 }
930680cb
PS
253
254 /**
255 * Returns description of method result value
4615817d
JM
256 *
257 * @return null
258 * @since Moodle 2.2
930680cb 259 */
d4e13355 260 public static function delete_users_returns() {
930680cb 261 return null;
d4e13355 262 }
ef22c1b6 263
264
930680cb
PS
265 /**
266 * Returns description of method parameters
4615817d 267 *
930680cb 268 * @return external_function_parameters
4615817d 269 * @since Moodle 2.2
930680cb 270 */
d4e13355 271 public static function update_users_parameters() {
fb79269b 272 global $CFG;
2336a843 273 return new external_function_parameters(
fb79269b 274 array(
275 'users' => new external_multiple_structure(
276 new external_single_structure(
277 array(
61cca0b7 278 'id' => new external_value(PARAM_INT, 'ID of the user'),
ec80bc6b 279 'username' => new external_value(PARAM_USERNAME, 'Username policy is defined in Moodle security config.', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
fb79269b 280 'password' => new external_value(PARAM_RAW, 'Plain text password consisting of any characters', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
281 'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
282 'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
283 'email' => new external_value(PARAM_EMAIL, 'A valid and unique email address', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
aff24313 284 'auth' => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL, '', NULL_NOT_ALLOWED),
fb79269b 285 'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
3a915b06 286 'lang' => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL, '', NULL_NOT_ALLOWED),
aff24313 287 'theme' => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
ccc77f91 288 'timezone' => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
1e12c120 289 'mailformat' => new external_value(PARAM_INT, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
d9ad0103 290 'description' => new external_value(PARAM_TEXT, 'User profile description, no HTML', VALUE_OPTIONAL),
fb79269b 291 'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
292 'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
fb79269b 293 'customfields' => new external_multiple_structure(
294 new external_single_structure(
295 array(
296 'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
297 'value' => new external_value(PARAM_RAW, 'The value of the custom field')
298 )
6bb31e40 299 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
d9ad0103 300 'preferences' => new external_multiple_structure(
301 new external_single_structure(
302 array(
303 'type' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preference'),
304 'value' => new external_value(PARAM_RAW, 'The value of the preference')
305 )
306 ), 'User preferences', VALUE_OPTIONAL),
fb79269b 307 )
308 )
309 )
310 )
311 );
d4e13355 312 }
38b76f3c 313
5d1017e1
JM
314 /**
315 * Update users
4615817d 316 *
5d1017e1 317 * @param array $users
e6acc551 318 * @return null
4615817d 319 * @since Moodle 2.2
5d1017e1 320 */
38b76f3c
PS
321 public static function update_users($users) {
322 global $CFG, $DB;
fb79269b 323 require_once($CFG->dirroot."/user/lib.php");
9baf3a7b 324 require_once($CFG->dirroot."/user/profile/lib.php"); //required for customfields related function
38b76f3c
PS
325
326 // Ensure the current user is allowed to run this function
43731030 327 $context = context_system::instance();
38b76f3c
PS
328 require_capability('moodle/user:update', $context);
329 self::validate_context($context);
330
331 $params = self::validate_parameters(self::update_users_parameters(), array('users'=>$users));
332
333 $transaction = $DB->start_delegated_transaction();
334
335 foreach ($params['users'] as $user) {
fb79269b 336 user_update_user($user);
9baf3a7b 337 //update user custom fields
338 if(!empty($user['customfields'])) {
339
340 foreach($user['customfields'] as $customfield) {
341 $user["profile_field_".$customfield['type']] = $customfield['value']; //profile_save_data() saves profile file
342 //it's expecting a user with the correct id,
343 //and custom field to be named profile_field_"shortname"
344 }
345 profile_save_data((object) $user);
346 }
d9ad0103 347
348 //preferences
349 if (!empty($user['preferences'])) {
350 foreach($user['preferences'] as $preference) {
351 set_user_preference($preference['type'], $preference['value'],$user['id']);
352 }
353 }
38b76f3c
PS
354 }
355
356 $transaction->allow_commit();
357
358 return null;
ef22c1b6 359 }
930680cb
PS
360
361 /**
362 * Returns description of method result value
4615817d
JM
363 *
364 * @return null
365 * @since Moodle 2.2
930680cb 366 */
d4e13355 367 public static function update_users_returns() {
930680cb 368 return null;
d4e13355 369 }
370
86477112
FS
371 /**
372 * Returns description of method parameters
373 *
374 * @return external_function_parameters
c70b9853 375 * @since Moodle 2.4
86477112 376 */
c70b9853 377 public static function get_users_by_field_parameters() {
86477112
FS
378 return new external_function_parameters(
379 array(
c70b9853
JM
380 'field' => new external_value(PARAM_ALPHA, 'the search field can be
381 \'id\' or \'idnumber\' or \'username\' or \'email\''),
382 'values' => new external_multiple_structure(
383 new external_value(PARAM_RAW, 'the value to match'))
86477112
FS
384 )
385 );
386 }
387
388 /**
c70b9853 389 * Get user information for a unique field.
86477112 390 *
c70b9853
JM
391 * @param string $field
392 * @param array $values
393 * @return array An array of arrays containg user profiles.
394 * @since Moodle 2.4
86477112 395 */
c70b9853 396 public static function get_users_by_field($field, $values) {
86477112
FS
397 global $CFG, $USER, $DB;
398 require_once($CFG->dirroot . "/user/lib.php");
399
c70b9853
JM
400 $params = self::validate_parameters(self::get_users_by_field_parameters(),
401 array('field' => $field, 'values' => $values));
402
403 // This array will keep all the users that are allowed to be searched,
404 // according to the current user's privileges.
405 $cleanedvalues = array();
406
407 switch ($field) {
408 case 'id':
409 $paramtype = PARAM_INT;
410 break;
411 case 'idnumber':
412 $paramtype = PARAM_RAW;
413 break;
414 case 'username':
ec80bc6b 415 $paramtype = PARAM_RAW;
c70b9853
JM
416 break;
417 case 'email':
418 $paramtype = PARAM_EMAIL;
419 break;
420 default:
421 throw new coding_exception('invalid field parameter',
422 'The search field \'' . $field . '\' is not supported, look at the web service documentation');
86477112
FS
423 }
424
c70b9853
JM
425 // Clean the values
426 foreach ($values as $value) {
427 $cleanedvalue = clean_param($value, $paramtype);
428 if ( $value != $cleanedvalue) {
429 throw new invalid_parameter_exception('The field \'' . $field .
430 '\' value is invalid: ' . $value . '(cleaned value: '.$cleanedvalue.')');
431 }
432 $cleanedvalues[] = $cleanedvalue;
86477112
FS
433 }
434
c70b9853
JM
435 // Retrieve the users
436 $users = $DB->get_records_list('user', $field, $cleanedvalues, 'id');
86477112 437
c70b9853
JM
438 // Finally retrieve each users information
439 $returnedusers = array();
86477112 440 foreach ($users as $user) {
86477112
FS
441 $userdetails = user_get_user_details_courses($user);
442
c70b9853
JM
443 // Return the user only if the searched field is returned
444 // Otherwise it means that the $USER was not allowed to search the returned user
445 if (!empty($userdetails) and !empty($userdetails[$field])) {
446 $returnedusers[] = $userdetails;
86477112
FS
447 }
448 }
86477112 449
c70b9853 450 return $returnedusers;
86477112
FS
451 }
452
453 /**
454 * Returns description of method result value
455 *
c70b9853
JM
456 * @return external_multiple_structure
457 * @since Moodle 2.4
86477112 458 */
c70b9853 459 public static function get_users_by_field_returns() {
85e6bf8e 460 return new external_multiple_structure(self::user_description());
b0365ea5
JM
461 }
462
463
464 /**
bb1105ae 465 * Returns description of get_users() parameters.
b0365ea5
JM
466 *
467 * @return external_function_parameters
bb1105ae 468 * @since Moodle 2.5
b0365ea5
JM
469 */
470 public static function get_users_parameters() {
471 return new external_function_parameters(
472 array(
473 'criteria' => new external_multiple_structure(
474 new external_single_structure(
475 array(
bb1105ae
JM
476 'key' => new external_value(PARAM_ALPHA, 'the user column to search, expected keys (value format) are:
477 "id" (int) matching user id,
478 "lastname" (string) user last name (Note: you can use % for searching but it may be considerably slower!),
479 "firstname" (string) user first name (Note: you can use % for searching but it may be considerably slower!),
480 "idnumber" (string) matching user idnumber,
481 "username" (string) matching user username,
482 "email" (string) user email (Note: you can use % for searching but it may be considerably slower!),
483 "auth" (string) matching user auth plugin'),
484 'value' => new external_value(PARAM_RAW, 'the value to search')
b0365ea5
JM
485 )
486 ), 'the key/value pairs to be considered in user search. Values can not be empty.
bb1105ae 487 Specify different keys only once (fullname => \'user1\', auth => \'manual\', ...) -
85e6bf8e 488 key occurences are forbidden.
0c34e803 489 The search is executed with AND operator on the criterias. Invalid criterias (keys) are ignored,
85e6bf8e
JM
490 the search is still executed on the valid criterias.
491 You can search without criteria, but the function is not designed for it.
492 It could very slow or timeout. The function is designed to search some specific users.'
86477112
FS
493 )
494 )
495 );
496 }
497
b0365ea5 498 /**
bb1105ae 499 * Retrieve matching user.
b0365ea5 500 *
bb1105ae
JM
501 * @param array $criteria the allowed array keys are id/lastname/firstname/idnumber/username/email/auth.
502 * @return array An array of arrays containing user profiles.
503 * @since Moodle 2.5
b0365ea5
JM
504 */
505 public static function get_users($criteria = array()) {
506 global $CFG, $USER, $DB;
507
508 require_once($CFG->dirroot . "/user/lib.php");
509
510 $params = self::validate_parameters(self::get_users_parameters(),
511 array('criteria' => $criteria));
512
bb1105ae 513 // Validate the criteria and retrieve the users.
b0365ea5
JM
514 $users = array();
515 $warnings = array();
b0365ea5 516 $sqlparams = array();
85e6bf8e
JM
517 $usedkeys = array();
518
519 // Do not retrieve deleted users.
520 $sql = ' deleted = 0';
b0365ea5 521
0c34e803 522 foreach ($params['criteria'] as $criteriaindex => $criteria) {
85e6bf8e
JM
523
524 // Check that the criteria has never been used.
525 if (array_key_exists($criteria['key'], $usedkeys)) {
526 throw new moodle_exception('keyalreadyset', '', '', null, 'The key ' . $criteria['key'] . ' can only be sent once');
527 } else {
528 $usedkeys[$criteria['key']] = true;
529 }
530
0c34e803 531 $invalidcriteria = false;
bb1105ae 532 // Clean the parameters.
b0365ea5
JM
533 $paramtype = PARAM_RAW;
534 switch ($criteria['key']) {
535 case 'id':
536 $paramtype = PARAM_INT;
537 break;
538 case 'idnumber':
539 $paramtype = PARAM_RAW;
540 break;
541 case 'username':
ec80bc6b 542 $paramtype = PARAM_RAW;
b0365ea5
JM
543 break;
544 case 'email':
bb1105ae 545 // We use PARAM_RAW to allow searches with %.
b0365ea5
JM
546 $paramtype = PARAM_RAW;
547 break;
548 case 'auth':
549 $paramtype = PARAM_AUTH;
550 break;
551 case 'lastname':
552 case 'firstname':
553 $paramtype = PARAM_TEXT;
554 break;
555 default:
bb1105ae
JM
556 // Send back a warning that this search key is not supported in this version.
557 // This warning will make the function extandable without breaking clients.
b0365ea5 558 $warnings[] = array(
0c34e803 559 'item' => $criteria['key'],
b0365ea5 560 'warningcode' => 'invalidfieldparameter',
bb1105ae 561 'message' => 'The search key \'' . $criteria['key'] . '\' is not supported, look at the web service documentation'
b0365ea5 562 );
0c34e803
JM
563 // Do not add this invalid criteria to the created SQL request.
564 $invalidcriteria = true;
565 unset($params['criteria'][$criteriaindex]);
566 break;
b0365ea5 567 }
b0365ea5 568
0c34e803
JM
569 if (!$invalidcriteria) {
570 $cleanedvalue = clean_param($criteria['value'], $paramtype);
b0365ea5 571
85e6bf8e 572 $sql .= ' AND ';
0c34e803
JM
573
574 // Create the SQL.
575 switch ($criteria['key']) {
576 case 'id':
577 case 'idnumber':
578 case 'username':
579 case 'auth':
580 $sql .= $criteria['key'] . ' = :' . $criteria['key'];
581 $sqlparams[$criteria['key']] = $cleanedvalue;
582 break;
583 case 'email':
584 case 'lastname':
585 case 'firstname':
586 $sql .= $DB->sql_like($criteria['key'], ':' . $criteria['key'], false);
587 $sqlparams[$criteria['key']] = $cleanedvalue;
588 break;
589 default:
590 break;
591 }
b0365ea5
JM
592 }
593 }
594
595 $users = $DB->get_records_select('user', $sql, $sqlparams, 'id ASC');
596
bb1105ae 597 // Finally retrieve each users information.
b0365ea5
JM
598 $returnedusers = array();
599 foreach ($users as $user) {
b0365ea5
JM
600 $userdetails = user_get_user_details_courses($user);
601
602 // Return the user only if all the searched fields are returned.
603 // Otherwise it means that the $USER was not allowed to search the returned user.
604 if (!empty($userdetails)) {
605 $validuser = true;
606
607 foreach($params['criteria'] as $criteria) {
608 if (empty($userdetails[$criteria['key']])) {
609 $validuser = false;
610 }
611 }
612
613 if ($validuser) {
614 $returnedusers[] = $userdetails;
615 }
616 }
617 }
618
619 return array('users' => $returnedusers, 'warnings' => $warnings);
620 }
621
622 /**
bb1105ae 623 * Returns description of get_users result value.
b0365ea5
JM
624 *
625 * @return external_description
bb1105ae 626 * @since Moodle 2.5
b0365ea5
JM
627 */
628 public static function get_users_returns() {
629 return new external_single_structure(
630 array('users' => new external_multiple_structure(
85e6bf8e 631 self::user_description()
b0365ea5 632 ),
bb1105ae 633 'warnings' => new external_warnings('always set to \'key\'', 'faulty key name')
b0365ea5
JM
634 )
635 );
636 }
637
7b472b32
PS
638 /**
639 * Returns description of method parameters
4615817d 640 *
7b472b32 641 * @return external_function_parameters
4615817d 642 * @since Moodle 2.2
7b472b32 643 */
fb79269b 644 public static function get_users_by_id_parameters() {
71864f15 645 return new external_function_parameters(
109b453b 646 array(
647 'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
648 )
71864f15 649 );
d4e13355 650 }
7b472b32 651
71864f15
PS
652 /**
653 * Get user information
b4c74367
JM
654 * - This function is matching the permissions of /user/profil.php
655 * - It is also matching some permissions from /user/editadvanced.php for the following fields:
656 * auth, confirmed, idnumber, lang, theme, timezone, mailformat
4615817d 657 *
71864f15
PS
658 * @param array $userids array of user ids
659 * @return array An array of arrays describing users
4615817d 660 * @since Moodle 2.2
71864f15 661 */
fb79269b 662 public static function get_users_by_id($userids) {
b4c74367 663 global $CFG, $USER, $DB;
109b453b 664 require_once($CFG->dirroot . "/user/lib.php");
fb79269b 665
109b453b 666 $params = self::validate_parameters(self::get_users_by_id_parameters(),
667 array('userids'=>$userids));
5de592b1 668
ea4e96c2
DC
669 list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
670 list($sqluserids, $params) = $DB->get_in_or_equal($userids);
671 $usersql = "SELECT u.* $uselect
672 FROM {user} u $ujoin
673 WHERE u.id $sqluserids";
674 $users = $DB->get_recordset_sql($usersql, $params);
d4e13355 675
109b453b 676 $result = array();
01479290 677 $hasuserupdatecap = has_capability('moodle/user:update', get_system_context());
d4e13355 678 foreach ($users as $user) {
ea4e96c2
DC
679 if (!empty($user->deleted)) {
680 continue;
681 }
682 context_instance_preload($user);
43731030 683 $usercontext = context_user::instance($user->id, IGNORE_MISSING);
01479290 684 self::validate_context($usercontext);
b4c74367
JM
685 $currentuser = ($user->id == $USER->id);
686
01479290
DC
687 if ($userarray = user_get_user_details($user)) {
688 //fields matching permissions from /user/editadvanced.php
689 if ($currentuser or $hasuserupdatecap) {
690 $userarray['auth'] = $user->auth;
691 $userarray['confirmed'] = $user->confirmed;
692 $userarray['idnumber'] = $user->idnumber;
693 $userarray['lang'] = $user->lang;
694 $userarray['theme'] = $user->theme;
695 $userarray['timezone'] = $user->timezone;
696 $userarray['mailformat'] = $user->mailformat;
b4c74367 697 }
01479290 698 $result[] = $userarray;
ea4e96c2 699 }
fb79269b 700 }
ea4e96c2 701 $users->close();
71864f15
PS
702
703 return $result;
d4e13355 704 }
7b472b32 705
109b453b 706 /**
7b472b32 707 * Returns description of method result value
4615817d 708 *
7b472b32 709 * @return external_description
4615817d 710 * @since Moodle 2.2
7b472b32 711 */
fb79269b 712 public static function get_users_by_id_returns() {
bb1105ae
JM
713 $additionalfields = array (
714 'enrolledcourses' => new external_multiple_structure(
503c14a6
DW
715 new external_single_structure(
716 array(
717 'id' => new external_value(PARAM_INT, 'Id of the course'),
718 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
719 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
720 )
721 ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL));
85e6bf8e 722 return new external_multiple_structure(self::user_description($additionalfields));
ea4e96c2 723 }
bb1105ae 724
ea4e96c2
DC
725 /**
726 * Returns description of method parameters
4615817d 727 *
ea4e96c2 728 * @return external_function_parameters
4615817d 729 * @since Moodle 2.2
ea4e96c2 730 */
5d1017e1 731 public static function get_course_user_profiles_parameters() {
ea4e96c2
DC
732 return new external_function_parameters(
733 array(
734 'userlist' => new external_multiple_structure(
735 new external_single_structure(
736 array(
737 'userid' => new external_value(PARAM_INT, 'userid'),
738 'courseid' => new external_value(PARAM_INT, 'courseid'),
109b453b 739 )
ea4e96c2 740 )
71864f15 741 )
ea4e96c2
DC
742 )
743 );
744 }
745
746 /**
747 * Get course participant's details
4615817d 748 *
ea4e96c2
DC
749 * @param array $userlist array of user ids and according course ids
750 * @return array An array of arrays describing course participants
4615817d 751 * @since Moodle 2.2
ea4e96c2 752 */
5d1017e1 753 public static function get_course_user_profiles($userlist) {
ea4e96c2
DC
754 global $CFG, $USER, $DB;
755 require_once($CFG->dirroot . "/user/lib.php");
5d1017e1 756 $params = self::validate_parameters(self::get_course_user_profiles_parameters(), array('userlist'=>$userlist));
ea4e96c2
DC
757
758 $userids = array();
759 $courseids = array();
760 foreach ($params['userlist'] as $value) {
761 $userids[] = $value['userid'];
762 $courseids[$value['userid']] = $value['courseid'];
763 }
764
765 // cache all courses
766 $courses = array();
767 list($cselect, $cjoin) = context_instance_preload_sql('c.id', CONTEXT_COURSE, 'ctx');
768 list($sqlcourseids, $params) = $DB->get_in_or_equal(array_unique($courseids));
ecfc06d8 769 $coursesql = "SELECT c.* $cselect
ea4e96c2
DC
770 FROM {course} c $cjoin
771 WHERE c.id $sqlcourseids";
772 $rs = $DB->get_recordset_sql($coursesql, $params);
773 foreach ($rs as $course) {
774 // adding course contexts to cache
775 context_instance_preload($course);
776 // cache courses
777 $courses[$course->id] = $course;
778 }
779 $rs->close();
780
781 list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
782 list($sqluserids, $params) = $DB->get_in_or_equal($userids);
783 $usersql = "SELECT u.* $uselect
784 FROM {user} u $ujoin
785 WHERE u.id $sqluserids";
786 $users = $DB->get_recordset_sql($usersql, $params);
787 $result = array();
788 foreach ($users as $user) {
789 if (!empty($user->deleted)) {
790 continue;
791 }
792 context_instance_preload($user);
ea4e96c2 793 $course = $courses[$courseids[$user->id]];
43731030 794 $context = context_course::instance($courseids[$user->id], IGNORE_MISSING);
ea4e96c2 795 self::validate_context($context);
01479290
DC
796 if ($userarray = user_get_user_details($user, $course)) {
797 $result[] = $userarray;
ea4e96c2 798 }
01479290 799 }
ea4e96c2 800
01479290 801 $users->close();
ea4e96c2 802
01479290
DC
803 return $result;
804 }
ea4e96c2 805
01479290
DC
806 /**
807 * Returns description of method result value
4615817d 808 *
01479290 809 * @return external_description
4615817d 810 * @since Moodle 2.2
01479290 811 */
5d1017e1 812 public static function get_course_user_profiles_returns() {
b0365ea5
JM
813 $additionalfields = array(
814 'groups' => new external_multiple_structure(
815 new external_single_structure(
816 array(
817 'id' => new external_value(PARAM_INT, 'group id'),
818 'name' => new external_value(PARAM_RAW, 'group name'),
819 'description' => new external_value(PARAM_RAW, 'group description'),
820 'descriptionformat' => new external_format_value('description'),
821 )
822 ), 'user groups', VALUE_OPTIONAL),
823 'roles' => new external_multiple_structure(
824 new external_single_structure(
825 array(
826 'roleid' => new external_value(PARAM_INT, 'role id'),
827 'name' => new external_value(PARAM_RAW, 'role name'),
828 'shortname' => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
829 'sortorder' => new external_value(PARAM_INT, 'role sortorder')
830 )
831 ), 'user roles', VALUE_OPTIONAL),
832 'enrolledcourses' => new external_multiple_structure(
503c14a6
DW
833 new external_single_structure(
834 array(
835 'id' => new external_value(PARAM_INT, 'Id of the course'),
836 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
837 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
838 )
839 ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
b0365ea5
JM
840 );
841
85e6bf8e 842 return new external_multiple_structure(self::user_description($additionalfields));
b0365ea5
JM
843 }
844
845 /**
846 * Create user return value description.
847 *
bb1105ae 848 * @param array $additionalfields some additional field
b0365ea5
JM
849 * @return single_structure_description
850 */
bb1105ae 851 public static function user_description($additionalfields = array()) {
b0365ea5 852 $userfields = array(
61cca0b7 853 'id' => new external_value(PARAM_INT, 'ID of the user'),
ec80bc6b 854 'username' => new external_value(PARAM_RAW, 'The username', VALUE_OPTIONAL),
01479290
DC
855 'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
856 'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
857 'fullname' => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
858 'email' => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
071e68f9 859 'address' => new external_value(PARAM_TEXT, 'Postal address', VALUE_OPTIONAL),
01479290
DC
860 'phone1' => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
861 'phone2' => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
862 'icq' => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
863 'skype' => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
864 'yahoo' => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
865 'aim' => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
866 'msn' => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
867 'department' => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
868 'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
3a3f3b22 869 'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
01479290
DC
870 'interests' => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
871 'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
872 'lastaccess' => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
b0365ea5
JM
873 'auth' => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL),
874 'confirmed' => new external_value(PARAM_INT, 'Active user: 1 if confirmed, 0 otherwise', VALUE_OPTIONAL),
875 'lang' => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL),
876 'theme' => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
877 'timezone' => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
878 'mailformat' => new external_value(PARAM_INT, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
01479290 879 'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
93ce0e82 880 'descriptionformat' => new external_format_value('description', VALUE_OPTIONAL),
01479290
DC
881 'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
882 'url' => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
883 'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
884 'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
885 'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
886 'customfields' => new external_multiple_structure(
887 new external_single_structure(
888 array(
889 'type' => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
890 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
891 'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
892 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
893 )
bb1105ae 894 ), 'User custom fields (also known as user profile fields)', VALUE_OPTIONAL),
01479290
DC
895 'preferences' => new external_multiple_structure(
896 new external_single_structure(
897 array(
898 'name' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
899 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
900 )
b0365ea5
JM
901 ), 'Users preferences', VALUE_OPTIONAL)
902 );
903 if (!empty($additionalfields)) {
904 $userfields = array_merge($userfields, $additionalfields);
905 }
906 return new external_single_structure($userfields);
01479290 907 }
b0365ea5 908
5d1017e1
JM
909}
910
4615817d
JM
911 /**
912 * Deprecated user external functions
913 *
914 * @package core_user
915 * @copyright 2009 Petr Skodak
916 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
917 * @since Moodle 2.0
918 * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
919 * @todo MDL-31194 This will be deleted in Moodle 2.5.
920 * @see core_user_external
5d1017e1
JM
921 */
922class moodle_user_external extends external_api {
923
924 /**
925 * Returns description of method parameters
4615817d 926 *
5d1017e1 927 * @return external_function_parameters
4615817d
JM
928 * @since Moodle 2.0
929 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
930 * @todo MDL-31194 This will be deleted in Moodle 2.5.
931 * @see core_user_external::create_users_parameters()
5d1017e1
JM
932 */
933 public static function create_users_parameters() {
934 return core_user_external::create_users_parameters();
935 }
936
937 /**
938 * Create one or more users
4615817d 939 *
5d1017e1
JM
940 * @param array $users An array of users to create.
941 * @return array An array of arrays
4615817d
JM
942 * @since Moodle 2.0
943 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
944 * @todo MDL-31194 This will be deleted in Moodle 2.5.
945 * @see core_user_external::create_users()
5d1017e1
JM
946 */
947 public static function create_users($users) {
948 return core_user_external::create_users($users);
949 }
950
951 /**
952 * Returns description of method result value
4615817d 953 *
5d1017e1 954 * @return external_description
4615817d
JM
955 * @since Moodle 2.0
956 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
957 * @todo MDL-31194 This will be deleted in Moodle 2.5.
958 * @see core_user_external::create_users_returns()
5d1017e1
JM
959 */
960 public static function create_users_returns() {
961 return core_user_external::create_users_returns();
962 }
963
964
965 /**
966 * Returns description of method parameters
4615817d 967 *
5d1017e1 968 * @return external_function_parameters
4615817d
JM
969 * @since Moodle 2.0
970 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
971 * @todo MDL-31194 This will be deleted in Moodle 2.5.
972 * @see core_user_external::delete_users_parameters()
5d1017e1
JM
973 */
974 public static function delete_users_parameters() {
975 return core_user_external::delete_users_parameters();
976 }
977
978 /**
979 * Delete users
4615817d 980 *
5d1017e1 981 * @param array $userids
e6acc551 982 * @return null
4615817d
JM
983 * @since Moodle 2.0
984 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
985 * @todo MDL-31194 This will be deleted in Moodle 2.5.
986 * @see core_user_external::delete_users()
5d1017e1
JM
987 */
988 public static function delete_users($userids) {
989 return core_user_external::delete_users($userids);
990 }
991
992 /**
993 * Returns description of method result value
4615817d
JM
994 *
995 * @return null
996 * @since Moodle 2.0
997 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
998 * @todo MDL-31194 This will be deleted in Moodle 2.5.
999 * @see core_user_external::delete_users_returns()
5d1017e1
JM
1000 */
1001 public static function delete_users_returns() {
1002 return core_user_external::delete_users_returns();
1003 }
1004
1005
1006 /**
1007 * Returns description of method parameters
4615817d 1008 *
5d1017e1 1009 * @return external_function_parameters
4615817d
JM
1010 * @since Moodle 2.0
1011 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1012 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1013 * @see core_user_external::update_users_parameters()
5d1017e1
JM
1014 */
1015 public static function update_users_parameters() {
1016 return core_user_external::update_users_parameters();
1017 }
1018
1019 /**
1020 * Update users
4615817d 1021 *
5d1017e1 1022 * @param array $users
e6acc551 1023 * @return null
4615817d
JM
1024 * @since Moodle 2.0
1025 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1026 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1027 * @see core_user_external::update_users()
5d1017e1
JM
1028 */
1029 public static function update_users($users) {
1030 return core_user_external::update_users($users);
1031 }
1032
1033 /**
1034 * Returns description of method result value
4615817d
JM
1035 *
1036 * @return null
1037 * @since Moodle 2.0
1038 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1039 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1040 * @see core_user_external::update_users_returns()
5d1017e1
JM
1041 */
1042 public static function update_users_returns() {
1043 return core_user_external::update_users_returns();
1044 }
1045
1046 /**
1047 * Returns description of method parameters
4615817d 1048 *
5d1017e1 1049 * @return external_function_parameters
4615817d
JM
1050 * @since Moodle 2.0
1051 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1052 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1053 * @see core_user_external::get_users_by_id_parameters()
5d1017e1
JM
1054 */
1055 public static function get_users_by_id_parameters() {
1056 return core_user_external::get_users_by_id_parameters();
1057 }
1058
1059 /**
1060 * Get user information
1061 * - This function is matching the permissions of /user/profil.php
1062 * - It is also matching some permissions from /user/editadvanced.php for the following fields:
1063 * auth, confirmed, idnumber, lang, theme, timezone, mailformat
4615817d 1064 *
5d1017e1
JM
1065 * @param array $userids array of user ids
1066 * @return array An array of arrays describing users
4615817d
JM
1067 * @since Moodle 2.0
1068 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1069 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1070 * @see core_user_external::get_users_by_id()
5d1017e1
JM
1071 */
1072 public static function get_users_by_id($userids) {
1073 return core_user_external::get_users_by_id($userids);
1074 }
1075
1076 /**
1077 * Returns description of method result value
4615817d 1078 *
5d1017e1 1079 * @return external_description
4615817d
JM
1080 * @since Moodle 2.0
1081 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1082 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1083 * @see core_user_external::get_users_by_id_returns()
5d1017e1
JM
1084 */
1085 public static function get_users_by_id_returns() {
bb1105ae 1086 return core_user_external::get_users_by_id_returns();
5d1017e1
JM
1087 }
1088 /**
1089 * Returns description of method parameters
4615817d 1090 *
5d1017e1 1091 * @return external_function_parameters
4615817d
JM
1092 * @since Moodle 2.1
1093 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1094 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1095 * @see core_user_external::get_course_user_profiles_parameters()
5d1017e1
JM
1096 */
1097 public static function get_course_participants_by_id_parameters() {
1098 return core_user_external::get_course_user_profiles_parameters();
1099 }
1100
1101 /**
1102 * Get course participant's details
4615817d 1103 *
5d1017e1
JM
1104 * @param array $userlist array of user ids and according course ids
1105 * @return array An array of arrays describing course participants
4615817d
JM
1106 * @since Moodle 2.1
1107 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1108 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1109 * @see core_user_external::get_course_user_profiles()
5d1017e1
JM
1110 */
1111 public static function get_course_participants_by_id($userlist) {
1112 return core_user_external::get_course_user_profiles($userlist);
1113 }
1114
1115 /**
1116 * Returns description of method result value
4615817d 1117 *
5d1017e1 1118 * @return external_description
4615817d
JM
1119 * @since Moodle 2.1
1120 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1121 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1122 * @see core_user_external::get_course_user_profiles_returns()
5d1017e1
JM
1123 */
1124 public static function get_course_participants_by_id_returns() {
1125 return core_user_external::get_course_user_profiles_returns();
1126 }
ea4e96c2 1127
01479290
DC
1128 /**
1129 * Returns description of method parameters
4615817d 1130 *
01479290 1131 * @return external_function_parameters
4615817d
JM
1132 * @since Moodle 2.1
1133 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1134 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1135 * @see core_enrol_external::get_enrolled_users_parameters()
01479290
DC
1136 */
1137 public static function get_users_by_courseid_parameters() {
5d1017e1
JM
1138 global $CFG;
1139 require_once($CFG->dirroot . '/enrol/externallib.php');
1140 return core_enrol_external::get_enrolled_users_parameters();
01479290 1141 }
ea4e96c2 1142
01479290
DC
1143 /**
1144 * Get course participants details
4615817d 1145 *
01479290
DC
1146 * @param int $courseid course id
1147 * @param array $options options {
4615817d
JM
1148 * 'name' => option name
1149 * 'value' => option value
1150 * }
01479290 1151 * @return array An array of users
4615817d
JM
1152 * @since Moodle 2.1
1153 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1154 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1155 * @see core_enrol_external::get_enrolled_users()
01479290
DC
1156 */
1157 public static function get_users_by_courseid($courseid, $options) {
5d1017e1
JM
1158 global $CFG;
1159 require_once($CFG->dirroot . '/enrol/externallib.php');
1160 return core_enrol_external::get_enrolled_users($courseid, $options);
ea4e96c2 1161 }
ea4e96c2
DC
1162 /**
1163 * Returns description of method result value
4615817d 1164 *
ea4e96c2 1165 * @return external_description
4615817d
JM
1166 * @since Moodle 2.1
1167 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1168 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1169 * @see core_enrol_external::get_enrolled_users_returns()
ea4e96c2 1170 */
01479290 1171 public static function get_users_by_courseid_returns() {
5d1017e1
JM
1172 global $CFG;
1173 require_once($CFG->dirroot . '/enrol/externallib.php');
1174 return core_enrol_external::get_enrolled_users_returns();
5de592b1 1175 }
b0365ea5 1176}