MDL-51615 mod_lti: New Web Service mod_lti_get_tool_launch_data
[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      * Trigger the course module viewed event.
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     }