NOBUG: Fixed PAGE->set_url() regression
[moodle.git] / lib / externallib.php
CommitLineData
9a0df45a 1<?php
2
3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17
18/**
19 * Support for external API
20 *
21 * @package moodlecore
22 * @subpackage webservice
23 * @copyright 2008 Petr Skoda (http://skodak.org)
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
27/**
28 * Exception indicating user is not allowed to use external function in
29 * the current context.
30 */
31class restricted_context_exception extends moodle_exception {
32 /**
33 * Constructor
34 */
35 function __construct() {
36 parent::__construct('restrictedcontextexception', 'error');
37 }
38}
39
40/**
41 * Base class for external api methods.
42 */
43class external_api {
9a0df45a 44 private static $contextrestriction;
45
1bea0c27 46 /**
47 * Set context restriction for all folowing subsequent function calls.
48 * @param stdClass $contex
49 * @return void
50 */
9a0df45a 51 public static function set_context_restriction($contex) {
52 self::$contextrestriction = $context;
53 }
54
1bea0c27 55 /**
56 * Validates submitted function barameters, if anything is incorrect
57 * invalid_parameter_exception is thrown.
58 * @param ? $description description of parameters
5b658d18 59 * @param ? $params the actual parameters
1bea0c27 60 * @return ? params with added defaults for optional items, invalid_parameters_exception thrown if any problem found
61 */
d4e13355 62 public static function validate_prameters($description, $params) {
1bea0c27 63 //TODO: we need to define the structure of param descriptions
64
65 return $params;
66 }
67
9a0df45a 68 /**
69 * Makes sure user may execute functions in this context.
70 * @param object $context
71 * @return void
72 */
73 protected static function validate_context($context) {
ab9a01f2 74 if (empty($context)) {
75 throw new invalid_parameter_exception('Context does not exist');
76 }
9a0df45a 77 if (empty(self::$contextrestriction)) {
78 self::$contextrestriction = get_context_instance(CONTEXT_SYSTEM);
79 }
80 $rcontext = self::$contextrestriction;
81
82 if ($rcontext->contextlevel == $context->contextlevel) {
83 if ($rcontex->id != $context->id) {
84 throw new restricted_context_exception();
85 }
86 } else if ($rcontext->contextlevel > $context->contextlevel) {
87 throw new restricted_context_exception();
88 } else {
89 $parents = get_parent_contexts($context);
90 if (!in_array($rcontext->id, $parents)) {
91 throw new restricted_context_exception();
92 }
93 }
94
95 if ($context->contextlevel >= CONTEXT_COURSE) {
96 //TODO: temporary bloody hack, this needs to be replaced by
97 // proper enrolment and course visibility check
98 // similar to require_login() (which can not be used
99 // because it can be used only once and redirects)
100 // oh - did I tell we need to rewrite enrolments in 2.0
101 // to solve this bloody mess?
102 //
103 // missing: hidden courses and categories, groupmembersonly,
104 // conditional activities, etc.
105 require_capability('moodle/course:view', $context);
106 }
107 }
9a0df45a 108}
109
b038c32c 110/**
111 * Common ancestor of all parameter description classes
112 */
113abstract class external_description {
114 /** @property string $description description of element */
115 public $desc;
116 /** @property bool $required element value required, null not alowed */
117 public $required;
118
119 /**
120 * Contructor
121 * @param string $desc
122 * @param bool $required
123 */
124 public function __contruct($desc, $required) {
125 $this->desc = $desc;
126 $this->required = $required;
127 }
128}
129
130/**
131 * Scalar parameter description class
132 */
133class external_param extends external_description {
134 /** @property mixed $type parameter type PARAM_XX */
135 public $type;
136 /** @property mixed $default default value */
137 public $default;
138 /** @property bool $allownull allow null values */
139 public $allownull;
140
141 /**
142 * Constructor
143 * @param mixed $type
144 * @param string $desc
145 * @param bool $required
146 * @param mixed $default
147 * @param bool $allownull
148 */
149 public function __contruct($type, $desc='', $required=true, $default=null, $allownull=true) {
150 parent::_construct($desc, $required);
151 $this->type = $type;
152 $this->default = $default;
153 $this->allownull = $allownull;
154 }
155}
156
157/**
158 * Associative array description class
159 */
160class external_single_structure extends external_description {
161 /** @property array $keys description of array keys key=>external_description */
162 public $keys;
163
164 /**
165 * Constructor
166 * @param array $keys
167 * @param string $desc
168 * @param bool $required
169 */
170 public function __construct(array $keys, $desc='', $required=true) {
171 parent::_construct($desc, $required);
172 $this->keys = $keys;
173 }
174}
175
176/**
177 * Bulk array description class.
178 */
179class external_multiple_structure extends external_description {
180 /** @property external_description $content */
181 public $content;
182
183 /**
184 * Constructor
185 * @param external_description $content
186 * @param string $desc
187 * @param bool $required
188 */
189 public function __construct(external_description $content, $desc='', $required=true) {
190 parent::_construct($desc, $required);
191 $this->content = $content;
192 }
193}
c29cca30 194
195/**
196 * Description of top level - PHP function parameters.
197 * @author skodak
198 *
199 */
200class external_function_parameters extends external_single_structure {
201}