webservice/lib.php

   1 <?php
   2
   3 // This file is part of Moodle - http://moodle.org/
   4 //
   5 // Moodle is free software: you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation, either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // Moodle is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 /**
  19  * 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  */
  25
  26 require_once($CFG->libdir.'/externallib.php');
  27
  28 function webservice_protocol_is_enabled($protocol) {
  29     global $CFG;
  30
  31     if (empty($CFG->enablewebservices)) {
  32         return false;
  33     }
  34
  35     $active = explode(',', $CFG->webserviceprotocols);
  36
  37     return(in_array($protocol, $active));
  38 }
  39
  40 /**
  41  * Mandatory web service server interface
  42  * @author Petr Skoda (skodak)
  43  */
  44 interface webservice_server {
  45     /**
  46      * Process request from client.
  47      * @param bool $simple use simple authentication
  48      * @return void
  49      */
  50     public function run($simple);
  51 }
  52
  53 /**
  54  * Special abstraction of our srvices that allows
  55  * interaction with stock Zend ws servers.
  56  * @author skodak
  57  */
  58 abstract class webservice_zend_server implements webservice_server {
  59
  60     /** @property string name of the zend server class */
  61     protected $zend_class;
  62
  63     /** @property object Zend server instance */
  64     protected $zend_server;
  65
  66     /** @property string $wsname name of the web server plugin */
  67     protected $wsname = null;
  68
  69     /** @property bool $simple true if simple auth used */
  70     protected $simple;
  71
  72     /** @property string $service_class virtual web service class with all functions user name execute, created on the fly */
  73     protected $service_class;
  74
  75     /** @property object restricted context */
  76     protected $restricted_context;
  77
  78     /**
  79      * Contructor
  80      */
  81     public function __construct($zend_class) {
  82         $this->zend_class = $zend_class;
  83     }
  84
  85     /**
  86      * Process request from client.
  87      * @param bool $simple use simple authentication
  88      * @return void
  89      */
  90     public function run($simple) {
  91         $this->simple = $simple;
  92
  93         // we will probably need a lot of memory in some functions
  94         @raise_memory_limit('128M');
  95
  96         // set some longer timeout, this script is not sending any output,
  97         // this means we need to manually extend the timeout operations
  98         // that need longer time to finish
  99         external_api::set_timeout();
 100
 101         // set up exception handler first, we want to sent them back in correct format that
 102         // the other system understands
 103         // we do not need to call the original default handler because this ws handler does everything
 104         set_exception_handler(array($this, 'exception_handler'));
 105
 106         // now create the instance of zend server
 107         $this->init_zend_server();
 108
 109         // this sets up $USER and $SESSION and context restrictions
 110         $this->authenticate_user();
 111
 112         // make a list of all functions user is allowed to excecute
 113         $this->init_service_class();
 114
 115         // TODO: solve debugging level somehow
 116         Zend_XmlRpc_Server_Fault::attachFaultException('moodle_exception');
 117
 118         // start the server
 119         $this->zend_server->setClass($this->service_class);
 120         $response = $this->zend_server->handle();
 121
 122         //$grrr = ob_get_clean();
 123         //error_log($grrr);
 124
 125         // session cleanup
 126         $this->session_cleanup();
 127
 128         //TODO: we need to send some headers too I guess
 129         echo $response;
 130         die;
 131     }
 132
 133     /**
 134      * Load virtual class needed for Zend api
 135      * @return void
 136      */
 137     protected function init_service_class() {
 138         global $USER, $DB;
 139
 140         // first ofall get a complete list of services user is allowed to access
 141         if ($this->simple) {
 142             // now make sure the function is listed in at least one service user is allowed to use
 143             // allow access only if:
 144             //  1/ entry in the external_services_users table if required
 145             //  2/ validuntil not reached
 146             //  3/ has capability if specified in service desc
 147             //  4/ iprestriction
 148
 149             $sql = "SELECT s.*, NULL AS iprestriction
 150                       FROM {external_services} s
 151                       JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 0)
 152                      WHERE s.enabled = 1
 153
 154                      UNION
 155
 156                     SELECT s.*, su.iprestriction
 157                       FROM {external_services} s
 158                       JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 1)
 159                       JOIN {external_services_users} su ON (su.externalserviceid = s.id AND su.userid = :userid)
 160                      WHERE s.enabled = 1 AND su.validuntil IS NULL OR su.validuntil < :now";
 161             $params = array('userid'=>$USER->id, 'now'=>time());
 162         } else {
 163
 164             //TODO: token may restrict access to one service only
 165             die('not implemented yet');
 166         }
 167
 168         $serviceids = array();
 169         $rs = $DB->get_recordset_sql($sql, $params);
 170
 171         // now make sure user may access at least one service
 172         $remoteaddr = getremoteaddr();
 173         $allowed = false;
 174         foreach ($rs as $service) {
 175             if (isset($serviceids[$service->id])) {
 176                 continue;
 177             }
 178             if ($service->requiredcapability and !has_capability($service->requiredcapability, $this->restricted_context)) {
 179                 continue; // cap required, sorry
 180             }
 181             if ($service->iprestriction and !address_in_subnet($remoteaddr, $service->iprestriction)) {
 182                 continue; // wrong request source ip, sorry
 183             }
 184             $serviceids[$service->id] = $service->id;
 185         }
 186         $rs->close();
 187
 188         // now get the list of all functions
 189         if ($serviceids) {
 190             list($serviceids, $params) = $DB->get_in_or_equal($serviceids);
 191             $sql = "SELECT f.*
 192                       FROM {external_functions} f
 193                      WHERE f.name IN (SELECT sf.functionname
 194                                         FROM {external_services_functions} sf
 195                                        WHERE sf.externalserviceid $serviceids)";
 196             $functions = $DB->get_records_sql($sql, $params);
 197         } else {
 198             $functions = array();
 199         }
 200
 201         // now make the virtual WS class with all the fuctions for this particular user
 202         $methods = '';
 203         foreach ($functions as $function) {
 204             $methods .= $this->get_virtual_method_code($function);
 205         }
 206
 207         $classname = 'webservices_virtual_class_000000';
 208         while(class_exists($classname)) {
 209             $classname++;
 210         }
 211
 212         $code = '
 213 /**
 214  * Virtual class web services for user id '.$USER->id.' in context '.$this->restricted_context->id.'.
 215  */
 216 class '.$classname.' {
 217 '.$methods.'
 218 }
 219 ';
 220         // load the virtual class definition into memory
 221         eval($code);
 222         $this->service_class = $classname;
 223     }
 224
 225     /**
 226      * returns virtual method code
 227      * @param object $function
 228      * @return string PHP code
 229      */
 230     protected function get_virtual_method_code($function) {
 231         global $CFG;
 232
 233         //first find and include the ext implementation class
 234         $function->classpath = empty($function->classpath) ? get_component_directory($function->component).'/externallib.php' : $CFG->dirroot.'/'.$function->classpath;
 235         if (!file_exists($function->classpath)) {
 236             throw new coding_exception('Can not find file with external function implementation');
 237         }
 238         require_once($function->classpath);
 239
 240         $function->parameters_method = $function->methodname.'_parameters';
 241         $function->returns_method    = $function->methodname.'_returns';
 242
 243         // make sure the implementaion class is ok
 244         if (!method_exists($function->classname, $function->methodname)) {
 245             throw new coding_exception('Missing implementation method');
 246         }
 247         if (!method_exists($function->classname, $function->parameters_method)) {
 248             throw new coding_exception('Missing parameters description');
 249         }
 250         if (!method_exists($function->classname, $function->returns_method)) {
 251             throw new coding_exception('Missing returned values description');
 252         }
 253
 254         // fetch the parameters description
 255         $function->parameters_desc = call_user_func(array($function->classname, $function->parameters_method));
 256         if (!($function->parameters_desc instanceof external_function_parameters)) {
 257             throw new coding_exception('Invalid parameters description');
 258         }
 259
 260         // fetch the return values description
 261         $function->returns_desc = call_user_func(array($function->classname, $function->returns_method));
 262         // null means void result or result is ignored
 263         if (!is_null($function->returns_desc) and !($function->returns_desc instanceof external_description)) {
 264             throw new coding_exception('Invalid return description');
 265         }
 266
 267         $params      = array();
 268         $params_desc = array();
 269         foreach ($function->parameters_desc->keys as $name=>$keydesc) {
 270             $params[]      = '$'.$name;
 271             $type = 'string';
 272             if ($keydesc instanceof external_value) {
 273                 switch($keydesc->type) {
 274                     case PARAM_BOOL: // 0 or 1 only for now
 275                     case PARAM_INT:
 276                         $type = 'int'; break;
 277                     case PARAM_FLOAT;
 278                         $type = 'double'; break;
 279                     default:
 280                         $type = 'string';
 281                 }
 282             } else if ($keydesc instanceof external_single_structure) {
 283                 $type = 'struct';
 284             } else if ($keydesc instanceof external_multiple_structure) {
 285                 $type = 'array';
 286             }
 287             $params_desc[] = '     * @param '.$type.' $'.$name.' '.$keydesc->desc;
 288         }
 289         $params      = implode(', ', $params);
 290         $params_desc = implode("\n", $params_desc);
 291
 292         if (is_null($function->returns_desc)) {
 293             $return = '     * @return void';
 294         } else {
 295             $type = 'string';
 296             if ($function->returns_desc instanceof external_value) {
 297                 switch($function->returns_desc->type) {
 298                     case PARAM_BOOL: // 0 or 1 only for now
 299                     case PARAM_INT:
 300                         $type = 'int'; break;
 301                     case PARAM_FLOAT;
 302                         $type = 'double'; break;
 303                     default:
 304                         $type = 'string';
 305                 }
 306             } else if ($function->returns_desc instanceof external_single_structure) {
 307                 $type = 'struct';
 308             } else if ($function->returns_desc instanceof external_multiple_structure) {
 309                 $type = 'array';
 310             }
 311             $return = '     * @return '.$type.' '.$function->returns_desc->desc;
 312         }
 313
 314         // now crate a virtual method that calls the ext implemenation
 315         // TODO: add PHP docs and all missing info here
 316
 317         $code = '
 318     /**
 319      * External function: '.$function->name.'
 320      * TODO: add function description
 321 '.$params_desc.'
 322 '.$return.'
 323      */
 324     public function '.$function->name.'('.$params.') {
 325         return '.$function->classname.'::'.$function->methodname.'('.$params.');
 326     }
 327 ';
 328         return $code;
 329     }
 330
 331     /**
 332      * Set up zend serice class
 333      * @return void
 334      */
 335     protected function init_zend_server() {
 336         include "Zend/Loader.php";
 337         Zend_Loader::registerAutoload();
 338         //TODO: set up some server options and debugging too - maybe a new method
 339         //TODO: add some zend exeption handler too
 340         $this->zend_server = new $this->zend_class();
 341     }
 342
 343     /**
 344      * Send the error information to the WS client.
 345      * @param exception $ex
 346      * @return void
 347      */
 348     protected function send_error($ex=null) {
 349         var_dump($ex);
 350         die('TODO');
 351         // TODO: find some way to send the error back through the Zend
 352     }
 353
 354     /**
 355      * Authenticate user using username+password or token.
 356      * This function sets up $USER global.
 357      * It is safe to use has_capability() after this.
 358      * This method also verifies user is allowed to use this
 359      * server.
 360      * @return void
 361      */
 362     protected function authenticate_user() {
 363         global $CFG, $DB;
 364
 365         if (!NO_MOODLE_COOKIES) {
 366             throw new coding_exception('Cookies must be disabled in WS servers!');
 367         }
 368
 369         if ($this->simple) {
 370             $this->restricted_context = get_context_instance(CONTEXT_SYSTEM);
 371
 372             if (!is_enabled_auth('webservice')) {
 373                 error_log('WS auth not enabled');
 374                 die('WS auth not enabled');
 375             }
 376
 377             if (!$auth = get_auth_plugin('webservice')) {
 378                 error_log('WS auth missing');
 379                 die('WS auth missing');
 380             }
 381
 382             // the username is hardcoded as URL parameter because we can not easily parse the request data :-(
 383             if (!$username = optional_param('wsusername', '', PARAM_RAW)) {
 384                 throw new invalid_parameter_exception('Missing username');
 385             }
 386
 387             // the password is hardcoded as URL parameter because we can not easily parse the request data :-(
 388             if (!$password = optional_param('wspassword', '', PARAM_RAW)) {
 389                 throw new invalid_parameter_exception('Missing password');
 390             }
 391
 392             if (!$auth->user_login_webservice($username, $password)) {
 393                 throw new invalid_parameter_exception('Wrong username or password');
 394             }
 395
 396             $user = $DB->get_record('user', array('username'=>$username, 'mnethostid'=>$CFG->mnet_localhost_id, 'deleted'=>0), '*', MUST_EXIST);
 397
 398             // now fake user login, the session is completely empty too
 399             session_set_user($user);
 400
 401         } else {
 402
 403             //TODO: not implemented yet
 404             die('token login not implemented yet');
 405             //TODO: $this->restricted_context is derived from the token context
 406         }
 407
 408         if (!has_capability("webservice/$this->wsname:use", $this->restricted_context)) {
 409             throw new invalid_parameter_exception('Access to web service not allowed');
 410         }
 411
 412         external_api::set_context_restriction($this->restricted_context);
 413     }
 414
 415     /**
 416      * Specialised exception handler, we can not use the standard one because
 417      * it can not just print html to output.
 418      *
 419      * @param exception $ex
 420      * @return void does not return
 421      */
 422     public function exception_handler($ex) {
 423         global $CFG, $DB, $SCRIPT;
 424
 425         // detect active db transactions, rollback and log as error
 426         if ($DB->is_transaction_started()) {
 427             error_log('Database transaction aborted by exception in ' . $CFG->dirroot . $SCRIPT);
 428             try {
 429                 // note: transaction blocks should never change current $_SESSION
 430                 $DB->rollback_sql();
 431             } catch (Exception $ignored) {
 432             }
 433         }
 434
 435         // now let the plugin send the exception to client
 436         $this->send_error($ex);
 437
 438         // some hacks might need a cleanup hook
 439         $this->session_cleanup($ex);
 440
 441         // not much else we can do now, add some logging later
 442         exit(1);
 443     }
 444
 445     /**
 446      * Future hook needed for emulated sessions.
 447      * @param exception $exception null means normal termination, $exception received when WS call failed
 448      * @return void
 449      */
 450     protected function session_cleanup($exception=null) {
 451         if ($this->simple) {
 452             // nothing needs to be done, there is no persistent session
 453         } else {
 454             // close emulated session if used
 455         }
 456     }
 457
 458 }
 459
 460
 461 /**
 462  * Web Service server base class, this class handles both
 463  * simple and token authentication.
 464  * @author Petr Skoda (skodak)
 465  */
 466 abstract class webservice_base_server implements webservice_server {
 467
 468     /** @property string $wsname name of the web server plugin */
 469     protected $wsname = null;
 470
 471     /** @property bool $simple true if simple auth used */
 472     protected $simple;
 473
 474     /** @property string $username name of local user */
 475     protected $username = null;
 476
 477     /** @property string $password password of the local user */
 478     protected $password = null;
 479
 480     /** @property string $token authentication token*/
 481     protected $token = null;
 482
 483     /** @property object restricted context */
 484     protected $restricted_context;
 485
 486     /** @property array $parameters the function parameters - the real values submitted in the request */
 487     protected $parameters = null;
 488
 489     /** @property string $functionname the name of the function that is executed */
 490     protected $functionname = null;
 491
 492     /** @property object $function full function description */
 493     protected $function = null;
 494
 495     /** @property mixed $returns function return value */
 496     protected $returns = null;
 497
 498     /**
 499      * Contructor
 500      */
 501     public function __construct() {
 502     }
 503
 504     /**
 505      * This method parses the request input, it needs to get:
 506      *  1/ user authentication - username+password or token
 507      *  2/ function name
 508      *  3/ function parameters
 509      *
 510      * @return void
 511      */
 512     abstract protected function parse_request();
 513
 514     /**
 515      * Send the result of function call to the WS client.
 516      * @return void
 517      */
 518     abstract protected function send_response();
 519
 520     /**
 521      * Send the error information to the WS client.
 522      * @param exception $ex
 523      * @return void
 524      */
 525     abstract protected function send_error($ex=null);
 526
 527
 528     /**
 529      * Process request from client.
 530      * @param bool $simple use simple authentication
 531      * @return void
 532      */
 533     public function run($simple) {
 534         $this->simple = $simple;
 535
 536         // we will probably need a lot of memory in some functions
 537         @raise_memory_limit('128M');
 538
 539         // set some longer timeout, this script is not sending any output,
 540         // this means we need to manually extend the timeout operations
 541         // that need longer time to finish
 542         external_api::set_timeout();
 543
 544         // set up exception handler first, we want to sent them back in correct format that
 545         // the other system understands
 546         // we do not need to call the original default handler because this ws handler does everything
 547         set_exception_handler(array($this, 'exception_handler'));
 548
 549         // init all properties from the request data
 550         $this->parse_request();
 551
 552         // authenticate user, this has to be done after the request parsing
 553         // this also sets up $USER and $SESSION
 554         $this->authenticate_user();
 555
 556         // find all needed function info and make sure user may actually execute the function
 557         $this->load_function_info();
 558
 559         // finally, execute the function - any errors are catched by the default exception handler
 560         $this->execute();
 561
 562         // send the results back in correct format
 563         $this->send_response();
 564
 565         // session cleanup
 566         $this->session_cleanup();
 567
 568         die;
 569     }
 570
 571     /**
 572      * Specialised exception handler, we can not use the standard one because
 573      * it can not just print html to output.
 574      *
 575      * @param exception $ex
 576      * @return void does not return
 577      */
 578     public function exception_handler($ex) {
 579         global $CFG, $DB, $SCRIPT;
 580
 581         // detect active db transactions, rollback and log as error
 582         if ($DB->is_transaction_started()) {
 583             error_log('Database transaction aborted by exception in ' . $CFG->dirroot . $SCRIPT);
 584             try {
 585                 // note: transaction blocks should never change current $_SESSION
 586                 $DB->rollback_sql();
 587             } catch (Exception $ignored) {
 588             }
 589         }
 590
 591         // now let the plugin send the exception to client
 592         $this->send_error($ex);
 593
 594         // some hacks might need a cleanup hook
 595         $this->session_cleanup($ex);
 596
 597         // not much else we can do now, add some logging later
 598         exit(1);
 599     }
 600
 601     /**
 602      * Future hook needed for emulated sessions.
 603      * @param exception $exception null means normal termination, $exception received when WS call failed
 604      * @return void
 605      */
 606     protected function session_cleanup($exception=null) {
 607         if ($this->simple) {
 608             // nothing needs to be done, there is no persistent session
 609         } else {
 610             // close emulated session if used
 611         }
 612     }
 613
 614     /**
 615      * Authenticate user using username+password or token.
 616      * This function sets up $USER global.
 617      * It is safe to use has_capability() after this.
 618      * This method also verifies user is allowed to use this
 619      * server.
 620      * @return void
 621      */
 622     protected function authenticate_user() {
 623         global $CFG, $DB;
 624
 625         if (!NO_MOODLE_COOKIES) {
 626             throw new coding_exception('Cookies must be disabled in WS servers!');
 627         }
 628
 629         if ($this->simple) {
 630             $this->restricted_context = get_context_instance(CONTEXT_SYSTEM);
 631
 632             if (!is_enabled_auth('webservice')) {
 633                 die('WS auth not enabled');
 634             }
 635
 636             if (!$auth = get_auth_plugin('webservice')) {
 637                 die('WS auth missing');
 638             }
 639
 640             if (!$this->username) {
 641                 throw new invalid_parameter_exception('Missing username');
 642             }
 643
 644             if (!$this->password) {
 645                 throw new invalid_parameter_exception('Missing password');
 646             }
 647
 648             if (!$auth->user_login_webservice($this->username, $this->password)) {
 649                 throw new invalid_parameter_exception('Wrong username or password');
 650             }
 651
 652             $user = $DB->get_record('user', array('username'=>$this->username, 'mnethostid'=>$CFG->mnet_localhost_id, 'deleted'=>0), '*', MUST_EXIST);
 653
 654             // now fake user login, the session is completely empty too
 655             session_set_user($user);
 656         } else {
 657
 658             //TODO: not implemented yet
 659             die('token login not implemented yet');
 660             //TODO: $this->restricted_context is derived from the token context
 661         }
 662
 663         if (!has_capability("webservice/$this->wsname:use", $this->restricted_context)) {
 664             throw new invalid_parameter_exception('Access to web service not allowed');
 665         }
 666
 667         external_api::set_context_restriction($this->restricted_context);
 668     }
 669
 670     /**
 671      * Fetches the function description from database,
 672      * verifies user is allowed to use this function and
 673      * loads all paremeters and return descriptions.
 674      * @return void
 675      */
 676     protected function load_function_info() {
 677         global $DB, $USER, $CFG;
 678
 679         if (empty($this->functionname)) {
 680             throw new invalid_parameter_exception('Missing function name');
 681         }
 682
 683         // function must exist
 684         $function = $DB->get_record('external_functions', array('name'=>$this->functionname), '*', MUST_EXIST);
 685
 686
 687         // now let's verify access control
 688         if ($this->simple) {
 689             // now make sure the function is listed in at least one service user is allowed to use
 690             // allow access only if:
 691             //  1/ entry in the external_services_users table if required
 692             //  2/ validuntil not reached
 693             //  3/ has capability if specified in service desc
 694             //  4/ iprestriction
 695
 696             $sql = "SELECT s.*, NULL AS iprestriction
 697                       FROM {external_services} s
 698                       JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 0 AND sf.functionname = :name1)
 699                      WHERE s.enabled = 1
 700
 701                      UNION
 702
 703                     SELECT s.*, su.iprestriction
 704                       FROM {external_services} s
 705                       JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 1 AND sf.functionname = :name2)
 706                       JOIN {external_services_users} su ON (su.externalserviceid = s.id AND su.userid = :userid)
 707                      WHERE s.enabled = 1 AND su.validuntil IS NULL OR su.validuntil < :now";
 708             $params = array('userid'=>$USER->id, 'name1'=>$function->name, 'name2'=>$function->name, 'now'=>time());
 709         } else {
 710
 711             //TODO: token may restrict access to one service only
 712             die('not implemented yet');
 713         }
 714
 715         $rs = $DB->get_recordset_sql($sql, $params);
 716         // now make sure user may access at least one service
 717         $remoteaddr = getremoteaddr();
 718         $allowed = false;
 719         foreach ($rs as $service) {
 720             if ($service->requiredcapability and !has_capability($service->requiredcapability, $this->restricted_context)) {
 721                 continue; // cap required, sorry
 722             }
 723             if ($service->iprestriction and !address_in_subnet($remoteaddr, $service->iprestriction)) {
 724                 continue; // wrong request source ip, sorry
 725             }
 726             $allowed = true;
 727             break; // one service is enough, no need to continue
 728         }
 729         $rs->close();
 730         if (!$allowed) {
 731             throw new invalid_parameter_exception('Access to external function not allowed');
 732         }
 733         // now we finally know the user may execute this function,
 734         // the last step is to set context restriction - in this simple case
 735         // we use system context because each external system has different user account
 736         // and we can manage everything through normal permissions.
 737
 738         // get the params and return descriptions of the function
 739         unset($function->id); // we want to prevent any accidental db updates ;-)
 740
 741         $function->classpath = empty($function->classpath) ? get_component_directory($function->component).'/externallib.php' : $CFG->dirroot.'/'.$function->classpath;
 742         if (!file_exists($function->classpath)) {
 743             throw new coding_exception('Can not find file with external function implementation');
 744         }
 745         require_once($function->classpath);
 746
 747         $function->parameters_method = $function->methodname.'_parameters';
 748         $function->returns_method    = $function->methodname.'_returns';
 749
 750         // make sure the implementaion class is ok
 751         if (!method_exists($function->classname, $function->methodname)) {
 752             throw new coding_exception('Missing implementation method');
 753         }
 754         if (!method_exists($function->classname, $function->parameters_method)) {
 755             throw new coding_exception('Missing parameters description');
 756         }
 757         if (!method_exists($function->classname, $function->returns_method)) {
 758             throw new coding_exception('Missing returned values description');
 759         }
 760
 761         // fetch the parameters description
 762         $function->parameters_desc = call_user_func(array($function->classname, $function->parameters_method));
 763         if (!($function->parameters_desc instanceof external_function_parameters)) {
 764             throw new coding_exception('Invalid parameters description');
 765         }
 766
 767         // fetch the return values description
 768         $function->returns_desc = call_user_func(array($function->classname, $function->returns_method));
 769         // null means void result or result is ignored
 770         if (!is_null($function->returns_desc) and !($function->returns_desc instanceof external_description)) {
 771             throw new coding_exception('Invalid return description');
 772         }
 773
 774         // we have all we need now
 775         $this->function = $function;
 776     }
 777
 778     /**
 779      * Execute previously loaded function using parameters parsed from the request data.
 780      * @return void
 781      */
 782     protected function execute() {
 783         // validate params, this also sorts the params properly, we need the correct order in the next part
 784         $params = call_user_func(array($this->function->classname, 'validate_parameters'), $this->function->parameters_desc, $this->parameters);
 785
 786         // execute - yay!
 787         $this->returns = call_user_func_array(array($this->function->classname, $this->function->methodname), array_values($params));
 788     }
 789 }
 790
 791