MDL-38030 new core_user_get_users_by_field function deprecates core_user_get_users_by_id
[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
41f5285f
JM
643 * @deprecated Moodle 2.5 MDL-38030 - Please do not call this function any more.
644 * @see core_user_external::get_users_by_field_parameters()
7b472b32 645 */
fb79269b 646 public static function get_users_by_id_parameters() {
71864f15 647 return new external_function_parameters(
109b453b 648 array(
649 'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
650 )
71864f15 651 );
d4e13355 652 }
7b472b32 653
71864f15
PS
654 /**
655 * Get user information
b4c74367
JM
656 * - This function is matching the permissions of /user/profil.php
657 * - It is also matching some permissions from /user/editadvanced.php for the following fields:
658 * auth, confirmed, idnumber, lang, theme, timezone, mailformat
4615817d 659 *
71864f15
PS
660 * @param array $userids array of user ids
661 * @return array An array of arrays describing users
4615817d 662 * @since Moodle 2.2
41f5285f
JM
663 * @deprecated Moodle 2.5 MDL-38030 - Please do not call this function any more.
664 * @see core_user_external::get_users_by_field()
71864f15 665 */
fb79269b 666 public static function get_users_by_id($userids) {
b4c74367 667 global $CFG, $USER, $DB;
109b453b 668 require_once($CFG->dirroot . "/user/lib.php");
fb79269b 669
109b453b 670 $params = self::validate_parameters(self::get_users_by_id_parameters(),
671 array('userids'=>$userids));
5de592b1 672
ea4e96c2
DC
673 list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
674 list($sqluserids, $params) = $DB->get_in_or_equal($userids);
675 $usersql = "SELECT u.* $uselect
676 FROM {user} u $ujoin
677 WHERE u.id $sqluserids";
678 $users = $DB->get_recordset_sql($usersql, $params);
d4e13355 679
109b453b 680 $result = array();
01479290 681 $hasuserupdatecap = has_capability('moodle/user:update', get_system_context());
d4e13355 682 foreach ($users as $user) {
ea4e96c2
DC
683 if (!empty($user->deleted)) {
684 continue;
685 }
686 context_instance_preload($user);
43731030 687 $usercontext = context_user::instance($user->id, IGNORE_MISSING);
01479290 688 self::validate_context($usercontext);
b4c74367
JM
689 $currentuser = ($user->id == $USER->id);
690
01479290
DC
691 if ($userarray = user_get_user_details($user)) {
692 //fields matching permissions from /user/editadvanced.php
693 if ($currentuser or $hasuserupdatecap) {
694 $userarray['auth'] = $user->auth;
695 $userarray['confirmed'] = $user->confirmed;
696 $userarray['idnumber'] = $user->idnumber;
697 $userarray['lang'] = $user->lang;
698 $userarray['theme'] = $user->theme;
699 $userarray['timezone'] = $user->timezone;
700 $userarray['mailformat'] = $user->mailformat;
b4c74367 701 }
01479290 702 $result[] = $userarray;
ea4e96c2 703 }
fb79269b 704 }
ea4e96c2 705 $users->close();
71864f15
PS
706
707 return $result;
d4e13355 708 }
7b472b32 709
109b453b 710 /**
7b472b32 711 * Returns description of method result value
4615817d 712 *
7b472b32 713 * @return external_description
4615817d 714 * @since Moodle 2.2
41f5285f
JM
715 * @deprecated Moodle 2.5 MDL-38030 - Please do not call this function any more.
716 * @see core_user_external::get_users_by_field_returns()
7b472b32 717 */
fb79269b 718 public static function get_users_by_id_returns() {
bb1105ae
JM
719 $additionalfields = array (
720 'enrolledcourses' => new external_multiple_structure(
503c14a6
DW
721 new external_single_structure(
722 array(
723 'id' => new external_value(PARAM_INT, 'Id of the course'),
724 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
725 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
726 )
727 ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL));
85e6bf8e 728 return new external_multiple_structure(self::user_description($additionalfields));
ea4e96c2 729 }
bb1105ae 730
ea4e96c2
DC
731 /**
732 * Returns description of method parameters
4615817d 733 *
ea4e96c2 734 * @return external_function_parameters
4615817d 735 * @since Moodle 2.2
ea4e96c2 736 */
5d1017e1 737 public static function get_course_user_profiles_parameters() {
ea4e96c2
DC
738 return new external_function_parameters(
739 array(
740 'userlist' => new external_multiple_structure(
741 new external_single_structure(
742 array(
743 'userid' => new external_value(PARAM_INT, 'userid'),
744 'courseid' => new external_value(PARAM_INT, 'courseid'),
109b453b 745 )
ea4e96c2 746 )
71864f15 747 )
ea4e96c2
DC
748 )
749 );
750 }
751
752 /**
753 * Get course participant's details
4615817d 754 *
ea4e96c2
DC
755 * @param array $userlist array of user ids and according course ids
756 * @return array An array of arrays describing course participants
4615817d 757 * @since Moodle 2.2
ea4e96c2 758 */
5d1017e1 759 public static function get_course_user_profiles($userlist) {
ea4e96c2
DC
760 global $CFG, $USER, $DB;
761 require_once($CFG->dirroot . "/user/lib.php");
5d1017e1 762 $params = self::validate_parameters(self::get_course_user_profiles_parameters(), array('userlist'=>$userlist));
ea4e96c2
DC
763
764 $userids = array();
765 $courseids = array();
766 foreach ($params['userlist'] as $value) {
767 $userids[] = $value['userid'];
768 $courseids[$value['userid']] = $value['courseid'];
769 }
770
771 // cache all courses
772 $courses = array();
773 list($cselect, $cjoin) = context_instance_preload_sql('c.id', CONTEXT_COURSE, 'ctx');
774 list($sqlcourseids, $params) = $DB->get_in_or_equal(array_unique($courseids));
ecfc06d8 775 $coursesql = "SELECT c.* $cselect
ea4e96c2
DC
776 FROM {course} c $cjoin
777 WHERE c.id $sqlcourseids";
778 $rs = $DB->get_recordset_sql($coursesql, $params);
779 foreach ($rs as $course) {
780 // adding course contexts to cache
781 context_instance_preload($course);
782 // cache courses
783 $courses[$course->id] = $course;
784 }
785 $rs->close();
786
787 list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
788 list($sqluserids, $params) = $DB->get_in_or_equal($userids);
789 $usersql = "SELECT u.* $uselect
790 FROM {user} u $ujoin
791 WHERE u.id $sqluserids";
792 $users = $DB->get_recordset_sql($usersql, $params);
793 $result = array();
794 foreach ($users as $user) {
795 if (!empty($user->deleted)) {
796 continue;
797 }
798 context_instance_preload($user);
ea4e96c2 799 $course = $courses[$courseids[$user->id]];
43731030 800 $context = context_course::instance($courseids[$user->id], IGNORE_MISSING);
ea4e96c2 801 self::validate_context($context);
01479290
DC
802 if ($userarray = user_get_user_details($user, $course)) {
803 $result[] = $userarray;
ea4e96c2 804 }
01479290 805 }
ea4e96c2 806
01479290 807 $users->close();
ea4e96c2 808
01479290
DC
809 return $result;
810 }
ea4e96c2 811
01479290
DC
812 /**
813 * Returns description of method result value
4615817d 814 *
01479290 815 * @return external_description
4615817d 816 * @since Moodle 2.2
01479290 817 */
5d1017e1 818 public static function get_course_user_profiles_returns() {
b0365ea5
JM
819 $additionalfields = array(
820 'groups' => new external_multiple_structure(
821 new external_single_structure(
822 array(
823 'id' => new external_value(PARAM_INT, 'group id'),
824 'name' => new external_value(PARAM_RAW, 'group name'),
825 'description' => new external_value(PARAM_RAW, 'group description'),
826 'descriptionformat' => new external_format_value('description'),
827 )
828 ), 'user groups', VALUE_OPTIONAL),
829 'roles' => new external_multiple_structure(
830 new external_single_structure(
831 array(
832 'roleid' => new external_value(PARAM_INT, 'role id'),
833 'name' => new external_value(PARAM_RAW, 'role name'),
834 'shortname' => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
835 'sortorder' => new external_value(PARAM_INT, 'role sortorder')
836 )
837 ), 'user roles', VALUE_OPTIONAL),
838 'enrolledcourses' => new external_multiple_structure(
503c14a6
DW
839 new external_single_structure(
840 array(
841 'id' => new external_value(PARAM_INT, 'Id of the course'),
842 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
843 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
844 )
845 ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
b0365ea5
JM
846 );
847
85e6bf8e 848 return new external_multiple_structure(self::user_description($additionalfields));
b0365ea5
JM
849 }
850
851 /**
852 * Create user return value description.
853 *
bb1105ae 854 * @param array $additionalfields some additional field
b0365ea5
JM
855 * @return single_structure_description
856 */
bb1105ae 857 public static function user_description($additionalfields = array()) {
b0365ea5 858 $userfields = array(
61cca0b7 859 'id' => new external_value(PARAM_INT, 'ID of the user'),
ec80bc6b 860 'username' => new external_value(PARAM_RAW, 'The username', VALUE_OPTIONAL),
01479290
DC
861 'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
862 'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
863 'fullname' => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
864 'email' => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
071e68f9 865 'address' => new external_value(PARAM_TEXT, 'Postal address', VALUE_OPTIONAL),
01479290
DC
866 'phone1' => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
867 'phone2' => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
868 'icq' => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
869 'skype' => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
870 'yahoo' => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
871 'aim' => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
872 'msn' => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
873 'department' => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
874 'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
3a3f3b22 875 'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
01479290
DC
876 'interests' => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
877 'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
878 'lastaccess' => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
b0365ea5
JM
879 'auth' => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL),
880 'confirmed' => new external_value(PARAM_INT, 'Active user: 1 if confirmed, 0 otherwise', VALUE_OPTIONAL),
881 'lang' => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL),
882 'theme' => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
883 'timezone' => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
884 'mailformat' => new external_value(PARAM_INT, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
01479290 885 'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
93ce0e82 886 'descriptionformat' => new external_format_value('description', VALUE_OPTIONAL),
01479290
DC
887 'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
888 'url' => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
889 'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
890 'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
891 'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
892 'customfields' => new external_multiple_structure(
893 new external_single_structure(
894 array(
895 'type' => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
896 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
897 'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
898 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
899 )
bb1105ae 900 ), 'User custom fields (also known as user profile fields)', VALUE_OPTIONAL),
01479290
DC
901 'preferences' => new external_multiple_structure(
902 new external_single_structure(
903 array(
904 'name' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
905 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
906 )
b0365ea5
JM
907 ), 'Users preferences', VALUE_OPTIONAL)
908 );
909 if (!empty($additionalfields)) {
910 $userfields = array_merge($userfields, $additionalfields);
911 }
912 return new external_single_structure($userfields);
01479290 913 }
b0365ea5 914
5d1017e1
JM
915}
916
4615817d
JM
917 /**
918 * Deprecated user external functions
919 *
920 * @package core_user
921 * @copyright 2009 Petr Skodak
922 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
923 * @since Moodle 2.0
924 * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
925 * @todo MDL-31194 This will be deleted in Moodle 2.5.
926 * @see core_user_external
5d1017e1
JM
927 */
928class moodle_user_external extends external_api {
929
930 /**
931 * Returns description of method parameters
4615817d 932 *
5d1017e1 933 * @return external_function_parameters
4615817d
JM
934 * @since Moodle 2.0
935 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
936 * @todo MDL-31194 This will be deleted in Moodle 2.5.
937 * @see core_user_external::create_users_parameters()
5d1017e1
JM
938 */
939 public static function create_users_parameters() {
940 return core_user_external::create_users_parameters();
941 }
942
943 /**
944 * Create one or more users
4615817d 945 *
5d1017e1
JM
946 * @param array $users An array of users to create.
947 * @return array An array of arrays
4615817d
JM
948 * @since Moodle 2.0
949 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
950 * @todo MDL-31194 This will be deleted in Moodle 2.5.
951 * @see core_user_external::create_users()
5d1017e1
JM
952 */
953 public static function create_users($users) {
954 return core_user_external::create_users($users);
955 }
956
957 /**
958 * Returns description of method result value
4615817d 959 *
5d1017e1 960 * @return external_description
4615817d
JM
961 * @since Moodle 2.0
962 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
963 * @todo MDL-31194 This will be deleted in Moodle 2.5.
964 * @see core_user_external::create_users_returns()
5d1017e1
JM
965 */
966 public static function create_users_returns() {
967 return core_user_external::create_users_returns();
968 }
969
970
971 /**
972 * Returns description of method parameters
4615817d 973 *
5d1017e1 974 * @return external_function_parameters
4615817d
JM
975 * @since Moodle 2.0
976 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
977 * @todo MDL-31194 This will be deleted in Moodle 2.5.
978 * @see core_user_external::delete_users_parameters()
5d1017e1
JM
979 */
980 public static function delete_users_parameters() {
981 return core_user_external::delete_users_parameters();
982 }
983
984 /**
985 * Delete users
4615817d 986 *
5d1017e1 987 * @param array $userids
e6acc551 988 * @return null
4615817d
JM
989 * @since Moodle 2.0
990 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
991 * @todo MDL-31194 This will be deleted in Moodle 2.5.
992 * @see core_user_external::delete_users()
5d1017e1
JM
993 */
994 public static function delete_users($userids) {
995 return core_user_external::delete_users($userids);
996 }
997
998 /**
999 * Returns description of method result value
4615817d
JM
1000 *
1001 * @return null
1002 * @since Moodle 2.0
1003 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1004 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1005 * @see core_user_external::delete_users_returns()
5d1017e1
JM
1006 */
1007 public static function delete_users_returns() {
1008 return core_user_external::delete_users_returns();
1009 }
1010
1011
1012 /**
1013 * Returns description of method parameters
4615817d 1014 *
5d1017e1 1015 * @return external_function_parameters
4615817d
JM
1016 * @since Moodle 2.0
1017 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1018 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1019 * @see core_user_external::update_users_parameters()
5d1017e1
JM
1020 */
1021 public static function update_users_parameters() {
1022 return core_user_external::update_users_parameters();
1023 }
1024
1025 /**
1026 * Update users
4615817d 1027 *
5d1017e1 1028 * @param array $users
e6acc551 1029 * @return null
4615817d
JM
1030 * @since Moodle 2.0
1031 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1032 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1033 * @see core_user_external::update_users()
5d1017e1
JM
1034 */
1035 public static function update_users($users) {
1036 return core_user_external::update_users($users);
1037 }
1038
1039 /**
1040 * Returns description of method result value
4615817d
JM
1041 *
1042 * @return null
1043 * @since Moodle 2.0
1044 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1045 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1046 * @see core_user_external::update_users_returns()
5d1017e1
JM
1047 */
1048 public static function update_users_returns() {
1049 return core_user_external::update_users_returns();
1050 }
1051
1052 /**
1053 * Returns description of method parameters
4615817d 1054 *
5d1017e1 1055 * @return external_function_parameters
4615817d
JM
1056 * @since Moodle 2.0
1057 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1058 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1059 * @see core_user_external::get_users_by_id_parameters()
5d1017e1
JM
1060 */
1061 public static function get_users_by_id_parameters() {
1062 return core_user_external::get_users_by_id_parameters();
1063 }
1064
1065 /**
1066 * Get user information
1067 * - This function is matching the permissions of /user/profil.php
1068 * - It is also matching some permissions from /user/editadvanced.php for the following fields:
1069 * auth, confirmed, idnumber, lang, theme, timezone, mailformat
4615817d 1070 *
5d1017e1
JM
1071 * @param array $userids array of user ids
1072 * @return array An array of arrays describing users
4615817d
JM
1073 * @since Moodle 2.0
1074 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1075 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1076 * @see core_user_external::get_users_by_id()
5d1017e1
JM
1077 */
1078 public static function get_users_by_id($userids) {
1079 return core_user_external::get_users_by_id($userids);
1080 }
1081
1082 /**
1083 * Returns description of method result value
4615817d 1084 *
5d1017e1 1085 * @return external_description
4615817d
JM
1086 * @since Moodle 2.0
1087 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1088 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1089 * @see core_user_external::get_users_by_id_returns()
5d1017e1
JM
1090 */
1091 public static function get_users_by_id_returns() {
bb1105ae 1092 return core_user_external::get_users_by_id_returns();
5d1017e1
JM
1093 }
1094 /**
1095 * Returns description of method parameters
4615817d 1096 *
5d1017e1 1097 * @return external_function_parameters
4615817d
JM
1098 * @since Moodle 2.1
1099 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1100 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1101 * @see core_user_external::get_course_user_profiles_parameters()
5d1017e1
JM
1102 */
1103 public static function get_course_participants_by_id_parameters() {
1104 return core_user_external::get_course_user_profiles_parameters();
1105 }
1106
1107 /**
1108 * Get course participant's details
4615817d 1109 *
5d1017e1
JM
1110 * @param array $userlist array of user ids and according course ids
1111 * @return array An array of arrays describing course participants
4615817d
JM
1112 * @since Moodle 2.1
1113 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1114 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1115 * @see core_user_external::get_course_user_profiles()
5d1017e1
JM
1116 */
1117 public static function get_course_participants_by_id($userlist) {
1118 return core_user_external::get_course_user_profiles($userlist);
1119 }
1120
1121 /**
1122 * Returns description of method result value
4615817d 1123 *
5d1017e1 1124 * @return external_description
4615817d
JM
1125 * @since Moodle 2.1
1126 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1127 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1128 * @see core_user_external::get_course_user_profiles_returns()
5d1017e1
JM
1129 */
1130 public static function get_course_participants_by_id_returns() {
1131 return core_user_external::get_course_user_profiles_returns();
1132 }
ea4e96c2 1133
01479290
DC
1134 /**
1135 * Returns description of method parameters
4615817d 1136 *
01479290 1137 * @return external_function_parameters
4615817d
JM
1138 * @since Moodle 2.1
1139 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1140 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1141 * @see core_enrol_external::get_enrolled_users_parameters()
01479290
DC
1142 */
1143 public static function get_users_by_courseid_parameters() {
5d1017e1
JM
1144 global $CFG;
1145 require_once($CFG->dirroot . '/enrol/externallib.php');
1146 return core_enrol_external::get_enrolled_users_parameters();
01479290 1147 }
ea4e96c2 1148
01479290
DC
1149 /**
1150 * Get course participants details
4615817d 1151 *
01479290
DC
1152 * @param int $courseid course id
1153 * @param array $options options {
4615817d
JM
1154 * 'name' => option name
1155 * 'value' => option value
1156 * }
01479290 1157 * @return array An array of users
4615817d
JM
1158 * @since Moodle 2.1
1159 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1160 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1161 * @see core_enrol_external::get_enrolled_users()
01479290
DC
1162 */
1163 public static function get_users_by_courseid($courseid, $options) {
5d1017e1
JM
1164 global $CFG;
1165 require_once($CFG->dirroot . '/enrol/externallib.php');
1166 return core_enrol_external::get_enrolled_users($courseid, $options);
ea4e96c2 1167 }
ea4e96c2
DC
1168 /**
1169 * Returns description of method result value
4615817d 1170 *
ea4e96c2 1171 * @return external_description
4615817d
JM
1172 * @since Moodle 2.1
1173 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1174 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1175 * @see core_enrol_external::get_enrolled_users_returns()
ea4e96c2 1176 */
01479290 1177 public static function get_users_by_courseid_returns() {
5d1017e1
JM
1178 global $CFG;
1179 require_once($CFG->dirroot . '/enrol/externallib.php');
1180 return core_enrol_external::get_enrolled_users_returns();
5de592b1 1181 }
b0365ea5 1182}