enrol/externallib.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17
  18 /**
  19  * External course participation api.
  20  *
  21  * This api is mostly read only, the actual enrol and unenrol
  22  * support is in each enrol plugin.
  23  *
  24  * @package    core_enrol
  25  * @category   external
  26  * @copyright  2010 Jerome Mouneyrac
  27  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  28  */
  29
  30 defined('MOODLE_INTERNAL') || die();
  31
  32 require_once("$CFG->libdir/externallib.php");
  33
  34 /**
  35  * Enrol external functions
  36  *
  37  * @package    core_enrol
  38  * @category   external
  39  * @copyright  2011 Jerome Mouneyrac
  40  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  41  * @since Moodle 2.2
  42  */
  43 class core_enrol_external extends external_api {
  44
  45     /**
  46      * Returns description of method parameters
  47      *
  48      * @return external_function_parameters
  49      * @since Moodle 2.4
  50      */
  51     public static function get_enrolled_users_with_capability_parameters() {
  52         return new external_function_parameters(
  53             array (
  54                 'coursecapabilities' => new external_multiple_structure(
  55                     new external_single_structure(
  56                         array (
  57                             'courseid' => new external_value(PARAM_INT, 'Course ID number in the Moodle course table'),
  58                             'capabilities' => new external_multiple_structure(
  59                                 new external_value(PARAM_CAPABILITY, 'Capability name, such as mod/forum:viewdiscussion')),
  60                         )
  61                     )
  62                 , 'course id and associated capability name'),
  63                  'options'  => new external_multiple_structure(
  64                     new external_single_structure(
  65                         array(
  66                             'name'  => new external_value(PARAM_ALPHANUMEXT, 'option name'),
  67                             'value' => new external_value(PARAM_RAW, 'option value')
  68                         )
  69                     ), 'Option names:
  70                             * groupid (integer) return only users in this group id. Requires \'moodle/site:accessallgroups\' .
  71                             * onlyactive (integer) only users with active enrolments. Requires \'moodle/course:enrolreview\' .
  72                             * userfields (\'string, string, ...\') return only the values of these user fields.
  73                             * limitfrom (integer) sql limit from.
  74                             * limitnumber (integer) max number of users per course and capability.', VALUE_DEFAULT, array())
  75             )
  76         );
  77     }
  78
  79     /**
  80      * Return users that have the capabilities for each course specified. For each course and capability specified,
  81      * a list of the users that are enrolled in the course and have that capability are returned.
  82      *
  83      * @param array $coursecapabilities array of course ids and associated capability names {courseid, {capabilities}}
  84      * @return array An array of arrays describing users for each associated courseid and capability
  85      * @since  Moodle 2.4
  86      */
  87     public static function get_enrolled_users_with_capability($coursecapabilities, $options) {
  88         global $CFG, $DB;
  89         require_once($CFG->dirroot . "/user/lib.php");
  90
  91         if (empty($coursecapabilities)) {
  92             throw new invalid_parameter_exception('Parameter can not be empty');
  93         }
  94         $params = self::validate_parameters(self::get_enrolled_users_with_capability_parameters(),
  95             array ('coursecapabilities' => $coursecapabilities,  'options'=>$options));
  96         $result = array();
  97         $userlist = array();
  98         $groupid        = 0;
  99         $onlyactive     = false;
 100         $userfields     = array();
 101         $limitfrom = 0;
 102         $limitnumber = 0;
 103         foreach ($params['options'] as $option) {
 104             switch ($option['name']) {
 105                 case 'groupid':
 106                     $groupid = (int)$option['value'];
 107                     break;
 108                 case 'onlyactive':
 109                     $onlyactive = !empty($option['value']);
 110                     break;
 111                 case 'userfields':
 112                     $thefields = explode(',', $option['value']);
 113                     foreach ($thefields as $f) {
 114                         $userfields[] = clean_param($f, PARAM_ALPHANUMEXT);
 115                     }
 116                     break;
 117                 case 'limitfrom' :
 118                     $limitfrom = clean_param($option['value'], PARAM_INT);
 119                     break;
 120                 case 'limitnumber' :
 121                     $limitnumber = clean_param($option['value'], PARAM_INT);
 122                     break;
 123             }
 124         }
 125
 126         foreach ($params['coursecapabilities'] as $coursecapability) {
 127             $courseid = $coursecapability['courseid'];
 128             $course = $DB->get_record('course', array('id'=>$courseid), '*', MUST_EXIST);
 129             $coursecontext = context_course::instance($courseid);
 130             if (!$coursecontext) {
 131                 throw new moodle_exception('cannotfindcourse', 'error', '', null,
 132                         'The course id ' . $courseid . ' doesn\'t exist.');
 133             }
 134             if ($courseid == SITEID) {
 135                 $context = context_system::instance();
 136             } else {
 137                 $context = $coursecontext;
 138             }
 139             try {
 140                 self::validate_context($context);
 141             } catch (Exception $e) {
 142                 $exceptionparam = new stdClass();
 143                 $exceptionparam->message = $e->getMessage();
 144                 $exceptionparam->courseid = $params['courseid'];
 145                 throw new moodle_exception(get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
 146             }
 147
 148             if ($courseid == SITEID) {
 149                 require_capability('moodle/site:viewparticipants', $context);
 150             } else {
 151                 require_capability('moodle/course:viewparticipants', $context);
 152             }
 153             // The accessallgroups capability is needed to use this option.
 154             if (!empty($groupid) && groups_is_member($groupid)) {
 155                 require_capability('moodle/site:accessallgroups', $coursecontext);
 156             }
 157             // The course:enrolereview capability is needed to use this option.
 158             if ($onlyactive) {
 159                 require_capability('moodle/course:enrolreview', $coursecontext);
 160             }
 161
 162             // To see the permissions of others role:review capability is required.
 163             require_capability('moodle/role:review', $coursecontext);
 164             foreach ($coursecapability['capabilities'] as $capability) {
 165                 $courseusers['courseid'] = $courseid;
 166                 $courseusers['capability'] = $capability;
 167
 168                 list($enrolledsql, $enrolledparams) = get_enrolled_sql($coursecontext, $capability, $groupid, $onlyactive);
 169
 170                 $sql = "SELECT u.* FROM {user} u WHERE u.id IN ($enrolledsql) ORDER BY u.id ASC";
 171
 172                 $enrolledusers = $DB->get_recordset_sql($sql, $enrolledparams, $limitfrom, $limitnumber);
 173                 $users = array();
 174                 foreach ($enrolledusers as $courseuser) {
 175                     if ($userdetails = user_get_user_details($courseuser, $course, $userfields)) {
 176                         $users[] = $userdetails;
 177                     }
 178                 }
 179                 $enrolledusers->close();
 180                 $courseusers['users'] = $users;
 181                 $result[] = $courseusers;
 182             }
 183         }
 184         return $result;
 185     }
 186
 187     /**
 188      * Returns description of method result value
 189      *
 190      * @return external_multiple_structure
 191      * @since Moodle 2.4
 192      */
 193     public static function get_enrolled_users_with_capability_returns() {
 194         return  new external_multiple_structure( new external_single_structure (
 195                 array (
 196                     'courseid' => new external_value(PARAM_INT, 'Course ID number in the Moodle course table'),
 197                     'capability' => new external_value(PARAM_CAPABILITY, 'Capability name'),
 198                     'users' => new external_multiple_structure(
 199                         new external_single_structure(
 200                 array(
 201                     'id'    => new external_value(PARAM_INT, 'ID of the user'),
 202                     'username'    => new external_value(PARAM_RAW, 'Username', VALUE_OPTIONAL),
 203                     'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
 204                     'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
 205                     'fullname'    => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
 206                     'email'       => new external_value(PARAM_TEXT, 'Email address', VALUE_OPTIONAL),
 207                     'address'     => new external_value(PARAM_MULTILANG, 'Postal address', VALUE_OPTIONAL),
 208                     'phone1'      => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
 209                     'phone2'      => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
 210                     'icq'         => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
 211                     'skype'       => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
 212                     'yahoo'       => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
 213                     'aim'         => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
 214                     'msn'         => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
 215                     'department'  => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
 216                     'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
 217                     'interests'   => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
 218                     'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
 219                     'lastaccess'  => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
 220                     'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
 221                     'descriptionformat' => new external_value(PARAM_INT, 'User profile description format', VALUE_OPTIONAL),
 222                     'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
 223                     'url'         => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
 224                     'country'     => new external_value(PARAM_ALPHA, 'Country code of the user, such as AU or CZ', VALUE_OPTIONAL),
 225                     'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small', VALUE_OPTIONAL),
 226                     'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big', VALUE_OPTIONAL),
 227                     'customfields' => new external_multiple_structure(
 228                         new external_single_structure(
 229                             array(
 230                                 'type'  => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field'),
 231                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 232                                 'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
 233                                 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field'),
 234                             )
 235                         ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
 236                     'groups' => new external_multiple_structure(
 237                         new external_single_structure(
 238                             array(
 239                                 'id'  => new external_value(PARAM_INT, 'group id'),
 240                                 'name' => new external_value(PARAM_RAW, 'group name'),
 241                                 'description' => new external_value(PARAM_RAW, 'group description'),
 242                             )
 243                         ), 'user groups', VALUE_OPTIONAL),
 244                     'roles' => new external_multiple_structure(
 245                         new external_single_structure(
 246                             array(
 247                                 'roleid'       => new external_value(PARAM_INT, 'role id'),
 248                                 'name'         => new external_value(PARAM_RAW, 'role name'),
 249                                 'shortname'    => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
 250                                 'sortorder'    => new external_value(PARAM_INT, 'role sortorder')
 251                             )
 252                         ), 'user roles', VALUE_OPTIONAL),
 253                     'preferences' => new external_multiple_structure(
 254                         new external_single_structure(
 255                             array(
 256                                 'name'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
 257                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 258                             )
 259                     ), 'User preferences', VALUE_OPTIONAL),
 260                     'enrolledcourses' => new external_multiple_structure(
 261                         new external_single_structure(
 262                             array(
 263                                 'id'  => new external_value(PARAM_INT, 'Id of the course'),
 264                                 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
 265                                 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
 266                             )
 267                     ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
 268                 )
 269                         ), 'List of users that are enrolled in the course and have the specified capability'),
 270                     )
 271                 )
 272             );
 273     }
 274
 275     /**
 276      * Returns description of method parameters
 277      *
 278      * @return external_function_parameters
 279      */
 280     public static function get_users_courses_parameters() {
 281         return new external_function_parameters(
 282             array(
 283                 'userid' => new external_value(PARAM_INT, 'user id'),
 284             )
 285         );
 286     }
 287
 288     /**
 289      * Get list of courses user is enrolled in (only active enrolments are returned).
 290      * Please note the current user must be able to access the course, otherwise the course is not included.
 291      *
 292      * @param int $userid
 293      * @return array of courses
 294      */
 295     public static function get_users_courses($userid) {
 296         global $USER, $DB;
 297
 298         // Do basic automatic PARAM checks on incoming data, using params description
 299         // If any problems are found then exceptions are thrown with helpful error messages
 300         $params = self::validate_parameters(self::get_users_courses_parameters(), array('userid'=>$userid));
 301
 302         $courses = enrol_get_users_courses($params['userid'], true, 'id, shortname, fullname, idnumber, visible,
 303                    summary, summaryformat, format, showgrades, lang, enablecompletion');
 304         $result = array();
 305
 306         foreach ($courses as $course) {
 307             $context = context_course::instance($course->id, IGNORE_MISSING);
 308             try {
 309                 self::validate_context($context);
 310             } catch (Exception $e) {
 311                 // current user can not access this course, sorry we can not disclose who is enrolled in this course!
 312                 continue;
 313             }
 314
 315             if ($userid != $USER->id and !has_capability('moodle/course:viewparticipants', $context)) {
 316                 // we need capability to view participants
 317                 continue;
 318             }
 319
 320             list($enrolledsqlselect, $enrolledparams) = get_enrolled_sql($context);
 321             $enrolledsql = "SELECT COUNT('x') FROM ($enrolledsqlselect) enrolleduserids";
 322             $enrolledusercount = $DB->count_records_sql($enrolledsql, $enrolledparams);
 323
 324             list($course->summary, $course->summaryformat) =
 325                 external_format_text($course->summary, $course->summaryformat, $context->id, 'course', 'summary', null);
 326
 327             $result[] = array('id' => $course->id, 'shortname' => $course->shortname, 'fullname' => $course->fullname,
 328                 'idnumber' => $course->idnumber, 'visible' => $course->visible, 'enrolledusercount' => $enrolledusercount,
 329                 'summary' => $course->summary, 'summaryformat' => $course->summaryformat, 'format' => $course->format,
 330                 'showgrades' => $course->showgrades, 'lang' => $course->lang, 'enablecompletion' => $course->enablecompletion
 331                 );
 332         }
 333
 334         return $result;
 335     }
 336
 337     /**
 338      * Returns description of method result value
 339      *
 340      * @return external_description
 341      */
 342     public static function get_users_courses_returns() {
 343         return new external_multiple_structure(
 344             new external_single_structure(
 345                 array(
 346                     'id'        => new external_value(PARAM_INT, 'id of course'),
 347                     'shortname' => new external_value(PARAM_RAW, 'short name of course'),
 348                     'fullname'  => new external_value(PARAM_RAW, 'long name of course'),
 349                     'enrolledusercount' => new external_value(PARAM_INT, 'Number of enrolled users in this course'),
 350                     'idnumber'  => new external_value(PARAM_RAW, 'id number of course'),
 351                     'visible'   => new external_value(PARAM_INT, '1 means visible, 0 means hidden course'),
 352                     'summary'   => new external_value(PARAM_RAW, 'summary', VALUE_OPTIONAL),
 353                     'summaryformat' => new external_format_value('summary', VALUE_OPTIONAL),
 354                     'format'    => new external_value(PARAM_PLUGIN, 'course format: weeks, topics, social, site', VALUE_OPTIONAL),
 355                     'showgrades' => new external_value(PARAM_BOOL, 'true if grades are shown, otherwise false', VALUE_OPTIONAL),
 356                     'lang'      => new external_value(PARAM_LANG, 'forced course language', VALUE_OPTIONAL),
 357                     'enablecompletion' => new external_value(PARAM_BOOL, 'true if completion is enabled, otherwise false',
 358                                                                 VALUE_OPTIONAL)
 359                 )
 360             )
 361         );
 362     }
 363
 364     /**
 365      * Returns description of method parameters
 366      *
 367      * @return external_function_parameters
 368      */
 369     public static function get_enrolled_users_parameters() {
 370         return new external_function_parameters(
 371             array(
 372                 'courseid' => new external_value(PARAM_INT, 'course id'),
 373                 'options'  => new external_multiple_structure(
 374                     new external_single_structure(
 375                         array(
 376                             'name'  => new external_value(PARAM_ALPHANUMEXT, 'option name'),
 377                             'value' => new external_value(PARAM_RAW, 'option value')
 378                         )
 379                     ), 'Option names:
 380                             * withcapability (string) return only users with this capability. This option requires \'moodle/role:review\' on the course context.
 381                             * groupid (integer) return only users in this group id. If the course has groups enabled and this param
 382                                                 isn\'t defined, returns all the viewable users.
 383                                                 This option requires \'moodle/site:accessallgroups\' on the course context if the
 384                                                 user doesn\'t belong to the group.
 385                             * onlyactive (integer) return only users with active enrolments and matching time restrictions. This option requires \'moodle/course:enrolreview\' on the course context.
 386                             * userfields (\'string, string, ...\') return only the values of these user fields.
 387                             * limitfrom (integer) sql limit from.
 388                             * limitnumber (integer) maximum number of returned users.', VALUE_DEFAULT, array()),
 389             )
 390         );
 391     }
 392
 393     /**
 394      * Get course participants details
 395      *
 396      * @param int $courseid  course id
 397      * @param array $options options {
 398      *                                'name' => option name
 399      *                                'value' => option value
 400      *                               }
 401      * @return array An array of users
 402      */
 403     public static function get_enrolled_users($courseid, $options = array()) {
 404         global $CFG, $USER, $DB;
 405         require_once($CFG->dirroot . "/user/lib.php");
 406
 407         $params = self::validate_parameters(
 408             self::get_enrolled_users_parameters(),
 409             array(
 410                 'courseid'=>$courseid,
 411                 'options'=>$options
 412             )
 413         );
 414         $withcapability = '';
 415         $groupid        = 0;
 416         $onlyactive     = false;
 417         $userfields     = array();
 418         $limitfrom = 0;
 419         $limitnumber = 0;
 420         foreach ($options as $option) {
 421             switch ($option['name']) {
 422             case 'withcapability':
 423                 $withcapability = $option['value'];
 424                 break;
 425             case 'groupid':
 426                 $groupid = (int)$option['value'];
 427                 break;
 428             case 'onlyactive':
 429                 $onlyactive = !empty($option['value']);
 430                 break;
 431             case 'userfields':
 432                 $thefields = explode(',', $option['value']);
 433                 foreach ($thefields as $f) {
 434                     $userfields[] = clean_param($f, PARAM_ALPHANUMEXT);
 435                 }
 436                 break;
 437             case 'limitfrom' :
 438                 $limitfrom = clean_param($option['value'], PARAM_INT);
 439                 break;
 440             case 'limitnumber' :
 441                 $limitnumber = clean_param($option['value'], PARAM_INT);
 442                 break;
 443             }
 444         }
 445
 446         $course = $DB->get_record('course', array('id'=>$courseid), '*', MUST_EXIST);
 447         $coursecontext = context_course::instance($courseid, IGNORE_MISSING);
 448         if ($courseid == SITEID) {
 449             $context = context_system::instance();
 450         } else {
 451             $context = $coursecontext;
 452         }
 453         try {
 454             self::validate_context($context);
 455         } catch (Exception $e) {
 456             $exceptionparam = new stdClass();
 457             $exceptionparam->message = $e->getMessage();
 458             $exceptionparam->courseid = $params['courseid'];
 459             throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
 460         }
 461
 462         if ($courseid == SITEID) {
 463             require_capability('moodle/site:viewparticipants', $context);
 464         } else {
 465             require_capability('moodle/course:viewparticipants', $context);
 466         }
 467         // to overwrite this parameter, you need role:review capability
 468         if ($withcapability) {
 469             require_capability('moodle/role:review', $coursecontext);
 470         }
 471         // need accessallgroups capability if you want to overwrite this option
 472         if (!empty($groupid) && !groups_is_member($groupid)) {
 473             require_capability('moodle/site:accessallgroups', $coursecontext);
 474         }
 475         // to overwrite this option, you need course:enrolereview permission
 476         if ($onlyactive) {
 477             require_capability('moodle/course:enrolreview', $coursecontext);
 478         }
 479
 480         list($enrolledsql, $enrolledparams) = get_enrolled_sql($coursecontext, $withcapability, $groupid, $onlyactive);
 481         $ctxselect = ', ' . context_helper::get_preload_record_columns_sql('ctx');
 482         $ctxjoin = "LEFT JOIN {context} ctx ON (ctx.instanceid = u.id AND ctx.contextlevel = :contextlevel)";
 483         $enrolledparams['contextlevel'] = CONTEXT_USER;
 484
 485         $groupjoin = '';
 486         if (empty($groupid) && groups_get_course_groupmode($course) == SEPARATEGROUPS &&
 487                 !has_capability('moodle/site:accessallgroups', $coursecontext)) {
 488             // Filter by groups the user can view.
 489             $usergroups = groups_get_user_groups($course->id);
 490             if (!empty($usergroups['0'])) {
 491                 list($groupsql, $groupparams) = $DB->get_in_or_equal($usergroups['0'], SQL_PARAMS_NAMED);
 492                 $groupjoin = "JOIN {groups_members} gm ON (u.id = gm.userid AND gm.groupid $groupsql)";
 493                 $enrolledparams = array_merge($enrolledparams, $groupparams);
 494             } else {
 495                 // User doesn't belong to any group, so he can't see any user. Return an empty array.
 496                 return array();
 497             }
 498         }
 499         $sql = "SELECT us.*
 500                   FROM {user} us
 501                   JOIN (
 502                       SELECT DISTINCT u.id $ctxselect
 503                         FROM {user} u $ctxjoin $groupjoin
 504                        WHERE u.id IN ($enrolledsql)
 505                   ) q ON q.id = us.id
 506                 ORDER BY us.id ASC";
 507         $enrolledusers = $DB->get_recordset_sql($sql, $enrolledparams, $limitfrom, $limitnumber);
 508         $users = array();
 509         foreach ($enrolledusers as $user) {
 510             context_helper::preload_from_record($user);
 511             if ($userdetails = user_get_user_details($user, $course, $userfields)) {
 512                 $users[] = $userdetails;
 513             }
 514         }
 515         $enrolledusers->close();
 516
 517         return $users;
 518     }
 519
 520     /**
 521      * Returns description of method result value
 522      *
 523      * @return external_description
 524      */
 525     public static function get_enrolled_users_returns() {
 526         return new external_multiple_structure(
 527             new external_single_structure(
 528                 array(
 529                     'id'    => new external_value(PARAM_INT, 'ID of the user'),
 530                     'username'    => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
 531                     'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
 532                     'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
 533                     'fullname'    => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
 534                     'email'       => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
 535                     'address'     => new external_value(PARAM_TEXT, 'Postal address', VALUE_OPTIONAL),
 536                     'phone1'      => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
 537                     'phone2'      => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
 538                     'icq'         => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
 539                     'skype'       => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
 540                     'yahoo'       => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
 541                     'aim'         => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
 542                     'msn'         => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
 543                     'department'  => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
 544                     'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
 545                     'idnumber'    => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
 546                     'interests'   => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
 547                     'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
 548                     'lastaccess'  => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
 549                     'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
 550                     'descriptionformat' => new external_format_value('description', VALUE_OPTIONAL),
 551                     'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
 552                     'url'         => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
 553                     'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
 554                     'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version', VALUE_OPTIONAL),
 555                     'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version', VALUE_OPTIONAL),
 556                     'customfields' => new external_multiple_structure(
 557                         new external_single_structure(
 558                             array(
 559                                 'type'  => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
 560                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 561                                 'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
 562                                 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
 563                             )
 564                         ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
 565                     'groups' => new external_multiple_structure(
 566                         new external_single_structure(
 567                             array(
 568                                 'id'  => new external_value(PARAM_INT, 'group id'),
 569                                 'name' => new external_value(PARAM_RAW, 'group name'),
 570                                 'description' => new external_value(PARAM_RAW, 'group description'),
 571                                 'descriptionformat' => new external_format_value('description'),
 572                             )
 573                         ), 'user groups', VALUE_OPTIONAL),
 574                     'roles' => new external_multiple_structure(
 575                         new external_single_structure(
 576                             array(
 577                                 'roleid'       => new external_value(PARAM_INT, 'role id'),
 578                                 'name'         => new external_value(PARAM_RAW, 'role name'),
 579                                 'shortname'    => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
 580                                 'sortorder'    => new external_value(PARAM_INT, 'role sortorder')
 581                             )
 582                         ), 'user roles', VALUE_OPTIONAL),
 583                     'preferences' => new external_multiple_structure(
 584                         new external_single_structure(
 585                             array(
 586                                 'name'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
 587                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 588                             )
 589                     ), 'User preferences', VALUE_OPTIONAL),
 590                     'enrolledcourses' => new external_multiple_structure(
 591                         new external_single_structure(
 592                             array(
 593                                 'id'  => new external_value(PARAM_INT, 'Id of the course'),
 594                                 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
 595                                 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
 596                             )
 597                     ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
 598                 )
 599             )
 600         );
 601     }
 602
 603     /**
 604      * Returns description of get_course_enrolment_methods() parameters
 605      *
 606      * @return external_function_parameters
 607      */
 608     public static function get_course_enrolment_methods_parameters() {
 609         return new external_function_parameters(
 610             array(
 611                 'courseid' => new external_value(PARAM_INT, 'Course id')
 612             )
 613         );
 614     }
 615
 616     /**
 617      * Get list of active course enrolment methods for current user.
 618      *
 619      * @param int $courseid
 620      * @return array of course enrolment methods
 621      */
 622     public static function get_course_enrolment_methods($courseid) {
 623
 624         $params = self::validate_parameters(self::get_course_enrolment_methods_parameters(), array('courseid' => $courseid));
 625
 626         $coursecontext = context_course::instance($params['courseid']);
 627         $categorycontext = $coursecontext->get_parent_context();
 628         self::validate_context($categorycontext);
 629
 630         $result = array();
 631         $enrolinstances = enrol_get_instances($params['courseid'], true);
 632         foreach ($enrolinstances as $enrolinstance) {
 633             if ($enrolplugin = enrol_get_plugin($enrolinstance->enrol)) {
 634                 if ($instanceinfo = $enrolplugin->get_enrol_info($enrolinstance)) {
 635                     $result[] = (array) $instanceinfo;
 636                 }
 637             }
 638         }
 639         return $result;
 640     }
 641
 642     /**
 643      * Returns description of get_course_enrolment_methods() result value
 644      *
 645      * @return external_description
 646      */
 647     public static function get_course_enrolment_methods_returns() {
 648         return new external_multiple_structure(
 649             new external_single_structure(
 650                 array(
 651                     'id' => new external_value(PARAM_INT, 'id of course enrolment instance'),
 652                     'courseid' => new external_value(PARAM_INT, 'id of course'),
 653                     'type' => new external_value(PARAM_PLUGIN, 'type of enrolment plugin'),
 654                     'name' => new external_value(PARAM_RAW, 'name of enrolment plugin'),
 655                     'status' => new external_value(PARAM_RAW, 'status of enrolment plugin'),
 656                     'wsfunction' => new external_value(PARAM_ALPHANUMEXT, 'webservice function to get more information', VALUE_OPTIONAL),
 657                 )
 658             )
 659         );
 660     }
 661 }
 662
 663 /**
 664  * Role external functions
 665  *
 666  * @package    core_role
 667  * @category   external
 668  * @copyright  2011 Jerome Mouneyrac
 669  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 670  * @since Moodle 2.2
 671  */
 672 class core_role_external extends external_api {
 673
 674     /**
 675      * Returns description of method parameters
 676      *
 677      * @return external_function_parameters
 678      */
 679     public static function assign_roles_parameters() {
 680         return new external_function_parameters(
 681             array(
 682                 'assignments' => new external_multiple_structure(
 683                     new external_single_structure(
 684                         array(
 685                             'roleid'    => new external_value(PARAM_INT, 'Role to assign to the user'),
 686                             'userid'    => new external_value(PARAM_INT, 'The user that is going to be assigned'),
 687                             'contextid' => new external_value(PARAM_INT, 'The context to assign the user role in', VALUE_OPTIONAL),
 688                             'contextlevel' => new external_value(PARAM_ALPHA, 'The context level to assign the user role in
 689                                     (block, course, coursecat, system, user, module)', VALUE_OPTIONAL),
 690                             'instanceid' => new external_value(PARAM_INT, 'The Instance id of item where the role needs to be assigned', VALUE_OPTIONAL),
 691                         )
 692                     )
 693                 )
 694             )
 695         );
 696     }
 697
 698     /**
 699      * Manual role assignments to users
 700      *
 701      * @param array $assignments An array of manual role assignment
 702      */
 703     public static function assign_roles($assignments) {
 704         global $DB;
 705
 706         // Do basic automatic PARAM checks on incoming data, using params description
 707         // If any problems are found then exceptions are thrown with helpful error messages
 708         $params = self::validate_parameters(self::assign_roles_parameters(), array('assignments'=>$assignments));
 709
 710         $transaction = $DB->start_delegated_transaction();
 711
 712         foreach ($params['assignments'] as $assignment) {
 713             // Ensure correct context level with a instance id or contextid is passed.
 714             $context = self::get_context_from_params($assignment);
 715
 716             // Ensure the current user is allowed to run this function in the enrolment context.
 717             self::validate_context($context);
 718             require_capability('moodle/role:assign', $context);
 719
 720             // throw an exception if user is not able to assign the role in this context
 721             $roles = get_assignable_roles($context, ROLENAME_SHORT);
 722
 723             if (!array_key_exists($assignment['roleid'], $roles)) {
 724                 throw new invalid_parameter_exception('Can not assign roleid='.$assignment['roleid'].' in contextid='.$assignment['contextid']);
 725             }
 726
 727             role_assign($assignment['roleid'], $assignment['userid'], $context->id);
 728         }
 729
 730         $transaction->allow_commit();
 731     }
 732
 733     /**
 734      * Returns description of method result value
 735      *
 736      * @return null
 737      */
 738     public static function assign_roles_returns() {
 739         return null;
 740     }
 741
 742
 743     /**
 744      * Returns description of method parameters
 745      *
 746      * @return external_function_parameters
 747      */
 748     public static function unassign_roles_parameters() {
 749         return new external_function_parameters(
 750             array(
 751                 'unassignments' => new external_multiple_structure(
 752                     new external_single_structure(
 753                         array(
 754                             'roleid'    => new external_value(PARAM_INT, 'Role to assign to the user'),
 755                             'userid'    => new external_value(PARAM_INT, 'The user that is going to be assigned'),
 756                             'contextid' => new external_value(PARAM_INT, 'The context to unassign the user role from', VALUE_OPTIONAL),
 757                             'contextlevel' => new external_value(PARAM_ALPHA, 'The context level to unassign the user role in
 758 +                                    (block, course, coursecat, system, user, module)', VALUE_OPTIONAL),
 759                             'instanceid' => new external_value(PARAM_INT, 'The Instance id of item where the role needs to be unassigned', VALUE_OPTIONAL),
 760                         )
 761                     )
 762                 )
 763             )
 764         );
 765     }
 766
 767      /**
 768      * Unassign roles from users
 769      *
 770      * @param array $unassignments An array of unassignment
 771      */
 772     public static function unassign_roles($unassignments) {
 773          global $DB;
 774
 775         // Do basic automatic PARAM checks on incoming data, using params description
 776         // If any problems are found then exceptions are thrown with helpful error messages
 777         $params = self::validate_parameters(self::unassign_roles_parameters(), array('unassignments'=>$unassignments));
 778
 779         $transaction = $DB->start_delegated_transaction();
 780
 781         foreach ($params['unassignments'] as $unassignment) {
 782             // Ensure the current user is allowed to run this function in the unassignment context
 783             $context = self::get_context_from_params($unassignment);
 784             self::validate_context($context);
 785             require_capability('moodle/role:assign', $context);
 786
 787             // throw an exception if user is not able to unassign the role in this context
 788             $roles = get_assignable_roles($context, ROLENAME_SHORT);
 789             if (!array_key_exists($unassignment['roleid'], $roles)) {
 790                 throw new invalid_parameter_exception('Can not unassign roleid='.$unassignment['roleid'].' in contextid='.$unassignment['contextid']);
 791             }
 792
 793             role_unassign($unassignment['roleid'], $unassignment['userid'], $context->id);
 794         }
 795
 796         $transaction->allow_commit();
 797     }
 798
 799    /**
 800      * Returns description of method result value
 801      *
 802      * @return null
 803      */
 804     public static function unassign_roles_returns() {
 805         return null;
 806     }
 807 }
 808
 809
 810 /**
 811  * Deprecated enrol and role external functions
 812  *
 813  * @package    core_enrol
 814  * @copyright  2010 Jerome Mouneyrac
 815  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 816  * @since Moodle 2.0
 817  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
 818  * @see core_enrol_external
 819  * @see core_role_external
 820  */
 821 class moodle_enrol_external extends external_api {
 822
 823
 824     /**
 825      * Returns description of method parameters
 826      *
 827      * @return external_function_parameters
 828      * @since Moodle 2.0
 829      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 830      * @see core_enrol_external::get_enrolled_users_parameters()
 831      */
 832     public static function get_enrolled_users_parameters() {
 833         return new external_function_parameters(
 834             array(
 835                 'courseid'       => new external_value(PARAM_INT, 'Course id'),
 836                 'withcapability' => new external_value(PARAM_CAPABILITY, 'User should have this capability', VALUE_DEFAULT, null),
 837                 'groupid'        => new external_value(PARAM_INT, 'Group id, null means all groups', VALUE_DEFAULT, null),
 838                 'onlyactive'     => new external_value(PARAM_INT, 'True means only active, false means all participants', VALUE_DEFAULT, 0),
 839             )
 840         );
 841     }
 842
 843     /**
 844      * Get list of course participants.
 845      *
 846      * @param int $courseid
 847      * @param text $withcapability
 848      * @param int $groupid
 849      * @param bool $onlyactive
 850      * @return array of course participants
 851      * @since Moodle 2.0
 852      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 853      * @see core_enrol_external::get_enrolled_users()
 854      */
 855     public static function get_enrolled_users($courseid, $withcapability = null, $groupid = null, $onlyactive = false) {
 856         global $DB, $CFG, $USER;
 857
 858         // Do basic automatic PARAM checks on incoming data, using params description
 859         // If any problems are found then exceptions are thrown with helpful error messages
 860         $params = self::validate_parameters(self::get_enrolled_users_parameters(), array(
 861             'courseid'=>$courseid,
 862             'withcapability'=>$withcapability,
 863             'groupid'=>$groupid,
 864             'onlyactive'=>$onlyactive)
 865         );
 866
 867         $coursecontext = context_course::instance($params['courseid'], IGNORE_MISSING);
 868         if ($courseid == SITEID) {
 869             $context = context_system::instance();
 870         } else {
 871             $context = $coursecontext;
 872         }
 873
 874         try {
 875             self::validate_context($context);
 876         } catch (Exception $e) {
 877             $exceptionparam = new stdClass();
 878             $exceptionparam->message = $e->getMessage();
 879             $exceptionparam->courseid = $params['courseid'];
 880             throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
 881         }
 882
 883         if ($courseid == SITEID) {
 884             require_capability('moodle/site:viewparticipants', $context);
 885         } else {
 886             require_capability('moodle/course:viewparticipants', $context);
 887         }
 888
 889         if ($withcapability) {
 890             require_capability('moodle/role:review', $coursecontext);
 891         }
 892         if ($groupid && groups_is_member($groupid)) {
 893             require_capability('moodle/site:accessallgroups', $coursecontext);
 894         }
 895         if ($onlyactive) {
 896             require_capability('moodle/course:enrolreview', $coursecontext);
 897         }
 898
 899         list($sqlparams, $params) =  get_enrolled_sql($coursecontext, $withcapability, $groupid, $onlyactive);
 900         $sql = "SELECT ue.userid, e.courseid, u.firstname, u.lastname, u.username, c.id as usercontextid
 901                   FROM {user_enrolments} ue
 902                   JOIN {enrol} e ON (e.id = ue.enrolid)
 903                   JOIN {user} u ON (ue.userid = u.id)
 904                   JOIN {context} c ON (u.id = c.instanceid AND contextlevel = " . CONTEXT_USER . ")
 905                   WHERE e.courseid = :courseid AND ue.userid IN ($sqlparams)
 906                   GROUP BY ue.userid, e.courseid, u.firstname, u.lastname, u.username, c.id";
 907         $params['courseid'] = $courseid;
 908         $enrolledusers = $DB->get_records_sql($sql, $params);
 909         $result = array();
 910         $isadmin = is_siteadmin($USER);
 911         $canviewfullnames = has_capability('moodle/site:viewfullnames', $context);
 912         foreach ($enrolledusers as $enrolleduser) {
 913             $profilimgurl = moodle_url::make_pluginfile_url($enrolleduser->usercontextid, 'user', 'icon', NULL, '/', 'f1');
 914             $profilimgurlsmall = moodle_url::make_pluginfile_url($enrolleduser->usercontextid, 'user', 'icon', NULL, '/', 'f2');
 915             $resultuser = array(
 916                 'courseid' => $enrolleduser->courseid,
 917                 'userid' => $enrolleduser->userid,
 918                 'fullname' => fullname($enrolleduser),
 919                 'profileimgurl' => $profilimgurl->out(false),
 920                 'profileimgurlsmall' => $profilimgurlsmall->out(false)
 921             );
 922             // check if we can return username
 923             if ($isadmin) {
 924                 $resultuser['username'] = $enrolleduser->username;
 925             }
 926             // check if we can return first and last name
 927             if ($isadmin or $canviewfullnames) {
 928                 $resultuser['firstname'] = $enrolleduser->firstname;
 929                 $resultuser['lastname'] = $enrolleduser->lastname;
 930             }
 931             $result[] = $resultuser;
 932         }
 933
 934         return $result;
 935     }
 936
 937     /**
 938      * Returns description of method result value
 939      *
 940      * @return external_description
 941      * @since Moodle 2.0
 942      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 943      * @see core_enrol_external::get_enrolled_users_returns()
 944      */
 945     public static function get_enrolled_users_returns() {
 946         return new external_multiple_structure(
 947             new external_single_structure(
 948                 array(
 949                     'courseid' => new external_value(PARAM_INT, 'id of course'),
 950                     'userid' => new external_value(PARAM_INT, 'id of user'),
 951                     'firstname' => new external_value(PARAM_RAW, 'first name of user', VALUE_OPTIONAL),
 952                     'lastname' => new external_value(PARAM_RAW, 'last name of user', VALUE_OPTIONAL),
 953                     'fullname' => new external_value(PARAM_RAW, 'fullname of user'),
 954                     'username' => new external_value(PARAM_RAW, 'username of user', VALUE_OPTIONAL),
 955                     'profileimgurl' => new external_value(PARAM_URL, 'url of the profile image'),
 956                     'profileimgurlsmall' => new external_value(PARAM_URL, 'url of the profile image (small version)')
 957                 )
 958             )
 959         );
 960     }
 961
 962     /**
 963      * Marking the method as deprecated.
 964      *
 965      * @return bool
 966      */
 967     public static function get_enrolled_users_is_deprecated() {
 968         return true;
 969     }
 970
 971     /**
 972      * Returns description of method parameters
 973      *
 974      * @return external_function_parameters
 975      * @since Moodle 2.1
 976      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 977      * @see core_enrol_external::get_users_courses_parameters()
 978      */
 979     public static function get_users_courses_parameters() {
 980         return core_enrol_external::get_users_courses_parameters();
 981     }
 982
 983     /**
 984      * Get list of courses user is enrolled in (only active enrolments are returned).
 985      * Please note the current user must be able to access the course, otherwise the course is not included.
 986      *
 987      * @param int $userid
 988      * @return array of courses
 989      * @since Moodle 2.1
 990      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 991      * @see use core_enrol_external::get_users_courses()
 992      */
 993     public static function get_users_courses($userid) {
 994         return core_enrol_external::get_users_courses($userid);
 995     }
 996
 997     /**
 998      * Returns description of method result value
 999      *
1000      * @return external_description
1001      * @since Moodle 2.1
1002      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1003      * @see core_enrol_external::get_users_courses_returns()
1004      */
1005     public static function get_users_courses_returns() {
1006         return core_enrol_external::get_users_courses_returns();
1007     }
1008
1009     /**
1010      * Marking the method as deprecated.
1011      *
1012      * @return bool
1013      */
1014     public static function get_users_courses_is_deprecated() {
1015         return true;
1016     }
1017
1018     /**
1019      * Returns description of method parameters
1020      *
1021      * @return external_function_parameters
1022      * @since Moodle 2.0
1023      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1024      * @see core_role_external::assign_roles_parameters()
1025      */
1026     public static function role_assign_parameters() {
1027         return core_role_external::assign_roles_parameters();
1028     }
1029
1030     /**
1031      * Manual role assignments to users
1032      *
1033      * @param array $assignments An array of manual role assignment
1034      * @since Moodle 2.0
1035      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1036      * @see core_role_external::assign_roles()
1037      */
1038     public static function role_assign($assignments) {
1039         return core_role_external::assign_roles($assignments);
1040     }
1041
1042     /**
1043      * Returns description of method result value
1044      *
1045      * @return null
1046      * @since Moodle 2.0
1047      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1048      * @see core_role_external::assign_roles_returns()
1049      */
1050     public static function role_assign_returns() {
1051         return core_role_external::assign_roles_returns();
1052     }
1053
1054     /**
1055      * Marking the method as deprecated.
1056      *
1057      * @return bool
1058      */
1059     public static function role_assign_is_deprecated() {
1060         return true;
1061     }
1062
1063     /**
1064      * Returns description of method parameters
1065      *
1066      * @return external_function_parameters
1067      * @since Moodle 2.0
1068      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1069      * @see core_role_external::unassign_roles_parameters()
1070      */
1071     public static function role_unassign_parameters() {
1072         return core_role_external::unassign_roles_parameters();
1073     }
1074
1075      /**
1076      * Unassign roles from users
1077      *
1078      * @param array $unassignments An array of unassignment
1079      * @since Moodle 2.0
1080      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1081      * @see core_role_external::unassign_roles()
1082      */
1083     public static function role_unassign($unassignments) {
1084          return core_role_external::unassign_roles($unassignments);
1085     }
1086
1087    /**
1088      * Returns description of method result value
1089      *
1090      * @return null
1091      * @since Moodle 2.0
1092      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1093      * @see core_role_external::unassign_roles_returns()
1094      */
1095     public static function role_unassign_returns() {
1096         return core_role_external::unassign_roles_returns();
1097     }
1098
1099     /**
1100      * Marking the method as deprecated.
1101      *
1102      * @return bool
1103      */
1104     public static function role_unassign_is_deprecated() {
1105         return true;
1106     }
1107 }