MDL-21437 data - checkbox and multimenu fields search working + require all too
[moodle.git] / enrol / externallib.php
CommitLineData
e9b66095 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/**
df997f84 19 * External course participation api.
e9b66095 20 *
df997f84
PS
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
e9b66095 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
97795859 30defined('MOODLE_INTERNAL') || die();
df997f84 31
e9b66095 32require_once("$CFG->libdir/externallib.php");
33
df997f84 34
e9b66095 35class moodle_enrol_external extends external_api {
36
37 /**
38 * Returns description of method parameters
39 * @return external_function_parameters
40 */
c2d81ff4 41 public static function get_enrolled_users_parameters() {
df997f84
PS
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'),
12b8f433 47 'onlyactive' => new external_value(PARAM_INT, 'True means only active, false means all participants'),
df997f84
PS
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
c2d81ff4 66 $params = self::validate_parameters(self::get_enrolled_users_parameters(), array('courseid'=>$courseid, 'withcapability'=>$withcapability, 'groupid'=>$groupid, 'onlyactive'=>$onlyactive));
df997f84
PS
67
68 $coursecontext = get_context_instance(CONTEXT_COURSE, $params['courseid']);
69 if ($courseid == SITEID) {
b02b5fb7 70 $context = get_context_instance(CONTEXT_SYSTEM);
df997f84
PS
71 } else {
72 $context = $coursecontext;
73 }
74
41e962ff 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 }
df997f84
PS
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 }
12b8f433 99 if ($onlyactive) {
df997f84
PS
100 require_capability('moodle/course:enrolreview', $coursecontext);
101 }
102
103 list($sql, $params) = get_enrolled_sql($coursecontext, $withcapability, $groupid, $onlyactive);
b02b5fb7 104 $sql = "SELECT DISTINCT ue.userid, e.courseid
df997f84
PS
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;
e9b66095 109
b02b5fb7 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;
df997f84
PS
119 }
120
121 /**
122 * Returns description of method result value
123 * @return external_description
124 */
125 public static function get_enrolled_users_returns() {
b02b5fb7 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 )
df997f84
PS
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() {
e9b66095 142 return new external_function_parameters(
143 array(
df997f84 144 'assignments' => new external_multiple_structure(
e9b66095 145 new external_single_structure(
146 array(
f1c9ff36 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'),
df997f84 149 'contextid' => new external_value(PARAM_INT, 'The context to assign the user role in'),
e9b66095 150 )
151 )
152 )
153 )
154 );
155 }
156
157 /**
df997f84 158 * Manual role assignments to users
e9b66095 159 *
df997f84 160 * @param array $assignment An array of manual role assignment
e9b66095 161 * @return null
162 */
df997f84
PS
163 public static function role_assign($assignments) {
164 global $DB;
e9b66095 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
df997f84 168 $params = self::validate_parameters(self::role_assign_parameters(), array('assignments'=>$assignments));
e9b66095 169
170 $transaction = $DB->start_delegated_transaction();
171
df997f84 172 foreach ($params['assignments'] as $assignment) {
e9b66095 173 // Ensure the current user is allowed to run this function in the enrolment context
df997f84 174 $context = get_context_instance_by_id($assignment['contextid']);
e9b66095 175 self::validate_context($context);
176 require_capability('moodle/role:assign', $context);
177
df997f84 178 role_assign($assignment['roleid'], $assignment['userid'], $assignment['contextid']);
e9b66095 179 }
180
181 $transaction->allow_commit();
e9b66095 182 }
183
184 /**
185 * Returns description of method result value
186 * @return external_description
187 */
188 public static function role_assign_returns() {
df997f84 189 return null;
e9b66095 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(
df997f84 200 'unassignments' => new external_multiple_structure(
e9b66095 201 new external_single_structure(
202 array(
f1c9ff36 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'),
df997f84
PS
205 'contextid' => new external_value(PARAM_INT, 'The context to unassign the user role from'),
206 )
e9b66095 207 )
df997f84 208 )
e9b66095 209 )
df997f84 210 );
e9b66095 211 }
212
213 /**
df997f84 214 * Unassign roles from users
e9b66095 215 *
df997f84 216 * @param array $unassignment An array of unassignment
e9b66095 217 * @return null
218 */
df997f84
PS
219 public static function role_unassign($unassignments) {
220 global $DB;
e9b66095 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
df997f84 224 $params = self::validate_parameters(self::role_unassign_parameters(), array('unassignments'=>$unassignments));
e9b66095 225
226 $transaction = $DB->start_delegated_transaction();
227
df997f84
PS
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']);
e9b66095 231 self::validate_context($context);
232 require_capability('moodle/role:assign', $context);
233
df997f84 234 role_unassign($unassignment['roleid'], $unassignment['userid'], $unassignment['contextid']);
e9b66095 235 }
236
237 $transaction->allow_commit();
e9b66095 238 }
239
240 /**
241 * Returns description of method result value
242 * @return external_description
243 */
244 public static function role_unassign_returns() {
df997f84 245 return null;
e9b66095 246 }
e9b66095 247}