MDL-62487 quiz manual grading: implement suggestions from int review
[moodle.git] / backup / externallib.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/>.
18 /**
19  * External backup API.
20  *
21  * @package    core_backup
22  * @category   external
23  * @copyright  2018 Matt Porritt <mattp@catalyst-au.net>
24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25  */
27 defined('MOODLE_INTERNAL') || die;
29 require_once("$CFG->libdir/externallib.php");
30 require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php');
32 /**
33  * Backup external functions.
34  *
35  * @package    core_backup
36  * @category   external
37  * @copyright  2018 Matt Porritt <mattp@catalyst-au.net>
38  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
39  * @since Moodle 3.7
40  */
41 class core_backup_external extends external_api {
43     /**
44      * Returns description of method parameters
45      *
46      * @return external_function_parameters
47      * @since Moodle 3.7
48      */
49     public static function get_async_backup_progress_parameters() {
50         return new external_function_parameters(
51             array(
52                 'backupids' => new external_multiple_structure(
53                         new external_value(PARAM_ALPHANUM, 'Backup id to get progress for', VALUE_REQUIRED, null, NULL_ALLOWED),
54                         'Backup id to get progress for', VALUE_REQUIRED
55                  ),
56                 'contextid' => new external_value(PARAM_INT, 'Context id', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
57             )
58         );
59     }
61     /**
62      * Get asynchronous backup progress.
63      *
64      * @param string $backupids The ids of the backup to get progress for.
65      * @param int $contextid The context the backup relates to.
66      * @return array $results The array of results.
67      * @since Moodle 3.7
68      */
69     public static function get_async_backup_progress($backupids, $contextid) {
70         global $CFG;
71         require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php');
72         require_once($CFG->dirroot . '/backup/util/includes/restore_includes.php');
74         // Release session lock.
75         \core\session\manager::write_close();
77         // Parameter validation.
78         self::validate_parameters(
79                 self::get_async_backup_progress_parameters(),
80                 array(
81                     'backupids' => $backupids,
82                     'contextid' => $contextid
83                 )
84         );
86         // Context validation.
87         list($context, $course, $cm) = get_context_info_array($contextid);
88         self::validate_context($context);
90         if ($cm) {
91             require_capability('moodle/backup:backupactivity', $context);
92         } else {
93             require_capability('moodle/backup:backupcourse', $context);
94         }
96         $results = array();
97         foreach ($backupids as $backupid) {
98             $results[] = backup_controller_dbops::get_progress($backupid);
99         }
101         return $results;
102     }
104     /**
105      * Returns description of method result value
106      *
107      * @return external_description
108      * @since Moodle 3.7
109      */
110     public static function get_async_backup_progress_returns() {
111         return new external_multiple_structure(
112             new external_single_structure(
113                 array(
114                     'status'   => new external_value(PARAM_INT, 'Backup Status'),
115                     'progress' => new external_value(PARAM_FLOAT, 'Backup progress'),
116                     'backupid' => new external_value(PARAM_ALPHANUM, 'Backup id'),
117                     'operation' => new external_value(PARAM_ALPHANUM, 'operation type'),
118                 ), 'Backup completion status'
119           ), 'Backup data'
120         );
121     }
123     /**
124      * Returns description of method parameters
125      *
126      * @return external_function_parameters
127      * @since Moodle 3.7
128      */
129     public static function get_async_backup_links_backup_parameters() {
130         return new external_function_parameters(
131                 array(
132                     'filename' => new external_value(PARAM_FILE, 'Backup filename', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
133                     'contextid' => new external_value(PARAM_INT, 'Context id', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
134                 )
135          );
136     }
138     /**
139      * Get the data to be used when generating the table row for an asynchronous backup,
140      * the table row updates via ajax when backup is complete.
141      *
142      * @param string $filename The file name of the backup file.
143      * @param int $contextid The context the backup relates to.
144      * @since Moodle 3.7
145      */
146     public static function get_async_backup_links_backup($filename, $contextid) {
147         // Release session lock.
148         \core\session\manager::write_close();
150         // Parameter validation.
151         self::validate_parameters(
152                 self::get_async_backup_links_backup_parameters(),
153                     array(
154                         'filename' => $filename,
155                         'contextid' => $contextid
156                     )
157                 );
159         // Context validation.
160         list($context, $course, $cm) = get_context_info_array($contextid);
161         self::validate_context($context);
162         require_capability('moodle/backup:backupcourse', $context);
164         if ($cm) {
165             $filearea = 'activity';
166         } else {
167             $filearea = 'course';
168         }
170         $results = \async_helper::get_backup_file_info($filename, $filearea, $contextid);
172         return $results;
173     }
175     /**
176      * Returns description of method result value.
177      *
178      * @return external_description
179      * @since Moodle 3.7
180      */
181     public static function get_async_backup_links_backup_returns() {
182         return new external_single_structure(
183             array(
184                'filesize'   => new external_value(PARAM_TEXT, 'Backup file size'),
185                'fileurl' => new external_value(PARAM_URL, 'Backup file URL'),
186                'restoreurl' => new external_value(PARAM_URL, 'Backup restore URL'),
187         ), 'Table row data.');
188     }
189     /**
190      * Returns description of method parameters
191      *
192      * @return external_function_parameters
193      * @since Moodle 3.7
194      */
195     public static function get_async_backup_links_restore_parameters() {
196         return new external_function_parameters(
197                 array(
198                     'backupid' => new external_value(PARAM_ALPHANUMEXT, 'Backup id', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
199                     'contextid' => new external_value(PARAM_INT, 'Context id', VALUE_REQUIRED, null, NULL_NOT_ALLOWED),
200                 )
201         );
202     }
204     /**
205      * Get the data to be used when generating the table row for an asynchronous restore,
206      * the table row updates via ajax when restore is complete.
207      *
208      * @param string $backupid The id of the backup record.
209      * @param int $contextid The context the restore relates to.
210      * @return array $results The array of results.
211      * @since Moodle 3.7
212      */
213     public static function get_async_backup_links_restore($backupid, $contextid) {
214         // Release session lock.
215         \core\session\manager::write_close();
217         // Parameter validation.
218         self::validate_parameters(
219                 self::get_async_backup_links_restore_parameters(),
220                     array(
221                         'backupid' => $backupid,
222                         'contextid' => $contextid
223                     )
224                 );
226         // Context validation.
227         $context = context::instance_by_id($contextid);
228         self::validate_context($context);
229         require_capability('moodle/restore:restorecourse', $context);
231         $results = \async_helper::get_restore_url($backupid);
233         return $results;
234     }
236     /**
237      * Returns description of method result value.
238      *
239      * @return external_description
240      * @since Moodle 3.7
241      */
242     public static function get_async_backup_links_restore_returns() {
243         return new external_single_structure(
244                 array(
245                     'restoreurl' => new external_value(PARAM_URL, 'Restore url'),
246                 ), 'Table row data.');
247     }