enrol/externallib.php

   1 <?php
   2
   3 // This file is part of Moodle - http://moodle.org/
   4 //
   5 // Moodle is free software: you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation, either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // Moodle is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 /**
  19  * External 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
  25  * @subpackage enrol
  26  * @copyright  2009 Moodle Pty Ltd (http://moodle.com)
  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 class moodle_enrol_external extends external_api {
  36
  37     /**
  38      * Returns description of method parameters
  39      * @return external_function_parameters
  40      */
  41     public static function get_enrolled_users_parameters() {
  42         return new external_function_parameters(
  43             array(
  44                 'courseid'       => new external_value(PARAM_INT, 'Course id'),
  45                 'withcapability' => new external_value(PARAM_CAPABILITY, 'User should have this capability'),
  46                 'groupid'        => new external_value(PARAM_INT, 'Group id, null means all groups'),
  47                 'onlyactive'     => new external_value(PARAM_INT, 'True means only active, false means all participants'),
  48             )
  49         );
  50     }
  51
  52     /**
  53      * Get list of course participants.
  54      *
  55      * @param int $courseid
  56      * @param text $withcapability
  57      * @param int $groupid
  58      * @param bool $onlyactive
  59      * @return array of course participants
  60      */
  61     public static function get_enrolled_users($courseid, $withcapability, $groupid, $onlyactive) {
  62         global $DB;
  63
  64         // Do basic automatic PARAM checks on incoming data, using params description
  65         // If any problems are found then exceptions are thrown with helpful error messages
  66         $params = self::validate_parameters(self::get_enrolled_users_parameters(), array('courseid'=>$courseid, 'withcapability'=>$withcapability, 'groupid'=>$groupid, 'onlyactive'=>$onlyactive));
  67
  68         $coursecontext = get_context_instance(CONTEXT_COURSE, $params['courseid']);
  69         if ($courseid == SITEID) {
  70             $context = get_context_instance(CONTEXT_SYSTEM);
  71         } else {
  72             $context = $coursecontext;
  73         }
  74
  75         try {
  76             self::validate_context($context);
  77         } catch (Exception $e) {
  78                 $exceptionparam = new stdClass();
  79                 $exceptionparam->message = $e->getMessage();
  80                 $exceptionparam->courseid = $params['courseid'];
  81                 throw new moodle_exception(
  82                         get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
  83         }
  84
  85         if ($courseid == SITEID) {
  86             require_capability('moodle/site:viewparticipants', $context);
  87         } else {
  88             require_capability('moodle/course:viewparticipants', $context);
  89         }
  90
  91         if ($withcapability) {
  92             require_capability('moodle/role:review', $coursecontext);
  93         }
  94         if ($groupid) {
  95             if (groups_is_member($groupid)) {
  96                 require_capability('moodle/site:accessallgroups', $coursecontext);
  97             }
  98         }
  99         if ($onlyactive) {
 100             require_capability('moodle/course:enrolreview', $coursecontext);
 101         }
 102
 103         list($sql, $params) =  get_enrolled_sql($coursecontext, $withcapability, $groupid, $onlyactive);
 104         $sql = "SELECT DISTINCT ue.userid, e.courseid
 105                   FROM {user_enrolments} ue
 106                   JOIN {enrol} e ON (e.id = ue.enrolid)
 107                  WHERE e.courseid = :courseid AND ue.userid IN ($sql)";
 108         $params['courseid'] = $courseid;
 109
 110         $enrolledusers = $DB->get_records_sql($sql, $params);
 111
 112         $result = array();
 113         foreach ($enrolledusers as $enrolleduser) {
 114             $result[] = array('courseid' => $enrolleduser->courseid,
 115                 'userid' => $enrolleduser->userid);
 116         }
 117
 118         return $result;
 119     }
 120
 121     /**
 122      * Returns description of method result value
 123      * @return external_description
 124      */
 125     public static function get_enrolled_users_returns() {
 126         return new external_multiple_structure(
 127             new external_single_structure(
 128                 array(
 129                     'courseid' => new external_value(PARAM_INT, 'id of course'),
 130                     'userid' => new external_value(PARAM_INT, 'id of user'),
 131                 )
 132             )
 133         );
 134     }
 135
 136
 137     /**
 138      * Returns description of method parameters
 139      * @return external_function_parameters
 140      */
 141     public static function role_assign_parameters() {
 142         return new external_function_parameters(
 143             array(
 144                 'assignments' => new external_multiple_structure(
 145                     new external_single_structure(
 146                         array(
 147                             'roleid'    => new external_value(PARAM_INT, 'Role to assign to the user'),
 148                             'userid'    => new external_value(PARAM_INT, 'The user that is going to be assigned'),
 149                             'contextid' => new external_value(PARAM_INT, 'The context to assign the user role in'),
 150                         )
 151                     )
 152                 )
 153             )
 154         );
 155     }
 156
 157     /**
 158      * Manual role assignments to users
 159      *
 160      * @param array $assignment  An array of manual role assignment
 161      * @return null
 162      */
 163     public static function role_assign($assignments) {
 164         global $DB;
 165
 166         // Do basic automatic PARAM checks on incoming data, using params description
 167         // If any problems are found then exceptions are thrown with helpful error messages
 168         $params = self::validate_parameters(self::role_assign_parameters(), array('assignments'=>$assignments));
 169
 170         $transaction = $DB->start_delegated_transaction();
 171
 172         foreach ($params['assignments'] as $assignment) {
 173             // Ensure the current user is allowed to run this function in the enrolment context
 174             $context = get_context_instance_by_id($assignment['contextid']);
 175             self::validate_context($context);
 176             require_capability('moodle/role:assign', $context);
 177
 178             role_assign($assignment['roleid'], $assignment['userid'], $assignment['contextid']);
 179         }
 180
 181         $transaction->allow_commit();
 182     }
 183
 184     /**
 185      * Returns description of method result value
 186      * @return external_description
 187      */
 188     public static function role_assign_returns() {
 189         return null;
 190     }
 191
 192
 193     /**
 194      * Returns description of method parameters
 195      * @return external_function_parameters
 196      */
 197     public static function role_unassign_parameters() {
 198         return new external_function_parameters(
 199             array(
 200                 'unassignments' => new external_multiple_structure(
 201                     new external_single_structure(
 202                         array(
 203                             'roleid'    => new external_value(PARAM_INT, 'Role to assign to the user'),
 204                             'userid'    => new external_value(PARAM_INT, 'The user that is going to be assigned'),
 205                             'contextid' => new external_value(PARAM_INT, 'The context to unassign the user role from'),
 206                         )
 207                     )
 208                 )
 209             )
 210         );
 211     }
 212
 213      /**
 214      * Unassign roles from users
 215      *
 216      * @param array $unassignment  An array of unassignment
 217      * @return null
 218      */
 219     public static function role_unassign($unassignments) {
 220          global $DB;
 221
 222         // Do basic automatic PARAM checks on incoming data, using params description
 223         // If any problems are found then exceptions are thrown with helpful error messages
 224         $params = self::validate_parameters(self::role_unassign_parameters(), array('unassignments'=>$unassignments));
 225
 226         $transaction = $DB->start_delegated_transaction();
 227
 228         foreach ($params['unassignments'] as $unassignment) {
 229             // Ensure the current user is allowed to run this function in the unassignment context
 230             $context = get_context_instance_by_id($unassignment['contextid']);
 231             self::validate_context($context);
 232             require_capability('moodle/role:assign', $context);
 233
 234             role_unassign($unassignment['roleid'], $unassignment['userid'], $unassignment['contextid']);
 235         }
 236
 237         $transaction->allow_commit();
 238     }
 239
 240    /**
 241      * Returns description of method result value
 242      * @return external_description
 243      */
 244     public static function role_unassign_returns() {
 245         return null;
 246     }
 247 }