MDL-21437 data - checkbox and multimenu fields search working + require all too
[moodle.git] / enrol / externallib.php
1 <?php
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/>.
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  */
30 defined('MOODLE_INTERNAL') || die();
32 require_once("$CFG->libdir/externallib.php");
35 class moodle_enrol_external extends external_api {
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     }
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;
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));
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         }
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         }
85         if ($courseid == SITEID) {
86             require_capability('moodle/site:viewparticipants', $context);
87         } else {
88             require_capability('moodle/course:viewparticipants', $context);
89         }
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         }
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;
110         $enrolledusers = $DB->get_records_sql($sql, $params);
112         $result = array();
113         foreach ($enrolledusers as $enrolleduser) {
114             $result[] = array('courseid' => $enrolleduser->courseid,
115                 'userid' => $enrolleduser->userid);
116         }
118         return $result;
119     }
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     }
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     }
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;
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));
170         $transaction = $DB->start_delegated_transaction();
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);
178             role_assign($assignment['roleid'], $assignment['userid'], $assignment['contextid']);
179         }
181         $transaction->allow_commit();
182     }
184     /**
185      * Returns description of method result value
186      * @return external_description
187      */
188     public static function role_assign_returns() {
189         return null;
190     }
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     }
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;
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));
226         $transaction = $DB->start_delegated_transaction();
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);
234             role_unassign($unassignment['roleid'], $unassignment['userid'], $unassignment['contextid']);
235         }
237         $transaction->allow_commit();
238     }
240    /**
241      * Returns description of method result value
242      * @return external_description
243      */
244     public static function role_unassign_returns() {
245         return null;
246     }