[Summary view] [Print] [Text view]

   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, category');
 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              $course->fullname = external_format_string($course->fullname, $context->id);
 327              $course->shortname = external_format_string($course->shortname, $context->id);
 328  
 329              $result[] = array(
 330                  'id' => $course->id,
 331                  'shortname' => $course->shortname,
 332                  'fullname' => $course->fullname,
 333                  'idnumber' => $course->idnumber,
 334                  'visible' => $course->visible,
 335                  'enrolledusercount' => $enrolledusercount,
 336                  'summary' => $course->summary,
 337                  'summaryformat' => $course->summaryformat,
 338                  'format' => $course->format,
 339                  'showgrades' => $course->showgrades,
 340                  'lang' => $course->lang,
 341                  'enablecompletion' => $course->enablecompletion,
 342                  'category' => $course->category
 343              );
 344          }
 345  
 346          return $result;
 347      }
 348  
 349      /**
 350       * Returns description of method result value
 351       *
 352       * @return external_description
 353       */
 354      public static function get_users_courses_returns() {
 355          return new external_multiple_structure(
 356              new external_single_structure(
 357                  array(
 358                      'id'        => new external_value(PARAM_INT, 'id of course'),
 359                      'shortname' => new external_value(PARAM_RAW, 'short name of course'),
 360                      'fullname'  => new external_value(PARAM_RAW, 'long name of course'),
 361                      'enrolledusercount' => new external_value(PARAM_INT, 'Number of enrolled users in this course'),
 362                      'idnumber'  => new external_value(PARAM_RAW, 'id number of course'),
 363                      'visible'   => new external_value(PARAM_INT, '1 means visible, 0 means hidden course'),
 364                      'summary'   => new external_value(PARAM_RAW, 'summary', VALUE_OPTIONAL),
 365                      'summaryformat' => new external_format_value('summary', VALUE_OPTIONAL),
 366                      'format'    => new external_value(PARAM_PLUGIN, 'course format: weeks, topics, social, site', VALUE_OPTIONAL),
 367                      'showgrades' => new external_value(PARAM_BOOL, 'true if grades are shown, otherwise false', VALUE_OPTIONAL),
 368                      'lang'      => new external_value(PARAM_LANG, 'forced course language', VALUE_OPTIONAL),
 369                      'enablecompletion' => new external_value(PARAM_BOOL, 'true if completion is enabled, otherwise false',
 370                                                                  VALUE_OPTIONAL),
 371                      'category' => new external_value(PARAM_INT, 'course category id', VALUE_OPTIONAL),
 372                  )
 373              )
 374          );
 375      }
 376  
 377      /**
 378       * Returns description of method parameters
 379       *
 380       * @return external_function_parameters
 381       */
 382      public static function get_enrolled_users_parameters() {
 383          return new external_function_parameters(
 384              array(
 385                  'courseid' => new external_value(PARAM_INT, 'course id'),
 386                  'options'  => new external_multiple_structure(
 387                      new external_single_structure(
 388                          array(
 389                              'name'  => new external_value(PARAM_ALPHANUMEXT, 'option name'),
 390                              'value' => new external_value(PARAM_RAW, 'option value')
 391                          )
 392                      ), 'Option names:
 393                              * withcapability (string) return only users with this capability. This option requires \'moodle/role:review\' on the course context.
 394                              * groupid (integer) return only users in this group id. If the course has groups enabled and this param
 395                                                  isn\'t defined, returns all the viewable users.
 396                                                  This option requires \'moodle/site:accessallgroups\' on the course context if the
 397                                                  user doesn\'t belong to the group.
 398                              * onlyactive (integer) return only users with active enrolments and matching time restrictions. This option requires \'moodle/course:enrolreview\' on the course context.
 399                              * userfields (\'string, string, ...\') return only the values of these user fields.
 400                              * limitfrom (integer) sql limit from.
 401                              * limitnumber (integer) maximum number of returned users.
 402                              * sortby (string) sort by id, firstname or lastname. For ordering like the site does, use siteorder.
 403                              * sortdirection (string) ASC or DESC',
 404                              VALUE_DEFAULT, array()),
 405              )
 406          );
 407      }
 408  
 409      /**
 410       * Get course participants details
 411       *
 412       * @param int $courseid  course id
 413       * @param array $options options {
 414       *                                'name' => option name
 415       *                                'value' => option value
 416       *                               }
 417       * @return array An array of users
 418       */
 419      public static function get_enrolled_users($courseid, $options = array()) {
 420          global $CFG, $USER, $DB;
 421          require_once($CFG->dirroot . "/user/lib.php");
 422  
 423          $params = self::validate_parameters(
 424              self::get_enrolled_users_parameters(),
 425              array(
 426                  'courseid'=>$courseid,
 427                  'options'=>$options
 428              )
 429          );
 430          $withcapability = '';
 431          $groupid        = 0;
 432          $onlyactive     = false;
 433          $userfields     = array();
 434          $limitfrom = 0;
 435          $limitnumber = 0;
 436          $sortby = 'us.id';
 437          $sortparams = array();
 438          $sortdirection = 'ASC';
 439          foreach ($options as $option) {
 440              switch ($option['name']) {
 441              case 'withcapability':
 442                  $withcapability = $option['value'];
 443                  break;
 444              case 'groupid':
 445                  $groupid = (int)$option['value'];
 446                  break;
 447              case 'onlyactive':
 448                  $onlyactive = !empty($option['value']);
 449                  break;
 450              case 'userfields':
 451                  $thefields = explode(',', $option['value']);
 452                  foreach ($thefields as $f) {
 453                      $userfields[] = clean_param($f, PARAM_ALPHANUMEXT);
 454                  }
 455                  break;
 456              case 'limitfrom' :
 457                  $limitfrom = clean_param($option['value'], PARAM_INT);
 458                  break;
 459              case 'limitnumber' :
 460                  $limitnumber = clean_param($option['value'], PARAM_INT);
 461                  break;
 462              case 'sortby':
 463                  $sortallowedvalues = array('id', 'firstname', 'lastname', 'siteorder');
 464                  if (!in_array($option['value'], $sortallowedvalues)) {
 465                      throw new invalid_parameter_exception('Invalid value for sortby parameter (value: ' . $option['value'] . '),' .
 466                          'allowed values are: ' . implode(',', $sortallowedvalues));
 467                  }
 468                  if ($option['value'] == 'siteorder') {
 469                      list($sortby, $sortparams) = users_order_by_sql('us');
 470                  } else {
 471                      $sortby = 'us.' . $option['value'];
 472                  }
 473                  break;
 474              case 'sortdirection':
 475                  $sortdirection = strtoupper($option['value']);
 476                  $directionallowedvalues = array('ASC', 'DESC');
 477                  if (!in_array($sortdirection, $directionallowedvalues)) {
 478                      throw new invalid_parameter_exception('Invalid value for sortdirection parameter
 479                          (value: ' . $sortdirection . '),' . 'allowed values are: ' . implode(',', $directionallowedvalues));
 480                  }
 481                  break;
 482              }
 483          }
 484  
 485          $course = $DB->get_record('course', array('id'=>$courseid), '*', MUST_EXIST);
 486          $coursecontext = context_course::instance($courseid, IGNORE_MISSING);
 487          if ($courseid == SITEID) {
 488              $context = context_system::instance();
 489          } else {
 490              $context = $coursecontext;
 491          }
 492          try {
 493              self::validate_context($context);
 494          } catch (Exception $e) {
 495              $exceptionparam = new stdClass();
 496              $exceptionparam->message = $e->getMessage();
 497              $exceptionparam->courseid = $params['courseid'];
 498              throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
 499          }
 500  
 501          if ($courseid == SITEID) {
 502              require_capability('moodle/site:viewparticipants', $context);
 503          } else {
 504              require_capability('moodle/course:viewparticipants', $context);
 505          }
 506          // to overwrite this parameter, you need role:review capability
 507          if ($withcapability) {
 508              require_capability('moodle/role:review', $coursecontext);
 509          }
 510          // need accessallgroups capability if you want to overwrite this option
 511          if (!empty($groupid) && !groups_is_member($groupid)) {
 512              require_capability('moodle/site:accessallgroups', $coursecontext);
 513          }
 514          // to overwrite this option, you need course:enrolereview permission
 515          if ($onlyactive) {
 516              require_capability('moodle/course:enrolreview', $coursecontext);
 517          }
 518  
 519          list($enrolledsql, $enrolledparams) = get_enrolled_sql($coursecontext, $withcapability, $groupid, $onlyactive);
 520          $ctxselect = ', ' . context_helper::get_preload_record_columns_sql('ctx');
 521          $ctxjoin = "LEFT JOIN {context} ctx ON (ctx.instanceid = u.id AND ctx.contextlevel = :contextlevel)";
 522          $enrolledparams['contextlevel'] = CONTEXT_USER;
 523  
 524          $groupjoin = '';
 525          if (empty($groupid) && groups_get_course_groupmode($course) == SEPARATEGROUPS &&
 526                  !has_capability('moodle/site:accessallgroups', $coursecontext)) {
 527              // Filter by groups the user can view.
 528              $usergroups = groups_get_user_groups($course->id);
 529              if (!empty($usergroups['0'])) {
 530                  list($groupsql, $groupparams) = $DB->get_in_or_equal($usergroups['0'], SQL_PARAMS_NAMED);
 531                  $groupjoin = "JOIN {groups_members} gm ON (u.id = gm.userid AND gm.groupid $groupsql)";
 532                  $enrolledparams = array_merge($enrolledparams, $groupparams);
 533              } else {
 534                  // User doesn't belong to any group, so he can't see any user. Return an empty array.
 535                  return array();
 536              }
 537          }
 538          $sql = "SELECT us.*
 539                    FROM {user} us
 540                    JOIN (
 541                        SELECT DISTINCT u.id $ctxselect
 542                          FROM {user} u $ctxjoin $groupjoin
 543                         WHERE u.id IN ($enrolledsql)
 544                    ) q ON q.id = us.id
 545                  ORDER BY $sortby $sortdirection";
 546          $enrolledparams = array_merge($enrolledparams, $sortparams);
 547          $enrolledusers = $DB->get_recordset_sql($sql, $enrolledparams, $limitfrom, $limitnumber);
 548          $users = array();
 549          foreach ($enrolledusers as $user) {
 550              context_helper::preload_from_record($user);
 551              if ($userdetails = user_get_user_details($user, $course, $userfields)) {
 552                  $users[] = $userdetails;
 553              }
 554          }
 555          $enrolledusers->close();
 556  
 557          return $users;
 558      }
 559  
 560      /**
 561       * Returns description of method result value
 562       *
 563       * @return external_description
 564       */
 565      public static function get_enrolled_users_returns() {
 566          return new external_multiple_structure(
 567              new external_single_structure(
 568                  array(
 569                      'id'    => new external_value(PARAM_INT, 'ID of the user'),
 570                      'username'    => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
 571                      'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
 572                      'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
 573                      'fullname'    => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
 574                      'email'       => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
 575                      'address'     => new external_value(PARAM_TEXT, 'Postal address', VALUE_OPTIONAL),
 576                      'phone1'      => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
 577                      'phone2'      => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
 578                      'icq'         => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
 579                      'skype'       => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
 580                      'yahoo'       => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
 581                      'aim'         => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
 582                      'msn'         => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
 583                      'department'  => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
 584                      'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
 585                      'idnumber'    => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
 586                      'interests'   => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
 587                      'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
 588                      'lastaccess'  => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
 589                      'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
 590                      'descriptionformat' => new external_format_value('description', VALUE_OPTIONAL),
 591                      'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
 592                      'url'         => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
 593                      'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
 594                      'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version', VALUE_OPTIONAL),
 595                      'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version', VALUE_OPTIONAL),
 596                      'customfields' => new external_multiple_structure(
 597                          new external_single_structure(
 598                              array(
 599                                  'type'  => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
 600                                  'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 601                                  'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
 602                                  'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
 603                              )
 604                          ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
 605                      'groups' => new external_multiple_structure(
 606                          new external_single_structure(
 607                              array(
 608                                  'id'  => new external_value(PARAM_INT, 'group id'),
 609                                  'name' => new external_value(PARAM_RAW, 'group name'),
 610                                  'description' => new external_value(PARAM_RAW, 'group description'),
 611                                  'descriptionformat' => new external_format_value('description'),
 612                              )
 613                          ), 'user groups', VALUE_OPTIONAL),
 614                      'roles' => new external_multiple_structure(
 615                          new external_single_structure(
 616                              array(
 617                                  'roleid'       => new external_value(PARAM_INT, 'role id'),
 618                                  'name'         => new external_value(PARAM_RAW, 'role name'),
 619                                  'shortname'    => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
 620                                  'sortorder'    => new external_value(PARAM_INT, 'role sortorder')
 621                              )
 622                          ), 'user roles', VALUE_OPTIONAL),
 623                      'preferences' => new external_multiple_structure(
 624                          new external_single_structure(
 625                              array(
 626                                  'name'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
 627                                  'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 628                              )
 629                      ), 'User preferences', VALUE_OPTIONAL),
 630                      'enrolledcourses' => new external_multiple_structure(
 631                          new external_single_structure(
 632                              array(
 633                                  'id'  => new external_value(PARAM_INT, 'Id of the course'),
 634                                  'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
 635                                  'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
 636                              )
 637                      ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
 638                  )
 639              )
 640          );
 641      }
 642  
 643      /**
 644       * Returns description of get_course_enrolment_methods() parameters
 645       *
 646       * @return external_function_parameters
 647       */
 648      public static function get_course_enrolment_methods_parameters() {
 649          return new external_function_parameters(
 650              array(
 651                  'courseid' => new external_value(PARAM_INT, 'Course id')
 652              )
 653          );
 654      }
 655  
 656      /**
 657       * Get list of active course enrolment methods for current user.
 658       *
 659       * @param int $courseid
 660       * @return array of course enrolment methods
 661       * @throws moodle_exception
 662       */
 663      public static function get_course_enrolment_methods($courseid) {
 664          global $DB;
 665  
 666          $params = self::validate_parameters(self::get_course_enrolment_methods_parameters(), array('courseid' => $courseid));
 667          self::validate_context(context_system::instance());
 668  
 669          $course = $DB->get_record('course', array('id' => $params['courseid']), '*', MUST_EXIST);
 670          $context = context_course::instance($course->id);
 671          if (!$course->visible and !has_capability('moodle/course:viewhiddencourses', $context)) {
 672              throw new moodle_exception('coursehidden');
 673          }
 674  
 675          $result = array();
 676          $enrolinstances = enrol_get_instances($params['courseid'], true);
 677          foreach ($enrolinstances as $enrolinstance) {
 678              if ($enrolplugin = enrol_get_plugin($enrolinstance->enrol)) {
 679                  if ($instanceinfo = $enrolplugin->get_enrol_info($enrolinstance)) {
 680                      $result[] = (array) $instanceinfo;
 681                  }
 682              }
 683          }
 684          return $result;
 685      }
 686  
 687      /**
 688       * Returns description of get_course_enrolment_methods() result value
 689       *
 690       * @return external_description
 691       */
 692      public static function get_course_enrolment_methods_returns() {
 693          return new external_multiple_structure(
 694              new external_single_structure(
 695                  array(
 696                      'id' => new external_value(PARAM_INT, 'id of course enrolment instance'),
 697                      'courseid' => new external_value(PARAM_INT, 'id of course'),
 698                      'type' => new external_value(PARAM_PLUGIN, 'type of enrolment plugin'),
 699                      'name' => new external_value(PARAM_RAW, 'name of enrolment plugin'),
 700                      'status' => new external_value(PARAM_RAW, 'status of enrolment plugin'),
 701                      'wsfunction' => new external_value(PARAM_ALPHANUMEXT, 'webservice function to get more information', VALUE_OPTIONAL),
 702                  )
 703              )
 704          );
 705      }
 706  }
 707  
 708  /**
 709   * Role external functions
 710   *
 711   * @package    core_role
 712   * @category   external
 713   * @copyright  2011 Jerome Mouneyrac
 714   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 715   * @since Moodle 2.2
 716   */
 717  class core_role_external extends external_api {
 718  
 719      /**
 720       * Returns description of method parameters
 721       *
 722       * @return external_function_parameters
 723       */
 724      public static function assign_roles_parameters() {
 725          return new external_function_parameters(
 726              array(
 727                  'assignments' => new external_multiple_structure(
 728                      new external_single_structure(
 729                          array(
 730                              'roleid'    => new external_value(PARAM_INT, 'Role to assign to the user'),
 731                              'userid'    => new external_value(PARAM_INT, 'The user that is going to be assigned'),
 732                              'contextid' => new external_value(PARAM_INT, 'The context to assign the user role in', VALUE_OPTIONAL),
 733                              'contextlevel' => new external_value(PARAM_ALPHA, 'The context level to assign the user role in
 734                                      (block, course, coursecat, system, user, module)', VALUE_OPTIONAL),
 735                              'instanceid' => new external_value(PARAM_INT, 'The Instance id of item where the role needs to be assigned', VALUE_OPTIONAL),
 736                          )
 737                      )
 738                  )
 739              )
 740          );
 741      }
 742  
 743      /**
 744       * Manual role assignments to users
 745       *
 746       * @param array $assignments An array of manual role assignment
 747       */
 748      public static function assign_roles($assignments) {
 749          global $DB;
 750  
 751          // Do basic automatic PARAM checks on incoming data, using params description
 752          // If any problems are found then exceptions are thrown with helpful error messages
 753          $params = self::validate_parameters(self::assign_roles_parameters(), array('assignments'=>$assignments));
 754  
 755          $transaction = $DB->start_delegated_transaction();
 756  
 757          foreach ($params['assignments'] as $assignment) {
 758              // Ensure correct context level with a instance id or contextid is passed.
 759              $context = self::get_context_from_params($assignment);
 760  
 761              // Ensure the current user is allowed to run this function in the enrolment context.
 762              self::validate_context($context);
 763              require_capability('moodle/role:assign', $context);
 764  
 765              // throw an exception if user is not able to assign the role in this context
 766              $roles = get_assignable_roles($context, ROLENAME_SHORT);
 767  
 768              if (!array_key_exists($assignment['roleid'], $roles)) {
 769                  throw new invalid_parameter_exception('Can not assign roleid='.$assignment['roleid'].' in contextid='.$assignment['contextid']);
 770              }
 771  
 772              role_assign($assignment['roleid'], $assignment['userid'], $context->id);
 773          }
 774  
 775          $transaction->allow_commit();
 776      }
 777  
 778      /**
 779       * Returns description of method result value
 780       *
 781       * @return null
 782       */
 783      public static function assign_roles_returns() {
 784          return null;
 785      }
 786  
 787  
 788      /**
 789       * Returns description of method parameters
 790       *
 791       * @return external_function_parameters
 792       */
 793      public static function unassign_roles_parameters() {
 794          return new external_function_parameters(
 795              array(
 796                  'unassignments' => new external_multiple_structure(
 797                      new external_single_structure(
 798                          array(
 799                              'roleid'    => new external_value(PARAM_INT, 'Role to assign to the user'),
 800                              'userid'    => new external_value(PARAM_INT, 'The user that is going to be assigned'),
 801                              'contextid' => new external_value(PARAM_INT, 'The context to unassign the user role from', VALUE_OPTIONAL),
 802                              'contextlevel' => new external_value(PARAM_ALPHA, 'The context level to unassign the user role in
 803  +                                    (block, course, coursecat, system, user, module)', VALUE_OPTIONAL),
 804                              'instanceid' => new external_value(PARAM_INT, 'The Instance id of item where the role needs to be unassigned', VALUE_OPTIONAL),
 805                          )
 806                      )
 807                  )
 808              )
 809          );
 810      }
 811  
 812       /**
 813       * Unassign roles from users
 814       *
 815       * @param array $unassignments An array of unassignment
 816       */
 817      public static function unassign_roles($unassignments) {
 818           global $DB;
 819  
 820          // Do basic automatic PARAM checks on incoming data, using params description
 821          // If any problems are found then exceptions are thrown with helpful error messages
 822          $params = self::validate_parameters(self::unassign_roles_parameters(), array('unassignments'=>$unassignments));
 823  
 824          $transaction = $DB->start_delegated_transaction();
 825  
 826          foreach ($params['unassignments'] as $unassignment) {
 827              // Ensure the current user is allowed to run this function in the unassignment context
 828              $context = self::get_context_from_params($unassignment);
 829              self::validate_context($context);
 830              require_capability('moodle/role:assign', $context);
 831  
 832              // throw an exception if user is not able to unassign the role in this context
 833              $roles = get_assignable_roles($context, ROLENAME_SHORT);
 834              if (!array_key_exists($unassignment['roleid'], $roles)) {
 835                  throw new invalid_parameter_exception('Can not unassign roleid='.$unassignment['roleid'].' in contextid='.$unassignment['contextid']);
 836              }
 837  
 838              role_unassign($unassignment['roleid'], $unassignment['userid'], $context->id);
 839          }
 840  
 841          $transaction->allow_commit();
 842      }
 843  
 844     /**
 845       * Returns description of method result value
 846       *
 847       * @return null
 848       */
 849      public static function unassign_roles_returns() {
 850          return null;
 851      }
 852  }