3 // This file is part of Moodle - http://moodle.org/
5 // Moodle is free software: you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation, either version 3 of the License, or
8 // (at your option) any later version.
10 // Moodle is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 // GNU General Public License for more details.
15 // You should have received a copy of the GNU General Public License
16 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
22 * @subpackage webservice
23 * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27 require_once("$CFG->libdir/externallib.php");
32 class core_user_external
extends external_api
{
35 * Returns description of method parameters
36 * @return external_function_parameters
38 public static function create_users_parameters() {
41 return new external_function_parameters(
43 'users' => new external_multiple_structure(
44 new external_single_structure(
46 'username' => new external_value(PARAM_RAW
, 'Username policy is defined in Moodle security config'),
47 'password' => new external_value(PARAM_RAW
, 'Plain text password consisting of any characters'),
48 'firstname' => new external_value(PARAM_NOTAGS
, 'The first name(s) of the user'),
49 'lastname' => new external_value(PARAM_NOTAGS
, 'The family name of the user'),
50 'email' => new external_value(PARAM_EMAIL
, 'A valid and unique email address'),
51 'auth' => new external_value(PARAM_PLUGIN
, 'Auth plugins include manual, ldap, imap, etc', VALUE_DEFAULT
, 'manual', NULL_NOT_ALLOWED
),
52 'idnumber' => new external_value(PARAM_RAW
, 'An arbitrary ID code number perhaps from the institution', VALUE_DEFAULT
, ''),
53 'lang' => new external_value(PARAM_SAFEDIR
, 'Language code such as "en", must exist on server', VALUE_DEFAULT
, $CFG->lang
, NULL_NOT_ALLOWED
),
54 'theme' => new external_value(PARAM_PLUGIN
, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL
),
55 'timezone' => new external_value(PARAM_TIMEZONE
, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL
),
56 'mailformat' => new external_value(PARAM_INTEGER
, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL
),
57 'description' => new external_value(PARAM_TEXT
, 'User profile description, no HTML', VALUE_OPTIONAL
),
58 'city' => new external_value(PARAM_NOTAGS
, 'Home city of the user', VALUE_OPTIONAL
),
59 'country' => new external_value(PARAM_ALPHA
, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL
),
60 'preferences' => new external_multiple_structure(
61 new external_single_structure(
63 'type' => new external_value(PARAM_ALPHANUMEXT
, 'The name of the preference'),
64 'value' => new external_value(PARAM_RAW
, 'The value of the preference')
66 ), 'User preferences', VALUE_OPTIONAL
),
67 'customfields' => new external_multiple_structure(
68 new external_single_structure(
70 'type' => new external_value(PARAM_ALPHANUMEXT
, 'The name of the custom field'),
71 'value' => new external_value(PARAM_RAW
, 'The value of the custom field')
73 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL
)
82 * Create one or more users
84 * @param array $users An array of users to create.
85 * @return array An array of arrays
87 public static function create_users($users) {
89 require_once($CFG->dirroot
."/user/lib.php");
90 require_once($CFG->dirroot
."/user/profile/lib.php"); //required for customfields related function
91 //TODO: move the functions somewhere else as
92 //they are "user" related
94 // Ensure the current user is allowed to run this function
95 $context = get_context_instance(CONTEXT_SYSTEM
);
96 self
::validate_context($context);
97 require_capability('moodle/user:create', $context);
99 // Do basic automatic PARAM checks on incoming data, using params description
100 // If any problems are found then exceptions are thrown with helpful error messages
101 $params = self
::validate_parameters(self
::create_users_parameters(), array('users'=>$users));
103 $availableauths = get_plugin_list('auth');
104 unset($availableauths['mnet']); // these would need mnethostid too
105 unset($availableauths['webservice']); // we do not want new webservice users for now
107 $availablethemes = get_plugin_list('theme');
108 $availablelangs = get_string_manager()->get_list_of_translations();
110 $transaction = $DB->start_delegated_transaction();
113 foreach ($params['users'] as $user) {
114 // Make sure that the username doesn't already exist
115 if ($DB->record_exists('user', array('username'=>$user['username'], 'mnethostid'=>$CFG->mnet_localhost_id
))) {
116 throw new invalid_parameter_exception('Username already exists: '.$user['username']);
119 // Make sure auth is valid
120 if (empty($availableauths[$user['auth']])) {
121 throw new invalid_parameter_exception('Invalid authentication type: '.$user['auth']);
124 // Make sure lang is valid
125 if (empty($availablelangs[$user['lang']])) {
126 throw new invalid_parameter_exception('Invalid language code: '.$user['lang']);
129 // Make sure lang is valid
130 if (!empty($user['theme']) && empty($availablethemes[$user['theme']])) { //theme is VALUE_OPTIONAL,
131 // so no default value.
132 // We need to test if the client sent it
133 // => !empty($user['theme'])
134 throw new invalid_parameter_exception('Invalid theme: '.$user['theme']);
137 // make sure there is no data loss during truncation
138 $truncated = truncate_userinfo($user);
139 foreach ($truncated as $key=>$value) {
140 if ($truncated[$key] !== $user[$key]) {
141 throw new invalid_parameter_exception('Property: '.$key.' is too long: '.$user[$key]);
145 $user['confirmed'] = true;
146 $user['mnethostid'] = $CFG->mnet_localhost_id
;
147 $user['id'] = user_create_user($user);
150 if(!empty($user['customfields'])) {
151 foreach($user['customfields'] as $customfield) {
152 $user["profile_field_".$customfield['type']] = $customfield['value']; //profile_save_data() saves profile file
153 //it's expecting a user with the correct id,
154 //and custom field to be named profile_field_"shortname"
156 profile_save_data((object) $user);
160 if (!empty($user['preferences'])) {
161 foreach($user['preferences'] as $preference) {
162 set_user_preference($preference['type'], $preference['value'],$user['id']);
166 $userids[] = array('id'=>$user['id'], 'username'=>$user['username']);
169 $transaction->allow_commit();
175 * Returns description of method result value
176 * @return external_description
178 public static function create_users_returns() {
179 return new external_multiple_structure(
180 new external_single_structure(
182 'id' => new external_value(PARAM_INT
, 'user id'),
183 'username' => new external_value(PARAM_RAW
, 'user name'),
191 * Returns description of method parameters
192 * @return external_function_parameters
194 public static function delete_users_parameters() {
195 return new external_function_parameters(
197 'userids' => new external_multiple_structure(new external_value(PARAM_INT
, 'user ID')),
204 * @param array $userids
207 public static function delete_users($userids) {
208 global $CFG, $DB, $USER;
209 require_once($CFG->dirroot
."/user/lib.php");
211 // Ensure the current user is allowed to run this function
212 $context = get_context_instance(CONTEXT_SYSTEM
);
213 require_capability('moodle/user:delete', $context);
214 self
::validate_context($context);
216 $params = self
::validate_parameters(self
::delete_users_parameters(), array('userids'=>$userids));
218 $transaction = $DB->start_delegated_transaction();
220 foreach ($params['userids'] as $userid) {
221 $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0), '*', MUST_EXIST
);
222 // must not allow deleting of admins or self!!!
223 if (is_siteadmin($user)) {
224 throw new moodle_exception('useradminodelete', 'error');
226 if ($USER->id
== $user->id
) {
227 throw new moodle_exception('usernotdeletederror', 'error');
229 user_delete_user($user);
232 $transaction->allow_commit();
238 * Returns description of method result value
239 * @return external_description
241 public static function delete_users_returns() {
247 * Returns description of method parameters
248 * @return external_function_parameters
250 public static function update_users_parameters() {
252 return new external_function_parameters(
254 'users' => new external_multiple_structure(
255 new external_single_structure(
257 'id' => new external_value(PARAM_NUMBER
, 'ID of the user'),
258 'username' => new external_value(PARAM_RAW
, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL
, '',NULL_NOT_ALLOWED
),
259 'password' => new external_value(PARAM_RAW
, 'Plain text password consisting of any characters', VALUE_OPTIONAL
, '',NULL_NOT_ALLOWED
),
260 'firstname' => new external_value(PARAM_NOTAGS
, 'The first name(s) of the user', VALUE_OPTIONAL
, '',NULL_NOT_ALLOWED
),
261 'lastname' => new external_value(PARAM_NOTAGS
, 'The family name of the user', VALUE_OPTIONAL
),
262 'email' => new external_value(PARAM_EMAIL
, 'A valid and unique email address', VALUE_OPTIONAL
, '',NULL_NOT_ALLOWED
),
263 'auth' => new external_value(PARAM_PLUGIN
, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL
, '', NULL_NOT_ALLOWED
),
264 'idnumber' => new external_value(PARAM_RAW
, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL
),
265 'lang' => new external_value(PARAM_SAFEDIR
, 'Language code such as "en", must exist on server', VALUE_OPTIONAL
, '', NULL_NOT_ALLOWED
),
266 'theme' => new external_value(PARAM_PLUGIN
, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL
),
267 'timezone' => new external_value(PARAM_TIMEZONE
, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL
),
268 'mailformat' => new external_value(PARAM_INTEGER
, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL
),
269 'description' => new external_value(PARAM_TEXT
, 'User profile description, no HTML', VALUE_OPTIONAL
),
270 'city' => new external_value(PARAM_NOTAGS
, 'Home city of the user', VALUE_OPTIONAL
),
271 'country' => new external_value(PARAM_ALPHA
, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL
),
272 'customfields' => new external_multiple_structure(
273 new external_single_structure(
275 'type' => new external_value(PARAM_ALPHANUMEXT
, 'The name of the custom field'),
276 'value' => new external_value(PARAM_RAW
, 'The value of the custom field')
278 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL
),
279 'preferences' => new external_multiple_structure(
280 new external_single_structure(
282 'type' => new external_value(PARAM_ALPHANUMEXT
, 'The name of the preference'),
283 'value' => new external_value(PARAM_RAW
, 'The value of the preference')
285 ), 'User preferences', VALUE_OPTIONAL
),
295 * @param array $users
298 public static function update_users($users) {
300 require_once($CFG->dirroot
."/user/lib.php");
301 require_once($CFG->dirroot
."/user/profile/lib.php"); //required for customfields related function
302 //TODO: move the functions somewhere else as
303 //they are "user" related
305 // Ensure the current user is allowed to run this function
306 $context = get_context_instance(CONTEXT_SYSTEM
);
307 require_capability('moodle/user:update', $context);
308 self
::validate_context($context);
310 $params = self
::validate_parameters(self
::update_users_parameters(), array('users'=>$users));
312 $transaction = $DB->start_delegated_transaction();
314 foreach ($params['users'] as $user) {
315 user_update_user($user);
316 //update user custom fields
317 if(!empty($user['customfields'])) {
319 foreach($user['customfields'] as $customfield) {
320 $user["profile_field_".$customfield['type']] = $customfield['value']; //profile_save_data() saves profile file
321 //it's expecting a user with the correct id,
322 //and custom field to be named profile_field_"shortname"
324 profile_save_data((object) $user);
328 if (!empty($user['preferences'])) {
329 foreach($user['preferences'] as $preference) {
330 set_user_preference($preference['type'], $preference['value'],$user['id']);
335 $transaction->allow_commit();
341 * Returns description of method result value
342 * @return external_description
344 public static function update_users_returns() {
349 * Returns description of method parameters
350 * @return external_function_parameters
352 public static function get_users_by_id_parameters() {
353 return new external_function_parameters(
355 'userids' => new external_multiple_structure(new external_value(PARAM_INT
, 'user ID')),
361 * Get user information
362 * - This function is matching the permissions of /user/profil.php
363 * - It is also matching some permissions from /user/editadvanced.php for the following fields:
364 * auth, confirmed, idnumber, lang, theme, timezone, mailformat
365 * @param array $userids array of user ids
366 * @return array An array of arrays describing users
368 public static function get_users_by_id($userids) {
369 global $CFG, $USER, $DB;
370 require_once($CFG->dirroot
. "/user/lib.php");
372 $params = self
::validate_parameters(self
::get_users_by_id_parameters(),
373 array('userids'=>$userids));
375 list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER
, 'ctx');
376 list($sqluserids, $params) = $DB->get_in_or_equal($userids);
377 $usersql = "SELECT u.* $uselect
379 WHERE u.id $sqluserids";
380 $users = $DB->get_recordset_sql($usersql, $params);
383 $hasuserupdatecap = has_capability('moodle/user:update', get_system_context());
384 foreach ($users as $user) {
385 if (!empty($user->deleted
)) {
388 context_instance_preload($user);
389 $usercontext = get_context_instance(CONTEXT_USER
, $user->id
);
390 self
::validate_context($usercontext);
391 $currentuser = ($user->id
== $USER->id
);
393 if ($userarray = user_get_user_details($user)) {
394 //fields matching permissions from /user/editadvanced.php
395 if ($currentuser or $hasuserupdatecap) {
396 $userarray['auth'] = $user->auth
;
397 $userarray['confirmed'] = $user->confirmed
;
398 $userarray['idnumber'] = $user->idnumber
;
399 $userarray['lang'] = $user->lang
;
400 $userarray['theme'] = $user->theme
;
401 $userarray['timezone'] = $user->timezone
;
402 $userarray['mailformat'] = $user->mailformat
;
404 $result[] = $userarray;
413 * Returns description of method result value
414 * @return external_description
416 public static function get_users_by_id_returns() {
417 return new external_multiple_structure(
418 new external_single_structure(
420 'id' => new external_value(PARAM_NUMBER
, 'ID of the user'),
421 'username' => new external_value(PARAM_RAW
, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL
),
422 'firstname' => new external_value(PARAM_NOTAGS
, 'The first name(s) of the user', VALUE_OPTIONAL
),
423 'lastname' => new external_value(PARAM_NOTAGS
, 'The family name of the user', VALUE_OPTIONAL
),
424 'fullname' => new external_value(PARAM_NOTAGS
, 'The fullname of the user'),
425 'email' => new external_value(PARAM_TEXT
, 'An email address - allow email as root@localhost', VALUE_OPTIONAL
),
426 'address' => new external_value(PARAM_MULTILANG
, 'Postal address', VALUE_OPTIONAL
),
427 'phone1' => new external_value(PARAM_NOTAGS
, 'Phone 1', VALUE_OPTIONAL
),
428 'phone2' => new external_value(PARAM_NOTAGS
, 'Phone 2', VALUE_OPTIONAL
),
429 'icq' => new external_value(PARAM_NOTAGS
, 'icq number', VALUE_OPTIONAL
),
430 'skype' => new external_value(PARAM_NOTAGS
, 'skype id', VALUE_OPTIONAL
),
431 'yahoo' => new external_value(PARAM_NOTAGS
, 'yahoo id', VALUE_OPTIONAL
),
432 'aim' => new external_value(PARAM_NOTAGS
, 'aim id', VALUE_OPTIONAL
),
433 'msn' => new external_value(PARAM_NOTAGS
, 'msn number', VALUE_OPTIONAL
),
434 'department' => new external_value(PARAM_TEXT
, 'department', VALUE_OPTIONAL
),
435 'institution' => new external_value(PARAM_TEXT
, 'institution', VALUE_OPTIONAL
),
436 'interests' => new external_value(PARAM_TEXT
, 'user interests (separated by commas)', VALUE_OPTIONAL
),
437 'firstaccess' => new external_value(PARAM_INT
, 'first access to the site (0 if never)', VALUE_OPTIONAL
),
438 'lastaccess' => new external_value(PARAM_INT
, 'last access to the site (0 if never)', VALUE_OPTIONAL
),
439 'auth' => new external_value(PARAM_PLUGIN
, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL
),
440 'confirmed' => new external_value(PARAM_NUMBER
, 'Active user: 1 if confirmed, 0 otherwise', VALUE_OPTIONAL
),
441 'idnumber' => new external_value(PARAM_RAW
, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL
),
442 'lang' => new external_value(PARAM_SAFEDIR
, 'Language code such as "en", must exist on server', VALUE_OPTIONAL
),
443 'theme' => new external_value(PARAM_PLUGIN
, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL
),
444 'timezone' => new external_value(PARAM_TIMEZONE
, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL
),
445 'mailformat' => new external_value(PARAM_INTEGER
, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL
),
446 'description' => new external_value(PARAM_RAW
, 'User profile description', VALUE_OPTIONAL
),
447 'descriptionformat' => new external_value(PARAM_INT
, 'User profile description format', VALUE_OPTIONAL
),
448 'city' => new external_value(PARAM_NOTAGS
, 'Home city of the user', VALUE_OPTIONAL
),
449 'url' => new external_value(PARAM_URL
, 'URL of the user', VALUE_OPTIONAL
),
450 'country' => new external_value(PARAM_ALPHA
, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL
),
451 'profileimageurlsmall' => new external_value(PARAM_URL
, 'User image profile URL - small version'),
452 'profileimageurl' => new external_value(PARAM_URL
, 'User image profile URL - big version'),
453 'customfields' => new external_multiple_structure(
454 new external_single_structure(
456 'type' => new external_value(PARAM_ALPHANUMEXT
, 'The type of the custom field - text field, checkbox...'),
457 'value' => new external_value(PARAM_RAW
, 'The value of the custom field'),
458 'name' => new external_value(PARAM_RAW
, 'The name of the custom field'),
459 'shortname' => new external_value(PARAM_RAW
, 'The shortname of the custom field - to be able to build the field class in the code'),
461 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL
),
462 'preferences' => new external_multiple_structure(
463 new external_single_structure(
465 'name' => new external_value(PARAM_ALPHANUMEXT
, 'The name of the preferences'),
466 'value' => new external_value(PARAM_RAW
, 'The value of the custom field'),
468 ), 'User preferences', VALUE_OPTIONAL
),
469 'enrolledcourses' => new external_multiple_structure(
470 new external_single_structure(
472 'id' => new external_value(PARAM_INT
, 'Id of the course'),
473 'fullname' => new external_value(PARAM_RAW
, 'Fullname of the course'),
474 'shortname' => new external_value(PARAM_RAW
, 'Shortname of the course')
476 ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL
)
482 * Returns description of method parameters
483 * @return external_function_parameters
485 public static function get_course_user_profiles_parameters() {
486 return new external_function_parameters(
488 'userlist' => new external_multiple_structure(
489 new external_single_structure(
491 'userid' => new external_value(PARAM_INT
, 'userid'),
492 'courseid' => new external_value(PARAM_INT
, 'courseid'),
501 * Get course participant's details
502 * @param array $userlist array of user ids and according course ids
503 * @return array An array of arrays describing course participants
505 public static function get_course_user_profiles($userlist) {
506 global $CFG, $USER, $DB;
507 require_once($CFG->dirroot
. "/user/lib.php");
508 $params = self
::validate_parameters(self
::get_course_user_profiles_parameters(), array('userlist'=>$userlist));
511 $courseids = array();
512 foreach ($params['userlist'] as $value) {
513 $userids[] = $value['userid'];
514 $courseids[$value['userid']] = $value['courseid'];
519 list($cselect, $cjoin) = context_instance_preload_sql('c.id', CONTEXT_COURSE
, 'ctx');
520 list($sqlcourseids, $params) = $DB->get_in_or_equal(array_unique($courseids));
521 $coursesql = "SELECT c.* $uselect
522 FROM {course} c $cjoin
523 WHERE c.id $sqlcourseids";
524 $rs = $DB->get_recordset_sql($coursesql, $params);
525 foreach ($rs as $course) {
526 // adding course contexts to cache
527 context_instance_preload($course);
529 $courses[$course->id
] = $course;
533 list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER
, 'ctx');
534 list($sqluserids, $params) = $DB->get_in_or_equal($userids);
535 $usersql = "SELECT u.* $uselect
537 WHERE u.id $sqluserids";
538 $users = $DB->get_recordset_sql($usersql, $params);
540 foreach ($users as $user) {
541 if (!empty($user->deleted
)) {
544 context_instance_preload($user);
545 $course = $courses[$courseids[$user->id
]];
546 $context = get_context_instance(CONTEXT_COURSE
, $courseids[$user->id
]);
547 self
::validate_context($context);
548 if ($userarray = user_get_user_details($user, $course)) {
549 $result[] = $userarray;
559 * Returns description of method result value
560 * @return external_description
562 public static function get_course_user_profiles_returns() {
563 return new external_multiple_structure(
564 new external_single_structure(
566 'id' => new external_value(PARAM_NUMBER
, 'ID of the user'),
567 'username' => new external_value(PARAM_RAW
, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL
),
568 'firstname' => new external_value(PARAM_NOTAGS
, 'The first name(s) of the user', VALUE_OPTIONAL
),
569 'lastname' => new external_value(PARAM_NOTAGS
, 'The family name of the user', VALUE_OPTIONAL
),
570 'fullname' => new external_value(PARAM_NOTAGS
, 'The fullname of the user'),
571 'email' => new external_value(PARAM_TEXT
, 'An email address - allow email as root@localhost', VALUE_OPTIONAL
),
572 'address' => new external_value(PARAM_MULTILANG
, 'Postal address', VALUE_OPTIONAL
),
573 'phone1' => new external_value(PARAM_NOTAGS
, 'Phone 1', VALUE_OPTIONAL
),
574 'phone2' => new external_value(PARAM_NOTAGS
, 'Phone 2', VALUE_OPTIONAL
),
575 'icq' => new external_value(PARAM_NOTAGS
, 'icq number', VALUE_OPTIONAL
),
576 'skype' => new external_value(PARAM_NOTAGS
, 'skype id', VALUE_OPTIONAL
),
577 'yahoo' => new external_value(PARAM_NOTAGS
, 'yahoo id', VALUE_OPTIONAL
),
578 'aim' => new external_value(PARAM_NOTAGS
, 'aim id', VALUE_OPTIONAL
),
579 'msn' => new external_value(PARAM_NOTAGS
, 'msn number', VALUE_OPTIONAL
),
580 'department' => new external_value(PARAM_TEXT
, 'department', VALUE_OPTIONAL
),
581 'institution' => new external_value(PARAM_TEXT
, 'institution', VALUE_OPTIONAL
),
582 'interests' => new external_value(PARAM_TEXT
, 'user interests (separated by commas)', VALUE_OPTIONAL
),
583 'firstaccess' => new external_value(PARAM_INT
, 'first access to the site (0 if never)', VALUE_OPTIONAL
),
584 'lastaccess' => new external_value(PARAM_INT
, 'last access to the site (0 if never)', VALUE_OPTIONAL
),
585 'description' => new external_value(PARAM_RAW
, 'User profile description', VALUE_OPTIONAL
),
586 'descriptionformat' => new external_value(PARAM_INT
, 'User profile description format', VALUE_OPTIONAL
),
587 'city' => new external_value(PARAM_NOTAGS
, 'Home city of the user', VALUE_OPTIONAL
),
588 'url' => new external_value(PARAM_URL
, 'URL of the user', VALUE_OPTIONAL
),
589 'country' => new external_value(PARAM_ALPHA
, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL
),
590 'profileimageurlsmall' => new external_value(PARAM_URL
, 'User image profile URL - small version'),
591 'profileimageurl' => new external_value(PARAM_URL
, 'User image profile URL - big version'),
592 'customfields' => new external_multiple_structure(
593 new external_single_structure(
595 'type' => new external_value(PARAM_ALPHANUMEXT
, 'The type of the custom field - text field, checkbox...'),
596 'value' => new external_value(PARAM_RAW
, 'The value of the custom field'),
597 'name' => new external_value(PARAM_RAW
, 'The name of the custom field'),
598 'shortname' => new external_value(PARAM_RAW
, 'The shortname of the custom field - to be able to build the field class in the code'),
600 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL
),
601 'groups' => new external_multiple_structure(
602 new external_single_structure(
604 'id' => new external_value(PARAM_INT
, 'group id'),
605 'name' => new external_value(PARAM_RAW
, 'group name'),
606 'description' => new external_value(PARAM_RAW
, 'group description'),
608 ), 'user groups', VALUE_OPTIONAL
),
609 'roles' => new external_multiple_structure(
610 new external_single_structure(
612 'roleid' => new external_value(PARAM_INT
, 'role id'),
613 'name' => new external_value(PARAM_RAW
, 'role name'),
614 'shortname' => new external_value(PARAM_ALPHANUMEXT
, 'role shortname'),
615 'sortorder' => new external_value(PARAM_INT
, 'role sortorder')
617 ), 'user roles', VALUE_OPTIONAL
),
618 'preferences' => new external_multiple_structure(
619 new external_single_structure(
621 'name' => new external_value(PARAM_ALPHANUMEXT
, 'The name of the preferences'),
622 'value' => new external_value(PARAM_RAW
, 'The value of the custom field'),
624 ), 'User preferences', VALUE_OPTIONAL
),
625 'enrolledcourses' => new external_multiple_structure(
626 new external_single_structure(
628 'id' => new external_value(PARAM_INT
, 'Id of the course'),
629 'fullname' => new external_value(PARAM_RAW
, 'Fullname of the course'),
630 'shortname' => new external_value(PARAM_RAW
, 'Shortname of the course')
632 ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL
)
640 * Deprecated user functions
641 * @deprecated since Moodle 2.2 please use core_user_external instead
643 class moodle_user_external
extends external_api
{
646 * Returns description of method parameters
647 * @deprecated since Moodle 2.2 please use core_user_external::create_users_parameters instead
648 * @return external_function_parameters
650 public static function create_users_parameters() {
651 return core_user_external
::create_users_parameters();
655 * Create one or more users
656 * @deprecated since Moodle 2.2 please use core_user_external::create_users instead
657 * @param array $users An array of users to create.
658 * @return array An array of arrays
660 public static function create_users($users) {
661 return core_user_external
::create_users($users);
665 * Returns description of method result value
666 * @deprecated since Moodle 2.2 please use core_user_external::create_users_returns instead
667 * @return external_description
669 public static function create_users_returns() {
670 return core_user_external
::create_users_returns();
675 * Returns description of method parameters
676 * @deprecated since Moodle 2.2 please use core_user_external::delete_users_parameters instead
677 * @return external_function_parameters
679 public static function delete_users_parameters() {
680 return core_user_external
::delete_users_parameters();
685 * @deprecated since Moodle 2.2 please use core_user_external::delete_users instead
686 * @param array $userids
689 public static function delete_users($userids) {
690 return core_user_external
::delete_users($userids);
694 * Returns description of method result value
695 * @deprecated since Moodle 2.2 please use core_user_external::delete_users_returns instead
696 * @return external_description
698 public static function delete_users_returns() {
699 return core_user_external
::delete_users_returns();
704 * Returns description of method parameters
705 * @deprecated since Moodle 2.2 please use core_user_external::update_users_parameters instead
706 * @return external_function_parameters
708 public static function update_users_parameters() {
709 return core_user_external
::update_users_parameters();
714 * @deprecated since Moodle 2.2 please use core_user_external::update_users instead
715 * @param array $users
718 public static function update_users($users) {
719 return core_user_external
::update_users($users);
723 * Returns description of method result value
724 * @deprecated since Moodle 2.2 please use core_user_external::update_users_returns instead
725 * @return external_description
727 public static function update_users_returns() {
728 return core_user_external
::update_users_returns();
732 * Returns description of method parameters
733 * @deprecated since Moodle 2.2 please use core_user_external::get_users_by_id_parameters instead
734 * @return external_function_parameters
736 public static function get_users_by_id_parameters() {
737 return core_user_external
::get_users_by_id_parameters();
741 * Get user information
742 * - This function is matching the permissions of /user/profil.php
743 * - It is also matching some permissions from /user/editadvanced.php for the following fields:
744 * auth, confirmed, idnumber, lang, theme, timezone, mailformat
745 * @deprecated since Moodle 2.2 please use core_user_external::get_users_by_id instead
746 * @param array $userids array of user ids
747 * @return array An array of arrays describing users
749 public static function get_users_by_id($userids) {
750 return core_user_external
::get_users_by_id($userids);
754 * Returns description of method result value
755 * @deprecated since Moodle 2.2 please use core_user_external::get_users_by_id_returns instead
756 * @return external_description
758 public static function get_users_by_id_returns() {
759 return core_user_external
::get_users_by_id_returns();
762 * Returns description of method parameters
763 * @deprecated since Moodle 2.2 please use core_user_external::get_course_user_profiles_parameters instead
764 * @return external_function_parameters
766 public static function get_course_participants_by_id_parameters() {
767 return core_user_external
::get_course_user_profiles_parameters();
771 * Get course participant's details
772 * @deprecated since Moodle 2.2 please use core_user_external::get_course_user_profiles instead
773 * @param array $userlist array of user ids and according course ids
774 * @return array An array of arrays describing course participants
776 public static function get_course_participants_by_id($userlist) {
777 return core_user_external
::get_course_user_profiles($userlist);
781 * Returns description of method result value
782 * @deprecated since Moodle 2.2 please use core_user_external::get_course_user_profiles_returns instead
783 * @return external_description
785 public static function get_course_participants_by_id_returns() {
786 return core_user_external
::get_course_user_profiles_returns();
790 * Returns description of method parameters
791 * @deprecated since Moodle 2.2 please use core_enrol_external::get_enrolled_users_parameters instead
792 * @return external_function_parameters
794 public static function get_users_by_courseid_parameters() {
796 require_once($CFG->dirroot
. '/enrol/externallib.php');
797 return core_enrol_external
::get_enrolled_users_parameters();
801 * Get course participants details
802 * @deprecated since Moodle 2.2 please use core_enrol_external::get_enrolled_users instead
803 * @param int $courseid course id
804 * @param array $options options {
805 * 'name' => option name
806 * 'value' => option value
808 * @return array An array of users
810 public static function get_users_by_courseid($courseid, $options) {
812 require_once($CFG->dirroot
. '/enrol/externallib.php');
813 return core_enrol_external
::get_enrolled_users($courseid, $options);
816 * Returns description of method result value
817 * @deprecated since Moodle 2.2 please use core_enrol_external::get_enrolled_users_returns instead
818 * @return external_description
820 public static function get_users_by_courseid_returns() {
822 require_once($CFG->dirroot
. '/enrol/externallib.php');
823 return core_enrol_external
::get_enrolled_users_returns();