MDL-26198 make user_has_role_assignment() check parent contexts too
[moodle.git] / webservice / lib.php
1 <?php
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/>.
18 /**
19  * Web services utility functions and classes
20  *
21  * @package   webservice
22  * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
23  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
26 require_once($CFG->libdir.'/externallib.php');
28 define('WEBSERVICE_AUTHMETHOD_USERNAME', 0);
29 define('WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN', 1);
30 define('WEBSERVICE_AUTHMETHOD_SESSION_TOKEN', 2);
32 /**
33  * General web service library
34  */
35 class webservice {
37     /**
38      * Add a user to the list of authorised user of a given service
39      * @param object $user
40      */
41     public function add_ws_authorised_user($user) {
42         global $DB;
43         $user->timecreated = mktime();
44         $DB->insert_record('external_services_users', $user);
45     }
47     /**
48      * Remove a user from a list of allowed user of a service
49      * @param object $user
50      * @param int $serviceid
51      */
52     public function remove_ws_authorised_user($user, $serviceid) {
53         global $DB;
54         $DB->delete_records('external_services_users',
55                 array('externalserviceid' => $serviceid, 'userid' => $user->id));
56     }
58     /**
59      * Update service allowed user settings
60      * @param object $user
61      */
62     public function update_ws_authorised_user($user) {
63         global $DB;
64         $DB->update_record('external_services_users', $user);
65     }
67     /**
68      * Return list of allowed users with their options (ip/timecreated / validuntil...)
69      * for a given service
70      * @param int $serviceid
71      * @return array $users
72      */
73     public function get_ws_authorised_users($serviceid) {
74         global $DB, $CFG;
75         $params = array($CFG->siteguest, $serviceid);
76         $sql = " SELECT u.id as id, esu.id as serviceuserid, u.email as email, u.firstname as firstname,
77                         u.lastname as lastname,
78                         esu.iprestriction as iprestriction, esu.validuntil as validuntil,
79                         esu.timecreated as timecreated
80                    FROM {user} u, {external_services_users} esu
81                   WHERE u.id <> ? AND u.deleted = 0 AND u.confirmed = 1
82                         AND esu.userid = u.id
83                         AND esu.externalserviceid = ?";
85         $users = $DB->get_records_sql($sql, $params);
86         return $users;
87     }
89     /**
90      * Return a authorised user with his options (ip/timecreated / validuntil...)
91      * @param int $serviceid
92      * @param int $userid
93      * @return object
94      */
95     public function get_ws_authorised_user($serviceid, $userid) {
96         global $DB, $CFG;
97         $params = array($CFG->siteguest, $serviceid, $userid);
98         $sql = " SELECT u.id as id, esu.id as serviceuserid, u.email as email, u.firstname as firstname,
99                         u.lastname as lastname,
100                         esu.iprestriction as iprestriction, esu.validuntil as validuntil,
101                         esu.timecreated as timecreated
102                    FROM {user} u, {external_services_users} esu
103                   WHERE u.id <> ? AND u.deleted = 0 AND u.confirmed = 1
104                         AND esu.userid = u.id
105                         AND esu.externalserviceid = ?
106                         AND u.id = ?";
107         $user = $DB->get_record_sql($sql, $params);
108         return $user;
109     }
111     /**
112      * Generate all ws token needed by a user
113      * @param int $userid
114      */
115     public function generate_user_ws_tokens($userid) {
116         global $CFG, $DB;
118         /// generate a token for non admin if web service are enable and the user has the capability to create a token
119         if (!is_siteadmin() && has_capability('moodle/webservice:createtoken', get_context_instance(CONTEXT_SYSTEM), $userid) && !empty($CFG->enablewebservices)) {
120         /// for every service than the user is authorised on, create a token (if it doesn't already exist)
122             ///get all services which are set to all user (no restricted to specific users)
123             $norestrictedservices = $DB->get_records('external_services', array('restrictedusers' => 0));
124             $serviceidlist = array();
125             foreach ($norestrictedservices as $service) {
126                 $serviceidlist[] = $service->id;
127             }
129             //get all services which are set to the current user (the current user is specified in the restricted user list)
130             $servicesusers = $DB->get_records('external_services_users', array('userid' => $userid));
131             foreach ($servicesusers as $serviceuser) {
132                 if (!in_array($serviceuser->externalserviceid,$serviceidlist)) {
133                      $serviceidlist[] = $serviceuser->externalserviceid;
134                 }
135             }
137             //get all services which already have a token set for the current user
138             $usertokens = $DB->get_records('external_tokens', array('userid' => $userid, 'tokentype' => EXTERNAL_TOKEN_PERMANENT));
139             $tokenizedservice = array();
140             foreach ($usertokens as $token) {
141                     $tokenizedservice[]  = $token->externalserviceid;
142             }
144             //create a token for the service which have no token already
145             foreach ($serviceidlist as $serviceid) {
146                 if (!in_array($serviceid, $tokenizedservice)) {
147                     //create the token for this service
148                     $newtoken = new stdClass();
149                     $newtoken->token = md5(uniqid(rand(),1));
150                     //check that the user has capability on this service
151                     $newtoken->tokentype = EXTERNAL_TOKEN_PERMANENT;
152                     $newtoken->userid = $userid;
153                     $newtoken->externalserviceid = $serviceid;
154                     //TODO: find a way to get the context - UPDATE FOLLOWING LINE
155                     $newtoken->contextid = get_context_instance(CONTEXT_SYSTEM)->id;
156                     $newtoken->creatorid = $userid;
157                     $newtoken->timecreated = time();
159                     $DB->insert_record('external_tokens', $newtoken);
160                 }
161             }
164         }
165     }
167     /**
168      * Return all ws user token
169      * @param integer $userid
170      * @return array of token
171      */
172     public function get_user_ws_tokens($userid) {
173         global $DB;
174         //here retrieve token list (including linked users firstname/lastname and linked services name)
175         $sql = "SELECT
176                     t.id, t.creatorid, t.token, u.firstname, u.lastname, s.name, t.validuntil
177                 FROM
178                     {external_tokens} t, {user} u, {external_services} s
179                 WHERE
180                     t.userid=? AND t.tokentype = ".EXTERNAL_TOKEN_PERMANENT." AND s.id = t.externalserviceid AND t.userid = u.id";
181         $tokens = $DB->get_records_sql($sql, array( $userid));
182         return $tokens;
183     }
185     /**
186      * Return a user token that has been created by the user
187      * If doesn't exist a exception is thrown
188      * @param integer $userid
189      * @param integer $tokenid
190      * @return object token
191      * ->id token id
192      * ->token
193      * ->firstname user firstname
194      * ->lastname
195      * ->name service name
196      */
197     public function get_created_by_user_ws_token($userid, $tokenid) {
198         global $DB;
199         $sql = "SELECT
200                         t.id, t.token, u.firstname, u.lastname, s.name
201                     FROM
202                         {external_tokens} t, {user} u, {external_services} s
203                     WHERE
204                         t.creatorid=? AND t.id=? AND t.tokentype = "
205                 . EXTERNAL_TOKEN_PERMANENT
206                 . " AND s.id = t.externalserviceid AND t.userid = u.id";
207         //must be the token creator
208         $token = $DB->get_record_sql($sql, array($userid, $tokenid), MUST_EXIST);
209         return $token;
210     }
212     /**
213      * Return a token for a given id
214      * @param integer $tokenid
215      * @return object token
216      */
217     public function get_token_by_id($tokenid) {
218         global $DB;
219         return $DB->get_record('external_tokens', array('id' => $tokenid));
220     }
222     /**
223      * Delete a user token
224      * @param int $tokenid
225      */
226     public function delete_user_ws_token($tokenid) {
227         global $DB;
228         $DB->delete_records('external_tokens', array('id'=>$tokenid));
229     }
231     /**
232      * Delete a service - it also delete the functions and users references to this service
233      * @param int $serviceid
234      */
235     public function delete_service($serviceid) {
236         global $DB;
237         $DB->delete_records('external_services_users', array('externalserviceid' => $serviceid));
238         $DB->delete_records('external_services_functions', array('externalserviceid' => $serviceid));
239         $DB->delete_records('external_tokens', array('externalserviceid' => $serviceid));
240         $DB->delete_records('external_services', array('id' => $serviceid));
241     }
243     /**
244      * Get a user token by token
245      * @param string $token
246      * @throws moodle_exception if there is multiple result
247      */
248     public function get_user_ws_token($token) {
249         global $DB;
250         return $DB->get_record('external_tokens', array('token'=>$token), '*', MUST_EXIST);
251     }
253     /**
254      * Get the list of all functions for given service ids
255      * @param array $serviceids
256      * @return array functions
257      */
258     public function get_external_functions($serviceids) {
259         global $DB;
260         if (!empty($serviceids)) {
261             list($serviceids, $params) = $DB->get_in_or_equal($serviceids);
262             $sql = "SELECT f.*
263                       FROM {external_functions} f
264                      WHERE f.name IN (SELECT sf.functionname
265                                         FROM {external_services_functions} sf
266                                        WHERE sf.externalserviceid $serviceids)";
267             $functions = $DB->get_records_sql($sql, $params);
268         } else {
269             $functions = array();
270         }
271         return $functions;
272     }
274     /**
275      * Get the list of all functions not in the given service id
276      * @param int $serviceid
277      * @return array functions
278      */
279     public function get_not_associated_external_functions($serviceid) {
280         global $DB;
281         $select = "name NOT IN (SELECT s.functionname
282                                   FROM {external_services_functions} s
283                                  WHERE s.externalserviceid = :sid
284                                )";
286         $functions = $DB->get_records_select('external_functions',
287                         $select, array('sid' => $serviceid), 'name');
289         return $functions;
290     }
292     /**
293      * Get list of required capabilities of a service, sorted by functions
294      * @param integer $serviceid
295      * @return array
296      * example of return value:
297      *  Array
298      *  (
299      *    [moodle_group_create_groups] => Array
300      *    (
301      *       [0] => moodle/course:managegroups
302      *    )
303      *
304      *    [moodle_enrol_get_enrolled_users] => Array
305      *    (
306      *       [0] => moodle/site:viewparticipants
307      *       [1] => moodle/course:viewparticipants
308      *       [2] => moodle/role:review
309      *       [3] => moodle/site:accessallgroups
310      *       [4] => moodle/course:enrolreview
311      *    )
312      *  )
313      */
314     public function get_service_required_capabilities($serviceid) {
315         $functions = $this->get_external_functions(array($serviceid));
316         $requiredusercaps = array();
317         foreach ($functions as $function) {
318             $functioncaps = split(',', $function->capabilities);
319             if (!empty($functioncaps) and !empty($functioncaps[0])) {
320                 foreach ($functioncaps as $functioncap) {
321                     $requiredusercaps[$function->name][] = trim($functioncap);
322                 }
323             }
324         }
325         return $requiredusercaps;
326     }
328     /**
329      * Get user capabilities (with context)
330      * Only usefull for documentation purpose
331      * @param integer $userid
332      * @return array
333      */
334     public function get_user_capabilities($userid) {
335         global $DB;
336         //retrieve the user capabilities
337         $sql = "SELECT rc.id, rc.capability FROM {role_capabilities} rc, {role_assignments} ra
338             WHERE rc.roleid=ra.roleid AND ra.userid= ?";
339         $dbusercaps = $DB->get_records_sql($sql, array($userid));
340         $usercaps = array();
341         foreach ($dbusercaps as $usercap) {
342             $usercaps[$usercap->capability] = true;
343         }
344         return $usercaps;
345     }
347     /**
348      * Get users missing capabilities for a given service
349      * @param array $users
350      * @param integer $serviceid
351      * @return array of missing capabilities, the key being the user id
352      */
353     public function get_missing_capabilities_by_users($users, $serviceid) {
354         global $DB;
355         $usersmissingcaps = array();
357         //retrieve capabilities required by the service
358         $servicecaps = $this->get_service_required_capabilities($serviceid);
360         //retrieve users missing capabilities
361         foreach ($users as $user) {
362             //cast user array into object to be a bit more flexible
363             if (is_array($user)) {
364                 $user = (object) $user;
365             }
366             $usercaps = $this->get_user_capabilities($user->id);
368             //detect the missing capabilities
369             foreach ($servicecaps as $functioname => $functioncaps) {
370                 foreach ($functioncaps as $functioncap) {
371                     if (!key_exists($functioncap, $usercaps)) {
372                         if (!isset($usersmissingcaps[$user->id])
373                                 or array_search($functioncap, $usersmissingcaps[$user->id]) === false) {
374                             $usersmissingcaps[$user->id][] = $functioncap;
375                         }
376                     }
377                 }
378             }
379         }
381         return $usersmissingcaps;
382     }
384     /**
385      * Get a external service for a given id
386      * @param service id $serviceid
387      * @param integer $strictness IGNORE_MISSING, MUST_EXIST...
388      * @return object external service
389      */
390     public function get_external_service_by_id($serviceid, $strictness=IGNORE_MISSING) {
391         global $DB;
392         $service = $DB->get_record('external_services',
393                         array('id' => $serviceid), '*', $strictness);
394         return $service;
395     }
397     /**
398      * Get a external function for a given id
399      * @param function id $functionid
400      * @param integer $strictness IGNORE_MISSING, MUST_EXIST...
401      * @return object external function
402      */
403     public function get_external_function_by_id($functionid, $strictness=IGNORE_MISSING) {
404         global $DB;
405         $function = $DB->get_record('external_functions',
406                             array('id' => $functionid), '*', $strictness);
407         return $function;
408     }
410     /**
411      * Add a function to a service
412      * @param string $functionname
413      * @param integer $serviceid
414      */
415     public function add_external_function_to_service($functionname, $serviceid) {
416         global $DB;
417         $addedfunction = new stdClass();
418         $addedfunction->externalserviceid = $serviceid;
419         $addedfunction->functionname = $functionname;
420         $DB->insert_record('external_services_functions', $addedfunction);
421     }
423     /**
424      * Add a service
425      * @param object $service
426      * @return serviceid integer
427      */
428     public function add_external_service($service) {
429         global $DB;
430         $service->timecreated = mktime();
431         $serviceid = $DB->insert_record('external_services', $service);
432         return $serviceid;
433     }
435      /**
436      * Update a service
437      * @param object $service
438      */
439     public function update_external_service($service) {
440         global $DB;
441         $service->timemodified = mktime();
442         $DB->update_record('external_services', $service);
443     }
445     /**
446      * Test whether a external function is already linked to a service
447      * @param string $functionname
448      * @param integer $serviceid
449      * @return bool true if a matching function exists for the service, else false.
450      * @throws dml_exception if error
451      */
452     public function service_function_exists($functionname, $serviceid) {
453         global $DB;
454         return $DB->record_exists('external_services_functions',
455                             array('externalserviceid' => $serviceid,
456                                 'functionname' => $functionname));
457     }
459     public function remove_external_function_from_service($functionname, $serviceid) {
460         global $DB;
461         $DB->delete_records('external_services_functions',
462                     array('externalserviceid' => $serviceid, 'functionname' => $functionname));
464     }
469 /**
470  * Exception indicating access control problem in web service call
471  * @author Petr Skoda (skodak)
472  */
473 class webservice_access_exception extends moodle_exception {
474     /**
475      * Constructor
476      */
477     function __construct($debuginfo) {
478         parent::__construct('accessexception', 'webservice', '', null, $debuginfo);
479     }
482 /**
483  * Is protocol enabled?
484  * @param string $protocol name of WS protocol
485  * @return bool
486  */
487 function webservice_protocol_is_enabled($protocol) {
488     global $CFG;
490     if (empty($CFG->enablewebservices)) {
491         return false;
492     }
494     $active = explode(',', $CFG->webserviceprotocols);
496     return(in_array($protocol, $active));
499 //=== WS classes ===
501 /**
502  * Mandatory interface for all test client classes.
503  * @author Petr Skoda (skodak)
504  */
505 interface webservice_test_client_interface {
506     /**
507      * Execute test client WS request
508      * @param string $serverurl
509      * @param string $function
510      * @param array $params
511      * @return mixed
512      */
513     public function simpletest($serverurl, $function, $params);
516 /**
517  * Mandatory interface for all web service protocol classes
518  * @author Petr Skoda (skodak)
519  */
520 interface webservice_server_interface {
521     /**
522      * Process request from client.
523      * @return void
524      */
525     public function run();
528 /**
529  * Abstract web service base class.
530  * @author Petr Skoda (skodak)
531  */
532 abstract class webservice_server implements webservice_server_interface {
534     /** @property string $wsname name of the web server plugin */
535     protected $wsname = null;
537     /** @property string $username name of local user */
538     protected $username = null;
540     /** @property string $password password of the local user */
541     protected $password = null;
543     /** @property int $userid the local user */
544     protected $userid = null;
546     /** @property integer $authmethod authentication method one of WEBSERVICE_AUTHMETHOD_* */
547     protected $authmethod;
549     /** @property string $token authentication token*/
550     protected $token = null;
552     /** @property object restricted context */
553     protected $restricted_context;
555     /** @property int restrict call to one service id*/
556     protected $restricted_serviceid = null;
558     /**
559      * Contructor
560      * @param integer $authmethod authentication method one of WEBSERVICE_AUTHMETHOD_*
561      */
562     public function __construct($authmethod) {
563         $this->authmethod = $authmethod;
564     }
567     /**
568      * Authenticate user using username+password or token.
569      * This function sets up $USER global.
570      * It is safe to use has_capability() after this.
571      * This method also verifies user is allowed to use this
572      * server.
573      * @return void
574      */
575     protected function authenticate_user() {
576         global $CFG, $DB;
578         if (!NO_MOODLE_COOKIES) {
579             throw new coding_exception('Cookies must be disabled in WS servers!');
580         }
582         if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
584             //we check that authentication plugin is enabled
585             //it is only required by simple authentication
586             if (!is_enabled_auth('webservice')) {
587                 throw new webservice_access_exception(get_string('wsauthnotenabled', 'webservice'));
588             }
590             if (!$auth = get_auth_plugin('webservice')) {
591                 throw new webservice_access_exception(get_string('wsauthmissing', 'webservice'));
592             }
594             $this->restricted_context = get_context_instance(CONTEXT_SYSTEM);
596             if (!$this->username) {
597                 throw new webservice_access_exception(get_string('missingusername', 'webservice'));
598             }
600             if (!$this->password) {
601                 throw new webservice_access_exception(get_string('missingpassword', 'webservice'));
602             }
604             if (!$auth->user_login_webservice($this->username, $this->password)) {
605                 // log failed login attempts
606                 add_to_log(SITEID, 'webservice', get_string('simpleauthlog', 'webservice'), '' , get_string('failedtolog', 'webservice').": ".$this->username."/".$this->password." - ".getremoteaddr() , 0);
607                 throw new webservice_access_exception(get_string('wrongusernamepassword', 'webservice'));
608             }
610             $user = $DB->get_record('user', array('username'=>$this->username, 'mnethostid'=>$CFG->mnet_localhost_id, 'deleted'=>0), '*', MUST_EXIST);
612         } else if ($this->authmethod == WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN){
613             $user = $this->authenticate_by_token(EXTERNAL_TOKEN_PERMANENT);
614         } else {
615             $user = $this->authenticate_by_token(EXTERNAL_TOKEN_EMBEDDED);
616         }
618         // now fake user login, the session is completely empty too
619         session_set_user($user);
620         $this->userid = $user->id;
622         if ($this->authmethod != WEBSERVICE_AUTHMETHOD_SESSION_TOKEN && !has_capability("webservice/$this->wsname:use", $this->restricted_context)) {
623             throw new webservice_access_exception(get_string('accessnotallowed', 'webservice'));
624         }
626         external_api::set_context_restriction($this->restricted_context);
627     }
629     protected function authenticate_by_token($tokentype){
630         global $DB;
631         if (!$token = $DB->get_record('external_tokens', array('token'=>$this->token, 'tokentype'=>$tokentype))) {
632             // log failed login attempts
633             add_to_log(SITEID, 'webservice', get_string('tokenauthlog', 'webservice'), '' , get_string('failedtolog', 'webservice').": ".$this->token. " - ".getremoteaddr() , 0);
634             throw new webservice_access_exception(get_string('invalidtoken', 'webservice'));
635         }
637         if ($token->validuntil and $token->validuntil < time()) {
638             $DB->delete_records('external_tokens', array('token'=>$this->token, 'tokentype'=>$tokentype));
639             throw new webservice_access_exception(get_string('invalidtimedtoken', 'webservice'));
640         }
642         if ($token->sid){//assumes that if sid is set then there must be a valid associated session no matter the token type
643             $session = session_get_instance();
644             if (!$session->session_exists($token->sid)){
645                 $DB->delete_records('external_tokens', array('sid'=>$token->sid));
646                 throw new webservice_access_exception(get_string('invalidtokensession', 'webservice'));
647             }
648         }
650         if ($token->iprestriction and !address_in_subnet(getremoteaddr(), $token->iprestriction)) {
651             add_to_log(SITEID, 'webservice', get_string('tokenauthlog', 'webservice'), '' , get_string('failedtolog', 'webservice').": ".getremoteaddr() , 0);
652             throw new webservice_access_exception(get_string('invalidiptoken', 'webservice'));
653         }
655         $this->restricted_context = get_context_instance_by_id($token->contextid);
656         $this->restricted_serviceid = $token->externalserviceid;
658         $user = $DB->get_record('user', array('id'=>$token->userid, 'deleted'=>0), '*', MUST_EXIST);
660         // log token access
661         $DB->set_field('external_tokens', 'lastaccess', time(), array('id'=>$token->id));
663         return $user;
665     }
668 /**
669  * Special abstraction of our srvices that allows
670  * interaction with stock Zend ws servers.
671  * @author Petr Skoda (skodak)
672  */
673 abstract class webservice_zend_server extends webservice_server {
675     /** @property string name of the zend server class : Zend_XmlRpc_Server, Zend_Soap_Server, Zend_Soap_AutoDiscover, ...*/
676     protected $zend_class;
678     /** @property object Zend server instance */
679     protected $zend_server;
681     /** @property string $service_class virtual web service class with all functions user name execute, created on the fly */
682     protected $service_class;
684     /**
685      * Contructor
686      * @param integer $authmethod authentication method - one of WEBSERVICE_AUTHMETHOD_*
687      */
688     public function __construct($authmethod, $zend_class) {
689         parent::__construct($authmethod);
690         $this->zend_class = $zend_class;
691     }
693     /**
694      * Process request from client.
695      * @param bool $simple use simple authentication
696      * @return void
697      */
698     public function run() {
699         // we will probably need a lot of memory in some functions
700         raise_memory_limit(MEMORY_EXTRA);
702         // set some longer timeout, this script is not sending any output,
703         // this means we need to manually extend the timeout operations
704         // that need longer time to finish
705         external_api::set_timeout();
707         // now create the instance of zend server
708         $this->init_zend_server();
710         // set up exception handler first, we want to sent them back in correct format that
711         // the other system understands
712         // we do not need to call the original default handler because this ws handler does everything
713         set_exception_handler(array($this, 'exception_handler'));
715         // init all properties from the request data
716         $this->parse_request();
718         // this sets up $USER and $SESSION and context restrictions
719         $this->authenticate_user();
721         // make a list of all functions user is allowed to excecute
722         $this->init_service_class();
724         // tell server what functions are available
725         $this->zend_server->setClass($this->service_class);
727         //log the web service request
728         add_to_log(SITEID, 'webservice', '', '' , $this->zend_class." ".getremoteaddr() , 0, $this->userid);
730         // execute and return response, this sends some headers too
731         $response = $this->zend_server->handle();
733         // session cleanup
734         $this->session_cleanup();
736         //finally send the result
737         $this->send_headers();
738         echo $response;
739         die;
740     }
742     /**
743      * Load virtual class needed for Zend api
744      * @return void
745      */
746     protected function init_service_class() {
747         global $USER, $DB;
749         // first ofall get a complete list of services user is allowed to access
751         if ($this->restricted_serviceid) {
752             $params = array('sid1'=>$this->restricted_serviceid, 'sid2'=>$this->restricted_serviceid);
753             $wscond1 = 'AND s.id = :sid1';
754             $wscond2 = 'AND s.id = :sid2';
755         } else {
756             $params = array();
757             $wscond1 = '';
758             $wscond2 = '';
759         }
761         // now make sure the function is listed in at least one service user is allowed to use
762         // allow access only if:
763         //  1/ entry in the external_services_users table if required
764         //  2/ validuntil not reached
765         //  3/ has capability if specified in service desc
766         //  4/ iprestriction
768         $sql = "SELECT s.*, NULL AS iprestriction
769                   FROM {external_services} s
770                   JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 0)
771                  WHERE s.enabled = 1 $wscond1
773                  UNION
775                 SELECT s.*, su.iprestriction
776                   FROM {external_services} s
777                   JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 1)
778                   JOIN {external_services_users} su ON (su.externalserviceid = s.id AND su.userid = :userid)
779                  WHERE s.enabled = 1 AND su.validuntil IS NULL OR su.validuntil < :now $wscond2";
781         $params = array_merge($params, array('userid'=>$USER->id, 'now'=>time()));
783         $serviceids = array();
784         $rs = $DB->get_recordset_sql($sql, $params);
786         // now make sure user may access at least one service
787         $remoteaddr = getremoteaddr();
788         $allowed = false;
789         foreach ($rs as $service) {
790             if (isset($serviceids[$service->id])) {
791                 continue;
792             }
793             if ($service->requiredcapability and !has_capability($service->requiredcapability, $this->restricted_context)) {
794                 continue; // cap required, sorry
795             }
796             if ($service->iprestriction and !address_in_subnet($remoteaddr, $service->iprestriction)) {
797                 continue; // wrong request source ip, sorry
798             }
799             $serviceids[$service->id] = $service->id;
800         }
801         $rs->close();
803         // now get the list of all functions
804         $wsmanager = new webservice();
805         $functions = $wsmanager->get_external_functions($serviceids);
807         // now make the virtual WS class with all the fuctions for this particular user
808         $methods = '';
809         foreach ($functions as $function) {
810             $methods .= $this->get_virtual_method_code($function);
811         }
813         // let's use unique class name, there might be problem in unit tests
814         $classname = 'webservices_virtual_class_000000';
815         while(class_exists($classname)) {
816             $classname++;
817         }
819         $code = '
820 /**
821  * Virtual class web services for user id '.$USER->id.' in context '.$this->restricted_context->id.'.
822  */
823 class '.$classname.' {
824 '.$methods.'
826 ';
828         // load the virtual class definition into memory
829         eval($code);
830         $this->service_class = $classname;
831     }
833     /**
834      * returns virtual method code
835      * @param object $function
836      * @return string PHP code
837      */
838     protected function get_virtual_method_code($function) {
839         global $CFG;
841         $function = external_function_info($function);
843         //arguments in function declaration line with defaults.
844         $paramanddefaults      = array();
845         //arguments used as parameters for external lib call.
846         $params      = array();
847         $params_desc = array();
848         foreach ($function->parameters_desc->keys as $name=>$keydesc) {
849             $param = '$'.$name;
850             $paramanddefault = $param;
851             //need to generate the default if there is any
852             if ($keydesc instanceof external_value) {
853                 if ($keydesc->required == VALUE_DEFAULT) {
854                     if ($keydesc->default===null) {
855                         $paramanddefault .= '=null';
856                     } else {
857                         switch($keydesc->type) {
858                             case PARAM_BOOL:
859                                 $paramanddefault .= '='.$keydesc->default; break;
860                             case PARAM_INT:
861                                 $paramanddefault .= '='.$keydesc->default; break;
862                             case PARAM_FLOAT;
863                                 $paramanddefault .= '='.$keydesc->default; break;
864                             default:
865                                 $paramanddefault .= '=\''.$keydesc->default.'\'';
866                         }
867                     }
868                 } else if ($keydesc->required == VALUE_OPTIONAL) {
869                     //it does make sens to declare a parameter VALUE_OPTIONAL
870                     //VALUE_OPTIONAL is used only for array/object key
871                     throw new moodle_exception('parametercannotbevalueoptional');
872                 }
873             } else { //for the moment we do not support default for other structure types
874                  if ($keydesc->required == VALUE_DEFAULT) {
875                      //accept empty array as default
876                      if (isset($keydesc->default) and is_array($keydesc->default)
877                              and empty($keydesc->default)) {
878                          $paramanddefault .= '=array()';
879                      } else {
880                         throw new moodle_exception('errornotemptydefaultparamarray', 'webservice', '', $name);
881                      }
882                  }
883                  if ($keydesc->required == VALUE_OPTIONAL) {
884                      throw new moodle_exception('erroroptionalparamarray', 'webservice', '', $name);
885                  }
886             }
887             $params[] = $param;
888             $paramanddefaults[] = $paramanddefault;
889             $type = 'string';
890             if ($keydesc instanceof external_value) {
891                 switch($keydesc->type) {
892                     case PARAM_BOOL: // 0 or 1 only for now
893                     case PARAM_INT:
894                         $type = 'int'; break;
895                     case PARAM_FLOAT;
896                         $type = 'double'; break;
897                     default:
898                         $type = 'string';
899                 }
900             } else if ($keydesc instanceof external_single_structure) {
901                 $type = 'object|struct';
902             } else if ($keydesc instanceof external_multiple_structure) {
903                 $type = 'array';
904             }
905             $params_desc[] = '     * @param '.$type.' $'.$name.' '.$keydesc->desc;
906         }
907         $params                = implode(', ', $params);
908         $paramanddefaults      = implode(', ', $paramanddefaults);
909         $params_desc           = implode("\n", $params_desc);
911         $serviceclassmethodbody = $this->service_class_method_body($function, $params);
913         if (is_null($function->returns_desc)) {
914             $return = '     * @return void';
915         } else {
916             $type = 'string';
917             if ($function->returns_desc instanceof external_value) {
918                 switch($function->returns_desc->type) {
919                     case PARAM_BOOL: // 0 or 1 only for now
920                     case PARAM_INT:
921                         $type = 'int'; break;
922                     case PARAM_FLOAT;
923                         $type = 'double'; break;
924                     default:
925                         $type = 'string';
926                 }
927             } else if ($function->returns_desc instanceof external_single_structure) {
928                 $type = 'object|struct'; //only 'object' is supported by SOAP, 'struct' by XML-RPC MDL-23083
929             } else if ($function->returns_desc instanceof external_multiple_structure) {
930                 $type = 'array';
931             }
932             $return = '     * @return '.$type.' '.$function->returns_desc->desc;
933         }
935         // now crate the virtual method that calls the ext implementation
937         $code = '
938     /**
939      * '.$function->description.'
940      *
941 '.$params_desc.'
942 '.$return.'
943      */
944     public function '.$function->name.'('.$paramanddefaults.') {
945 '.$serviceclassmethodbody.'
946     }
947 ';
948         return $code;
949     }
951     /**
952      * You can override this function in your child class to add extra code into the dynamically
953      * created service class. For example it is used in the amf server to cast types of parameters and to
954      * cast the return value to the types as specified in the return value description.
955      * @param stdClass $function
956      * @param array $params
957      * @return string body of the method for $function ie. everything within the {} of the method declaration.
958      */
959     protected function service_class_method_body($function, $params){
960         //cast the param from object to array (validate_parameters except array only)
961         $castingcode = '';
962         if ($params){
963             $paramstocast = explode(',', $params);
964             foreach ($paramstocast as $paramtocast) {
965                 //clean the parameter from any white space
966                 $paramtocast = trim($paramtocast);
967                 $castingcode .= $paramtocast .
968                 '=webservice_zend_server::cast_objects_to_array('.$paramtocast.');';
969             }
971         }
973         $descriptionmethod = $function->methodname.'_returns()';
974         $callforreturnvaluedesc = $function->classname.'::'.$descriptionmethod;
975         return $castingcode . '    if ('.$callforreturnvaluedesc.' == null)  {'.
976                         $function->classname.'::'.$function->methodname.'('.$params.');
977                         return null;
978                     }
979                     return external_api::clean_returnvalue('.$callforreturnvaluedesc.', '.$function->classname.'::'.$function->methodname.'('.$params.'));';
980     }
982     /**
983      * Recursive function to recurse down into a complex variable and convert all
984      * objects to arrays.
985      * @param mixed $param value to cast
986      * @return mixed Cast value
987      */
988     public static function cast_objects_to_array($param){
989         if (is_object($param)){
990             $param = (array)$param;
991         }
992         if (is_array($param)){
993             $toreturn = array();
994             foreach ($param as $key=> $param){
995                 $toreturn[$key] = self::cast_objects_to_array($param);
996             }
997             return $toreturn;
998         } else {
999             return $param;
1000         }
1001     }
1003     /**
1004      * Set up zend service class
1005      * @return void
1006      */
1007     protected function init_zend_server() {
1008         $this->zend_server = new $this->zend_class();
1009     }
1011     /**
1012      * This method parses the $_REQUEST superglobal and looks for
1013      * the following information:
1014      *  1/ user authentication - username+password or token (wsusername, wspassword and wstoken parameters)
1015      *
1016      * @return void
1017      */
1018     protected function parse_request() {
1019         if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
1020             //note: some clients have problems with entity encoding :-(
1021             if (isset($_REQUEST['wsusername'])) {
1022                 $this->username = $_REQUEST['wsusername'];
1023             }
1024             if (isset($_REQUEST['wspassword'])) {
1025                 $this->password = $_REQUEST['wspassword'];
1026             }
1027         } else {
1028             if (isset($_REQUEST['wstoken'])) {
1029                 $this->token = $_REQUEST['wstoken'];
1030             }
1031         }
1032     }
1034     /**
1035      * Internal implementation - sending of page headers.
1036      * @return void
1037      */
1038     protected function send_headers() {
1039         header('Cache-Control: private, must-revalidate, pre-check=0, post-check=0, max-age=0');
1040         header('Expires: '. gmdate('D, d M Y H:i:s', 0) .' GMT');
1041         header('Pragma: no-cache');
1042         header('Accept-Ranges: none');
1043     }
1045     /**
1046      * Specialised exception handler, we can not use the standard one because
1047      * it can not just print html to output.
1048      *
1049      * @param exception $ex
1050      * @return void does not return
1051      */
1052     public function exception_handler($ex) {
1053         // detect active db transactions, rollback and log as error
1054         abort_all_db_transactions();
1056         // some hacks might need a cleanup hook
1057         $this->session_cleanup($ex);
1059         // now let the plugin send the exception to client
1060         $this->send_error($ex);
1062         // not much else we can do now, add some logging later
1063         exit(1);
1064     }
1066     /**
1067      * Send the error information to the WS client
1068      * formatted as XML document.
1069      * @param exception $ex
1070      * @return void
1071      */
1072     protected function send_error($ex=null) {
1073         $this->send_headers();
1074         echo $this->zend_server->fault($ex);
1075     }
1077     /**
1078      * Future hook needed for emulated sessions.
1079      * @param exception $exception null means normal termination, $exception received when WS call failed
1080      * @return void
1081      */
1082     protected function session_cleanup($exception=null) {
1083         if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
1084             // nothing needs to be done, there is no persistent session
1085         } else {
1086             // close emulated session if used
1087         }
1088     }
1092 /**
1093  * Web Service server base class, this class handles both
1094  * simple and token authentication.
1095  * @author Petr Skoda (skodak)
1096  */
1097 abstract class webservice_base_server extends webservice_server {
1099     /** @property array $parameters the function parameters - the real values submitted in the request */
1100     protected $parameters = null;
1102     /** @property string $functionname the name of the function that is executed */
1103     protected $functionname = null;
1105     /** @property object $function full function description */
1106     protected $function = null;
1108     /** @property mixed $returns function return value */
1109     protected $returns = null;
1111     /**
1112      * This method parses the request input, it needs to get:
1113      *  1/ user authentication - username+password or token
1114      *  2/ function name
1115      *  3/ function parameters
1116      *
1117      * @return void
1118      */
1119     abstract protected function parse_request();
1121     /**
1122      * Send the result of function call to the WS client.
1123      * @return void
1124      */
1125     abstract protected function send_response();
1127     /**
1128      * Send the error information to the WS client.
1129      * @param exception $ex
1130      * @return void
1131      */
1132     abstract protected function send_error($ex=null);
1134     /**
1135      * Process request from client.
1136      * @return void
1137      */
1138     public function run() {
1139         // we will probably need a lot of memory in some functions
1140         raise_memory_limit(MEMORY_EXTRA);
1142         // set some longer timeout, this script is not sending any output,
1143         // this means we need to manually extend the timeout operations
1144         // that need longer time to finish
1145         external_api::set_timeout();
1147         // set up exception handler first, we want to sent them back in correct format that
1148         // the other system understands
1149         // we do not need to call the original default handler because this ws handler does everything
1150         set_exception_handler(array($this, 'exception_handler'));
1152         // init all properties from the request data
1153         $this->parse_request();
1155         // authenticate user, this has to be done after the request parsing
1156         // this also sets up $USER and $SESSION
1157         $this->authenticate_user();
1159         // find all needed function info and make sure user may actually execute the function
1160         $this->load_function_info();
1162         //log the web service request
1163         add_to_log(SITEID, 'webservice', $this->functionname, '' , getremoteaddr() , 0, $this->userid);
1165         // finally, execute the function - any errors are catched by the default exception handler
1166         $this->execute();
1168         // send the results back in correct format
1169         $this->send_response();
1171         // session cleanup
1172         $this->session_cleanup();
1174         die;
1175     }
1177     /**
1178      * Specialised exception handler, we can not use the standard one because
1179      * it can not just print html to output.
1180      *
1181      * @param exception $ex
1182      * @return void does not return
1183      */
1184     public function exception_handler($ex) {
1185         // detect active db transactions, rollback and log as error
1186         abort_all_db_transactions();
1188         // some hacks might need a cleanup hook
1189         $this->session_cleanup($ex);
1191         // now let the plugin send the exception to client
1192         $this->send_error($ex);
1194         // not much else we can do now, add some logging later
1195         exit(1);
1196     }
1198     /**
1199      * Future hook needed for emulated sessions.
1200      * @param exception $exception null means normal termination, $exception received when WS call failed
1201      * @return void
1202      */
1203     protected function session_cleanup($exception=null) {
1204         if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
1205             // nothing needs to be done, there is no persistent session
1206         } else {
1207             // close emulated session if used
1208         }
1209     }
1211     /**
1212      * Fetches the function description from database,
1213      * verifies user is allowed to use this function and
1214      * loads all paremeters and return descriptions.
1215      * @return void
1216      */
1217     protected function load_function_info() {
1218         global $DB, $USER, $CFG;
1220         if (empty($this->functionname)) {
1221             throw new invalid_parameter_exception('Missing function name');
1222         }
1224         // function must exist
1225         $function = external_function_info($this->functionname);
1227         if ($this->restricted_serviceid) {
1228             $params = array('sid1'=>$this->restricted_serviceid, 'sid2'=>$this->restricted_serviceid);
1229             $wscond1 = 'AND s.id = :sid1';
1230             $wscond2 = 'AND s.id = :sid2';
1231         } else {
1232             $params = array();
1233             $wscond1 = '';
1234             $wscond2 = '';
1235         }
1237         // now let's verify access control
1239         // now make sure the function is listed in at least one service user is allowed to use
1240         // allow access only if:
1241         //  1/ entry in the external_services_users table if required
1242         //  2/ validuntil not reached
1243         //  3/ has capability if specified in service desc
1244         //  4/ iprestriction
1246         $sql = "SELECT s.*, NULL AS iprestriction
1247                   FROM {external_services} s
1248                   JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 0 AND sf.functionname = :name1)
1249                  WHERE s.enabled = 1 $wscond1
1251                  UNION
1253                 SELECT s.*, su.iprestriction
1254                   FROM {external_services} s
1255                   JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 1 AND sf.functionname = :name2)
1256                   JOIN {external_services_users} su ON (su.externalserviceid = s.id AND su.userid = :userid)
1257                  WHERE s.enabled = 1 AND su.validuntil IS NULL OR su.validuntil < :now $wscond2";
1258         $params = array_merge($params, array('userid'=>$USER->id, 'name1'=>$function->name, 'name2'=>$function->name, 'now'=>time()));
1260         $rs = $DB->get_recordset_sql($sql, $params);
1261         // now make sure user may access at least one service
1262         $remoteaddr = getremoteaddr();
1263         $allowed = false;
1264         foreach ($rs as $service) {
1265             if ($service->requiredcapability and !has_capability($service->requiredcapability, $this->restricted_context)) {
1266                 continue; // cap required, sorry
1267             }
1268             if ($service->iprestriction and !address_in_subnet($remoteaddr, $service->iprestriction)) {
1269                 continue; // wrong request source ip, sorry
1270             }
1271             $allowed = true;
1272             break; // one service is enough, no need to continue
1273         }
1274         $rs->close();
1275         if (!$allowed) {
1276             throw new webservice_access_exception('Access to external function not allowed');
1277         }
1279         // we have all we need now
1280         $this->function = $function;
1281     }
1283     /**
1284      * Execute previously loaded function using parameters parsed from the request data.
1285      * @return void
1286      */
1287     protected function execute() {
1288         // validate params, this also sorts the params properly, we need the correct order in the next part
1289         $params = call_user_func(array($this->function->classname, 'validate_parameters'), $this->function->parameters_desc, $this->parameters);
1291         // execute - yay!
1292         $this->returns = call_user_func_array(array($this->function->classname, $this->function->methodname), array_values($params));
1293     }