question/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 /**
  19  * External question API
  20  *
  21  * @package    core_question
  22  * @category   external
  23  * @copyright  2016 Pau Ferrer <pau@moodle.com>
  24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25  */
  26
  27 require_once("$CFG->libdir/externallib.php");
  28 require_once($CFG->dirroot . '/question/engine/lib.php');
  29
  30 /**
  31  * Question external functions
  32  *
  33  * @package    core_question
  34  * @category   external
  35  * @copyright  2016 Pau Ferrer <pau@moodle.com>
  36  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  37  * @since Moodle 3.1
  38  */
  39 class core_question_external extends external_api {
  40
  41     /**
  42      * Returns description of method parameters
  43      *
  44      * @return external_function_parameters
  45      * @since Moodle 3.1
  46      */
  47     public static function update_flag_parameters() {
  48         return new external_function_parameters(
  49             array(
  50                 'qubaid' => new external_value(PARAM_INT, 'the question usage id.'),
  51                 'questionid' => new external_value(PARAM_INT, 'the question id'),
  52                 'qaid' => new external_value(PARAM_INT, 'the question_attempt id'),
  53                 'slot' => new external_value(PARAM_INT, 'the slot number within the usage'),
  54                 'checksum' => new external_value(PARAM_ALPHANUM, 'computed checksum with the last three arguments and
  55                              the users username'),
  56                 'newstate' => new external_value(PARAM_BOOL, 'the new state of the flag. true = flagged')
  57             )
  58         );
  59     }
  60
  61     /**
  62      * Update the flag state of a question attempt.
  63      *
  64      * @param int $qubaid the question usage id.
  65      * @param int $questionid the question id.
  66      * @param int $qaid the question_attempt id.
  67      * @param int $slot the slot number within the usage.
  68      * @param string $checksum checksum, as computed by {@link get_toggle_checksum()}
  69      *      corresponding to the last three arguments and the users username.
  70      * @param bool $newstate the new state of the flag. true = flagged.
  71      * @return array (success infos and fail infos)
  72      * @since Moodle 3.1
  73      */
  74     public static function update_flag($qubaid, $questionid, $qaid, $slot, $checksum, $newstate) {
  75         global $CFG, $DB;
  76
  77         $params = self::validate_parameters(self::update_flag_parameters(),
  78             array(
  79                 'qubaid' => $qubaid,
  80                 'questionid' => $questionid,
  81                 'qaid' => $qaid,
  82                 'slot' => $slot,
  83                 'checksum' => $checksum,
  84                 'newstate' => $newstate
  85             )
  86         );
  87
  88         $warnings = array();
  89
  90         // Check user is logged in.
  91         require_login(null, false, null, false, true);
  92
  93         // The checksum will be checked to provide security flagging other users questions.
  94         question_flags::update_flag($params['qubaid'], $params['questionid'], $params['qaid'], $params['slot'], $params['checksum'],
  95                                     $params['newstate']);
  96
  97         $result = array();
  98         $result['status'] = true;
  99         $result['warnings'] = $warnings;
 100         return $result;
 101     }
 102
 103     /**
 104      * Returns description of method result value
 105      *
 106      * @return external_description
 107      * @since Moodle 3.1
 108      */
 109     public static function update_flag_returns() {
 110         return new external_single_structure(
 111             array(
 112                 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
 113                 'warnings' => new external_warnings()
 114             )
 115         );
 116     }
 117 }