MDL-56019 ws: Use itemid null when getting modules intro
[moodle.git] / mod / lti / classes / external.php
CommitLineData
ae67efa8
JL
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 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 */
26
27defined('MOODLE_INTERNAL') || die;
28
29require_once($CFG->libdir . '/externallib.php');
30require_once($CFG->dirroot . '/mod/lti/lib.php');
31require_once($CFG->dirroot . '/mod/lti/locallib.php');
32
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 */
42class mod_lti_external extends external_api {
43
cc193e0d 44 /**
811d9ff9 45 * Returns structure be used for returning a tool type from a web service.
cc193e0d
RW
46 *
47 * @return external_function_parameters
48 * @since Moodle 3.1
49 */
811d9ff9 50 private static function tool_type_return_structure() {
cc193e0d
RW
51 return new external_single_structure(
52 array(
53 'id' => new external_value(PARAM_INT, 'Tool type id'),
5c1b749d
JP
54 'name' => new external_value(PARAM_NOTAGS, 'Tool type name'),
55 'description' => new external_value(PARAM_NOTAGS, 'Tool type description'),
cc193e0d
RW
56 'urls' => new external_single_structure(
57 array(
58 'icon' => new external_value(PARAM_URL, 'Tool type icon URL'),
59 'edit' => new external_value(PARAM_URL, 'Tool type edit URL'),
60 'course' => new external_value(PARAM_URL, 'Tool type edit URL', VALUE_OPTIONAL),
61 )
62 ),
63 'state' => new external_single_structure(
64 array(
65 'text' => new external_value(PARAM_TEXT, 'Tool type state name string'),
66 'pending' => new external_value(PARAM_BOOL, 'Is the state pending'),
67 'configured' => new external_value(PARAM_BOOL, 'Is the state configured'),
68 'rejected' => new external_value(PARAM_BOOL, 'Is the state rejected'),
cc193e0d
RW
69 'unknown' => new external_value(PARAM_BOOL, 'Is the state unknown'),
70 )
71 ),
72 'hascapabilitygroups' => new external_value(PARAM_BOOL, 'Indicate if capabilitygroups is populated'),
73 'capabilitygroups' => new external_multiple_structure(
74 new external_value(PARAM_TEXT, 'Tool type capability groups enabled'),
75 'Array of capability groups', VALUE_DEFAULT, array()
76 ),
77 'courseid' => new external_value(PARAM_INT, 'Tool type course', VALUE_DEFAULT, 0),
78 'instanceids' => new external_multiple_structure(
79 new external_value(PARAM_INT, 'LTI instance ID'),
80 'IDs for the LTI instances using this type', VALUE_DEFAULT, array()
81 ),
82 'instancecount' => new external_value(PARAM_INT, 'The number of times this tool is being used')
83 ), 'Tool'
84 );
85 }
86
87 /**
88 * Returns description of a tool proxy
89 *
90 * @return external_function_parameters
91 * @since Moodle 3.1
92 */
811d9ff9 93 private static function tool_proxy_return_structure() {
cc193e0d
RW
94 return new external_function_parameters(
95 array(
96 'id' => new external_value(PARAM_INT, 'Tool proxy id'),
97 'name' => new external_value(PARAM_TEXT, 'Tool proxy name'),
98 'regurl' => new external_value(PARAM_URL, 'Tool proxy registration URL'),
99 'state' => new external_value(PARAM_INT, 'Tool proxy state'),
100 'guid' => new external_value(PARAM_TEXT, 'Tool proxy globally unique identifier'),
101 'secret' => new external_value(PARAM_TEXT, 'Tool proxy shared secret'),
102 'vendorcode' => new external_value(PARAM_TEXT, 'Tool proxy consumer code'),
103 'capabilityoffered' => new external_value(PARAM_TEXT, 'Tool proxy capabilities offered'),
104 'serviceoffered' => new external_value(PARAM_TEXT, 'Tool proxy services offered'),
105 'toolproxy' => new external_value(PARAM_TEXT, 'Tool proxy'),
106 'timecreated' => new external_value(PARAM_INT, 'Tool proxy time created'),
107 'timemodified' => new external_value(PARAM_INT, 'Tool proxy modified'),
108 )
109 );
110 }
111
ae67efa8
JL
112 /**
113 * Returns description of method parameters
114 *
115 * @return external_function_parameters
811d9ff9
JO
116 * @since Moodle 3.1
117 */
118 public static function get_tool_proxies_parameters() {
119 return new external_function_parameters(
120 array(
121 'orphanedonly' => new external_value(PARAM_BOOL, 'Orphaned tool types only', VALUE_DEFAULT, 0)
122 )
123 );
124 }
125
126 /**
127 * Returns the tool types.
128 *
129 * @param bool $orphanedonly Retrieve only tool proxies that do not have a corresponding tool type
130 * @return array of tool types
131 * @since Moodle 3.1
132 * @throws moodle_exception
133 */
134 public static function get_tool_proxies($orphanedonly) {
135 global $PAGE;
136 $params = self::validate_parameters(self::get_tool_proxies_parameters(),
137 array(
138 'orphanedonly' => $orphanedonly
139 ));
140 $orphanedonly = $params['orphanedonly'];
141
142 $proxies = array();
143 $context = context_system::instance();
144
145 self::validate_context($context);
146 require_capability('moodle/site:config', $context);
147
148 $proxies = lti_get_tool_proxies($orphanedonly);
149
150 return array_map('serialise_tool_proxy', $proxies);
151 }
152
153 /**
154 * Returns description of method result value.
155 *
156 * @return external_description
157 * @since Moodle 3.1
158 */
159 public static function get_tool_proxies_returns() {
160 return new external_multiple_structure(
161 self::tool_type_return_structure()
162 );
163 }
164
165 /**
166 * Returns description of method parameters.
167 *
168 * @return external_function_parameters
ae67efa8
JL
169 * @since Moodle 3.0
170 */
171 public static function get_tool_launch_data_parameters() {
172 return new external_function_parameters(
173 array(
174 'toolid' => new external_value(PARAM_INT, 'external tool instance id')
175 )
176 );
177 }
178
179 /**
180 * Return the launch data for a given external tool.
181 *
182 * @param int $toolid the external tool instance id
183 * @return array of warnings and launch data
184 * @since Moodle 3.0
185 * @throws moodle_exception
186 */
187 public static function get_tool_launch_data($toolid) {
188 global $DB, $CFG;
189 require_once($CFG->dirroot . '/mod/lti/lib.php');
190
191 $params = self::validate_parameters(self::get_tool_launch_data_parameters(),
192 array(
193 'toolid' => $toolid
194 ));
195 $warnings = array();
196
197 // Request and permission validation.
198 $lti = $DB->get_record('lti', array('id' => $params['toolid']), '*', MUST_EXIST);
199 list($course, $cm) = get_course_and_cm_from_instance($lti, 'lti');
200
201 $context = context_module::instance($cm->id);
202 self::validate_context($context);
203
204 require_capability('mod/lti:view', $context);
205
206 $lti->cmid = $cm->id;
207 list($endpoint, $parms) = lti_get_launch_data($lti);
208
209 $parameters = array();
210 foreach ($parms as $name => $value) {
211 $parameters[] = array(
212 'name' => $name,
213 'value' => $value
214 );
215 }
216
217 $result = array();
218 $result['endpoint'] = $endpoint;
219 $result['parameters'] = $parameters;
220 $result['warnings'] = $warnings;
221 return $result;
222 }
223
224 /**
225 * Returns description of method result value
226 *
227 * @return external_description
228 * @since Moodle 3.0
229 */
230 public static function get_tool_launch_data_returns() {
231 return new external_single_structure(
232 array(
233 'endpoint' => new external_value(PARAM_RAW, 'Endpoint URL'), // Using PARAM_RAW as is defined in the module.
234 'parameters' => new external_multiple_structure(
235 new external_single_structure(
236 array(
237 'name' => new external_value(PARAM_NOTAGS, 'Parameter name'),
238 'value' => new external_value(PARAM_RAW, 'Parameter value')
239 )
240 )
241 ),
242 'warnings' => new external_warnings()
243 )
244 );
245 }
dfcdec12
JL
246
247 /**
248 * Describes the parameters for get_ltis_by_courses.
249 *
250 * @return external_function_parameters
251 * @since Moodle 3.0
252 */
253 public static function get_ltis_by_courses_parameters() {
254 return new external_function_parameters (
255 array(
256 'courseids' => new external_multiple_structure(
257 new external_value(PARAM_INT, 'course id'), 'Array of course ids', VALUE_DEFAULT, array()
258 ),
259 )
260 );
261 }
262
263 /**
264 * Returns a list of external tools in a provided list of courses,
265 * if no list is provided all external tools that the user can view will be returned.
266 *
267 * @param array $courseids the course ids
268 * @return array the lti details
269 * @since Moodle 3.0
270 */
271 public static function get_ltis_by_courses($courseids = array()) {
272 global $CFG;
273
274 $returnedltis = array();
275 $warnings = array();
276
277 $params = self::validate_parameters(self::get_ltis_by_courses_parameters(), array('courseids' => $courseids));
278
052da730 279 $mycourses = array();
dfcdec12 280 if (empty($params['courseids'])) {
052da730
DP
281 $mycourses = enrol_get_my_courses();
282 $params['courseids'] = array_keys($mycourses);
dfcdec12
JL
283 }
284
285 // Ensure there are courseids to loop through.
286 if (!empty($params['courseids'])) {
287
052da730 288 list($courses, $warnings) = external_util::validate_courses($params['courseids'], $mycourses);
dfcdec12
JL
289
290 // Get the ltis in this course, this function checks users visibility permissions.
291 // We can avoid then additional validate_context calls.
292 $ltis = get_all_instances_in_courses("lti", $courses);
293
294 foreach ($ltis as $lti) {
295
296 $context = context_module::instance($lti->coursemodule);
297
298 // Entry to return.
299 $module = array();
300
301 // First, we return information that any user can see in (or can deduce from) the web interface.
302 $module['id'] = $lti->id;
303 $module['coursemodule'] = $lti->coursemodule;
304 $module['course'] = $lti->course;
305 $module['name'] = external_format_string($lti->name, $context->id);
306
307 $viewablefields = [];
308 if (has_capability('mod/lti:view', $context)) {
309 list($module['intro'], $module['introformat']) =
d33c67bc 310 external_format_text($lti->intro, $lti->introformat, $context->id, 'mod_lti', 'intro', null);
dfcdec12 311
7ef49bd3 312 $module['introfiles'] = external_util::get_area_files($context->id, 'mod_lti', 'intro', false, false);
dfcdec12
JL
313 $viewablefields = array('launchcontainer', 'showtitlelaunch', 'showdescriptionlaunch', 'icon', 'secureicon');
314 }
315
316 // Check additional permissions for returning optional private settings.
317 if (has_capability('moodle/course:manageactivities', $context)) {
318
319 $additionalfields = array('timecreated', 'timemodified', 'typeid', 'toolurl', 'securetoolurl',
320 'instructorchoicesendname', 'instructorchoicesendemailaddr', 'instructorchoiceallowroster',
321 'instructorchoiceallowsetting', 'instructorcustomparameters', 'instructorchoiceacceptgrades', 'grade',
322 'resourcekey', 'password', 'debuglaunch', 'servicesalt', 'visible', 'groupmode', 'groupingid');
323 $viewablefields = array_merge($viewablefields, $additionalfields);
324
325 }
326
327 foreach ($viewablefields as $field) {
328 $module[$field] = $lti->{$field};
329 }
330
331 $returnedltis[] = $module;
332 }
333 }
334
335 $result = array();
336 $result['ltis'] = $returnedltis;
337 $result['warnings'] = $warnings;
338 return $result;
339 }
340
341 /**
342 * Describes the get_ltis_by_courses return value.
343 *
344 * @return external_single_structure
345 * @since Moodle 3.0
346 */
347 public static function get_ltis_by_courses_returns() {
348
349 return new external_single_structure(
350 array(
351 'ltis' => new external_multiple_structure(
352 new external_single_structure(
353 array(
354 'id' => new external_value(PARAM_INT, 'External tool id'),
355 'coursemodule' => new external_value(PARAM_INT, 'Course module id'),
356 'course' => new external_value(PARAM_INT, 'Course id'),
357 'name' => new external_value(PARAM_RAW, 'LTI name'),
358 'intro' => new external_value(PARAM_RAW, 'The LTI intro', VALUE_OPTIONAL),
359 'introformat' => new external_format_value('intro', VALUE_OPTIONAL),
7ef49bd3 360 'introfiles' => new external_files('Files in the introduction text', VALUE_OPTIONAL),
dfcdec12
JL
361 'timecreated' => new external_value(PARAM_INT, 'Time of creation', VALUE_OPTIONAL),
362 'timemodified' => new external_value(PARAM_INT, 'Time of last modification', VALUE_OPTIONAL),
363 'typeid' => new external_value(PARAM_INT, 'Type id', VALUE_OPTIONAL),
364 'toolurl' => new external_value(PARAM_URL, 'Tool url', VALUE_OPTIONAL),
365 'securetoolurl' => new external_value(PARAM_RAW, 'Secure tool url', VALUE_OPTIONAL),
366 'instructorchoicesendname' => new external_value(PARAM_TEXT, 'Instructor choice send name',
367 VALUE_OPTIONAL),
368 'instructorchoicesendemailaddr' => new external_value(PARAM_INT, 'instructor choice send mail address',
369 VALUE_OPTIONAL),
370 'instructorchoiceallowroster' => new external_value(PARAM_INT, 'Instructor choice allow roster',
371 VALUE_OPTIONAL),
372 'instructorchoiceallowsetting' => new external_value(PARAM_INT, 'Instructor choice allow setting',
373 VALUE_OPTIONAL),
374 'instructorcustomparameters' => new external_value(PARAM_RAW, 'instructor custom parameters',
375 VALUE_OPTIONAL),
376 'instructorchoiceacceptgrades' => new external_value(PARAM_INT, 'instructor choice accept grades',
377 VALUE_OPTIONAL),
378 'grade' => new external_value(PARAM_INT, 'Enable grades', VALUE_OPTIONAL),
379 'launchcontainer' => new external_value(PARAM_INT, 'Launch container mode', VALUE_OPTIONAL),
380 'resourcekey' => new external_value(PARAM_RAW, 'Resource key', VALUE_OPTIONAL),
381 'password' => new external_value(PARAM_RAW, 'Shared secret', VALUE_OPTIONAL),
382 'debuglaunch' => new external_value(PARAM_INT, 'Debug launch', VALUE_OPTIONAL),
383 'showtitlelaunch' => new external_value(PARAM_INT, 'Show title launch', VALUE_OPTIONAL),
384 'showdescriptionlaunch' => new external_value(PARAM_INT, 'Show description launch', VALUE_OPTIONAL),
385 'servicesalt' => new external_value(PARAM_RAW, 'Service salt', VALUE_OPTIONAL),
386 'icon' => new external_value(PARAM_URL, 'Alternative icon URL', VALUE_OPTIONAL),
387 'secureicon' => new external_value(PARAM_URL, 'Secure icon URL', VALUE_OPTIONAL),
388 'section' => new external_value(PARAM_INT, 'course section id', VALUE_OPTIONAL),
389 'visible' => new external_value(PARAM_INT, 'visible', VALUE_OPTIONAL),
390 'groupmode' => new external_value(PARAM_INT, 'group mode', VALUE_OPTIONAL),
391 'groupingid' => new external_value(PARAM_INT, 'group id', VALUE_OPTIONAL),
392 ), 'Tool'
393 )
394 ),
395 'warnings' => new external_warnings(),
396 )
397 );
398 }
4bed1682
JL
399
400 /**
401 * Returns description of method parameters
402 *
403 * @return external_function_parameters
404 * @since Moodle 3.0
405 */
406 public static function view_lti_parameters() {
407 return new external_function_parameters(
408 array(
409 'ltiid' => new external_value(PARAM_INT, 'lti instance id')
410 )
411 );
412 }
413
414 /**
415 * Trigger the course module viewed event and update the module completion status.
416 *
417 * @param int $ltiid the lti instance id
418 * @return array of warnings and status result
419 * @since Moodle 3.0
420 * @throws moodle_exception
421 */
422 public static function view_lti($ltiid) {
423 global $DB;
424
425 $params = self::validate_parameters(self::view_lti_parameters(),
426 array(
427 'ltiid' => $ltiid
428 ));
429 $warnings = array();
430
431 // Request and permission validation.
432 $lti = $DB->get_record('lti', array('id' => $params['ltiid']), '*', MUST_EXIST);
433 list($course, $cm) = get_course_and_cm_from_instance($lti, 'lti');
434
435 $context = context_module::instance($cm->id);
436 self::validate_context($context);
437 require_capability('mod/lti:view', $context);
438
439 // Trigger course_module_viewed event and completion.
440 lti_view($lti, $course, $cm, $context);
441
442 $result = array();
443 $result['status'] = true;
444 $result['warnings'] = $warnings;
445 return $result;
446 }
447
448 /**
449 * Returns description of method result value
450 *
451 * @return external_description
452 * @since Moodle 3.0
453 */
454 public static function view_lti_returns() {
455 return new external_single_structure(
456 array(
457 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
458 'warnings' => new external_warnings()
459 )
460 );
461 }
cc193e0d
RW
462
463 /**
464 * Returns description of method parameters
465 *
466 * @return external_function_parameters
af9d3a92 467 * @since Moodle 3.1
cc193e0d
RW
468 */
469 public static function create_tool_proxy_parameters() {
470 return new external_function_parameters(
471 array(
472 'name' => new external_value(PARAM_TEXT, 'Tool proxy name', VALUE_DEFAULT, ''),
473 'regurl' => new external_value(PARAM_URL, 'Tool proxy registration URL'),
474 'capabilityoffered' => new external_multiple_structure(
475 new external_value(PARAM_TEXT, 'Tool proxy capabilities offered'),
476 'Array of capabilities', VALUE_DEFAULT, array()
477 ),
478 'serviceoffered' => new external_multiple_structure(
479 new external_value(PARAM_TEXT, 'Tool proxy services offered'),
480 'Array of services', VALUE_DEFAULT, array()
481 )
482 )
483 );
484 }
485
486 /**
af9d3a92 487 * Creates a new tool proxy
cc193e0d 488 *
af9d3a92
JO
489 * @param string $name Tool proxy name
490 * @param string $registrationurl Registration url
491 * @param string[] $capabilityoffered List of capabilities this tool proxy should be offered
492 * @param string[] $serviceoffered List of services this tool proxy should be offered
493 * @return object The new tool proxy
494 * @since Moodle 3.1
cc193e0d
RW
495 * @throws moodle_exception
496 */
497 public static function create_tool_proxy($name, $registrationurl, $capabilityoffered, $serviceoffered) {
498 $params = self::validate_parameters(self::create_tool_proxy_parameters(),
499 array(
500 'name' => $name,
501 'regurl' => $registrationurl,
502 'capabilityoffered' => $capabilityoffered,
503 'serviceoffered' => $serviceoffered
504 ));
af9d3a92
JO
505 $name = $params['name'];
506 $regurl = $params['regurl'];
507 $capabilityoffered = $params['capabilityoffered'];
508 $serviceoffered = $params['serviceoffered'];
cc193e0d
RW
509
510 $context = context_system::instance();
511 self::validate_context($context);
af9d3a92 512 require_capability('moodle/site:config', $context);
cc193e0d
RW
513
514 // Can't create duplicate proxies with the same URL.
af9d3a92
JO
515 $duplicates = lti_get_tool_proxies_from_registration_url($registrationurl);
516 if (!empty($duplicates)) {
517 throw new moodle_exception('duplicateregurl', 'mod_lti');
cc193e0d
RW
518 }
519
520 $config = new stdClass();
521 $config->lti_registrationurl = $registrationurl;
522
523 if (!empty($name)) {
524 $config->lti_registrationname = $name;
525 }
526
527 if (!empty($capabilityoffered)) {
eb55f72d 528 $config->lti_capabilities = $capabilityoffered;
cc193e0d
RW
529 }
530
531 if (!empty($serviceoffered)) {
532 $config->lti_services = $serviceoffered;
533 }
534
535 $id = lti_add_tool_proxy($config);
536 $toolproxy = lti_get_tool_proxy($id);
537
538 // Pending makes more sense than configured as the first state, since
539 // the next step is to register, which requires the state be pending.
540 $toolproxy->state = LTI_TOOL_PROXY_STATE_PENDING;
541 lti_update_tool_proxy($toolproxy);
542
543 return $toolproxy;
544 }
545
546 /**
547 * Returns description of method result value
548 *
549 * @return external_description
af9d3a92 550 * @since Moodle 3.1
cc193e0d
RW
551 */
552 public static function create_tool_proxy_returns() {
811d9ff9 553 return self::tool_proxy_return_structure();
cc193e0d
RW
554 }
555
556 /**
557 * Returns description of method parameters
558 *
559 * @return external_function_parameters
af9d3a92 560 * @since Moodle 3.1
cc193e0d
RW
561 */
562 public static function delete_tool_proxy_parameters() {
563 return new external_function_parameters(
564 array(
565 'id' => new external_value(PARAM_INT, 'Tool proxy id'),
566 )
567 );
568 }
569
570 /**
571 * Trigger the course module viewed event and update the module completion status.
572 *
af9d3a92
JO
573 * @param int $id the lti instance id
574 * @return object The tool proxy
575 * @since Moodle 3.1
cc193e0d
RW
576 * @throws moodle_exception
577 */
578 public static function delete_tool_proxy($id) {
579 $params = self::validate_parameters(self::delete_tool_proxy_parameters(),
580 array(
581 'id' => $id,
582 ));
af9d3a92 583 $id = $params['id'];
cc193e0d
RW
584
585 $context = context_system::instance();
586 self::validate_context($context);
af9d3a92 587 require_capability('moodle/site:config', $context);
cc193e0d
RW
588
589 $toolproxy = lti_get_tool_proxy($id);
590
591 lti_delete_tool_proxy($id);
592
593 return $toolproxy;
594 }
595
596 /**
597 * Returns description of method result value
598 *
599 * @return external_description
af9d3a92 600 * @since Moodle 3.1
cc193e0d
RW
601 */
602 public static function delete_tool_proxy_returns() {
811d9ff9 603 return self::tool_proxy_return_structure();
cc193e0d
RW
604 }
605
606 /**
607 * Returns description of method parameters
608 *
609 * @return external_function_parameters
610 * @since Moodle 3.0
611 */
612 public static function get_tool_proxy_registration_request_parameters() {
613 return new external_function_parameters(
614 array(
615 'id' => new external_value(PARAM_INT, 'Tool proxy id'),
616 )
617 );
618 }
619
620 /**
621 * Returns the registration request for a tool proxy.
622 *
623 * @param int $id the lti instance id
af9d3a92
JO
624 * @return array of registration parameters
625 * @since Moodle 3.1
cc193e0d
RW
626 * @throws moodle_exception
627 */
628 public static function get_tool_proxy_registration_request($id) {
629 $params = self::validate_parameters(self::get_tool_proxy_registration_request_parameters(),
630 array(
631 'id' => $id,
632 ));
af9d3a92 633 $id = $params['id'];
cc193e0d
RW
634
635 $context = context_system::instance();
636 self::validate_context($context);
af9d3a92 637 require_capability('moodle/site:config', $context);
cc193e0d
RW
638
639 $toolproxy = lti_get_tool_proxy($id);
af9d3a92 640 return lti_build_registration_request($toolproxy);
cc193e0d
RW
641 }
642
643 /**
644 * Returns description of method result value
645 *
646 * @return external_description
af9d3a92 647 * @since Moodle 3.1
cc193e0d
RW
648 */
649 public static function get_tool_proxy_registration_request_returns() {
650 return new external_function_parameters(
651 array(
af9d3a92
JO
652 'lti_message_type' => new external_value(PARAM_ALPHANUMEXT, 'LTI message type'),
653 'lti_version' => new external_value(PARAM_ALPHANUMEXT, 'LTI version'),
cc193e0d
RW
654 'reg_key' => new external_value(PARAM_TEXT, 'Tool proxy registration key'),
655 'reg_password' => new external_value(PARAM_TEXT, 'Tool proxy registration password'),
811d9ff9 656 'reg_url' => new external_value(PARAM_TEXT, 'Tool proxy registration url'),
cc193e0d
RW
657 'tc_profile_url' => new external_value(PARAM_URL, 'Tool consumers profile URL'),
658 'launch_presentation_return_url' => new external_value(PARAM_URL, 'URL to redirect on registration completion'),
659 )
660 );
661 }
662
663 /**
664 * Returns description of method parameters
665 *
666 * @return external_function_parameters
af9d3a92 667 * @since Moodle 3.1
cc193e0d
RW
668 */
669 public static function get_tool_types_parameters() {
670 return new external_function_parameters(
671 array(
672 'toolproxyid' => new external_value(PARAM_INT, 'Tool proxy id', VALUE_DEFAULT, 0)
673 )
674 );
675 }
676
677 /**
678 * Returns the tool types.
679 *
af9d3a92 680 * @param int $toolproxyid The tool proxy id
cc193e0d 681 * @return array of tool types
af9d3a92 682 * @since Moodle 3.1
cc193e0d
RW
683 * @throws moodle_exception
684 */
685 public static function get_tool_types($toolproxyid) {
af9d3a92 686 global $PAGE;
cc193e0d
RW
687 $params = self::validate_parameters(self::get_tool_types_parameters(),
688 array(
689 'toolproxyid' => $toolproxyid
690 ));
af9d3a92 691 $toolproxyid = $params['toolproxyid'];
cc193e0d
RW
692
693 $types = array();
694 $context = context_system::instance();
695
696 self::validate_context($context);
af9d3a92 697 require_capability('moodle/site:config', $context);
cc193e0d
RW
698
699 if (!empty($toolproxyid)) {
700 $types = lti_get_lti_types_from_proxy_id($toolproxyid);
701 } else {
702 $types = lti_get_lti_types();
703 }
704
705 return array_map("serialise_tool_type", array_values($types));
706 }
707
708 /**
709 * Returns description of method result value
710 *
711 * @return external_description
af9d3a92 712 * @since Moodle 3.1
cc193e0d
RW
713 */
714 public static function get_tool_types_returns() {
715 return new external_multiple_structure(
811d9ff9 716 self::tool_type_return_structure()
cc193e0d
RW
717 );
718 }
719
720 /**
721 * Returns description of method parameters
722 *
723 * @return external_function_parameters
af9d3a92 724 * @since Moodle 3.1
cc193e0d
RW
725 */
726 public static function create_tool_type_parameters() {
727 return new external_function_parameters(
728 array(
729 'cartridgeurl' => new external_value(PARAM_URL, 'URL to cardridge to load tool information', VALUE_DEFAULT, ''),
730 'key' => new external_value(PARAM_TEXT, 'Consumer key', VALUE_DEFAULT, ''),
731 'secret' => new external_value(PARAM_TEXT, 'Shared secret', VALUE_DEFAULT, ''),
732 )
733 );
734 }
735
736 /**
737 * Creates a tool type.
738 *
af9d3a92
JO
739 * @param string $cartridgeurl Url of the xml cartridge representing the LTI tool
740 * @param string $key The consumer key to identify this consumer
741 * @param string $secret The secret
cc193e0d 742 * @return array created tool type
af9d3a92
JO
743 * @since Moodle 3.1
744 * @throws moodle_exception If the tool type could not be created
cc193e0d
RW
745 */
746 public static function create_tool_type($cartridgeurl, $key, $secret) {
747 $params = self::validate_parameters(self::create_tool_type_parameters(),
748 array(
749 'cartridgeurl' => $cartridgeurl,
750 'key' => $key,
751 'secret' => $secret
752 ));
af9d3a92
JO
753 $cartridgeurl = $params['cartridgeurl'];
754 $key = $params['key'];
755 $secret = $params['secret'];
cc193e0d
RW
756
757 $context = context_system::instance();
758 self::validate_context($context);
af9d3a92 759 require_capability('moodle/site:config', $context);
cc193e0d
RW
760
761 $id = null;
762
763 if (!empty($cartridgeurl)) {
764 $type = new stdClass();
765 $data = new stdClass();
766 $type->state = LTI_TOOL_STATE_CONFIGURED;
767 $data->lti_coursevisible = 1;
af9d3a92
JO
768 $data->lti_sendname = LTI_SETTING_DELEGATE;
769 $data->lti_sendemailaddr = LTI_SETTING_DELEGATE;
770 $data->lti_acceptgrades = LTI_SETTING_DELEGATE;
771 $data->lti_forcessl = 0;
cc193e0d
RW
772
773 if (!empty($key)) {
774 $data->lti_resourcekey = $key;
775 }
776
777 if (!empty($secret)) {
778 $data->lti_password = $secret;
779 }
780
781 lti_load_type_from_cartridge($cartridgeurl, $data);
af9d3a92
JO
782 if (empty($data->lti_toolurl)) {
783 throw new moodle_exception('unabletocreatetooltype', 'mod_lti');
784 } else {
785 $id = lti_add_type($type, $data);
786 }
cc193e0d
RW
787 }
788
789 if (!empty($id)) {
790 $type = lti_get_type($id);
791 return serialise_tool_type($type);
792 } else {
af9d3a92 793 throw new moodle_exception('unabletocreatetooltype', 'mod_lti');
cc193e0d
RW
794 }
795 }
796
797 /**
798 * Returns description of method result value
799 *
800 * @return external_description
af9d3a92 801 * @since Moodle 3.1
cc193e0d
RW
802 */
803 public static function create_tool_type_returns() {
811d9ff9 804 return self::tool_type_return_structure();
cc193e0d
RW
805 }
806
807 /**
808 * Returns description of method parameters
809 *
810 * @return external_function_parameters
af9d3a92 811 * @since Moodle 3.1
cc193e0d
RW
812 */
813 public static function update_tool_type_parameters() {
814 return new external_function_parameters(
815 array(
816 'id' => new external_value(PARAM_INT, 'Tool type id'),
5c1b749d
JP
817 'name' => new external_value(PARAM_RAW, 'Tool type name', VALUE_DEFAULT, null),
818 'description' => new external_value(PARAM_RAW, 'Tool type description', VALUE_DEFAULT, null),
cc193e0d
RW
819 'state' => new external_value(PARAM_INT, 'Tool type state', VALUE_DEFAULT, null)
820 )
821 );
822 }
823
824 /**
825 * Update a tool type.
826 *
af9d3a92
JO
827 * @param int $id The id of the tool type to update
828 * @param string $name The name of the tool type
829 * @param string $description The name of the tool type
830 * @param int $state The state of the tool type
831 * @return array updated tool type
832 * @since Moodle 3.1
cc193e0d
RW
833 * @throws moodle_exception
834 */
835 public static function update_tool_type($id, $name, $description, $state) {
836 $params = self::validate_parameters(self::update_tool_type_parameters(),
837 array(
838 'id' => $id,
839 'name' => $name,
840 'description' => $description,
841 'state' => $state,
842 ));
af9d3a92
JO
843 $id = $params['id'];
844 $name = $params['name'];
845 $description = $params['description'];
846 $state = $params['state'];
cc193e0d
RW
847
848 $context = context_system::instance();
849 self::validate_context($context);
af9d3a92 850 require_capability('moodle/site:config', $context);
cc193e0d
RW
851
852 $type = lti_get_type($id);
853
854 if (empty($type)) {
af9d3a92 855 throw new moodle_exception('unabletofindtooltype', 'mod_lti', '', array('id' => $id));
cc193e0d
RW
856 }
857
858 if (!empty($name)) {
859 $type->name = $name;
860 }
861
862 if (!empty($description)) {
863 $type->description = $description;
864 }
865
866 if (!empty($state)) {
867 // Valid state range.
af9d3a92 868 if (in_array($state, array(1, 2, 3))) {
cc193e0d
RW
869 $type->state = $state;
870 } else {
af9d3a92 871 throw new moodle_exception("Invalid state: $state - must be 1, 2, or 3");
cc193e0d
RW
872 }
873 }
874
af9d3a92 875 lti_update_type($type, new stdClass());
cc193e0d
RW
876
877 return serialise_tool_type($type);
878 }
879
880 /**
881 * Returns description of method result value
882 *
883 * @return external_description
af9d3a92 884 * @since Moodle 3.1
cc193e0d
RW
885 */
886 public static function update_tool_type_returns() {
811d9ff9 887 return self::tool_type_return_structure();
cc193e0d
RW
888 }
889
890 /**
891 * Returns description of method parameters
892 *
893 * @return external_function_parameters
af9d3a92 894 * @since Moodle 3.1
cc193e0d
RW
895 */
896 public static function delete_tool_type_parameters() {
897 return new external_function_parameters(
898 array(
899 'id' => new external_value(PARAM_INT, 'Tool type id'),
900 )
901 );
902 }
903
904 /**
905 * Delete a tool type.
906 *
af9d3a92
JO
907 * @param int $id The id of the tool type to be deleted
908 * @return array deleted tool type
909 * @since Moodle 3.1
cc193e0d
RW
910 * @throws moodle_exception
911 */
912 public static function delete_tool_type($id) {
913 $params = self::validate_parameters(self::delete_tool_type_parameters(),
914 array(
915 'id' => $id,
916 ));
af9d3a92 917 $id = $params['id'];
cc193e0d
RW
918
919 $context = context_system::instance();
920 self::validate_context($context);
af9d3a92 921 require_capability('moodle/site:config', $context);
cc193e0d
RW
922
923 $type = lti_get_type($id);
924
925 if (!empty($type)) {
926 lti_delete_type($id);
927
928 // If this is the last type for this proxy then remove the proxy
929 // as well so that it isn't orphaned.
af9d3a92
JO
930 $types = lti_get_lti_types_from_proxy_id($type->toolproxyid);
931 if (empty($types)) {
cc193e0d
RW
932 lti_delete_tool_proxy($type->toolproxyid);
933 }
934 }
935
936 return array('id' => $id);
937 }
938
939 /**
940 * Returns description of method result value
941 *
942 * @return external_description
af9d3a92 943 * @since Moodle 3.1
cc193e0d
RW
944 */
945 public static function delete_tool_type_returns() {
946 return new external_function_parameters(
947 array(
948 'id' => new external_value(PARAM_INT, 'Tool type id'),
949 )
950 );
951 }
952
953 /**
954 * Returns description of method parameters
955 *
956 * @return external_function_parameters
af9d3a92 957 * @since Moodle 3.1
cc193e0d
RW
958 */
959 public static function is_cartridge_parameters() {
960 return new external_function_parameters(
961 array(
962 'url' => new external_value(PARAM_URL, 'Tool url'),
963 )
964 );
965 }
966
967 /**
968 * Determine if the url to a tool is for a cartridge.
969 *
af9d3a92 970 * @param string $url Url that may or may not be an xml cartridge
cc193e0d 971 * @return bool True if the url is for a cartridge.
af9d3a92 972 * @since Moodle 3.1
cc193e0d
RW
973 * @throws moodle_exception
974 */
975 public static function is_cartridge($url) {
976 $params = self::validate_parameters(self::is_cartridge_parameters(),
977 array(
978 'url' => $url,
979 ));
af9d3a92 980 $url = $params['url'];
cc193e0d
RW
981
982 $context = context_system::instance();
983 self::validate_context($context);
af9d3a92 984 require_capability('moodle/site:config', $context);
cc193e0d
RW
985
986 $iscartridge = lti_is_cartridge($url);
987
988 return array('iscartridge' => $iscartridge);
989 }
990
991 /**
992 * Returns description of method result value
993 *
994 * @return external_description
af9d3a92 995 * @since Moodle 3.1
cc193e0d
RW
996 */
997 public static function is_cartridge_returns() {
998 return new external_function_parameters(
999 array(
1000 'iscartridge' => new external_value(PARAM_BOOL, 'True if the URL is a cartridge'),
1001 )
1002 );
1003 }
ae67efa8 1004}