user/externallib.php

   1 <?php
   2
   3 // This file is part of Moodle - http://moodle.org/
   4 //
   5 // Moodle is free software: you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation, either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // Moodle is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 /**
  19  * External user API
  20  *
  21  * @package    moodlecore
  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
  25  */
  26
  27 require_once("$CFG->libdir/externallib.php");
  28
  29 class moodle_user_external extends external_api {
  30
  31     /**
  32      * Returns description of method parameters
  33      * @return external_function_parameters
  34      */
  35     public static function create_users_parameters() {
  36         global $CFG;
  37
  38         return new external_function_parameters(
  39             array(
  40                 'users' => new external_multiple_structure(
  41                     new external_single_structure(
  42                         array(
  43                             'username'    => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config'),
  44                             'password'    => new external_value(PARAM_RAW, 'Plain text password consisting of any characters'),
  45                             'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user'),
  46                             'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user'),
  47                             'email'       => new external_value(PARAM_EMAIL, 'A valid and unique email address'),
  48                             'auth'        => new external_value(PARAM_SAFEDIR, 'Auth plugins include manual, ldap, imap, etc', VALUE_DEFAULT, 'manual', NULL_NOT_ALLOWED),
  49                             'idnumber'    => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_DEFAULT, ''),
  50                             'lang'        => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_DEFAULT, $CFG->lang, NULL_NOT_ALLOWED),
  51                             'theme'       => new external_value(PARAM_SAFEDIR, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
  52                             'timezone'    => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
  53                             'mailformat'  => new external_value(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
  54                             'description' => new external_value(PARAM_TEXT, 'User profile description, no HTML', VALUE_OPTIONAL),
  55                             'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
  56                             'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
  57                             'preferences' => new external_multiple_structure(
  58                                 new external_single_structure(
  59                                     array(
  60                                         'type'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the preference'),
  61                                         'value' => new external_value(PARAM_RAW, 'The value of the preference')
  62                                     )
  63                                 ), 'User preferences', VALUE_OPTIONAL),
  64                             'customfields' => new external_multiple_structure(
  65                                 new external_single_structure(
  66                                     array(
  67                                         'type'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
  68                                         'value' => new external_value(PARAM_RAW, 'The value of the custom field')
  69                                     )
  70                                 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL)
  71                         )
  72                     )
  73                 )
  74             )
  75         );
  76     }
  77
  78     /**
  79      * Create one or more users
  80      *
  81      * @param array $users  An array of users to create.
  82      * @return array An array of arrays
  83      */
  84     public static function create_users($users) {
  85         global $CFG, $DB;
  86         require_once($CFG->dirroot."/user/lib.php");
  87         require_once($CFG->dirroot."/user/profile/lib.php"); //required for customfields related function
  88                                                              //TODO: move the functions somewhere else as
  89                                                              //they are "user" related
  90
  91         // Ensure the current user is allowed to run this function
  92         $context = get_context_instance(CONTEXT_SYSTEM);
  93         self::validate_context($context);
  94         require_capability('moodle/user:create', $context);
  95
  96         // Do basic automatic PARAM checks on incoming data, using params description
  97         // If any problems are found then exceptions are thrown with helpful error messages
  98         $params = self::validate_parameters(self::create_users_parameters(), array('users'=>$users));
  99
 100         $availableauths  = get_plugin_list('auth');
 101         unset($availableauths['mnet']);       // these would need mnethostid too
 102         unset($availableauths['webservice']); // we do not want new webservice users for now
 103
 104         $availablethemes = get_plugin_list('theme');
 105         $availablelangs  = get_string_manager()->get_list_of_translations();
 106
 107         $transaction = $DB->start_delegated_transaction();
 108
 109         $userids = array();
 110         foreach ($params['users'] as $user) {
 111             // Make sure that the username doesn't already exist
 112             if ($DB->record_exists('user', array('username'=>$user['username'], 'mnethostid'=>$CFG->mnet_localhost_id))) {
 113                 throw new invalid_parameter_exception('Username already exists: '.$user['username']);
 114             }
 115
 116             // Make sure auth is valid
 117             if (empty($availableauths[$user['auth']])) {
 118                 throw new invalid_parameter_exception('Invalid authentication type: '.$user['auth']);
 119             }
 120
 121             // Make sure lang is valid
 122             if (empty($availablelangs[$user['lang']])) {
 123                 throw new invalid_parameter_exception('Invalid language code: '.$user['lang']);
 124             }
 125
 126             // Make sure lang is valid
 127             if (!empty($user['theme']) && empty($availablethemes[$user['theme']])) { //theme is VALUE_OPTIONAL,
 128                                                                                      // so no default value.
 129                                                                                      // We need to test if the client sent it
 130                                                                                      // => !empty($user['theme'])
 131                 throw new invalid_parameter_exception('Invalid theme: '.$user['theme']);
 132             }
 133
 134             // make sure there is no data loss during truncation
 135             $truncated = truncate_userinfo($user);
 136             foreach ($truncated as $key=>$value) {
 137                     if ($truncated[$key] !== $user[$key]) {
 138                         throw new invalid_parameter_exception('Property: '.$key.' is too long: '.$user[$key]);
 139                     }
 140             }
 141
 142             $user['confirmed'] = true;
 143             $user['mnethostid'] = $CFG->mnet_localhost_id;
 144             $user['id'] = user_create_user($user);
 145
 146             // custom fields
 147             if(!empty($user['customfields'])) {
 148                 foreach($user['customfields'] as $customfield) {
 149                     $user["profile_field_".$customfield['type']] = $customfield['value']; //profile_save_data() saves profile file
 150                                                                                             //it's expecting a user with the correct id,
 151                                                                                             //and custom field to be named profile_field_"shortname"
 152                 }
 153                 profile_save_data((object) $user);
 154             }
 155
 156             //preferences
 157             if (!empty($user['preferences'])) {
 158                 foreach($user['preferences'] as $preference) {
 159                     set_user_preference($preference['type'], $preference['value'],$user['id']);
 160                 }
 161             }
 162
 163             $userids[] = array('id'=>$user['id'], 'username'=>$user['username']);
 164         }
 165
 166         $transaction->allow_commit();
 167
 168         return $userids;
 169     }
 170
 171    /**
 172      * Returns description of method result value
 173      * @return external_description
 174      */
 175     public static function create_users_returns() {
 176         return new external_multiple_structure(
 177             new external_single_structure(
 178                 array(
 179                     'id'       => new external_value(PARAM_INT, 'user id'),
 180                     'username' => new external_value(PARAM_RAW, 'user name'),
 181                 )
 182             )
 183         );
 184     }
 185
 186
 187     /**
 188      * Returns description of method parameters
 189      * @return external_function_parameters
 190      */
 191     public static function delete_users_parameters() {
 192         return new external_function_parameters(
 193             array(
 194                 'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
 195             )
 196         );
 197     }
 198
 199     public static function delete_users($userids) {
 200         global $CFG, $DB, $USER;
 201         require_once($CFG->dirroot."/user/lib.php");
 202
 203         // Ensure the current user is allowed to run this function
 204         $context = get_context_instance(CONTEXT_SYSTEM);
 205         require_capability('moodle/user:delete', $context);
 206         self::validate_context($context);
 207
 208         $params = self::validate_parameters(self::delete_users_parameters(), array('userids'=>$userids));
 209
 210         $transaction = $DB->start_delegated_transaction();
 211
 212         foreach ($params['userids'] as $userid) {
 213             $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0), '*', MUST_EXIST);
 214             // must not allow deleting of admins or self!!!
 215             if (is_siteadmin($user)) {
 216                 throw new moodle_exception('useradminodelete', 'error');
 217             }
 218             if ($USER->id == $user->id) {
 219                 throw new moodle_exception('usernotdeletederror', 'error');
 220             }
 221             user_delete_user($user);
 222         }
 223
 224         $transaction->allow_commit();
 225
 226         return null;
 227     }
 228
 229    /**
 230      * Returns description of method result value
 231      * @return external_description
 232      */
 233     public static function delete_users_returns() {
 234         return null;
 235     }
 236
 237
 238     /**
 239      * Returns description of method parameters
 240      * @return external_function_parameters
 241      */
 242     public static function update_users_parameters() {
 243         global $CFG;
 244        return new external_function_parameters(
 245             array(
 246                 'users' => new external_multiple_structure(
 247                     new external_single_structure(
 248                         array(
 249                             'id'    => new external_value(PARAM_NUMBER, 'ID of the user'),
 250                             'username'    => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
 251                             'password'    => new external_value(PARAM_RAW, 'Plain text password consisting of any characters', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
 252                             'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
 253                             'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
 254                             'email'       => new external_value(PARAM_EMAIL, 'A valid and unique email address', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED),
 255                             'auth'        => new external_value(PARAM_SAFEDIR, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL, '', NULL_NOT_ALLOWED),
 256                             'idnumber'    => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
 257                             'lang'        => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL, '', NULL_NOT_ALLOWED),
 258                             'theme'       => new external_value(PARAM_SAFEDIR, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
 259                             'timezone'    => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
 260                             'mailformat'  => new external_value(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
 261                             'description' => new external_value(PARAM_TEXT, 'User profile description, no HTML', VALUE_OPTIONAL),
 262                             'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
 263                             'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
 264                             'customfields' => new external_multiple_structure(
 265                                 new external_single_structure(
 266                                     array(
 267                                         'type'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the custom field'),
 268                                         'value' => new external_value(PARAM_RAW, 'The value of the custom field')
 269                                     )
 270                                 ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
 271                             'preferences' => new external_multiple_structure(
 272                                 new external_single_structure(
 273                                     array(
 274                                         'type'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the preference'),
 275                                         'value' => new external_value(PARAM_RAW, 'The value of the preference')
 276                                     )
 277                                 ), 'User preferences', VALUE_OPTIONAL),
 278                         )
 279                     )
 280                 )
 281             )
 282         );
 283     }
 284
 285     public static function update_users($users) {
 286         global $CFG, $DB;
 287         require_once($CFG->dirroot."/user/lib.php");
 288         require_once($CFG->dirroot."/user/profile/lib.php"); //required for customfields related function
 289                                                              //TODO: move the functions somewhere else as
 290                                                              //they are "user" related
 291
 292         // Ensure the current user is allowed to run this function
 293         $context = get_context_instance(CONTEXT_SYSTEM);
 294         require_capability('moodle/user:update', $context);
 295         self::validate_context($context);
 296
 297         $params = self::validate_parameters(self::update_users_parameters(), array('users'=>$users));
 298
 299         $transaction = $DB->start_delegated_transaction();
 300
 301         foreach ($params['users'] as $user) {
 302             user_update_user($user);
 303             //update user custom fields
 304             if(!empty($user['customfields'])) {
 305
 306                 foreach($user['customfields'] as $customfield) {
 307                     $user["profile_field_".$customfield['type']] = $customfield['value']; //profile_save_data() saves profile file
 308                                                                                             //it's expecting a user with the correct id,
 309                                                                                             //and custom field to be named profile_field_"shortname"
 310                 }
 311                 profile_save_data((object) $user);
 312             }
 313
 314             //preferences
 315             if (!empty($user['preferences'])) {
 316                 foreach($user['preferences'] as $preference) {
 317                     set_user_preference($preference['type'], $preference['value'],$user['id']);
 318                 }
 319             }
 320         }
 321
 322         $transaction->allow_commit();
 323
 324         return null;
 325     }
 326
 327    /**
 328      * Returns description of method result value
 329      * @return external_description
 330      */
 331     public static function update_users_returns() {
 332         return null;
 333     }
 334
 335     /**
 336      * Returns description of method parameters
 337      * @return external_function_parameters
 338      */
 339     public static function get_users_by_id_parameters() {
 340         return new external_function_parameters(
 341                 array(
 342                     'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user ID')),
 343                 )
 344         );
 345     }
 346
 347     /**
 348      * Get user information
 349      * - This function is matching the permissions of /user/profil.php
 350      * - It is also matching some permissions from /user/editadvanced.php for the following fields:
 351      *   auth, confirmed, idnumber, lang, theme, timezone, mailformat
 352      * @param array $userids  array of user ids
 353      * @return array An array of arrays describing users
 354      */
 355     public static function get_users_by_id($userids) {
 356         global $CFG, $USER, $DB;
 357         require_once($CFG->dirroot . "/user/lib.php");
 358
 359         $params = self::validate_parameters(self::get_users_by_id_parameters(),
 360                 array('userids'=>$userids));
 361
 362         list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
 363         list($sqluserids, $params) = $DB->get_in_or_equal($userids);
 364         $usersql = "SELECT u.* $uselect
 365                       FROM {user} u $ujoin
 366                      WHERE u.id $sqluserids";
 367         $users = $DB->get_recordset_sql($usersql, $params);
 368
 369         $result = array();
 370         $hasuserupdatecap = has_capability('moodle/user:update', get_system_context());
 371         foreach ($users as $user) {
 372             if (!empty($user->deleted)) {
 373                 continue;
 374             }
 375             context_instance_preload($user);
 376             $usercontext = get_context_instance(CONTEXT_USER, $user->id);
 377             self::validate_context($usercontext);
 378             $currentuser = ($user->id == $USER->id);
 379
 380             if ($userarray  = user_get_user_details($user)) {
 381                 //fields matching permissions from /user/editadvanced.php
 382                 if ($currentuser or $hasuserupdatecap) {
 383                     $userarray['auth']       = $user->auth;
 384                     $userarray['confirmed']  = $user->confirmed;
 385                     $userarray['idnumber']   = $user->idnumber;
 386                     $userarray['lang']       = $user->lang;
 387                     $userarray['theme']      = $user->theme;
 388                     $userarray['timezone']   = $user->timezone;
 389                     $userarray['mailformat'] = $user->mailformat;
 390                 }
 391                 $result[] = $userarray;
 392             }
 393         }
 394         $users->close();
 395
 396         return $result;
 397     }
 398
 399     /**
 400      * Returns description of method result value
 401      * @return external_description
 402      */
 403     public static function get_users_by_id_returns() {
 404         return new external_multiple_structure(
 405             new external_single_structure(
 406                 array(
 407                     'id'    => new external_value(PARAM_NUMBER, 'ID of the user'),
 408                     'username'    => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
 409                     'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
 410                     'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
 411                     'fullname'    => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
 412                     'email'       => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
 413                     'address'     => new external_value(PARAM_MULTILANG, 'Postal address', VALUE_OPTIONAL),
 414                     'phone1'      => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
 415                     'phone2'      => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
 416                     'icq'         => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
 417                     'skype'       => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
 418                     'yahoo'       => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
 419                     'aim'         => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
 420                     'msn'         => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
 421                     'department'  => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
 422                     'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
 423                     'interests'   => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
 424                     'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
 425                     'lastaccess'  => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
 426                     'auth'        => new external_value(PARAM_SAFEDIR, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL),
 427                     'confirmed'   => new external_value(PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', VALUE_OPTIONAL),
 428                     'idnumber'    => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
 429                     'lang'        => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL),
 430                     'theme'       => new external_value(PARAM_SAFEDIR, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
 431                     'timezone'    => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
 432                     'mailformat'  => new external_value(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
 433                     'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
 434                     'descriptionformat' => new external_value(PARAM_INT, 'User profile description format', VALUE_OPTIONAL),
 435                     'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
 436                     'url'         => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
 437                     'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
 438                     'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
 439                     'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
 440                     'customfields' => new external_multiple_structure(
 441                         new external_single_structure(
 442                             array(
 443                                 'type'  => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
 444                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 445                                 'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
 446                                 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
 447                             )
 448                     ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
 449                     'preferences' => new external_multiple_structure(
 450                         new external_single_structure(
 451                             array(
 452                                 'name'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
 453                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 454                             )
 455                     ), 'User preferences', VALUE_OPTIONAL),
 456                     'enrolledcourses' => new external_multiple_structure(
 457                         new external_single_structure(
 458                             array(
 459                                 'id'  => new external_value(PARAM_INT, 'Id of the course'),
 460                                 'fullname'  => new external_value(PARAM_RAW, 'Fullname of the course'),
 461                                 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
 462                             )
 463                     ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
 464                 )
 465             )
 466         );
 467     }
 468     /**
 469      * Returns description of method parameters
 470      * @return external_function_parameters
 471      */
 472     public static function get_course_participants_by_id_parameters() {
 473         return new external_function_parameters(
 474             array(
 475                 'userlist' => new external_multiple_structure(
 476                     new external_single_structure(
 477                         array(
 478                             'userid'    => new external_value(PARAM_INT, 'userid'),
 479                             'courseid'    => new external_value(PARAM_INT, 'courseid'),
 480                         )
 481                     )
 482                 )
 483             )
 484         );
 485     }
 486
 487     /**
 488      * Get course participant's details
 489      * @param array $userlist  array of user ids and according course ids
 490      * @return array An array of arrays describing course participants
 491      */
 492     public static function get_course_participants_by_id($userlist) {
 493         global $CFG, $USER, $DB;
 494         require_once($CFG->dirroot . "/user/lib.php");
 495         $params = self::validate_parameters(self::get_course_participants_by_id_parameters(), array('userlist'=>$userlist));
 496
 497         $userids = array();
 498         $courseids = array();
 499         foreach ($params['userlist'] as $value) {
 500             $userids[] = $value['userid'];
 501             $courseids[$value['userid']] = $value['courseid'];
 502         }
 503
 504         // cache all courses
 505         $courses = array();
 506         list($cselect, $cjoin) = context_instance_preload_sql('c.id', CONTEXT_COURSE, 'ctx');
 507         list($sqlcourseids, $params) = $DB->get_in_or_equal(array_unique($courseids));
 508         $coursesql = "SELECT c.* $uselect
 509                         FROM {course} c $cjoin
 510                        WHERE c.id $sqlcourseids";
 511         $rs = $DB->get_recordset_sql($coursesql, $params);
 512         foreach ($rs as $course) {
 513             // adding course contexts to cache
 514             context_instance_preload($course);
 515             // cache courses
 516             $courses[$course->id] = $course;
 517         }
 518         $rs->close();
 519
 520         list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
 521         list($sqluserids, $params) = $DB->get_in_or_equal($userids);
 522         $usersql = "SELECT u.* $uselect
 523                       FROM {user} u $ujoin
 524                      WHERE u.id $sqluserids";
 525         $users = $DB->get_recordset_sql($usersql, $params);
 526         $result = array();
 527         foreach ($users as $user) {
 528             if (!empty($user->deleted)) {
 529                 continue;
 530             }
 531             context_instance_preload($user);
 532             $course = $courses[$courseids[$user->id]];
 533             $context = get_context_instance(CONTEXT_COURSE, $courseids[$user->id]);
 534             self::validate_context($context);
 535             if ($userarray = user_get_user_details($user, $course)) {
 536                 $result[] = $userarray;
 537             }
 538         }
 539
 540         $users->close();
 541
 542         return $result;
 543     }
 544
 545     /**
 546      * Returns description of method result value
 547      * @return external_description
 548      */
 549     public static function get_course_participants_by_id_returns() {
 550         return new external_multiple_structure(
 551             new external_single_structure(
 552                 array(
 553                     'id'    => new external_value(PARAM_NUMBER, 'ID of the user'),
 554                     'username'    => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
 555                     'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
 556                     'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
 557                     'fullname'    => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
 558                     'email'       => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
 559                     'address'     => new external_value(PARAM_MULTILANG, 'Postal address', VALUE_OPTIONAL),
 560                     'phone1'      => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
 561                     'phone2'      => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
 562                     'icq'         => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
 563                     'skype'       => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
 564                     'yahoo'       => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
 565                     'aim'         => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
 566                     'msn'         => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
 567                     'department'  => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
 568                     'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
 569                     'interests'   => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
 570                     'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
 571                     'lastaccess'  => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
 572                     'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
 573                     'descriptionformat' => new external_value(PARAM_INT, 'User profile description format', VALUE_OPTIONAL),
 574                     'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
 575                     'url'         => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
 576                     'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
 577                     'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
 578                     'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
 579                     'customfields' => new external_multiple_structure(
 580                         new external_single_structure(
 581                             array(
 582                                 'type'  => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
 583                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 584                                 'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
 585                                 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
 586                             )
 587                         ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
 588                     'groups' => new external_multiple_structure(
 589                         new external_single_structure(
 590                             array(
 591                                 'id'  => new external_value(PARAM_INT, 'group id'),
 592                                 'name' => new external_value(PARAM_RAW, 'group name'),
 593                                 'description' => new external_value(PARAM_RAW, 'group description'),
 594                             )
 595                         ), 'user groups', VALUE_OPTIONAL),
 596                     'roles' => new external_multiple_structure(
 597                         new external_single_structure(
 598                             array(
 599                                 'roleid'       => new external_value(PARAM_INT, 'role id'),
 600                                 'name'         => new external_value(PARAM_RAW, 'role name'),
 601                                 'shortname'    => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
 602                                 'sortorder'    => new external_value(PARAM_INT, 'role sortorder')
 603                             )
 604                         ), 'user roles', VALUE_OPTIONAL),
 605                     'preferences' => new external_multiple_structure(
 606                         new external_single_structure(
 607                             array(
 608                                 'name'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
 609                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 610                             )
 611                     ), 'User preferences', VALUE_OPTIONAL),
 612                     'enrolledcourses' => new external_multiple_structure(
 613                         new external_single_structure(
 614                             array(
 615                                 'id'  => new external_value(PARAM_INT, 'Id of the course'),
 616                                 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
 617                                 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
 618                             )
 619                     ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
 620                 )
 621             )
 622         );
 623     }
 624
 625     /**
 626      * Returns description of method parameters
 627      * @return external_function_parameters
 628      */
 629     public static function get_users_by_courseid_parameters() {
 630         return new external_function_parameters(
 631             array(
 632                 'courseid' => new external_value(PARAM_INT, 'course id'),
 633                 'options'  => new external_multiple_structure(
 634                     new external_single_structure(
 635                         array(
 636                             'name'  => new external_value(PARAM_ALPHANUMEXT, 'option name'),
 637                             'value' => new external_value(PARAM_RAW, 'option value')
 638                         )
 639                     ), 'method options'),
 640             )
 641         );
 642     }
 643
 644     /**
 645      * Get course participants details
 646      * @param int $courseid  course id
 647      * @param array $options options {
 648      *          'name' => option name
 649      *          'value' => option value
 650      * }
 651      * @return array An array of users
 652      */
 653     public static function get_users_by_courseid($courseid, $options) {
 654         global $CFG, $USER, $DB;
 655         require_once($CFG->dirroot . "/user/lib.php");
 656
 657         $params = self::validate_parameters(
 658             self::get_users_by_courseid_parameters(),
 659             array(
 660                 'courseid'=>$courseid,
 661                 'options'=>$options
 662             )
 663         );
 664         $withcapability = '';
 665         $groupid        = 0;
 666         $onlyactive     = false;
 667         foreach ($options as $option) {
 668             switch ($option['name']) {
 669             case 'withcapability':
 670                 $withcapability = $option['value'];
 671                 break;
 672             case 'groupid':
 673                 $groupid = (int)$option['value'];
 674                 break;
 675             case 'onlyactive':
 676                 $onlyactive = !empty($option['value']);
 677                 break;
 678             }
 679         }
 680
 681         // to overwrite this parameter, you need role:review capability
 682         if ($withcapability) {
 683             require_capability('moodle/role:review', $coursecontext);
 684         }
 685         // need accessallgroups capability if you want to overwrite this option
 686         if (!empty($groupid) && groups_is_member($groupid)) {
 687             require_capability('moodle/site:accessallgroups', $context);
 688         }
 689         // to overwrite this option, you need course:enrolereview permission
 690         if ($onlyactive) {
 691             require_capability('moodle/course:enrolreview', $coursecontext);
 692         }
 693
 694         list($coursectxselect, $coursectxjoin) = context_instance_preload_sql('c.id', CONTEXT_COURSE, 'ctx');
 695         $coursesql = "SELECT c.* $coursectxselect
 696                         FROM {course} c $coursectxjoin
 697                        WHERE c.id = $courseid";
 698         $course = $DB->get_record_sql($coursesql);
 699         context_instance_preload($course);
 700         $coursecontext = get_context_instance(CONTEXT_COURSE, $params['courseid']);
 701         if ($courseid == SITEID) {
 702             $context = get_system_context();
 703         } else {
 704             $context = $coursecontext;
 705         }
 706         try {
 707             self::validate_context($context);
 708         } catch (Exception $e) {
 709             $exceptionparam = new stdClass();
 710             $exceptionparam->message = $e->getMessage();
 711             $exceptionparam->courseid = $params['courseid'];
 712             throw new moodle_exception(get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
 713         }
 714
 715         list($enrolledsql, $enrolledparams) = get_enrolled_sql($coursecontext, $withcapability, $groupid, $onlyactive);
 716         list($ctxselect, $ctxjoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx');
 717         $records = $DB->get_records_sql($enrolledsql, $enrolledparams);
 718         $sqlparams['courseid'] = $courseid;
 719         $sql = "SELECT u.* $ctxselect
 720                   FROM {user} u $ctxjoin
 721                  WHERE u.id IN ($enrolledsql)
 722                  ORDER BY u.id ASC";
 723         $enrolledusers = $DB->get_recordset_sql($sql, $enrolledparams);
 724         $users = array();
 725         foreach ($enrolledusers as $user) {
 726             if (!empty($user->deleted)) {
 727                 continue;
 728             }
 729             context_instance_preload($user);
 730             if ($userdetails = user_get_user_details($user, $course)) {
 731                 $users[] = $userdetails;
 732             }
 733         }
 734         $enrolledusers->close();
 735
 736         return $users;
 737     }
 738     /**
 739      * Returns description of method result value
 740      * @return external_description
 741      */
 742     public static function get_users_by_courseid_returns() {
 743         return new external_multiple_structure(
 744             new external_single_structure(
 745                 array(
 746                     'id'    => new external_value(PARAM_NUMBER, 'ID of the user'),
 747                     'username'    => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
 748                     'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
 749                     'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
 750                     'fullname'    => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
 751                     'email'       => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
 752                     'address'     => new external_value(PARAM_MULTILANG, 'Postal address', VALUE_OPTIONAL),
 753                     'phone1'      => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
 754                     'phone2'      => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
 755                     'icq'         => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
 756                     'skype'       => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
 757                     'yahoo'       => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
 758                     'aim'         => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
 759                     'msn'         => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
 760                     'department'  => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
 761                     'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
 762                     'interests'   => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
 763                     'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
 764                     'lastaccess'  => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
 765                     'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
 766                     'descriptionformat' => new external_value(PARAM_INT, 'User profile description format', VALUE_OPTIONAL),
 767                     'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
 768                     'url'         => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
 769                     'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
 770                     'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
 771                     'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
 772                     'customfields' => new external_multiple_structure(
 773                         new external_single_structure(
 774                             array(
 775                                 'type'  => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
 776                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 777                                 'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
 778                                 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
 779                             )
 780                         ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
 781                     'groups' => new external_multiple_structure(
 782                         new external_single_structure(
 783                             array(
 784                                 'id'  => new external_value(PARAM_INT, 'group id'),
 785                                 'name' => new external_value(PARAM_RAW, 'group name'),
 786                                 'description' => new external_value(PARAM_RAW, 'group description'),
 787                             )
 788                         ), 'user groups', VALUE_OPTIONAL),
 789                     'roles' => new external_multiple_structure(
 790                         new external_single_structure(
 791                             array(
 792                                 'roleid'       => new external_value(PARAM_INT, 'role id'),
 793                                 'name'         => new external_value(PARAM_RAW, 'role name'),
 794                                 'shortname'    => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
 795                                 'sortorder'    => new external_value(PARAM_INT, 'role sortorder')
 796                             )
 797                         ), 'user roles', VALUE_OPTIONAL),
 798                     'preferences' => new external_multiple_structure(
 799                         new external_single_structure(
 800                             array(
 801                                 'name'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
 802                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 803                             )
 804                     ), 'User preferences', VALUE_OPTIONAL),
 805                     'enrolledcourses' => new external_multiple_structure(
 806                         new external_single_structure(
 807                             array(
 808                                 'id'  => new external_value(PARAM_INT, 'Id of the course'),
 809                                 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
 810                                 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
 811                             )
 812                     ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
 813                 )
 814             )
 815         );
 816     }
 817 }