MDL-16094 File storage conversion Quiz and Questions
[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         $serviceuser->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;
75         $params = array($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 username <> 'guest' AND deleted = 0 AND confirmed = 1
82                         AND esu.userid = u.id
83                         AND esu.externalserviceid = ?";
84         if (!empty($userid)) {
85             $sql .= ' AND u.id = ?';
86             $params[] = $userid;
87         }
89         $users = $DB->get_records_sql($sql, $params);
90         return $users;
91     }
93     /**
94      * Return a authorised user with his options (ip/timecreated / validuntil...)
95      * @param int $serviceid
96      * @param int $userid
97      * @return object
98      */
99     public function get_ws_authorised_user($serviceid, $userid) {
100         global $DB;
101         $params = array($serviceid, $userid);
102         $sql = " SELECT u.id as id, esu.id as serviceuserid, u.email as email, u.firstname as firstname,
103                 u.lastname as lastname,
104                   esu.iprestriction as iprestriction, esu.validuntil as validuntil,
105                   esu.timecreated as timecreated
106                   FROM {user} u, {external_services_users} esu
107                   WHERE username <> 'guest' AND deleted = 0 AND confirmed = 1
108                         AND esu.userid = u.id
109                         AND esu.externalserviceid = ?
110                         AND u.id = ?";
111         $user = $DB->get_record_sql($sql, $params);
112         return $user;
113     }
115     /**
116      * Generate all ws token needed by a user
117      * @param int $userid
118      */
119     public function generate_user_ws_tokens($userid) {
120         global $CFG, $DB;
121         
122         /// generate a token for non admin if web service are enable and the user has the capability to create a token
123         if (!is_siteadmin() && has_capability('moodle/webservice:createtoken', get_context_instance(CONTEXT_SYSTEM), $userid) && !empty($CFG->enablewebservices)) {
124         /// for every service than the user is authorised on, create a token (if it doesn't already exist)
126             ///get all services which are set to all user (no restricted to specific users)
127             $norestrictedservices = $DB->get_records('external_services', array('restrictedusers' => 0));
128             $serviceidlist = array();
129             foreach ($norestrictedservices as $service) {
130                 $serviceidlist[] = $service->id;
131             }
133             //get all services which are set to the current user (the current user is specified in the restricted user list)
134             $servicesusers = $DB->get_records('external_services_users', array('userid' => $userid));
135             foreach ($servicesusers as $serviceuser) {
136                 if (!in_array($serviceuser->externalserviceid,$serviceidlist)) {
137                      $serviceidlist[] = $serviceuser->externalserviceid;
138                 }
139             }
141             //get all services which already have a token set for the current user
142             $usertokens = $DB->get_records('external_tokens', array('userid' => $userid, 'tokentype' => EXTERNAL_TOKEN_PERMANENT));
143             $tokenizedservice = array();
144             foreach ($usertokens as $token) {
145                     $tokenizedservice[]  = $token->externalserviceid;
146             }
148             //create a token for the service which have no token already
149             foreach ($serviceidlist as $serviceid) {
150                 if (!in_array($serviceid, $tokenizedservice)) {
151                     //create the token for this service
152                     $newtoken = new object();
153                     $newtoken->token = md5(uniqid(rand(),1));
154                     //check that the user has capability on this service
155                     $newtoken->tokentype = EXTERNAL_TOKEN_PERMANENT;
156                     $newtoken->userid = $userid;
157                     $newtoken->externalserviceid = $serviceid;
158                     //TODO: find a way to get the context - UPDATE FOLLOWING LINE
159                     $newtoken->contextid = get_context_instance(CONTEXT_SYSTEM)->id;
160                     $newtoken->creatorid = $userid;
161                     $newtoken->timecreated = time();
163                     $DB->insert_record('external_tokens', $newtoken);
164                 }
165             }
168         }
169     }
171     /**
172      * Return all ws user token
173      * @param integer $userid
174      * @return array of token
175      */
176     public function get_user_ws_tokens($userid) {
177         global $DB;
178         //here retrieve token list (including linked users firstname/lastname and linked services name)
179         $sql = "SELECT
180                     t.id, t.creatorid, t.token, u.firstname, u.lastname, s.name, t.validuntil
181                 FROM
182                     {external_tokens} t, {user} u, {external_services} s
183                 WHERE
184                     t.userid=? AND t.tokentype = ".EXTERNAL_TOKEN_PERMANENT." AND s.id = t.externalserviceid AND t.userid = u.id";
185         $tokens = $DB->get_records_sql($sql, array( $userid));
186         return $tokens;
187     }
189     /**
190      * Return a user token that has been created by the user
191      * If doesn't exist a exception is thrown
192      * @param integer $userid
193      * @param integer $tokenid
194      * @return object token
195      * ->id token id
196      * ->token
197      * ->firstname user firstname
198      * ->lastname
199      * ->name service name
200      */
201     public function get_created_by_user_ws_token($userid, $tokenid) {
202         global $DB;
203         $sql = "SELECT
204                         t.id, t.token, u.firstname, u.lastname, s.name
205                     FROM
206                         {external_tokens} t, {user} u, {external_services} s
207                     WHERE
208                         t.creatorid=? AND t.id=? AND t.tokentype = "
209                 . EXTERNAL_TOKEN_PERMANENT
210                 . " AND s.id = t.externalserviceid AND t.userid = u.id";
211         //must be the token creator
212         $token = $DB->get_record_sql($sql, array($userid, $tokenid), MUST_EXIST);
213         return $token;
214     }
216     /**
217      * Delete a user token
218      * @param int $tokenid
219      */
220     public function delete_user_ws_token($tokenid) {
221         global $DB;
222         $DB->delete_records('external_tokens', array('id'=>$tokenid));
223     }
225     /**
226      * Get a user token by token
227      * @param string $token
228      * @throws moodle_exception if there is multiple result
229      */
230     public function get_user_ws_token($token) {
231         global $DB;
232         return $DB->get_record('external_tokens', array('token'=>$token), '*', MUST_EXIST);
233     }
235     /**
236      * Get the list of all functions for given service ids
237      * @param array $serviceids
238      * @return array functions
239      */
240     public function get_external_functions($serviceids) {
241         global $DB;
242         if (!empty($serviceids)) {
243             list($serviceids, $params) = $DB->get_in_or_equal($serviceids);
244             $sql = "SELECT f.*
245                       FROM {external_functions} f
246                      WHERE f.name IN (SELECT sf.functionname
247                                         FROM {external_services_functions} sf
248                                        WHERE sf.externalserviceid $serviceids)";
249             $functions = $DB->get_records_sql($sql, $params);
250         } else {
251             $functions = array();
252         }
253         return $functions;
254     }
256     /**
257      * Get the list of all functions not in the given service id
258      * @param int $serviceid
259      * @return array functions
260      */
261     public function get_not_associated_external_functions($serviceid) {
262         global $DB;
263         $select = "name NOT IN (SELECT s.functionname
264                                   FROM {external_services_functions} s
265                                  WHERE s.externalserviceid = :sid
266                                )";
268         $functions = $DB->get_records_select('external_functions',
269                         $select, array('sid' => $serviceid), 'name');
271         return $functions;
272     }
274     /**
275      * Get list of required capabilities of a service, sorted by functions
276      * @param integer $serviceid
277      * @return array
278      * example of return value:
279      *  Array
280      *  (
281      *    [moodle_group_create_groups] => Array
282      *    (
283      *       [0] => moodle/course:managegroups
284      *    )
285      *
286      *    [moodle_enrol_get_enrolled_users] => Array
287      *    (
288      *       [0] => moodle/site:viewparticipants
289      *       [1] => moodle/course:viewparticipants
290      *       [2] => moodle/role:review
291      *       [3] => moodle/site:accessallgroups
292      *       [4] => moodle/course:enrolreview
293      *    )
294      *  )
295      */
296     public function get_service_required_capabilities($serviceid) {
297         $functions = $this->get_external_functions(array($serviceid));
298         $requiredusercaps = array();
299         foreach ($functions as $function) {
300             $functioncaps = split(',', $function->capabilities);
301             if (!empty($functioncaps) and !empty($functioncaps[0])) {
302                 foreach ($functioncaps as $functioncap) {
303                     $requiredusercaps[$function->name][] = trim($functioncap);
304                 }
305             }
306         }
307         return $requiredusercaps;
308     }
310     /**
311      * Get user capabilities (with context)
312      * Only usefull for documentation purpose
313      * @param integer $userid
314      * @return array
315      */
316     public function get_user_capabilities($userid) {
317         global $DB;
318         //retrieve the user capabilities
319         $sql = "SELECT rc.id, rc.capability FROM {role_capabilities} rc, {role_assignments} ra
320             WHERE rc.roleid=ra.roleid AND ra.userid= ?";
321         $dbusercaps = $DB->get_records_sql($sql, array($userid));
322         $usercaps = array();
323         foreach ($dbusercaps as $usercap) {
324             $usercaps[$usercap->capability] = true;
325         }
326         return $usercaps;
327     }
329     /**
330      * Get users missing capabilities for a given service
331      * @param array $users
332      * @param integer $serviceid
333      * @return array of missing capabilities, the key being the user id
334      */
335     public function get_missing_capabilities_by_users($users, $serviceid) {
336         global $DB;
337         $usersmissingcaps = array();
339         //retrieve capabilities required by the service
340         $servicecaps = $this->get_service_required_capabilities($serviceid);
342         //retrieve users missing capabilities
343         foreach ($users as $user) {
344             //cast user array into object to be a bit more flexible
345             if (is_array($user)) {
346                 $user = (object) $user;
347             }
348             $usercaps = $this->get_user_capabilities($user->id);
350             //detect the missing capabilities
351             foreach ($servicecaps as $functioname => $functioncaps) {
352                 foreach ($functioncaps as $functioncap) {
353                     if (!key_exists($functioncap, $usercaps)) {
354                         if (!isset($usersmissingcaps[$user->id])
355                                 or array_search($functioncap, $usersmissingcaps[$user->id]) === false) {
356                             $usersmissingcaps[$user->id][] = $functioncap;
357                         }
358                     }
359                 }
360             }
361         }
363         return $usersmissingcaps;
364     }
366     /**
367      * Get a external function for a given id
368      * @param function id $functionid
369      * @param integer $strictness IGNORE_MISSING, MUST_EXIST...
370      * @return object external function
371      */
372     public function get_external_function_by_id($functionid, $strictness=IGNORE_MISSING) {
373         global $DB;
374         $function = $DB->get_record('external_functions',
375                             array('id' => $functionid), '*', $strictness);
376         return $function;
377     }
379     /**
380      * Add a function to a service
381      * @param string $functionname
382      * @param integer $serviceid
383      */
384     public function add_external_function_to_service($functionname, $serviceid) {
385         global $DB;
386         $addedfunction = new object();
387         $addedfunction->externalserviceid = $serviceid;
388         $addedfunction->functionname = $functionname;
389         $DB->insert_record('external_services_functions', $addedfunction);
390     }
392     /**
393      * Test whether a external function is already linked to a service
394      * @param string $functionname
395      * @param integer $serviceid
396      * @return bool true if a matching function exists for the service, else false.
397      * @throws dml_exception if error
398      */
399     public function service_function_exists($functionname, $serviceid) {
400         global $DB;
401         return $DB->record_exists('external_services_functions',
402                             array('externalserviceid' => $serviceid,
403                                 'functionname' => $functionname));
404     }
406     public function remove_external_function_from_service($functionname, $serviceid) {
407         global $DB;
408         $DB->delete_records('external_services_functions',
409                     array('externalserviceid' => $serviceid, 'functionname' => $functionname));
411     }
416 /**
417  * Exception indicating access control problem in web service call
418  * @author Petr Skoda (skodak)
419  */
420 class webservice_access_exception extends moodle_exception {
421     /**
422      * Constructor
423      */
424     function __construct($debuginfo) {
425         parent::__construct('accessexception', 'webservice', '', null, $debuginfo);
426     }
429 /**
430  * Is protocol enabled?
431  * @param string $protocol name of WS protocol
432  * @return bool
433  */
434 function webservice_protocol_is_enabled($protocol) {
435     global $CFG;
437     if (empty($CFG->enablewebservices)) {
438         return false;
439     }
441     $active = explode(',', $CFG->webserviceprotocols);
443     return(in_array($protocol, $active));
446 //=== WS classes ===
448 /**
449  * Mandatory interface for all test client classes.
450  * @author Petr Skoda (skodak)
451  */
452 interface webservice_test_client_interface {
453     /**
454      * Execute test client WS request
455      * @param string $serverurl
456      * @param string $function
457      * @param array $params
458      * @return mixed
459      */
460     public function simpletest($serverurl, $function, $params);
463 /**
464  * Mandatory interface for all web service protocol classes
465  * @author Petr Skoda (skodak)
466  */
467 interface webservice_server_interface {
468     /**
469      * Process request from client.
470      * @return void
471      */
472     public function run();
475 /**
476  * Abstract web service base class.
477  * @author Petr Skoda (skodak)
478  */
479 abstract class webservice_server implements webservice_server_interface {
481     /** @property string $wsname name of the web server plugin */
482     protected $wsname = null;
484     /** @property string $username name of local user */
485     protected $username = null;
487     /** @property string $password password of the local user */
488     protected $password = null;
490     /** @property int $userid the local user */
491     protected $userid = null;
493     /** @property integer $authmethod authentication method one of WEBSERVICE_AUTHMETHOD_* */
494     protected $authmethod;
496     /** @property string $token authentication token*/
497     protected $token = null;
499     /** @property object restricted context */
500     protected $restricted_context;
502     /** @property int restrict call to one service id*/
503     protected $restricted_serviceid = null;
505     /**
506      * Contructor
507      * @param integer $authmethod authentication method one of WEBSERVICE_AUTHMETHOD_* 
508      */
509     public function __construct($authmethod) {
510         $this->authmethod = $authmethod;
511     }    
512     
513     
514     /**
515      * Authenticate user using username+password or token.
516      * This function sets up $USER global.
517      * It is safe to use has_capability() after this.
518      * This method also verifies user is allowed to use this
519      * server.
520      * @return void
521      */
522     protected function authenticate_user() {
523         global $CFG, $DB;
525         if (!NO_MOODLE_COOKIES) {
526             throw new coding_exception('Cookies must be disabled in WS servers!');
527         }
529         if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
531             //we check that authentication plugin is enabled
532             //it is only required by simple authentication
533             if (!is_enabled_auth('webservice')) {
534                 throw new webservice_access_exception(get_string('wsauthnotenabled', 'webservice'));
535             }
537             if (!$auth = get_auth_plugin('webservice')) {
538                 throw new webservice_access_exception(get_string('wsauthmissing', 'webservice'));
539             }
541             $this->restricted_context = get_context_instance(CONTEXT_SYSTEM);
543             if (!$this->username) {
544                 throw new webservice_access_exception(get_string('missingusername', 'webservice'));
545             }
547             if (!$this->password) {
548                 throw new webservice_access_exception(get_string('missingpassword', 'webservice'));
549             }
551             if (!$auth->user_login_webservice($this->username, $this->password)) {
552                 // log failed login attempts
553                 add_to_log(1, 'webservice', get_string('simpleauthlog', 'webservice'), '' , get_string('failedtolog', 'webservice').": ".$this->username."/".$this->password." - ".getremoteaddr() , 0);
554                 throw new webservice_access_exception(get_string('wrongusernamepassword', 'webservice'));
555             }
557             $user = $DB->get_record('user', array('username'=>$this->username, 'mnethostid'=>$CFG->mnet_localhost_id, 'deleted'=>0), '*', MUST_EXIST);
559         } else if ($this->authmethod == WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN){
560             $user = $this->authenticate_by_token(EXTERNAL_TOKEN_PERMANENT);
561         } else {
562             $user = $this->authenticate_by_token(EXTERNAL_TOKEN_EMBEDDED);
563         }
564         
565         // now fake user login, the session is completely empty too
566         session_set_user($user);
567         $this->userid = $user->id;
569         if ($this->authmethod != WEBSERVICE_AUTHMETHOD_SESSION_TOKEN && !has_capability("webservice/$this->wsname:use", $this->restricted_context)) {
570             throw new webservice_access_exception(get_string('accessnotallowed', 'webservice'));
571         }
573         external_api::set_context_restriction($this->restricted_context);
574     }
575     
576     protected function authenticate_by_token($tokentype){
577         global $DB;
578         if (!$token = $DB->get_record('external_tokens', array('token'=>$this->token, 'tokentype'=>$tokentype))) {
579             // log failed login attempts
580             add_to_log(1, 'webservice', get_string('tokenauthlog', 'webservice'), '' , get_string('failedtolog', 'webservice').": ".$this->token. " - ".getremoteaddr() , 0);
581             throw new webservice_access_exception(get_string('invalidtoken', 'webservice'));
582         }
583     
584         if ($token->validuntil and $token->validuntil < time()) {
585             $DB->delete_records('external_tokens', array('token'=>$this->token, 'tokentype'=>$tokentype));
586             throw new webservice_access_exception(get_string('invalidtimedtoken', 'webservice'));
587         }
588         
589         if ($token->sid){//assumes that if sid is set then there must be a valid associated session no matter the token type
590             $session = session_get_instance();
591             if (!$session->session_exists($token->sid)){
592                 $DB->delete_records('external_tokens', array('sid'=>$token->sid));
593                 throw new webservice_access_exception(get_string('invalidtokensession', 'webservice'));
594             }
595         }
597         if ($token->iprestriction and !address_in_subnet(getremoteaddr(), $token->iprestriction)) {
598             add_to_log(1, 'webservice', get_string('tokenauthlog', 'webservice'), '' , get_string('failedtolog', 'webservice').": ".getremoteaddr() , 0);
599             throw new webservice_access_exception(get_string('invalidiptoken', 'webservice'));
600         }
602         $this->restricted_context = get_context_instance_by_id($token->contextid);
603         $this->restricted_serviceid = $token->externalserviceid;
605         $user = $DB->get_record('user', array('id'=>$token->userid, 'deleted'=>0), '*', MUST_EXIST);
607         // log token access
608         $DB->set_field('external_tokens', 'lastaccess', time(), array('id'=>$token->id));
609         
610         return $user;
611         
612     }
615 /**
616  * Special abstraction of our srvices that allows
617  * interaction with stock Zend ws servers.
618  * @author Petr Skoda (skodak)
619  */
620 abstract class webservice_zend_server extends webservice_server {
622     /** @property string name of the zend server class : Zend_XmlRpc_Server, Zend_Soap_Server, Zend_Soap_AutoDiscover, ...*/
623     protected $zend_class;
625     /** @property object Zend server instance */
626     protected $zend_server;
628     /** @property string $service_class virtual web service class with all functions user name execute, created on the fly */
629     protected $service_class;
631     /**
632      * Contructor
633      * @param integer $authmethod authentication method - one of WEBSERVICE_AUTHMETHOD_*
634      */
635     public function __construct($authmethod, $zend_class) {
636         parent::__construct($authmethod);
637         $this->zend_class = $zend_class;
638     }
640     /**
641      * Process request from client.
642      * @param bool $simple use simple authentication
643      * @return void
644      */
645     public function run() {
646         // we will probably need a lot of memory in some functions
647         @raise_memory_limit('128M');
649         // set some longer timeout, this script is not sending any output,
650         // this means we need to manually extend the timeout operations
651         // that need longer time to finish
652         external_api::set_timeout();
654         // now create the instance of zend server
655         $this->init_zend_server();
657         // set up exception handler first, we want to sent them back in correct format that
658         // the other system understands
659         // we do not need to call the original default handler because this ws handler does everything
660         set_exception_handler(array($this, 'exception_handler'));
662         // init all properties from the request data
663         $this->parse_request();
665         // this sets up $USER and $SESSION and context restrictions
666         $this->authenticate_user();
668         // make a list of all functions user is allowed to excecute
669         $this->init_service_class();
671         // tell server what functions are available
672         $this->zend_server->setClass($this->service_class);
674         //log the web service request
675         add_to_log(1, 'webservice', '', '' , $this->zend_class." ".getremoteaddr() , 0, $this->userid);
677         // execute and return response, this sends some headers too
678         $response = $this->zend_server->handle();
680         // session cleanup
681         $this->session_cleanup();
683         //finally send the result
684         $this->send_headers();
685         echo $response;
686         die;
687     }
689     /**
690      * Load virtual class needed for Zend api
691      * @return void
692      */
693     protected function init_service_class() {
694         global $USER, $DB;
696         // first ofall get a complete list of services user is allowed to access
698         if ($this->restricted_serviceid) {
699             $params = array('sid1'=>$this->restricted_serviceid, 'sid2'=>$this->restricted_serviceid);
700             $wscond1 = 'AND s.id = :sid1';
701             $wscond2 = 'AND s.id = :sid2';
702         } else {
703             $params = array();
704             $wscond1 = '';
705             $wscond2 = '';
706         }
708         // now make sure the function is listed in at least one service user is allowed to use
709         // allow access only if:
710         //  1/ entry in the external_services_users table if required
711         //  2/ validuntil not reached
712         //  3/ has capability if specified in service desc
713         //  4/ iprestriction
715         $sql = "SELECT s.*, NULL AS iprestriction
716                   FROM {external_services} s
717                   JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 0)
718                  WHERE s.enabled = 1 $wscond1
720                  UNION
722                 SELECT s.*, su.iprestriction
723                   FROM {external_services} s
724                   JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 1)
725                   JOIN {external_services_users} su ON (su.externalserviceid = s.id AND su.userid = :userid)
726                  WHERE s.enabled = 1 AND su.validuntil IS NULL OR su.validuntil < :now $wscond2";
728         $params = array_merge($params, array('userid'=>$USER->id, 'now'=>time()));
730         $serviceids = array();
731         $rs = $DB->get_recordset_sql($sql, $params);
733         // now make sure user may access at least one service
734         $remoteaddr = getremoteaddr();
735         $allowed = false;
736         foreach ($rs as $service) {
737             if (isset($serviceids[$service->id])) {
738                 continue;
739             }
740             if ($service->requiredcapability and !has_capability($service->requiredcapability, $this->restricted_context)) {
741                 continue; // cap required, sorry
742             }
743             if ($service->iprestriction and !address_in_subnet($remoteaddr, $service->iprestriction)) {
744                 continue; // wrong request source ip, sorry
745             }
746             $serviceids[$service->id] = $service->id;
747         }
748         $rs->close();
750         // now get the list of all functions
751         $wsmanager = new webservice();
752         $functions = $wsmanager->get_external_functions($serviceids);
754         // now make the virtual WS class with all the fuctions for this particular user
755         $methods = '';
756         foreach ($functions as $function) {
757             $methods .= $this->get_virtual_method_code($function);
758         }
760         // let's use unique class name, there might be problem in unit tests
761         $classname = 'webservices_virtual_class_000000';
762         while(class_exists($classname)) {
763             $classname++;
764         }
766         $code = '
767 /**
768  * Virtual class web services for user id '.$USER->id.' in context '.$this->restricted_context->id.'.
769  */
770 class '.$classname.' {
771 '.$methods.'
773 ';
775         // load the virtual class definition into memory
776         eval($code);
777         $this->service_class = $classname;
778     }
780     /**
781      * returns virtual method code
782      * @param object $function
783      * @return string PHP code
784      */
785     protected function get_virtual_method_code($function) {
786         global $CFG;
788         $function = external_function_info($function);
790         //arguments in function declaration line with defaults.
791         $paramanddefaults      = array();
792         //arguments used as parameters for external lib call.
793         $params      = array();
794         $params_desc = array();
795         foreach ($function->parameters_desc->keys as $name=>$keydesc) {
796             $param = '$'.$name;
797             $paramanddefault = $param;
798             //need to generate the default if there is any
799             if ($keydesc instanceof external_value) {
800                 if ($keydesc->required == VALUE_DEFAULT) {
801                     if ($keydesc->default===null) {
802                         $paramanddefault .= '=null';
803                     } else {
804                         switch($keydesc->type) {
805                             case PARAM_BOOL:
806                                 $paramanddefault .= '='.$keydesc->default; break;
807                             case PARAM_INT:
808                                 $paramanddefault .= '='.$keydesc->default; break;
809                             case PARAM_FLOAT;
810                                 $paramanddefault .= '='.$keydesc->default; break;
811                             default:
812                                 $paramanddefault .= '=\''.$keydesc->default.'\'';
813                         }
814                     }
815                 } else if ($keydesc->required == VALUE_OPTIONAL) {
816                     //it does make sens to declare a parameter VALUE_OPTIONAL
817                     //VALUE_OPTIONAL is used only for array/object key
818                     throw new moodle_exception('parametercannotbevalueoptional');
819                 }
820             } else { //for the moment we do not support default for other structure types
821                  if ($keydesc->required == VALUE_DEFAULT) {
822                      //accept empty array as default
823                      if (isset($keydesc->default) and is_array($keydesc->default)
824                              and empty($keydesc->default)) {
825                          $paramanddefault .= '=array()';
826                      } else {
827                         throw new moodle_exception('errornotemptydefaultparamarray', 'webservice', '', $name);
828                      }
829                  }
830                  if ($keydesc->required == VALUE_OPTIONAL) {
831                      throw new moodle_exception('erroroptionalparamarray', 'webservice', '', $name);
832                  }
833             }
834             $params[] = $param;
835             $paramanddefaults[] = $paramanddefault;
836             $type = 'string';
837             if ($keydesc instanceof external_value) {
838                 switch($keydesc->type) {
839                     case PARAM_BOOL: // 0 or 1 only for now
840                     case PARAM_INT:
841                         $type = 'int'; break;
842                     case PARAM_FLOAT;
843                         $type = 'double'; break;
844                     default:
845                         $type = 'string';
846                 }
847             } else if ($keydesc instanceof external_single_structure) {
848                 $type = 'object|struct';
849             } else if ($keydesc instanceof external_multiple_structure) {
850                 $type = 'array';
851             }
852             $params_desc[] = '     * @param '.$type.' $'.$name.' '.$keydesc->desc;
853         }
854         $params                = implode(', ', $params);
855         $paramanddefaults      = implode(', ', $paramanddefaults);
856         $params_desc           = implode("\n", $params_desc);
858         $serviceclassmethodbody = $this->service_class_method_body($function, $params);
860         if (is_null($function->returns_desc)) {
861             $return = '     * @return void';
862         } else {
863             $type = 'string';
864             if ($function->returns_desc instanceof external_value) {
865                 switch($function->returns_desc->type) {
866                     case PARAM_BOOL: // 0 or 1 only for now
867                     case PARAM_INT:
868                         $type = 'int'; break;
869                     case PARAM_FLOAT;
870                         $type = 'double'; break;
871                     default:
872                         $type = 'string';
873                 }
874             } else if ($function->returns_desc instanceof external_single_structure) {
875                 $type = 'object|struct'; //only 'object' is supported by SOAP, 'struct' by XML-RPC MDL-23083
876             } else if ($function->returns_desc instanceof external_multiple_structure) {
877                 $type = 'array';
878             }
879             $return = '     * @return '.$type.' '.$function->returns_desc->desc;
880         }
882         // now crate the virtual method that calls the ext implementation
884         $code = '
885     /**
886      * '.$function->description.'
887      *
888 '.$params_desc.'
889 '.$return.'
890      */
891     public function '.$function->name.'('.$paramanddefaults.') {
892 '.$serviceclassmethodbody.'
893     }
894 ';
895         return $code;
896     }
897     
898     /**
899      * You can override this function in your child class to add extra code into the dynamically
900      * created service class. For example it is used in the amf server to cast types of parameters and to
901      * cast the return value to the types as specified in the return value description.
902      * @param unknown_type $function
903      * @param unknown_type $params
904      * @return string body of the method for $function ie. everything within the {} of the method declaration.
905      */
906     protected function service_class_method_body($function, $params){
907         //cast the param from object to array (validate_parameters except array only)
908         $castingcode = '';
909         if ($params){
910             $paramstocast = explode(',', $params);
911             foreach ($paramstocast as $paramtocast) {
912                 //clean the parameter from any white space
913                 $paramtocast = trim($paramtocast);                
914                 $castingcode .= $paramtocast .
915                 '=webservice_zend_server::cast_objects_to_array('.$paramtocast.');';
916             }
918         }
920         $descriptionmethod = $function->methodname.'_returns()';
921         $callforreturnvaluedesc = $function->classname.'::'.$descriptionmethod;
922         return $castingcode . '    if ('.$callforreturnvaluedesc.' == null)  {'.
923                         $function->classname.'::'.$function->methodname.'('.$params.');
924                         return null;
925                     }
926                     return external_api::clean_returnvalue('.$callforreturnvaluedesc.', '.$function->classname.'::'.$function->methodname.'('.$params.'));';
927     }
929     /**
930      * Recursive function to recurse down into a complex variable and convert all
931      * objects to arrays.
932      * @param mixed $param value to cast
933      * @return mixed Cast value
934      */
935     public static function cast_objects_to_array($param){
936         if (is_object($param)){
937             $param = (array)$param;
938         }
939         if (is_array($param)){
940             $toreturn = array();
941             foreach ($param as $key=> $param){
942                 $toreturn[$key] = self::cast_objects_to_array($param);
943             }
944             return $toreturn;
945         } else {
946             return $param;
947         }
948     }
950     /**
951      * Set up zend service class
952      * @return void
953      */
954     protected function init_zend_server() {
955         $this->zend_server = new $this->zend_class();
956     }
958     /**
959      * This method parses the $_REQUEST superglobal and looks for
960      * the following information:
961      *  1/ user authentication - username+password or token (wsusername, wspassword and wstoken parameters)
962      *
963      * @return void
964      */
965     protected function parse_request() {
966         if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
967             //note: some clients have problems with entity encoding :-(
968             if (isset($_REQUEST['wsusername'])) {
969                 $this->username = $_REQUEST['wsusername'];
970             }
971             if (isset($_REQUEST['wspassword'])) {
972                 $this->password = $_REQUEST['wspassword'];
973             }
974         } else {
975             if (isset($_REQUEST['wstoken'])) {
976                 $this->token = $_REQUEST['wstoken'];
977             }
978         }
979     }
981     /**
982      * Internal implementation - sending of page headers.
983      * @return void
984      */
985     protected function send_headers() {
986         header('Cache-Control: private, must-revalidate, pre-check=0, post-check=0, max-age=0');
987         header('Expires: '. gmdate('D, d M Y H:i:s', 0) .' GMT');
988         header('Pragma: no-cache');
989         header('Accept-Ranges: none');
990     }
992     /**
993      * Specialised exception handler, we can not use the standard one because
994      * it can not just print html to output.
995      *
996      * @param exception $ex
997      * @return void does not return
998      */
999     public function exception_handler($ex) {
1000         // detect active db transactions, rollback and log as error
1001         abort_all_db_transactions();
1003         // some hacks might need a cleanup hook
1004         $this->session_cleanup($ex);
1006         // now let the plugin send the exception to client
1007         $this->send_error($ex);
1009         // not much else we can do now, add some logging later
1010         exit(1);
1011     }
1013     /**
1014      * Send the error information to the WS client
1015      * formatted as XML document.
1016      * @param exception $ex
1017      * @return void
1018      */
1019     protected function send_error($ex=null) {
1020         $this->send_headers();
1021         echo $this->zend_server->fault($ex);
1022     }
1024     /**
1025      * Future hook needed for emulated sessions.
1026      * @param exception $exception null means normal termination, $exception received when WS call failed
1027      * @return void
1028      */
1029     protected function session_cleanup($exception=null) {
1030         if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
1031             // nothing needs to be done, there is no persistent session
1032         } else {
1033             // close emulated session if used
1034         }
1035     }
1039 /**
1040  * Web Service server base class, this class handles both
1041  * simple and token authentication.
1042  * @author Petr Skoda (skodak)
1043  */
1044 abstract class webservice_base_server extends webservice_server {
1046     /** @property array $parameters the function parameters - the real values submitted in the request */
1047     protected $parameters = null;
1049     /** @property string $functionname the name of the function that is executed */
1050     protected $functionname = null;
1052     /** @property object $function full function description */
1053     protected $function = null;
1055     /** @property mixed $returns function return value */
1056     protected $returns = null;
1058     /**
1059      * This method parses the request input, it needs to get:
1060      *  1/ user authentication - username+password or token
1061      *  2/ function name
1062      *  3/ function parameters
1063      *
1064      * @return void
1065      */
1066     abstract protected function parse_request();
1068     /**
1069      * Send the result of function call to the WS client.
1070      * @return void
1071      */
1072     abstract protected function send_response();
1074     /**
1075      * Send the error information to the WS client.
1076      * @param exception $ex
1077      * @return void
1078      */
1079     abstract protected function send_error($ex=null);
1081     /**
1082      * Process request from client.
1083      * @return void
1084      */
1085     public function run() {
1086         // we will probably need a lot of memory in some functions
1087         @raise_memory_limit('128M');
1089         // set some longer timeout, this script is not sending any output,
1090         // this means we need to manually extend the timeout operations
1091         // that need longer time to finish
1092         external_api::set_timeout();
1094         // set up exception handler first, we want to sent them back in correct format that
1095         // the other system understands
1096         // we do not need to call the original default handler because this ws handler does everything
1097         set_exception_handler(array($this, 'exception_handler'));
1099         // init all properties from the request data
1100         $this->parse_request();
1102         // authenticate user, this has to be done after the request parsing
1103         // this also sets up $USER and $SESSION
1104         $this->authenticate_user();
1106         // find all needed function info and make sure user may actually execute the function
1107         $this->load_function_info();
1108         
1109         //log the web service request
1110         add_to_log(1, 'webservice', $this->functionname, '' , getremoteaddr() , 0, $this->userid);
1112         // finally, execute the function - any errors are catched by the default exception handler
1113         $this->execute();
1115         // send the results back in correct format
1116         $this->send_response();
1118         // session cleanup
1119         $this->session_cleanup();
1121         die;
1122     }
1124     /**
1125      * Specialised exception handler, we can not use the standard one because
1126      * it can not just print html to output.
1127      *
1128      * @param exception $ex
1129      * @return void does not return
1130      */
1131     public function exception_handler($ex) {
1132         // detect active db transactions, rollback and log as error
1133         abort_all_db_transactions();
1135         // some hacks might need a cleanup hook
1136         $this->session_cleanup($ex);
1138         // now let the plugin send the exception to client
1139         $this->send_error($ex);
1141         // not much else we can do now, add some logging later
1142         exit(1);
1143     }
1145     /**
1146      * Future hook needed for emulated sessions.
1147      * @param exception $exception null means normal termination, $exception received when WS call failed
1148      * @return void
1149      */
1150     protected function session_cleanup($exception=null) {
1151         if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
1152             // nothing needs to be done, there is no persistent session
1153         } else {
1154             // close emulated session if used
1155         }
1156     }
1158     /**
1159      * Fetches the function description from database,
1160      * verifies user is allowed to use this function and
1161      * loads all paremeters and return descriptions.
1162      * @return void
1163      */
1164     protected function load_function_info() {
1165         global $DB, $USER, $CFG;
1167         if (empty($this->functionname)) {
1168             throw new invalid_parameter_exception('Missing function name');
1169         }
1171         // function must exist
1172         $function = external_function_info($this->functionname);
1174         if ($this->restricted_serviceid) {
1175             $params = array('sid1'=>$this->restricted_serviceid, 'sid2'=>$this->restricted_serviceid);
1176             $wscond1 = 'AND s.id = :sid1';
1177             $wscond2 = 'AND s.id = :sid2';
1178         } else {
1179             $params = array();
1180             $wscond1 = '';
1181             $wscond2 = '';
1182         }
1184         // now let's verify access control
1186         // now make sure the function is listed in at least one service user is allowed to use
1187         // allow access only if:
1188         //  1/ entry in the external_services_users table if required
1189         //  2/ validuntil not reached
1190         //  3/ has capability if specified in service desc
1191         //  4/ iprestriction
1193         $sql = "SELECT s.*, NULL AS iprestriction
1194                   FROM {external_services} s
1195                   JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 0 AND sf.functionname = :name1)
1196                  WHERE s.enabled = 1 $wscond1
1198                  UNION
1200                 SELECT s.*, su.iprestriction
1201                   FROM {external_services} s
1202                   JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 1 AND sf.functionname = :name2)
1203                   JOIN {external_services_users} su ON (su.externalserviceid = s.id AND su.userid = :userid)
1204                  WHERE s.enabled = 1 AND su.validuntil IS NULL OR su.validuntil < :now $wscond2";
1205         $params = array_merge($params, array('userid'=>$USER->id, 'name1'=>$function->name, 'name2'=>$function->name, 'now'=>time()));
1207         $rs = $DB->get_recordset_sql($sql, $params);
1208         // now make sure user may access at least one service
1209         $remoteaddr = getremoteaddr();
1210         $allowed = false;
1211         foreach ($rs as $service) {
1212             if ($service->requiredcapability and !has_capability($service->requiredcapability, $this->restricted_context)) {
1213                 continue; // cap required, sorry
1214             }
1215             if ($service->iprestriction and !address_in_subnet($remoteaddr, $service->iprestriction)) {
1216                 continue; // wrong request source ip, sorry
1217             }
1218             $allowed = true;
1219             break; // one service is enough, no need to continue
1220         }
1221         $rs->close();
1222         if (!$allowed) {
1223             throw new webservice_access_exception('Access to external function not allowed');
1224         }
1226         // we have all we need now
1227         $this->function = $function;
1228     }
1230     /**
1231      * Execute previously loaded function using parameters parsed from the request data.
1232      * @return void
1233      */
1234     protected function execute() {
1235         // validate params, this also sorts the params properly, we need the correct order in the next part
1236         $params = call_user_func(array($this->function->classname, 'validate_parameters'), $this->function->parameters_desc, $this->parameters);
1238         // execute - yay!
1239         $this->returns = call_user_func_array(array($this->function->classname, $this->function->methodname), array_values($params));
1240     }