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/>.
  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
  27 defined('MOODLE_INTERNAL') || die;
  28
  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');
  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  */
  42 class mod_lti_external extends external_api {
  43
  44     /**
  45      * Returns structure be used for returning a tool type from a web service.
  46      *
  47      * @return external_function_parameters
  48      * @since Moodle 3.1
  49      */
  50     private static function tool_type_return_structure() {
  51         return new external_single_structure(
  52             array(
  53                 'id' => new external_value(PARAM_INT, 'Tool type id'),
  54                 'name' => new external_value(PARAM_NOTAGS, 'Tool type name'),
  55                 'description' => new external_value(PARAM_NOTAGS, 'Tool type description'),
  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'),
  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      */
  93     private static function tool_proxy_return_structure() {
  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
 112     /**
 113      * Returns description of method parameters
 114      *
 115      * @return external_function_parameters
 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
 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     }
 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
 279         $mycourses = array();
 280         if (empty($params['courseids'])) {
 281             $mycourses = enrol_get_my_courses();
 282             $params['courseids'] = array_keys($mycourses);
 283         }
 284
 285         // Ensure there are courseids to loop through.
 286         if (!empty($params['courseids'])) {
 287
 288             list($courses, $warnings) = external_util::validate_courses($params['courseids'], $mycourses);
 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']) =
 310                         external_format_text($lti->intro, $lti->introformat, $context->id, 'mod_lti', 'intro', $lti->id);
 311
 312                     $module['introfiles'] = external_util::get_area_files($context->id, 'mod_lti', 'intro', false, false);
 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),
 360                             'introfiles' => new external_files('Files in the introduction text', VALUE_OPTIONAL),
 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     }
 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     }
 462
 463     /**
 464      * Returns description of method parameters
 465      *
 466      * @return external_function_parameters
 467      * @since Moodle 3.1
 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     /**
 487      * Creates a new tool proxy
 488      *
 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
 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                                             ));
 505         $name = $params['name'];
 506         $regurl = $params['regurl'];
 507         $capabilityoffered = $params['capabilityoffered'];
 508         $serviceoffered = $params['serviceoffered'];
 509
 510         $context = context_system::instance();
 511         self::validate_context($context);
 512         require_capability('moodle/site:config', $context);
 513
 514         // Can't create duplicate proxies with the same URL.
 515         $duplicates = lti_get_tool_proxies_from_registration_url($registrationurl);
 516         if (!empty($duplicates)) {
 517             throw new moodle_exception('duplicateregurl', 'mod_lti');
 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)) {
 528             $config->lti_capabilities = $capabilityoffered;
 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
 550      * @since Moodle 3.1
 551      */
 552     public static function create_tool_proxy_returns() {
 553         return self::tool_proxy_return_structure();
 554     }
 555
 556     /**
 557      * Returns description of method parameters
 558      *
 559      * @return external_function_parameters
 560      * @since Moodle 3.1
 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      *
 573      * @param int $id the lti instance id
 574      * @return object The tool proxy
 575      * @since Moodle 3.1
 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                                             ));
 583         $id = $params['id'];
 584
 585         $context = context_system::instance();
 586         self::validate_context($context);
 587         require_capability('moodle/site:config', $context);
 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
 600      * @since Moodle 3.1
 601      */
 602     public static function delete_tool_proxy_returns() {
 603         return self::tool_proxy_return_structure();
 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
 624      * @return array of registration parameters
 625      * @since Moodle 3.1
 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                                             ));
 633         $id = $params['id'];
 634
 635         $context = context_system::instance();
 636         self::validate_context($context);
 637         require_capability('moodle/site:config', $context);
 638
 639         $toolproxy = lti_get_tool_proxy($id);
 640         return lti_build_registration_request($toolproxy);
 641     }
 642
 643     /**
 644      * Returns description of method result value
 645      *
 646      * @return external_description
 647      * @since Moodle 3.1
 648      */
 649     public static function get_tool_proxy_registration_request_returns() {
 650         return new external_function_parameters(
 651             array(
 652                 'lti_message_type' => new external_value(PARAM_ALPHANUMEXT, 'LTI message type'),
 653                 'lti_version' => new external_value(PARAM_ALPHANUMEXT, 'LTI version'),
 654                 'reg_key' => new external_value(PARAM_TEXT, 'Tool proxy registration key'),
 655                 'reg_password' => new external_value(PARAM_TEXT, 'Tool proxy registration password'),
 656                 'reg_url' => new external_value(PARAM_TEXT, 'Tool proxy registration url'),
 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
 667      * @since Moodle 3.1
 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      *
 680      * @param int $toolproxyid The tool proxy id
 681      * @return array of tool types
 682      * @since Moodle 3.1
 683      * @throws moodle_exception
 684      */
 685     public static function get_tool_types($toolproxyid) {
 686         global $PAGE;
 687         $params = self::validate_parameters(self::get_tool_types_parameters(),
 688                                             array(
 689                                                 'toolproxyid' => $toolproxyid
 690                                             ));
 691         $toolproxyid = $params['toolproxyid'];
 692
 693         $types = array();
 694         $context = context_system::instance();
 695
 696         self::validate_context($context);
 697         require_capability('moodle/site:config', $context);
 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
 712      * @since Moodle 3.1
 713      */
 714     public static function get_tool_types_returns() {
 715         return new external_multiple_structure(
 716             self::tool_type_return_structure()
 717         );
 718     }
 719
 720     /**
 721      * Returns description of method parameters
 722      *
 723      * @return external_function_parameters
 724      * @since Moodle 3.1
 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      *
 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
 742      * @return array created tool type
 743      * @since Moodle 3.1
 744      * @throws moodle_exception If the tool type could not be created
 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                                             ));
 753         $cartridgeurl = $params['cartridgeurl'];
 754         $key = $params['key'];
 755         $secret = $params['secret'];
 756
 757         $context = context_system::instance();
 758         self::validate_context($context);
 759         require_capability('moodle/site:config', $context);
 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;
 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;
 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);
 782             if (empty($data->lti_toolurl)) {
 783                 throw new moodle_exception('unabletocreatetooltype', 'mod_lti');
 784             } else {
 785                 $id = lti_add_type($type, $data);
 786             }
 787         }
 788
 789         if (!empty($id)) {
 790             $type = lti_get_type($id);
 791             return serialise_tool_type($type);
 792         } else {
 793             throw new moodle_exception('unabletocreatetooltype', 'mod_lti');
 794         }
 795     }
 796
 797     /**
 798      * Returns description of method result value
 799      *
 800      * @return external_description
 801      * @since Moodle 3.1
 802      */
 803     public static function create_tool_type_returns() {
 804         return self::tool_type_return_structure();
 805     }
 806
 807     /**
 808      * Returns description of method parameters
 809      *
 810      * @return external_function_parameters
 811      * @since Moodle 3.1
 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'),
 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),
 819                 'state' => new external_value(PARAM_INT, 'Tool type state', VALUE_DEFAULT, null)
 820             )
 821         );
 822     }
 823
 824     /**
 825      * Update a tool type.
 826      *
 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
 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                                             ));
 843         $id = $params['id'];
 844         $name = $params['name'];
 845         $description = $params['description'];
 846         $state = $params['state'];
 847
 848         $context = context_system::instance();
 849         self::validate_context($context);
 850         require_capability('moodle/site:config', $context);
 851
 852         $type = lti_get_type($id);
 853
 854         if (empty($type)) {
 855             throw new moodle_exception('unabletofindtooltype', 'mod_lti', '', array('id' => $id));
 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.
 868             if (in_array($state, array(1, 2, 3))) {
 869                 $type->state = $state;
 870             } else {
 871                 throw new moodle_exception("Invalid state: $state - must be 1, 2, or 3");
 872             }
 873         }
 874
 875         lti_update_type($type, new stdClass());
 876
 877         return serialise_tool_type($type);
 878     }
 879
 880     /**
 881      * Returns description of method result value
 882      *
 883      * @return external_description
 884      * @since Moodle 3.1
 885      */
 886     public static function update_tool_type_returns() {
 887         return self::tool_type_return_structure();
 888     }
 889
 890     /**
 891      * Returns description of method parameters
 892      *
 893      * @return external_function_parameters
 894      * @since Moodle 3.1
 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      *
 907      * @param int $id The id of the tool type to be deleted
 908      * @return array deleted tool type
 909      * @since Moodle 3.1
 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                                             ));
 917         $id = $params['id'];
 918
 919         $context = context_system::instance();
 920         self::validate_context($context);
 921         require_capability('moodle/site:config', $context);
 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.
 930             $types = lti_get_lti_types_from_proxy_id($type->toolproxyid);
 931             if (empty($types)) {
 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
 943      * @since Moodle 3.1
 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
 957      * @since Moodle 3.1
 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      *
 970      * @param string $url Url that may or may not be an xml cartridge
 971      * @return bool True if the url is for a cartridge.
 972      * @since Moodle 3.1
 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                                             ));
 980         $url = $params['url'];
 981
 982         $context = context_system::instance();
 983         self::validate_context($context);
 984         require_capability('moodle/site:config', $context);
 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
 995      * @since Moodle 3.1
 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     }
1004 }