e5d61d590d30b12afdc3ba2c29ab71fd40cd6799
[moodle.git] / mod / lti / classes / external.php
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/>.
17 /**
18  * External tool module external API
19  *
20  * @package    mod_lti
21  * @category   external
22  * @copyright  2015 Juan Leyva <juan@moodle.com>
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  * @since      Moodle 3.0
25  */
27 defined('MOODLE_INTERNAL') || die;
29 require_once($CFG->libdir . '/externallib.php');
30 require_once($CFG->dirroot . '/mod/lti/lib.php');
31 require_once($CFG->dirroot . '/mod/lti/locallib.php');
33 /**
34  * External tool module external functions
35  *
36  * @package    mod_lti
37  * @category   external
38  * @copyright  2015 Juan Leyva <juan@moodle.com>
39  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
40  * @since      Moodle 3.0
41  */
42 class mod_lti_external extends external_api {
44     /**
45      * Returns description of method parameters
46      *
47      * @return external_function_parameters
48      * @since Moodle 3.0
49      */
50     public static function get_tool_launch_data_parameters() {
51         return new external_function_parameters(
52             array(
53                 'toolid' => new external_value(PARAM_INT, 'external tool instance id')
54             )
55         );
56     }
58     /**
59      * Return the launch data for a given external tool.
60      *
61      * @param int $toolid the external tool instance id
62      * @return array of warnings and launch data
63      * @since Moodle 3.0
64      * @throws moodle_exception
65      */
66     public static function get_tool_launch_data($toolid) {
67         global $DB, $CFG;
68         require_once($CFG->dirroot . '/mod/lti/lib.php');
70         $params = self::validate_parameters(self::get_tool_launch_data_parameters(),
71                                             array(
72                                                 'toolid' => $toolid
73                                             ));
74         $warnings = array();
76         // Request and permission validation.
77         $lti = $DB->get_record('lti', array('id' => $params['toolid']), '*', MUST_EXIST);
78         list($course, $cm) = get_course_and_cm_from_instance($lti, 'lti');
80         $context = context_module::instance($cm->id);
81         self::validate_context($context);
83         require_capability('mod/lti:view', $context);
85         $lti->cmid = $cm->id;
86         list($endpoint, $parms) = lti_get_launch_data($lti);
88         $parameters = array();
89         foreach ($parms as $name => $value) {
90             $parameters[] = array(
91                 'name' => $name,
92                 'value' => $value
93             );
94         }
96         $result = array();
97         $result['endpoint'] = $endpoint;
98         $result['parameters'] = $parameters;
99         $result['warnings'] = $warnings;
100         return $result;
101     }
103     /**
104      * Returns description of method result value
105      *
106      * @return external_description
107      * @since Moodle 3.0
108      */
109     public static function get_tool_launch_data_returns() {
110         return new external_single_structure(
111             array(
112                 'endpoint' => new external_value(PARAM_RAW, 'Endpoint URL'), // Using PARAM_RAW as is defined in the module.
113                 'parameters' => new external_multiple_structure(
114                     new external_single_structure(
115                         array(
116                             'name' => new external_value(PARAM_NOTAGS, 'Parameter name'),
117                             'value' => new external_value(PARAM_RAW, 'Parameter value')
118                         )
119                     )
120                 ),
121                 'warnings' => new external_warnings()
122             )
123         );
124     }
126     /**
127      * Describes the parameters for get_ltis_by_courses.
128      *
129      * @return external_function_parameters
130      * @since Moodle 3.0
131      */
132     public static function get_ltis_by_courses_parameters() {
133         return new external_function_parameters (
134             array(
135                 'courseids' => new external_multiple_structure(
136                     new external_value(PARAM_INT, 'course id'), 'Array of course ids', VALUE_DEFAULT, array()
137                 ),
138             )
139         );
140     }
142     /**
143      * Returns a list of external tools in a provided list of courses,
144      * if no list is provided all external tools that the user can view will be returned.
145      *
146      * @param array $courseids the course ids
147      * @return array the lti details
148      * @since Moodle 3.0
149      */
150     public static function get_ltis_by_courses($courseids = array()) {
151         global $CFG;
153         $returnedltis = array();
154         $warnings = array();
156         $params = self::validate_parameters(self::get_ltis_by_courses_parameters(), array('courseids' => $courseids));
158         if (empty($params['courseids'])) {
159             $params['courseids'] = array_keys(enrol_get_my_courses());
160         }
162         // Ensure there are courseids to loop through.
163         if (!empty($params['courseids'])) {
165             list($courses, $warnings) = external_util::validate_courses($params['courseids']);
167             // Get the ltis in this course, this function checks users visibility permissions.
168             // We can avoid then additional validate_context calls.
169             $ltis = get_all_instances_in_courses("lti", $courses);
171             foreach ($ltis as $lti) {
173                 $context = context_module::instance($lti->coursemodule);
175                 // Entry to return.
176                 $module = array();
178                 // First, we return information that any user can see in (or can deduce from) the web interface.
179                 $module['id'] = $lti->id;
180                 $module['coursemodule'] = $lti->coursemodule;
181                 $module['course'] = $lti->course;
182                 $module['name']  = external_format_string($lti->name, $context->id);
184                 $viewablefields = [];
185                 if (has_capability('mod/lti:view', $context)) {
186                     list($module['intro'], $module['introformat']) =
187                         external_format_text($lti->intro, $lti->introformat, $context->id, 'mod_lti', 'intro', $lti->id);
189                     $viewablefields = array('launchcontainer', 'showtitlelaunch', 'showdescriptionlaunch', 'icon', 'secureicon');
190                 }
192                 // Check additional permissions for returning optional private settings.
193                 if (has_capability('moodle/course:manageactivities', $context)) {
195                     $additionalfields = array('timecreated', 'timemodified', 'typeid', 'toolurl', 'securetoolurl',
196                         'instructorchoicesendname', 'instructorchoicesendemailaddr', 'instructorchoiceallowroster',
197                         'instructorchoiceallowsetting', 'instructorcustomparameters', 'instructorchoiceacceptgrades', 'grade',
198                         'resourcekey', 'password', 'debuglaunch', 'servicesalt', 'visible', 'groupmode', 'groupingid');
199                     $viewablefields = array_merge($viewablefields, $additionalfields);
201                 }
203                 foreach ($viewablefields as $field) {
204                     $module[$field] = $lti->{$field};
205                 }
207                 $returnedltis[] = $module;
208             }
209         }
211         $result = array();
212         $result['ltis'] = $returnedltis;
213         $result['warnings'] = $warnings;
214         return $result;
215     }
217     /**
218      * Describes the get_ltis_by_courses return value.
219      *
220      * @return external_single_structure
221      * @since Moodle 3.0
222      */
223     public static function get_ltis_by_courses_returns() {
225         return new external_single_structure(
226             array(
227                 'ltis' => new external_multiple_structure(
228                     new external_single_structure(
229                         array(
230                             'id' => new external_value(PARAM_INT, 'External tool id'),
231                             'coursemodule' => new external_value(PARAM_INT, 'Course module id'),
232                             'course' => new external_value(PARAM_INT, 'Course id'),
233                             'name' => new external_value(PARAM_RAW, 'LTI name'),
234                             'intro' => new external_value(PARAM_RAW, 'The LTI intro', VALUE_OPTIONAL),
235                             'introformat' => new external_format_value('intro', VALUE_OPTIONAL),
236                             'timecreated' => new external_value(PARAM_INT, 'Time of creation', VALUE_OPTIONAL),
237                             'timemodified' => new external_value(PARAM_INT, 'Time of last modification', VALUE_OPTIONAL),
238                             'typeid' => new external_value(PARAM_INT, 'Type id', VALUE_OPTIONAL),
239                             'toolurl' => new external_value(PARAM_URL, 'Tool url', VALUE_OPTIONAL),
240                             'securetoolurl' => new external_value(PARAM_RAW, 'Secure tool url', VALUE_OPTIONAL),
241                             'instructorchoicesendname' => new external_value(PARAM_TEXT, 'Instructor choice send name',
242                                                                                VALUE_OPTIONAL),
243                             'instructorchoicesendemailaddr' => new external_value(PARAM_INT, 'instructor choice send mail address',
244                                                                                     VALUE_OPTIONAL),
245                             'instructorchoiceallowroster' => new external_value(PARAM_INT, 'Instructor choice allow roster',
246                                                                                 VALUE_OPTIONAL),
247                             'instructorchoiceallowsetting' => new external_value(PARAM_INT, 'Instructor choice allow setting',
248                                                                                  VALUE_OPTIONAL),
249                             'instructorcustomparameters' => new external_value(PARAM_RAW, 'instructor custom parameters',
250                                                                                 VALUE_OPTIONAL),
251                             'instructorchoiceacceptgrades' => new external_value(PARAM_INT, 'instructor choice accept grades',
252                                                                                     VALUE_OPTIONAL),
253                             'grade' => new external_value(PARAM_INT, 'Enable grades', VALUE_OPTIONAL),
254                             'launchcontainer' => new external_value(PARAM_INT, 'Launch container mode', VALUE_OPTIONAL),
255                             'resourcekey' => new external_value(PARAM_RAW, 'Resource key', VALUE_OPTIONAL),
256                             'password' => new external_value(PARAM_RAW, 'Shared secret', VALUE_OPTIONAL),
257                             'debuglaunch' => new external_value(PARAM_INT, 'Debug launch', VALUE_OPTIONAL),
258                             'showtitlelaunch' => new external_value(PARAM_INT, 'Show title launch', VALUE_OPTIONAL),
259                             'showdescriptionlaunch' => new external_value(PARAM_INT, 'Show description launch', VALUE_OPTIONAL),
260                             'servicesalt' => new external_value(PARAM_RAW, 'Service salt', VALUE_OPTIONAL),
261                             'icon' => new external_value(PARAM_URL, 'Alternative icon URL', VALUE_OPTIONAL),
262                             'secureicon' => new external_value(PARAM_URL, 'Secure icon URL', VALUE_OPTIONAL),
263                             'section' => new external_value(PARAM_INT, 'course section id', VALUE_OPTIONAL),
264                             'visible' => new external_value(PARAM_INT, 'visible', VALUE_OPTIONAL),
265                             'groupmode' => new external_value(PARAM_INT, 'group mode', VALUE_OPTIONAL),
266                             'groupingid' => new external_value(PARAM_INT, 'group id', VALUE_OPTIONAL),
267                         ), 'Tool'
268                     )
269                 ),
270                 'warnings' => new external_warnings(),
271             )
272         );
273     }
275     /**
276      * Returns description of method parameters
277      *
278      * @return external_function_parameters
279      * @since Moodle 3.0
280      */
281     public static function view_lti_parameters() {
282         return new external_function_parameters(
283             array(
284                 'ltiid' => new external_value(PARAM_INT, 'lti instance id')
285             )
286         );
287     }
289     /**
290      * Trigger the course module viewed event and update the module completion status.
291      *
292      * @param int $ltiid the lti instance id
293      * @return array of warnings and status result
294      * @since Moodle 3.0
295      * @throws moodle_exception
296      */
297     public static function view_lti($ltiid) {
298         global $DB;
300         $params = self::validate_parameters(self::view_lti_parameters(),
301                                             array(
302                                                 'ltiid' => $ltiid
303                                             ));
304         $warnings = array();
306         // Request and permission validation.
307         $lti = $DB->get_record('lti', array('id' => $params['ltiid']), '*', MUST_EXIST);
308         list($course, $cm) = get_course_and_cm_from_instance($lti, 'lti');
310         $context = context_module::instance($cm->id);
311         self::validate_context($context);
312         require_capability('mod/lti:view', $context);
314         // Trigger course_module_viewed event and completion.
315         lti_view($lti, $course, $cm, $context);
317         $result = array();
318         $result['status'] = true;
319         $result['warnings'] = $warnings;
320         return $result;
321     }
323     /**
324      * Returns description of method result value
325      *
326      * @return external_description
327      * @since Moodle 3.0
328      */
329     public static function view_lti_returns() {
330         return new external_single_structure(
331             array(
332                 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
333                 'warnings' => new external_warnings()
334             )
335         );
336     }