on-demand release 2.4dev
[moodle.git] / mod / assign / externallib.php
CommitLineData
1f8c8f61
PC
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 * External assign API
19 *
20 * @package mod_assign
21 * @since Moodle 2.4
22 * @copyright 2012 Paul Charsley
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24 */
25
26defined('MOODLE_INTERNAL') || die;
27
28require_once("$CFG->libdir/externallib.php");
29
30/**
31 * Assign functions
32 */
33class mod_assign_external extends external_api {
34
35 /**
36 * Describes the parameters for get_grades
37 * @return external_external_function_parameters
38 * @since Moodle 2.4
39 */
40 public static function get_grades_parameters() {
41 return new external_function_parameters(
42 array(
43 'assignmentids' => new external_multiple_structure(
44 new external_value(PARAM_INT, 'assignment id'),
45 '1 or more assignment ids',
46 VALUE_REQUIRED),
47 'since' => new external_value(PARAM_INT,
48 'timestamp, only return records where timemodified >= since',
49 VALUE_DEFAULT, 0)
50 )
51 );
52 }
53
54 /**
55 * Returns grade information from assign_grades for the requested assignment ids
56 * @param array of ints $assignmentids
57 * @param int $since only return records with timemodified >= since
58 * @return array of grade records for each requested assignment
59 * @since Moodle 2.4
60 */
61 public static function get_grades($assignmentids, $since = 0) {
62 global $DB;
63 $params = self::validate_parameters(self::get_grades_parameters(),
64 array('assignmentids' => $assignmentids,
65 'since' => $since));
66
67 $assignments = array();
68 $warnings = array();
69 $requestedassignmentids = $params['assignmentids'];
70
71 // Check the user is allowed to get the grades for the assignments requested.
72 $placeholders = array();
73 list($sqlassignmentids, $placeholders) = $DB->get_in_or_equal($requestedassignmentids, SQL_PARAMS_NAMED);
74 $sql = "SELECT cm.id, cm.instance FROM {course_modules} cm JOIN {modules} md ON md.id = cm.module ".
75 "WHERE md.name = :modname AND cm.instance ".$sqlassignmentids;
76 $placeholders['modname'] = 'assign';
77 $cms = $DB->get_records_sql($sql, $placeholders);
78 foreach ($cms as $cm) {
79 try {
80 $context = context_module::instance($cm->id);
81 self::validate_context($context);
82 require_capability('mod/assign:grade', $context);
83 } catch (Exception $e) {
84 $requestedassignmentids = array_diff($requestedassignmentids, array($cm->instance));
85 $warning = array();
86 $warning['item'] = 'assignment';
87 $warning['itemid'] = $cm->instance;
88 $warning['warningcode'] = '1';
89 $warning['message'] = 'No access rights in module context';
90 $warnings[] = $warning;
91 }
92 }
93
94 // Create the query and populate an array of grade records from the recordset results.
95 if (count ($requestedassignmentids) > 0) {
96 $placeholders = array();
97 list($inorequalsql, $placeholders) = $DB->get_in_or_equal($requestedassignmentids, SQL_PARAMS_NAMED);
98 $sql = "SELECT ag.id,ag.assignment,ag.userid,ag.timecreated,ag.timemodified,".
99 "ag.grader,ag.grade,ag.locked,ag.mailed ".
100 "FROM {assign_grades} ag ".
101 "WHERE ag.assignment ".$inorequalsql.
102 " AND ag.timemodified >= :since".
103 " ORDER BY ag.assignment, ag.id";
104 $placeholders['since'] = $params['since'];
105 $rs = $DB->get_recordset_sql($sql, $placeholders);
106 $currentassignmentid = null;
107 $assignment = null;
108 foreach ($rs as $rd) {
109 $grade = array();
110 $grade['id'] = $rd->id;
111 $grade['userid'] = $rd->userid;
112 $grade['timecreated'] = $rd->timecreated;
113 $grade['timemodified'] = $rd->timemodified;
114 $grade['grader'] = $rd->grader;
115 $grade['grade'] = (string)$rd->grade;
116 $grade['locked'] = $rd->locked;
117 $grade['mailed'] = $rd->mailed;
118
119 if (is_null($currentassignmentid) || ($rd->assignment != $currentassignmentid )) {
120 if (!is_null($assignment)) {
121 $assignments[] = $assignment;
122 }
123 $assignment = array();
124 $assignment['assignmentid'] = $rd->assignment;
125 $assignment['grades'] = array();
126 $requestedassignmentids = array_diff($requestedassignmentids, array($rd->assignment));
127 }
128 $assignment['grades'][] = $grade;
129
130 $currentassignmentid = $rd->assignment;
131 }
132 if (!is_null($assignment)) {
133 $assignments[] = $assignment;
134 }
135 $rs->close();
136 }
137 foreach ($requestedassignmentids as $assignmentid) {
138 $warning = array();
139 $warning['item'] = 'assignment';
140 $warning['itemid'] = $assignmentid;
141 $warning['warningcode'] = '3';
142 $warning['message'] = 'No grades found';
143 $warnings[] = $warning;
144 }
145
146 $result = array();
147 $result['assignments'] = $assignments;
148 $result['warnings'] = $warnings;
149 return $result;
150 }
151
152 /**
153 * Creates an assign_grades external_single_structure
154 * @return external_single_structure
155 * @since Moodle 2.4
156 */
157 private static function assign_grades() {
158 return new external_single_structure(
159 array (
160 'assignmentid' => new external_value(PARAM_INT, 'assignment id'),
161 'grades' => new external_multiple_structure(new external_single_structure(
162 array(
163 'id' => new external_value(PARAM_INT, 'grade id'),
164 'userid' => new external_value(PARAM_INT, 'student id'),
165 'timecreated' => new external_value(PARAM_INT, 'grade creation time'),
166 'timemodified' => new external_value(PARAM_INT, 'grade last modified time'),
167 'grader' => new external_value(PARAM_INT, 'grader'),
168 'grade' => new external_value(PARAM_TEXT, 'grade'),
169 'locked' => new external_value(PARAM_BOOL, 'locked'),
170 'mailed' => new external_value(PARAM_BOOL, 'mailed')
171 )
172 )
173 )
174 )
175 );
176 }
177
178 /**
179 * Describes the get_grades return value
180 * @return external_single_structure
181 * @since Moodle 2.4
182 */
183 public static function get_grades_returns() {
184 return new external_single_structure(
185 array(
186 'assignments' => new external_multiple_structure(self::assign_grades(), 'list of assignment grade information'),
187 'warnings' => new external_warnings()
188 )
189 );
190 }
191
192}