diff --git a/enrol/manual/db/services.php b/enrol/manual/db/services.php
index 4b41d24ac88..b5959dc14ed 100644
--- a/enrol/manual/db/services.php
+++ b/enrol/manual/db/services.php
@@ -1,5 +1,4 @@
.
+
/**
* Manual plugin external functions and service definitions.
*
- * @package enrol
- * @subpackage manual
- * @author 2011 Jerome Mouneyrac
+ * @package enrol_manual
+ * @category webservice
+ * @copyright 2011 Jerome Mouneyrac
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
diff --git a/lib/db/services.php b/lib/db/services.php
index e721810f7e7..328d29db578 100644
--- a/lib/db/services.php
+++ b/lib/db/services.php
@@ -1,5 +1,4 @@
.
+
/**
* Core external functions and service definitions.
*
- * @package core
- * @subpackage webservice
- * @copyright 2009 Petr Skoda (http://skodak.org)
+ * @package core_webservice
+ * @category webservice
+ * @copyright 2009 Petr Skodak
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
diff --git a/webservice/amf/db/access.php b/webservice/amf/db/access.php
index 5b09feb6301..a984f57312c 100644
--- a/webservice/amf/db/access.php
+++ b/webservice/amf/db/access.php
@@ -1,4 +1,28 @@
.
+
+
+/**
+ * AMF server capabilities.
+ *
+ * @package webservice_amf
+ * @category access
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
$capabilities = array(
diff --git a/webservice/amf/introspector.php b/webservice/amf/introspector.php
index 6e8bef782dd..24853c1e5da 100644
--- a/webservice/amf/introspector.php
+++ b/webservice/amf/introspector.php
@@ -1,50 +1,67 @@
.
+
+
/**
- * Moodle - Modular Object-Oriented Dynamic Learning Environment
- * http://moodle.org
- * Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com
+ * Introspection for amf
*
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation, either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program. If not, see .
- *
- * @package moodle
- * @author Penny Leach
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL
- * @copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com
- *
- * Introspection for amf - figures out where all the services are and
+ * Figures out where all the services are and
* returns a list of their available methods.
* Requires $CFG->amf_introspection = true for security.
+ *
+ * @package webservice_amf
+ * @copyright 2009 Penny Leach
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
/**
* Provides a function to get details of methods available on another class.
- * @author HP
*
+ * @package webservice_amf
+ * @copyright HP
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class MethodDescriptor {
+ /** @var array The details of the methods*/
private $methods;
+
+ /** @var array Classes to introspect
+ * Note: setup() code has been written to introspect multiple classes.
+ * However the setup() only deal with $classnametointrospect.
+ */
private $classes;
- static public $classnametointrospect;
-
+ /** @var string Class to introspect */
+ static public $classnametointrospect;
+ /**
+ * constructor
+ */
public function __construct() {
$this->setup();
}
+ /**
+ * Generate the class method descriptions.
+ * These description are assigned in the class properties
+ *
+ * @return void
+ */
private function setup() {
global $CFG;
if (!empty($this->nothing)) {
@@ -53,11 +70,13 @@ class MethodDescriptor {
if (!empty($this->classes)) { // we've already done it successfully.
return;
}
+
+ //TODO MDL-31148 most likely can be removed, but check if there is any interest, never know...
/*if (empty($CFG->amf_introspection)) {
throw new Exception(get_string('amfintrospectiondisabled', 'local'));
}*/
- //just one class here, possibility for expansion in future
+ //TODO MDL-31148 just one class here, possibility for expansion in future
$classes = array(MethodDescriptor::$classnametointrospect);
$hugestructure = array();
@@ -90,16 +109,34 @@ class MethodDescriptor {
}
}
+ /**
+ * Get the method descriptions
+ *
+ * @return array
+ */
public function getMethods() {
$this->setup();
return $this->methods;
}
+ /**
+ * Get the class descriptions
+ *
+ * @return array
+ */
public function getClasses() {
$this->setup();
return $this->classes;
}
+ /**
+ * As the class does not extend another class and as this function does nothing
+ * except return true,
+ * I guess this is just a function that was a copy/paste and it has been forgotten.
+ * TODO MDL-31148 this function is not called and most likely can be removed
+ *
+ * @return true
+ */
public function isConnected() {
return true;
}
diff --git a/webservice/amf/lang/en/webservice_amf.php b/webservice/amf/lang/en/webservice_amf.php
index 15c26d843c3..7b049281289 100644
--- a/webservice/amf/lang/en/webservice_amf.php
+++ b/webservice/amf/lang/en/webservice_amf.php
@@ -1,5 +1,4 @@
.
+
/**
* Strings for component 'webservice_amf', language 'en', branch 'MOODLE_20_STABLE'
*
- * @package webservice_amf
- * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com}
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package webservice_amf
+ * @category string
+ * @copyright 2010 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
+
$string['amf:use'] = 'Use AMF protocol';
$string['pluginname'] = 'AMF protocol';
diff --git a/webservice/amf/locallib.php b/webservice/amf/locallib.php
index 2716027f1d1..cd0bd10dd49 100644
--- a/webservice/amf/locallib.php
+++ b/webservice/amf/locallib.php
@@ -1,5 +1,4 @@
.
+
/**
* AMF web service implementation classes and methods.
*
- * @package webservice
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package webservice_amf
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
require_once("$CFG->dirroot/webservice/lib.php");
require_once( "{$CFG->dirroot}/webservice/amf/introspector.php");
require_once 'Zend/Amf/Server.php';
+
/**
* Exception indicating an invalid return value from a function.
- * Used when an externallib function does not return values of the expected structure.
+ *
+ * Used when an externallib function does not return values of the expected structure.
+ *
+ * @package webservice_amf
+ * @copyright 2010 Jamie Pratt
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class invalid_return_value_exception extends moodle_exception {
+
/**
* Constructor
+ *
* @param string $debuginfo some detailed information
*/
function __construct($debuginfo=null) {
@@ -42,17 +50,26 @@ class invalid_return_value_exception extends moodle_exception {
/**
* AMF service server implementation.
- * @author Petr Skoda (skodak)
+ *
+ * @package webservice_amf
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class webservice_amf_server extends webservice_zend_server {
+
/**
* Contructor
+ *
* @param integer $authmethod authentication method - one of WEBSERVICE_AUTHMETHOD_*
*/
public function __construct($authmethod) {
parent::__construct($authmethod, 'Moodle_Amf_Server');
$this->wsname = 'amf';
}
+
+ /**
+ * Load virtual class needed for Zend api
+ */
protected function init_service_class(){
parent::init_service_class();
//allow access to data about methods available.
@@ -60,6 +77,13 @@ class webservice_amf_server extends webservice_zend_server {
MethodDescriptor::$classnametointrospect = $this->service_class;
}
+ /**
+ * Get the generated web service function code.
+ *
+ * @param stdClass $function contains function name and class name
+ * @param array $params all the function parameters
+ * @return string the generate web service function code
+ */
protected function service_class_method_body($function, $params){
//cast the param from object to array (validate_parameters except array only)
$castingcode = '';
@@ -79,15 +103,16 @@ class webservice_amf_server extends webservice_zend_server {
return $castingcode .
' return webservice_amf_server::validate_and_cast_values('.$callforreturnvaluedesc.', '.$externallibcall.');';
}
+
/**
* Validates submitted value, comparing it to a description. If anything is incorrect
* invalid_return_value_exception is thrown. Also casts the values to the type specified in
* the description.
- * @param mixed $description description of parameters or null if no return value
+ *
+ * @param external_description $description description of parameters or null if no return value
* @param mixed $value the actual values
- * @param boolean $singleasobject specifies whether a external_single_structure should be cast to a stdClass object
- * should always be false for use in validating parameters in externallib functions.
- * @return mixed params with added defaults for optional items, invalid_parameters_exception thrown if any problem found
+ * @return mixed params with added defaults for optional items
+ * @throws invalid_return_value_exception
*/
public static function validate_and_cast_values($description, $value) {
if (is_null($description)){
@@ -126,10 +151,7 @@ class webservice_amf_server extends webservice_zend_server {
}
unset($value[$key]);
}
-/* Was decided that extra keys should just be ignored and not returned.
- * if (!empty($value)) {
- throw new invalid_return_value_exception('Unexpected keys detected in parameter array.');
- }*/
+
return (object)$result;
} else if ($description instanceof external_multiple_structure) {
@@ -149,23 +171,28 @@ class webservice_amf_server extends webservice_zend_server {
/**
* Set up zend service class
- * @return void
*/
protected function init_zend_server() {
parent::init_zend_server();
$this->zend_server->setProduction(false); //set to false for development mode
//(complete error message displayed into your AMF client)
- // TODO: add some exception handling
}
-
-
}
+
+/**
+ * Zend Amf server with a different fault management
+ *
+ * @package webservice_amf
+ * @copyright 2010 Jamie Pratt
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
class Moodle_Amf_Server extends Zend_Amf_Server{
+
/**
* Raise a server fault
*
- * @param string|Exception $fault
- * @return void
+ * @param string|Exception $fault
+ * @param int $code fault code
*/
public function fault($fault = null, $code = 404)
{
@@ -198,5 +225,3 @@ class Moodle_Amf_Server extends Zend_Amf_Server{
echo $response;
}
}
-
-// TODO: implement AMF test client somehow, maybe we could use moodle form to feed the data to the flash app somehow
diff --git a/webservice/amf/server.php b/webservice/amf/server.php
index 2db5bcaa1a3..4103f002d06 100644
--- a/webservice/amf/server.php
+++ b/webservice/amf/server.php
@@ -1,5 +1,4 @@
.
+
/**
* AMF web service entry point. The authentication is done via tokens.
*
- * @package webservice
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package webservice_amf
+ * @copyright 2009 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
-// disable moodle specific debug messages and any errors in output
+/**
+ * NO_DEBUG_DISPLAY - disable moodle specific debug messages and any errors in output
+ */
define('NO_DEBUG_DISPLAY', true);
+
+/**
+ * NO_MOODLE_COOKIES - no cookies with web service
+ */
define('NO_MOODLE_COOKIES', true);
require('../../config.php');
diff --git a/webservice/amf/simpleserver.php b/webservice/amf/simpleserver.php
index 8ae9e65e618..896ff35ecf4 100644
--- a/webservice/amf/simpleserver.php
+++ b/webservice/amf/simpleserver.php
@@ -1,5 +1,4 @@
.
+
/**
- * AMF web service entry point. The authentication is done via tokens.
+ * AMF web service entry point. The authentication is done via username/password.
*
- * @package webservice
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package webservice_amf
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
-// disable moodle specific debug messages and any errors in output
+/**
+ * NO_DEBUG_DISPLAY - disable moodle specific debug messages and any errors in output
+ */
define('NO_DEBUG_DISPLAY', true);
+
+/**
+ * NO_MOODLE_COOKIES - no cookies with web service
+ */
define('NO_MOODLE_COOKIES', true);
require('../../config.php');
require_once("$CFG->dirroot/webservice/amf/locallib.php");
-//ob_start();
-
-//TODO: for now disable all mess in xml
+//disable all 'displayed error' mess in xml
ini_set('display_errors', '0');
ini_set('log_errors', '1');
$CFG->debugdisplay = false;
diff --git a/webservice/amf/testclient/index.php b/webservice/amf/testclient/index.php
index 7519151ba11..7d84acd7373 100644
--- a/webservice/amf/testclient/index.php
+++ b/webservice/amf/testclient/index.php
@@ -1,4 +1,28 @@
.
+
+
+/**
+ * Index page of the AMF test client
+ *
+ * @package webservice_amf
+ * @copyright 2009 Jamie Pratt
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
require "../../../config.php";
require_once($CFG->libdir . '/adminlib.php');
diff --git a/webservice/amf/version.php b/webservice/amf/version.php
index 34a2ff88160..3f410057aef 100644
--- a/webservice/amf/version.php
+++ b/webservice/amf/version.php
@@ -14,12 +14,12 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see .
+
/**
* Version details
*
- * @package webservice
- * @subpackage amf
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
+ * @package webservice_amf
+ * @copyright 2009 Petr Skodak
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
diff --git a/webservice/externallib.php b/webservice/externallib.php
index 0c86f3c1b94..11c91aa81f6 100644
--- a/webservice/externallib.php
+++ b/webservice/externallib.php
@@ -14,23 +14,32 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see .
+
/**
* external API for mobile web services
*
- * @package core
- * @subpackage webservice
- * @copyright 2011 Moodle Pty Ltd (http://moodle.com)
+ * @package core_webservice
+ * @category external
+ * @copyright 2011 Jerome Mouneyrac
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
/**
* Web service related functions
+ *
+ * @package core_webservice
+ * @category external
+ * @copyright 2011 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.2
*/
class core_webservice_external extends external_api {
/**
* Returns description of method parameters
+ *
* @return external_function_parameters
+ * @since Moodle 2.2
*/
public static function get_site_info_parameters() {
return new external_function_parameters(
@@ -49,9 +58,11 @@ class core_webservice_external extends external_api {
/**
* Return user information including profile picture + basic site information
* Note:
- * - no capability checking because we return just known information by logged user
+ * - no capability checking because we return only known information about logged user
+ *
* @param array $serviceshortnames - DEPRECATED PARAMETER - values will be ignored - it was an original design error, we keep for backward compatibility.
- * @return array
+ * @return array site info
+ * @since Moodle 2.2
*/
public function get_site_info($serviceshortnames = array()) {
global $USER, $SITE, $CFG, $DB;
@@ -139,7 +150,9 @@ class core_webservice_external extends external_api {
/**
* Returns description of method result value
+ *
* @return external_single_structure
+ * @since Moodle 2.2
*/
public static function get_site_info_returns() {
return new external_single_structure(
@@ -167,14 +180,26 @@ class core_webservice_external extends external_api {
/**
* Deprecated web service related functions
- * @deprecated since Moodle 2.2 please use core_webservice_external instead
+ *
+ * @package core_webservice
+ * @category external
+ * @copyright 2011 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @deprecated Moodle 2.2 MDL-29106 - please do not use this class any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_webservice_external
+ * @since Moodle 2.1
*/
class moodle_webservice_external extends external_api {
/**
* Returns description of method parameters
- * @deprecated since Moodle 2.2 please use core_webservice_external::get_site_info_parameters instead
+ *
* @return external_function_parameters
+ * @deprecated Moodle 2.2 - please do not use this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_webservice_external::get_site_info_parameters
+ * @since Moodle 2.1
*/
public static function get_siteinfo_parameters() {
return core_webservice_external::get_site_info_parameters();
@@ -184,9 +209,13 @@ class moodle_webservice_external extends external_api {
* Return user information including profile picture + basic site information
* Note:
* - no capability checking because we return just known information by logged user
- * @deprecated since Moodle 2.2 please use core_webservice_external::get_site_info instead
+ *
* @param array $serviceshortnames of service shortnames - the functions of these services will be returned
* @return array
+ * @deprecated Moodle 2.2 - please do not use this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_webservice_external::get_site_info
+ * @since Moodle 2.1
*/
public function get_siteinfo($serviceshortnames = array()) {
return core_webservice_external::get_site_info($serviceshortnames);
@@ -194,8 +223,12 @@ class moodle_webservice_external extends external_api {
/**
* Returns description of method result value
- * @deprecated since Moodle 2.2 please use core_webservice_external::get_site_info_returns instead
+ *
* @return external_single_structure
+ * @deprecated Moodle 2.2 - please do not use this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_webservice_external::get_site_info_returns
+ * @since Moodle 2.1
*/
public static function get_siteinfo_returns() {
return core_webservice_external::get_site_info_returns();
diff --git a/webservice/lib.php b/webservice/lib.php
index bc8ece95dd5..e889a328b5f 100644
--- a/webservice/lib.php
+++ b/webservice/lib.php
@@ -1,5 +1,4 @@
.
+
/**
* Web services utility functions and classes
*
- * @package webservice
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package core_webservice
+ * @copyright 2009 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
require_once($CFG->libdir.'/externallib.php');
+/**
+ * WEBSERVICE_AUTHMETHOD_USERNAME - username/password authentication (also called simple authentication)
+ */
define('WEBSERVICE_AUTHMETHOD_USERNAME', 0);
+
+/**
+ * WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN - most common token authentication (external app, mobile app...)
+ */
define('WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN', 1);
+
+/**
+ * WEBSERVICE_AUTHMETHOD_SESSION_TOKEN - token for embedded application (requires Moodle session)
+ */
define('WEBSERVICE_AUTHMETHOD_SESSION_TOKEN', 2);
/**
* General web service library
+ *
+ * @package core_webservice
+ * @copyright 2010 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class webservice {
/**
* Authenticate user (used by download/upload file scripts)
+ *
* @param string $token
* @return array - contains the authenticated user, token and service objects
*/
@@ -153,8 +169,9 @@ class webservice {
}
/**
- * Add a user to the list of authorised user of a given service
- * @param object $user
+ * Allow user to call a service
+ *
+ * @param stdClass $user a user
*/
public function add_ws_authorised_user($user) {
global $DB;
@@ -163,8 +180,9 @@ class webservice {
}
/**
- * Remove a user from a list of allowed user of a service
- * @param object $user
+ * Disallow a user to call a service
+ *
+ * @param stdClass $user a user
* @param int $serviceid
*/
public function remove_ws_authorised_user($user, $serviceid) {
@@ -174,8 +192,9 @@ class webservice {
}
/**
- * Update service allowed user settings
- * @param object $user
+ * Update allowed user settings (ip restriction, valid until...)
+ *
+ * @param stdClass $user
*/
public function update_ws_authorised_user($user) {
global $DB;
@@ -185,7 +204,8 @@ class webservice {
/**
* Return list of allowed users with their options (ip/timecreated / validuntil...)
* for a given service
- * @param int $serviceid
+ *
+ * @param int $serviceid the service id to search against
* @return array $users
*/
public function get_ws_authorised_users($serviceid) {
@@ -205,10 +225,11 @@ class webservice {
}
/**
- * Return a authorised user with his options (ip/timecreated / validuntil...)
- * @param int $serviceid
- * @param int $userid
- * @return object
+ * Return an authorised user with their options (ip/timecreated / validuntil...)
+ *
+ * @param int $serviceid the service id to search against
+ * @param int $userid the user to search against
+ * @return stdClass
*/
public function get_ws_authorised_user($serviceid, $userid) {
global $DB, $CFG;
@@ -227,24 +248,25 @@ class webservice {
}
/**
- * Generate all ws token needed by a user
- * @param int $userid
+ * Generate all tokens of a specific user
+ *
+ * @param int $userid user id
*/
public function generate_user_ws_tokens($userid) {
global $CFG, $DB;
- /// generate a token for non admin if web service are enable and the user has the capability to create a token
+ // generate a token for non admin if web service are enable and the user has the capability to create a token
if (!is_siteadmin() && has_capability('moodle/webservice:createtoken', get_context_instance(CONTEXT_SYSTEM), $userid) && !empty($CFG->enablewebservices)) {
- /// for every service than the user is authorised on, create a token (if it doesn't already exist)
+ // for every service than the user is authorised on, create a token (if it doesn't already exist)
- ///get all services which are set to all user (no restricted to specific users)
+ // get all services which are set to all user (no restricted to specific users)
$norestrictedservices = $DB->get_records('external_services', array('restrictedusers' => 0));
$serviceidlist = array();
foreach ($norestrictedservices as $service) {
$serviceidlist[] = $service->id;
}
- //get all services which are set to the current user (the current user is specified in the restricted user list)
+ // get all services which are set to the current user (the current user is specified in the restricted user list)
$servicesusers = $DB->get_records('external_services_users', array('userid' => $userid));
foreach ($servicesusers as $serviceuser) {
if (!in_array($serviceuser->externalserviceid,$serviceidlist)) {
@@ -252,24 +274,24 @@ class webservice {
}
}
- //get all services which already have a token set for the current user
+ // get all services which already have a token set for the current user
$usertokens = $DB->get_records('external_tokens', array('userid' => $userid, 'tokentype' => EXTERNAL_TOKEN_PERMANENT));
$tokenizedservice = array();
foreach ($usertokens as $token) {
$tokenizedservice[] = $token->externalserviceid;
}
- //create a token for the service which have no token already
+ // create a token for the service which have no token already
foreach ($serviceidlist as $serviceid) {
if (!in_array($serviceid, $tokenizedservice)) {
- //create the token for this service
+ // create the token for this service
$newtoken = new stdClass();
$newtoken->token = md5(uniqid(rand(),1));
- //check that the user has capability on this service
+ // check that the user has capability on this service
$newtoken->tokentype = EXTERNAL_TOKEN_PERMANENT;
$newtoken->userid = $userid;
$newtoken->externalserviceid = $serviceid;
- //TODO: find a way to get the context - UPDATE FOLLOWING LINE
+ // TODO MDL-31190 find a way to get the context - UPDATE FOLLOWING LINE
$newtoken->contextid = get_context_instance(CONTEXT_SYSTEM)->id;
$newtoken->creatorid = $userid;
$newtoken->timecreated = time();
@@ -283,9 +305,12 @@ class webservice {
}
/**
- * Return all ws user token with ws enabled/disabled and ws restricted users mode.
- * @param integer $userid
- * @return array of token
+ * Return all tokens of a specific user
+ * + the service state (enabled/disabled)
+ * + the authorised user mode (restricted/not restricted)
+ *
+ * @param int $userid user id
+ * @return array
*/
public function get_user_ws_tokens($userid) {
global $DB;
@@ -301,16 +326,19 @@ class webservice {
}
/**
- * Return a user token that has been created by the user
- * If doesn't exist a exception is thrown
- * @param integer $userid
- * @param integer $tokenid
- * @return object token
+ * Return a token that has been created by the user (i.e. to created by an admin)
+ * If no tokens exist an exception is thrown
+ *
+ * The returned value is a stdClass:
* ->id token id
* ->token
* ->firstname user firstname
* ->lastname
* ->name service name
+ *
+ * @param int $userid user id
+ * @param int $tokenid token id
+ * @return stdClass
*/
public function get_created_by_user_ws_token($userid, $tokenid) {
global $DB;
@@ -328,8 +356,9 @@ class webservice {
}
/**
- * Return a token for a given id
- * @param integer $tokenid
+ * Return a database token record for a token id
+ *
+ * @param int $tokenid token id
* @return object token
*/
public function get_token_by_id($tokenid) {
@@ -338,8 +367,9 @@ class webservice {
}
/**
- * Delete a user token
- * @param int $tokenid
+ * Delete a token
+ *
+ * @param int $tokenid token id
*/
public function delete_user_ws_token($tokenid) {
global $DB;
@@ -347,8 +377,10 @@ class webservice {
}
/**
- * Delete a service - it also delete the functions and users references to this service
- * @param int $serviceid
+ * Delete a service
+ * Also delete function references and authorised user references.
+ *
+ * @param int $serviceid service id
*/
public function delete_service($serviceid) {
global $DB;
@@ -359,7 +391,8 @@ class webservice {
}
/**
- * Get a user token by token
+ * Get a full database token record for a given token value
+ *
* @param string $token
* @throws moodle_exception if there is multiple result
*/
@@ -369,9 +402,10 @@ class webservice {
}
/**
- * Get the list of all functions for given service ids
- * @param array $serviceids
- * @return array functions
+ * Get the functions list of a service list (by id)
+ *
+ * @param array $serviceids service ids
+ * @return array of functions
*/
public function get_external_functions($serviceids) {
global $DB;
@@ -390,9 +424,10 @@ class webservice {
}
/**
- * Get the list of all functions for given service shortnames
- * @param array $serviceshortnames
- * @param $enabledonly if true then only return function for the service that has been enabled
+ * Get the functions of a service list (by shortname). It can return only enabled functions if required.
+ *
+ * @param array $serviceshortnames service shortnames
+ * @param bool $enabledonly if true then only return functions for services that have been enabled
* @return array functions
*/
public function get_external_functions_by_enabled_services($serviceshortnames, $enabledonly = true) {
@@ -415,8 +450,9 @@ class webservice {
}
/**
- * Get the list of all functions not in the given service id
- * @param int $serviceid
+ * Get functions not included in a service
+ *
+ * @param int $serviceid service id
* @return array functions
*/
public function get_not_associated_external_functions($serviceid) {
@@ -434,9 +470,7 @@ class webservice {
/**
* Get list of required capabilities of a service, sorted by functions
- * @param integer $serviceid
- * @return array
- * example of return value:
+ * Example of returned value:
* Array
* (
* [moodle_group_create_groups] => Array
@@ -453,6 +487,9 @@ class webservice {
* [4] => moodle/course:enrolreview
* )
* )
+ *
+ * @param int $serviceid service id
+ * @return array
*/
public function get_service_required_capabilities($serviceid) {
$functions = $this->get_external_functions(array($serviceid));
@@ -470,8 +507,9 @@ class webservice {
/**
* Get user capabilities (with context)
- * Only usefull for documentation purpose
- * @param integer $userid
+ * Only useful for documentation purpose
+ *
+ * @param int $userid user id
* @return array
*/
public function get_user_capabilities($userid) {
@@ -488,10 +526,11 @@ class webservice {
}
/**
- * Get users missing capabilities for a given service
- * @param array $users
- * @param integer $serviceid
- * @return array of missing capabilities, the key being the user id
+ * Get missing user capabilities for a given service
+ *
+ * @param array $users users
+ * @param int $serviceid service id
+ * @return array of missing capabilities, keys being the user ids
*/
public function get_missing_capabilities_by_users($users, $serviceid) {
global $DB;
@@ -525,10 +564,11 @@ class webservice {
}
/**
- * Get a external service for a given id
- * @param service id $serviceid
- * @param integer $strictness IGNORE_MISSING, MUST_EXIST...
- * @return object external service
+ * Get an external service for a given service id
+ *
+ * @param int $serviceid service id
+ * @param int $strictness IGNORE_MISSING, MUST_EXIST...
+ * @return stdClass external service
*/
public function get_external_service_by_id($serviceid, $strictness=IGNORE_MISSING) {
global $DB;
@@ -538,10 +578,11 @@ class webservice {
}
/**
- * Get a external service for a given shortname
- * @param service shortname $shortname
- * @param integer $strictness IGNORE_MISSING, MUST_EXIST...
- * @return object external service
+ * Get an external service for a given shortname
+ *
+ * @param string $shortname service shortname
+ * @param int $strictness IGNORE_MISSING, MUST_EXIST...
+ * @return stdClass external service
*/
public function get_external_service_by_shortname($shortname, $strictness=IGNORE_MISSING) {
global $DB;
@@ -551,10 +592,11 @@ class webservice {
}
/**
- * Get a external function for a given id
- * @param function id $functionid
- * @param integer $strictness IGNORE_MISSING, MUST_EXIST...
- * @return object external function
+ * Get an external function for a given function id
+ *
+ * @param int $functionid function id
+ * @param int $strictness IGNORE_MISSING, MUST_EXIST...
+ * @return stdClass external function
*/
public function get_external_function_by_id($functionid, $strictness=IGNORE_MISSING) {
global $DB;
@@ -565,8 +607,9 @@ class webservice {
/**
* Add a function to a service
- * @param string $functionname
- * @param integer $serviceid
+ *
+ * @param string $functionname function name
+ * @param int $serviceid service id
*/
public function add_external_function_to_service($functionname, $serviceid) {
global $DB;
@@ -578,7 +621,9 @@ class webservice {
/**
* Add a service
- * @param object $service
+ * It generates the timecreated field automatically.
+ *
+ * @param stdClass $service
* @return serviceid integer
*/
public function add_external_service($service) {
@@ -588,9 +633,11 @@ class webservice {
return $serviceid;
}
- /**
+ /**
* Update a service
- * @param object $service
+ * It modifies the timemodified automatically.
+ *
+ * @param stdClass $service
*/
public function update_external_service($service) {
global $DB;
@@ -599,9 +646,10 @@ class webservice {
}
/**
- * Test whether a external function is already linked to a service
- * @param string $functionname
- * @param integer $serviceid
+ * Test whether an external function is already linked to a service
+ *
+ * @param string $functionname function name
+ * @param int $serviceid service id
* @return bool true if a matching function exists for the service, else false.
* @throws dml_exception if error
*/
@@ -612,6 +660,12 @@ class webservice {
'functionname' => $functionname));
}
+ /**
+ * Remove a function from a service
+ *
+ * @param string $functionname function name
+ * @param int $serviceid service id
+ */
public function remove_external_function_from_service($functionname, $serviceid) {
global $DB;
$DB->delete_records('external_services_functions',
@@ -624,11 +678,17 @@ class webservice {
/**
* Exception indicating access control problem in web service call
- * @author Petr Skoda (skodak)
+ *
+ * @package core_webservice
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class webservice_access_exception extends moodle_exception {
+
/**
* Constructor
+ *
+ * @param string $debuginfo the debug info
*/
function __construct($debuginfo) {
parent::__construct('accessexception', 'webservice', '', null, $debuginfo);
@@ -636,9 +696,10 @@ class webservice_access_exception extends moodle_exception {
}
/**
- * Is protocol enabled?
- * @param string $protocol name of WS protocol
- * @return bool
+ * Check if a protocol is enabled
+ *
+ * @param string $protocol name of WS protocol ('rest', 'soap', 'xmlrpc', 'amf'...)
+ * @return bool true if the protocol is enabled
*/
function webservice_protocol_is_enabled($protocol) {
global $CFG;
@@ -652,18 +713,21 @@ function webservice_protocol_is_enabled($protocol) {
return(in_array($protocol, $active));
}
-//=== WS classes ===
-
/**
* Mandatory interface for all test client classes.
- * @author Petr Skoda (skodak)
+ *
+ * @package core_webservice
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
interface webservice_test_client_interface {
+
/**
* Execute test client WS request
- * @param string $serverurl
- * @param string $function
- * @param array $params
+ *
+ * @param string $serverurl server url (including the token param)
+ * @param string $function web service function name
+ * @param array $params parameters of the web service function
* @return mixed
*/
public function simpletest($serverurl, $function, $params);
@@ -671,48 +735,55 @@ interface webservice_test_client_interface {
/**
* Mandatory interface for all web service protocol classes
- * @author Petr Skoda (skodak)
+ *
+ * @package core_webservice
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
interface webservice_server_interface {
+
/**
* Process request from client.
- * @return void
*/
public function run();
}
/**
* Abstract web service base class.
- * @author Petr Skoda (skodak)
+ *
+ * @package core_webservice
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
abstract class webservice_server implements webservice_server_interface {
- /** @property string $wsname name of the web server plugin */
+ /** @var string Name of the web server plugin */
protected $wsname = null;
- /** @property string $username name of local user */
+ /** @var string Name of local user */
protected $username = null;
- /** @property string $password password of the local user */
+ /** @var string Password of the local user */
protected $password = null;
- /** @property int $userid the local user */
+ /** @var int The local user */
protected $userid = null;
- /** @property integer $authmethod authentication method one of WEBSERVICE_AUTHMETHOD_* */
+ /** @var integer Authentication method one of WEBSERVICE_AUTHMETHOD_* */
protected $authmethod;
- /** @property string $token authentication token*/
+ /** @var string Authentication token*/
protected $token = null;
- /** @property object restricted context */
+ /** @var stdClass Restricted context */
protected $restricted_context;
- /** @property int restrict call to one service id*/
+ /** @var int Restrict call to one service id*/
protected $restricted_serviceid = null;
/**
- * Contructor
+ * Constructor
+ *
* @param integer $authmethod authentication method one of WEBSERVICE_AUTHMETHOD_*
*/
public function __construct($authmethod) {
@@ -726,7 +797,6 @@ abstract class webservice_server implements webservice_server_interface {
* It is safe to use has_capability() after this.
* This method also verifies user is allowed to use this
* server.
- * @return void
*/
protected function authenticate_user() {
global $CFG, $DB;
@@ -827,6 +897,13 @@ abstract class webservice_server implements webservice_server_interface {
external_api::set_context_restriction($this->restricted_context);
}
+ /**
+ * User authentication by token
+ *
+ * @param string $tokentype token type (EXTERNAL_TOKEN_EMBEDDED or EXTERNAL_TOKEN_PERMANENT)
+ * @return stdClass the authenticated user
+ * @throws webservice_access_exception
+ */
protected function authenticate_by_token($tokentype){
global $DB;
if (!$token = $DB->get_record('external_tokens', array('token'=>$this->token, 'tokentype'=>$tokentype))) {
@@ -867,24 +944,28 @@ abstract class webservice_server implements webservice_server_interface {
}
/**
- * Special abstraction of our srvices that allows
- * interaction with stock Zend ws servers.
- * @author Petr Skoda (skodak)
+ * Special abstraction of our services that allows interaction with stock Zend ws servers.
+ *
+ * @package core_webservice
+ * @copyright 2009 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
abstract class webservice_zend_server extends webservice_server {
- /** @property string name of the zend server class : Zend_XmlRpc_Server, Zend_Soap_Server, Zend_Soap_AutoDiscover, ...*/
+ /** @var string Name of the zend server class : Zend_Amf_Server, moodle_zend_soap_server, Zend_Soap_AutoDiscover, ...*/
protected $zend_class;
- /** @property object Zend server instance */
+ /** @var stdClass Zend server instance */
protected $zend_server;
- /** @property string $service_class virtual web service class with all functions user name execute, created on the fly */
+ /** @var string Virtual web service class with all functions user name execute, created on the fly */
protected $service_class;
/**
- * Contructor
- * @param integer $authmethod authentication method - one of WEBSERVICE_AUTHMETHOD_*
+ * Constructor
+ *
+ * @param int $authmethod authentication method - one of WEBSERVICE_AUTHMETHOD_*
+ * @param string $zend_class Name of the zend server class
*/
public function __construct($authmethod, $zend_class) {
parent::__construct($authmethod);
@@ -893,8 +974,8 @@ abstract class webservice_zend_server extends webservice_server {
/**
* Process request from client.
- * @param bool $simple use simple authentication
- * @return void
+ *
+ * @uses die
*/
public function run() {
// we will probably need a lot of memory in some functions
@@ -944,7 +1025,6 @@ abstract class webservice_zend_server extends webservice_server {
/**
* Load virtual class needed for Zend api
- * @return void
*/
protected function init_service_class() {
global $USER, $DB;
@@ -1035,7 +1115,8 @@ class '.$classname.' {
/**
* returns virtual method code
- * @param object $function
+ *
+ * @param stdClass $function a record from external_function
* @return string PHP code
*/
protected function get_virtual_method_code($function) {
@@ -1121,6 +1202,15 @@ class '.$classname.' {
return $code;
}
+ /**
+ * Get the phpdoc type for an external_description
+ * external_value => int, double or string
+ * external_single_structure => object|struct, on-fly generated stdClass name, ...
+ * external_multiple_structure => array
+ *
+ * @param string $keydesc any of PARAM_*
+ * @return string phpdoc type (string, double, int, array...)
+ */
protected function get_phpdoc_type($keydesc) {
if ($keydesc instanceof external_value) {
switch($keydesc->type) {
@@ -1144,6 +1234,15 @@ class '.$classname.' {
return $type;
}
+ /**
+ * Generate 'struct'/'object' type name
+ * Some servers (our Zend ones) parse the phpdoc to know the parameter types.
+ * The purpose to this function is to be overwritten when the common object|struct type are not understood by the server.
+ * See webservice/soap/locallib.php - the SOAP server requires detailed structure)
+ *
+ * @param external_single_structure $structdesc the structure for which we generate the phpdoc type
+ * @return string the phpdoc type
+ */
protected function generate_simple_struct_class(external_single_structure $structdesc) {
return 'object|struct'; //only 'object' is supported by SOAP, 'struct' by XML-RPC MDL-23083
}
@@ -1152,8 +1251,9 @@ class '.$classname.' {
* You can override this function in your child class to add extra code into the dynamically
* created service class. For example it is used in the amf server to cast types of parameters and to
* cast the return value to the types as specified in the return value description.
- * @param stdClass $function
- * @param array $params
+ *
+ * @param stdClass $function a record from external_function
+ * @param array $params web service function parameters
* @return string body of the method for $function ie. everything within the {} of the method declaration.
*/
protected function service_class_method_body($function, $params){
@@ -1182,6 +1282,7 @@ class '.$classname.' {
/**
* Recursive function to recurse down into a complex variable and convert all
* objects to arrays.
+ *
* @param mixed $param value to cast
* @return mixed Cast value
*/
@@ -1202,7 +1303,6 @@ class '.$classname.' {
/**
* Set up zend service class
- * @return void
*/
protected function init_zend_server() {
$this->zend_server = new $this->zend_class();
@@ -1237,7 +1337,6 @@ class '.$classname.' {
/**
* Internal implementation - sending of page headers.
- * @return void
*/
protected function send_headers() {
header('Cache-Control: private, must-revalidate, pre-check=0, post-check=0, max-age=0');
@@ -1251,7 +1350,7 @@ class '.$classname.' {
* it can not just print html to output.
*
* @param exception $ex
- * @return void does not return
+ * @uses exit
*/
public function exception_handler($ex) {
// detect active db transactions, rollback and log as error
@@ -1270,8 +1369,8 @@ class '.$classname.' {
/**
* Send the error information to the WS client
* formatted as XML document.
+ *
* @param exception $ex
- * @return void
*/
protected function send_error($ex=null) {
$this->send_headers();
@@ -1280,8 +1379,8 @@ class '.$classname.' {
/**
* Future hook needed for emulated sessions.
+ *
* @param exception $exception null means normal termination, $exception received when WS call failed
- * @return void
*/
protected function session_cleanup($exception=null) {
if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
@@ -1294,22 +1393,26 @@ class '.$classname.' {
}
/**
- * Web Service server base class, this class handles both
- * simple and token authentication.
- * @author Petr Skoda (skodak)
+ * Web Service server base class.
+ *
+ * This class handles both simple and token authentication.
+ *
+ * @package core_webservice
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
abstract class webservice_base_server extends webservice_server {
- /** @property array $parameters the function parameters - the real values submitted in the request */
+ /** @var array The function parameters - the real values submitted in the request */
protected $parameters = null;
- /** @property string $functionname the name of the function that is executed */
+ /** @var string The name of the function that is executed */
protected $functionname = null;
- /** @property object $function full function description */
+ /** @var stdClass Full function description */
protected $function = null;
- /** @property mixed $returns function return value */
+ /** @var mixed Function return value */
protected $returns = null;
/**
@@ -1317,27 +1420,25 @@ abstract class webservice_base_server extends webservice_server {
* 1/ user authentication - username+password or token
* 2/ function name
* 3/ function parameters
- *
- * @return void
*/
abstract protected function parse_request();
/**
* Send the result of function call to the WS client.
- * @return void
*/
abstract protected function send_response();
/**
* Send the error information to the WS client.
+ *
* @param exception $ex
- * @return void
*/
abstract protected function send_error($ex=null);
/**
* Process request from client.
- * @return void
+ *
+ * @uses die
*/
public function run() {
// we will probably need a lot of memory in some functions
@@ -1383,7 +1484,7 @@ abstract class webservice_base_server extends webservice_server {
* it can not just print html to output.
*
* @param exception $ex
- * @return void does not return
+ * $uses exit
*/
public function exception_handler($ex) {
// detect active db transactions, rollback and log as error
@@ -1401,8 +1502,8 @@ abstract class webservice_base_server extends webservice_server {
/**
* Future hook needed for emulated sessions.
+ *
* @param exception $exception null means normal termination, $exception received when WS call failed
- * @return void
*/
protected function session_cleanup($exception=null) {
if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
@@ -1416,7 +1517,6 @@ abstract class webservice_base_server extends webservice_server {
* Fetches the function description from database,
* verifies user is allowed to use this function and
* loads all paremeters and return descriptions.
- * @return void
*/
protected function load_function_info() {
global $DB, $USER, $CFG;
@@ -1486,7 +1586,6 @@ abstract class webservice_base_server extends webservice_server {
/**
* Execute previously loaded function using parameters parsed from the request data.
- * @return void
*/
protected function execute() {
// validate params, this also sorts the params properly, we need the correct order in the next part
diff --git a/webservice/pluginfile.php b/webservice/pluginfile.php
index 186e36e709f..acc3f1ca0b8 100644
--- a/webservice/pluginfile.php
+++ b/webservice/pluginfile.php
@@ -1,5 +1,4 @@
.
+
/**
* A script to serve files from web service client
*
- * @package core
- * @subpackage file
+ * @package core_webservice
* @copyright 2011 Dongsheng Cai
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
+/**
+ * AJAX_SCRIPT - exception will be converted into JSON
+ */
define('AJAX_SCRIPT', true);
+
+/**
+ * NO_MOODLE_COOKIES - we don't want any cookie
+ */
define('NO_MOODLE_COOKIES', true);
+
+
require_once(dirname(dirname(__FILE__)) . '/config.php');
require_once($CFG->libdir . '/filelib.php');
require_once($CFG->dirroot . '/webservice/lib.php');
diff --git a/webservice/renderer.php b/webservice/renderer.php
index 75668fd6a8a..52f0e5f545a 100644
--- a/webservice/renderer.php
+++ b/webservice/renderer.php
@@ -1,37 +1,34 @@
.
-///////////////////////////////////////////////////////////////////////////
-// //
-// This file is part of Moodle - http://moodle.org/ //
-// Moodle - Modular Object-Oriented Dynamic Learning Environment //
-// //
-// Moodle is free software: you can redistribute it and/or modify //
-// it under the terms of the GNU General Public License as published by //
-// the Free Software Foundation, either version 3 of the License, or //
-// (at your option) any later version. //
-// //
-// Moodle is distributed in the hope that it will be useful, //
-// but WITHOUT ANY WARRANTY; without even the implied warranty of //
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the //
-// GNU General Public License for more details. //
-// //
-// You should have received a copy of the GNU General Public License //
-// along with Moodle. If not, see . //
-// //
-///////////////////////////////////////////////////////////////////////////
/**
* Web service documentation renderer.
- * @package webservice
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
- * @author Jerome Mouneyrac
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ *
+ * @package core_webservice
+ * @category output
+ * @copyright 2009 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class core_webservice_renderer extends plugin_renderer_base {
/**
* Display the authorised user selector
- * @param object $options
+ *
+ * @param stdClass $options It contains alloweduserselector, potentialuserselector and serviceid
* @return string html
*/
public function admin_authorised_user_selector(&$options) {
@@ -99,8 +96,10 @@ class core_webservice_renderer extends plugin_renderer_base {
}
/**
- * Display list of authorised user
- * @param array $users
+ * Display list of authorised users
+ *
+ * @param array $users authorised users
+ * @param int $serviceid service id
* @return string $html
*/
public function admin_authorised_user_list($users, $serviceid) {
@@ -129,8 +128,9 @@ class core_webservice_renderer extends plugin_renderer_base {
/**
* Display a confirmation page to remove a function from a service
- * @param object $function
- * @param object $service
+ *
+ * @param stdClass $function It needs function id + function name properties.
+ * @param stdClass $service It needs service id + service name properties.
* @return string html
*/
public function admin_remove_service_function_confirmation($function, $service) {
@@ -148,7 +148,8 @@ class core_webservice_renderer extends plugin_renderer_base {
/**
* Display a confirmation page to remove a service
- * @param object $service
+ *
+ * @param stdClass $service It needs service id + service name properties.
* @return string html
*/
public function admin_remove_service_confirmation($service) {
@@ -167,7 +168,8 @@ class core_webservice_renderer extends plugin_renderer_base {
/**
* Display a confirmation page to delete a token
- * @param object $token
+ *
+ * @param stdClass $token Required properties: id (token id), firstname (user firstname), lastname (user lastname), name (service name)
* @return string html
*/
public function admin_delete_token_confirmation($token) {
@@ -188,10 +190,11 @@ class core_webservice_renderer extends plugin_renderer_base {
}
/**
- * Display list of function for a given service
- * If the service is build-in do not display remove/add operation (read-only)
- * @param array $functions
- * @param object $service
+ * Display a list of functions for a given service
+ * If the service is built-in, do not display remove/add operation (read-only)
+ *
+ * @param array $functions list of functions
+ * @param stdClass $service the given service
* @return string the table html + add operation html
*/
public function admin_service_function_list($functions, $service) {
@@ -251,7 +254,8 @@ class core_webservice_renderer extends plugin_renderer_base {
/**
* Display Reset token confirmation box
- * @param object $token to reset
+ *
+ * @param stdClass $token token to reset
* @return string html
*/
public function user_reset_token_confirmation($token) {
@@ -273,8 +277,10 @@ class core_webservice_renderer extends plugin_renderer_base {
/**
* Display user tokens with buttons to reset them
- * @param object $tokens
- * @param int $userid
+ *
+ * @param stdClass $tokens user tokens
+ * @param int $userid user id
+ * @param bool $documentation if true display a link to the API documentation
* @return string html code
*/
public function user_webservice_tokens_box($tokens, $userid, $documentation = false) {
@@ -326,7 +332,7 @@ class core_webservice_renderer extends plugin_renderer_base {
$validuntil = '';
if (!empty($token->validuntil)) {
- $validuntil = date("F j, Y"); //TODO: language support (look for moodle function)
+ $validuntil = date("F j, Y"); //TODO MDL-31193 language support (look for moodle function)
}
$tokenname = $token->name;
@@ -357,20 +363,22 @@ class core_webservice_renderer extends plugin_renderer_base {
* Return documentation for a ws description object
* ws description object can be 'external_multiple_structure', 'external_single_structure'
* or 'external_value'
+ *
* Example of documentation for moodle_group_create_groups function:
- list of (
- object {
- courseid int //id of course
- name string //multilang compatible name, course unique
- description string //group description text
- enrolmentkey string //group enrol secret phrase
- }
- )
- * @param object $params a part of parameter/return description
+ * list of (
+ * object {
+ * courseid int //id of course
+ * name string //multilang compatible name, course unique
+ * description string //group description text
+ * enrolmentkey string //group enrol secret phrase
+ * }
+ * )
+ *
+ * @param stdClass $params a part of parameter/return description
* @return string the html to display
*/
public function detailed_description_html($params) {
- /// retrieve the description of the description object
+ // retrieve the description of the description object
$paramdesc = "";
if (!empty($params->desc)) {
$paramdesc .= html_writer::start_tag('span', array('style' => "color:#2A33A6"));
@@ -401,12 +409,12 @@ class core_webservice_renderer extends plugin_renderer_base {
$paramdesc .= html_writer::empty_tag('br', array());
}
- /// description object is a list
+ // description object is a list
if ($params instanceof external_multiple_structure) {
return $paramdesc . "list of ( " . html_writer::empty_tag('br', array())
. $this->detailed_description_html($params->content) . ")";
} else if ($params instanceof external_single_structure) {
- /// description object is an object
+ // description object is an object
$singlestructuredesc = $paramdesc . "object {" . html_writer::empty_tag('br', array());
foreach ($params->keys as $attributname => $attribut) {
$singlestructuredesc .= html_writer::start_tag('b', array());
@@ -419,7 +427,7 @@ class core_webservice_renderer extends plugin_renderer_base {
$singlestructuredesc .= html_writer::empty_tag('br', array());
return $singlestructuredesc;
} else {
- /// description object is a primary type (string, integer)
+ // description object is a primary type (string, integer)
switch ($params->type) {
case PARAM_BOOL: // 0 or 1 only for now
case PARAM_INT:
@@ -437,9 +445,10 @@ class core_webservice_renderer extends plugin_renderer_base {
/**
* Return a description object in indented xml format (for REST response)
- * It is indented in order to be displayed into
tag
- * @param object $returndescription
- * @param string $indentation composed by space only
+ * It is indented to be output within
tags
+ *
+ * @param external_description $returndescription the description structure of the web service function returned value
+ * @param string $indentation Indentation in the generated HTML code; should contain only spaces.
* @return string the html to diplay
*/
public function description_in_indented_xml_format($returndescription, $indentation = "") {
@@ -448,7 +457,7 @@ class core_webservice_renderer extends plugin_renderer_base {
EOF;
- /// description object is a list
+ // description object is a list
if ($returndescription instanceof external_multiple_structure) {
$return = $indentation . "" . $brakeline;
$return .= $this->description_in_indented_xml_format($returndescription->content,
@@ -456,7 +465,7 @@ EOF;
$return .= $indentation . "" . $brakeline;
return $return;
} else if ($returndescription instanceof external_single_structure) {
- /// description object is an object
+ // description object is an object
$singlestructuredesc = $indentation . "" . $brakeline;
$keyindentation = $indentation . " ";
foreach ($returndescription->keys as $attributname => $attribut) {
@@ -469,7 +478,7 @@ EOF;
$singlestructuredesc .= $indentation . "" . $brakeline;
return $singlestructuredesc;
} else {
- /// description object is a primary type (string, integer)
+ // description object is a primary type (string, integer)
switch ($returndescription->type) {
case PARAM_BOOL: // 0 or 1 only for now
case PARAM_INT:
@@ -487,8 +496,9 @@ EOF;
/**
* Create indented XML-RPC param description
- * @param object $paramdescription
- * @param string $indentation composed by space only
+ *
+ * @param external_description $paramdescription the description structure of the web service function parameters
+ * @param string $indentation Indentation in the generated HTML code; should contain only spaces.
* @return string the html to diplay
*/
public function xmlrpc_param_description_html($paramdescription, $indentation = "") {
@@ -497,7 +507,7 @@ EOF;
EOF;
- /// description object is a list
+ // description object is a list
if ($paramdescription instanceof external_multiple_structure) {
$return = $brakeline . $indentation . "Array ";
$indentation = $indentation . " ";
@@ -507,7 +517,7 @@ EOF;
$return .= $brakeline . $indentation . ")";
return $return;
} else if ($paramdescription instanceof external_single_structure) {
- /// description object is an object
+ // description object is an object
$singlestructuredesc = $brakeline . $indentation . "Array ";
$keyindentation = $indentation . " ";
$singlestructuredesc .= $brakeline . $keyindentation . "(";
@@ -520,7 +530,7 @@ EOF;
$singlestructuredesc .= $brakeline . $keyindentation . ")";
return $singlestructuredesc;
} else {
- /// description object is a primary type (string, integer)
+ // description object is a primary type (string, integer)
switch ($paramdescription->type) {
case PARAM_BOOL: // 0 or 1 only for now
case PARAM_INT:
@@ -537,14 +547,15 @@ EOF;
}
/**
- * Return the html of a colored box with content
+ * Return the html of a coloured box with content
+ *
* @param string $title - the title of the box
* @param string $content - the content to displayed
* @param string $rgb - the background color of the box
- * @return
+ * @return string HTML code
*/
public function colored_box_with_pre_tag($title, $content, $rgb = 'FEEBE5') {
- //TODO: this tag removes xhtml strict error but cause warning
+ //TODO MDL-31192 this tag removes xhtml strict error but cause warning
$coloredbox = html_writer::start_tag('div', array());
$coloredbox .= html_writer::start_tag('div',
array('style' => "border:solid 1px #DEDEDE;background:#" . $rgb
@@ -563,8 +574,9 @@ EOF;
/**
* Return indented REST param description
- * @param object $paramdescription
- * @param string $indentation composed by space only
+ *
+ * @param external_description $paramdescription the description structure of the web service function parameters
+ * @param string $paramstring parameter
* @return string the html to diplay
*/
public function rest_param_description_html($paramdescription, $paramstring) {
@@ -572,13 +584,13 @@ EOF;
EOF;
- /// description object is a list
+ // description object is a list
if ($paramdescription instanceof external_multiple_structure) {
$paramstring = $paramstring . '[0]';
$return = $this->rest_param_description_html($paramdescription->content, $paramstring);
return $return;
} else if ($paramdescription instanceof external_single_structure) {
- /// description object is an object
+ // description object is an object
$singlestructuredesc = "";
$initialparamstring = $paramstring;
foreach ($paramdescription->keys as $attributname => $attribut) {
@@ -588,7 +600,7 @@ EOF;
}
return $singlestructuredesc;
} else {
- /// description object is a primary type (string, integer)
+ // description object is a primary type (string, integer)
$paramstring = $paramstring . '=';
switch ($paramdescription->type) {
case PARAM_BOOL: // 0 or 1 only for now
@@ -606,11 +618,12 @@ EOF;
}
/**
- * This display all the documentation
- * @param array $functions contains all decription objects
- * @param array $authparam keys contains 'tokenid'
+ * Displays all the documentation
+ *
+ * @param array $functions external_description of all the web service functions
* @param boolean $printableformat true if we want to display the documentation in a printable format
- * @param array $activatedprotocol
+ * @param array $activatedprotocol the currently enabled protocol
+ * @param array $authparams url parameters (it contains 'tokenid' and sometimes 'print')
* @param string $parenturl url of the calling page - needed for the print button url:
* '/admin/documentation.php' or '/webservice/wsdoc.php' (default)
* @return string the html to diplay
@@ -625,7 +638,7 @@ EOF;
EOF;
- /// Some general information
+ // Some general information
$docinfo = new stdClass();
$docurl = new moodle_url('http://docs.moodle.org/dev/Creating_a_web_service_client');
$docinfo->doclink = html_writer::tag('a',
@@ -638,15 +651,14 @@ EOF;
$documentationhtml .= $br . $br;
- /// Print button
+ // Print button
$authparams['print'] = true;
- //$parameters = array ('token' => $token, 'wsusername' => $username, 'wspassword' => $password, 'print' => true);
$url = new moodle_url($parenturl, $authparams); // Required
$documentationhtml .= $this->output->single_button($url, get_string('print', 'webservice'));
$documentationhtml .= $br;
- /// each functions will be displayed into a collapsible region
+ // each functions will be displayed into a collapsible region
//(opened if printableformat = true)
foreach ($functions as $functionname => $description) {
@@ -663,7 +675,7 @@ EOF;
$documentationhtml .= $br;
}
- /// function global description
+ // function global description
$documentationhtml .= $br;
$documentationhtml .= html_writer::start_tag('div',
array('style' => 'border:solid 1px #DEDEDE;background:#E2E0E0;
@@ -672,13 +684,13 @@ EOF;
$documentationhtml .= html_writer::end_tag('div');
$documentationhtml .= $br . $br;
- /// function arguments documentation
+ // function arguments documentation
$documentationhtml .= html_writer::start_tag('span', array('style' => 'color:#EA33A6'));
$documentationhtml .= get_string('arguments', 'webservice');
$documentationhtml .= html_writer::end_tag('span');
$documentationhtml .= $br;
foreach ($description->parameters_desc->keys as $paramname => $paramdesc) {
- /// a argument documentation
+ // a argument documentation
$documentationhtml .= html_writer::start_tag('span', array('style' => 'font-size:80%'));
if ($paramdesc->required == VALUE_REQUIRED) {
@@ -704,12 +716,12 @@ EOF;
$documentationhtml .= " "
. $paramdesc->desc; // argument description
$documentationhtml .= $br . $br;
- ///general structure of the argument
+ // general structure of the argument
$documentationhtml .= $this->colored_box_with_pre_tag(
get_string('generalstructure', 'webservice'),
$this->detailed_description_html($paramdesc),
'FFF1BC');
- ///xml-rpc structure of the argument in PHP format
+ // xml-rpc structure of the argument in PHP format
if (!empty($activatedprotocol['xmlrpc'])) {
$documentationhtml .= $this->colored_box_with_pre_tag(
get_string('phpparam', 'webservice'),
@@ -717,7 +729,7 @@ EOF;
. $this->xmlrpc_param_description_html($paramdesc)),
'DFEEE7');
}
- ///POST format for the REST protocol for the argument
+ // POST format for the REST protocol for the argument
if (!empty($activatedprotocol['rest'])) {
$documentationhtml .= $this->colored_box_with_pre_tag(
get_string('restparam', 'webservice'),
@@ -730,24 +742,24 @@ EOF;
$documentationhtml .= $br . $br;
- /// function response documentation
+ // function response documentation
$documentationhtml .= html_writer::start_tag('span', array('style' => 'color:#EA33A6'));
$documentationhtml .= get_string('response', 'webservice');
$documentationhtml .= html_writer::end_tag('span');
$documentationhtml .= $br;
- /// function response description
+ // function response description
$documentationhtml .= html_writer::start_tag('span', array('style' => 'font-size:80%'));
if (!empty($description->returns_desc->desc)) {
$documentationhtml .= $description->returns_desc->desc;
$documentationhtml .= $br . $br;
}
if (!empty($description->returns_desc)) {
- ///general structure of the response
+ // general structure of the response
$documentationhtml .= $this->colored_box_with_pre_tag(
get_string('generalstructure', 'webservice'),
$this->detailed_description_html($description->returns_desc),
'FFF1BC');
- ///xml-rpc structure of the response in PHP format
+ // xml-rpc structure of the response in PHP format
if (!empty($activatedprotocol['xmlrpc'])) {
$documentationhtml .= $this->colored_box_with_pre_tag(
get_string('phpresponse', 'webservice'),
@@ -755,7 +767,7 @@ EOF;
$description->returns_desc)),
'DFEEE7');
}
- ///XML response for the REST protocol
+ // XML response for the REST protocol
if (!empty($activatedprotocol['rest'])) {
$restresponse = ""
. $brakeline . "" . $brakeline;
@@ -771,7 +783,7 @@ EOF;
$documentationhtml .= html_writer::end_tag('span');
$documentationhtml .= $br . $br;
- /// function errors documentation for REST protocol
+ // function errors documentation for REST protocol
if (!empty($activatedprotocol['rest'])) {
$documentationhtml .= html_writer::start_tag('span', array('style' => 'color:#EA33A6'));
$documentationhtml .= get_string('errorcodes', 'webservice');
@@ -799,7 +811,7 @@ EOF;
}
}
- /// close the table and return the documentation
+ // close the table and return the documentation
$documentationhtml .= html_writer::end_tag('td');
$documentationhtml .= html_writer::end_tag('tr');
$documentationhtml .= html_writer::end_tag('table');
diff --git a/webservice/rest/db/access.php b/webservice/rest/db/access.php
index 0d389121072..551e8df3d18 100644
--- a/webservice/rest/db/access.php
+++ b/webservice/rest/db/access.php
@@ -1,4 +1,28 @@
.
+
+
+/**
+ * REST server related capabilities
+ *
+ * @package webservice_rest
+ * @category access
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
$capabilities = array(
diff --git a/webservice/rest/lang/en/webservice_rest.php b/webservice/rest/lang/en/webservice_rest.php
index f268bdaa6cf..dfe42f2b7bf 100644
--- a/webservice/rest/lang/en/webservice_rest.php
+++ b/webservice/rest/lang/en/webservice_rest.php
@@ -1,5 +1,4 @@
.
+
/**
* Strings for component 'webservice_rest', language 'en', branch 'MOODLE_20_STABLE'
*
- * @package webservice_rest
- * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com}
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package webservice_rest
+ * @category string
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
$string['pluginname'] = 'REST protocol';
diff --git a/webservice/rest/lib.php b/webservice/rest/lib.php
index e2b7df8c6d6..5a79ded6cec 100644
--- a/webservice/rest/lib.php
+++ b/webservice/rest/lib.php
@@ -1,5 +1,4 @@
.
+
/**
- * Moodle REST client class
- * TODO: XML to PHP
+ * Moodle REST library
+ *
+ * @package webservice_rest
+ * @copyright 2009 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+
+/**
+ * Moodle REST client
+ *
+ * It has been implemented for unit testing purpose (all protocols have similar client)
+ *
+ * @package webservice_rest
+ * @copyright 2010 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class webservice_rest_client {
/** @var moodle_url the REST server url */
private $serverurl;
+ /** @var string token */
private $token;
+
+ /** @var string returned value format: xml or json */
private $format;
/**
* Constructor
+ *
* @param string $serverurl a Moodle URL
- * @param string $token
+ * @param string $token the token used to do the web service call
+ * @param string $format returned value format: xml or json
*/
public function __construct($serverurl, $token, $format = 'xml') {
$this->serverurl = new moodle_url($serverurl);
@@ -40,7 +59,8 @@ class webservice_rest_client {
/**
* Set the token used to do the REST call
- * @param string $token
+ *
+ * @param string $token the token used to do the web service call
*/
public function set_token($token) {
$this->token = $token;
@@ -48,8 +68,9 @@ class webservice_rest_client {
/**
* Execute client WS request with token authentication
- * @param string $functionname
- * @param array $params
+ *
+ * @param string $functionname the function name
+ * @param array $params the parameters of the function
* @return mixed
*/
public function call($functionname, $params) {
@@ -67,7 +88,7 @@ class webservice_rest_client {
$result = download_file_content($this->serverurl->out(false), null, $params);
- //TODO : transform the XML result into PHP values - MDL-22965
+ //TODO MDL-22965 transform the XML result into PHP values
if ($this->format == 'json') {
$result = json_decode($result);
}
diff --git a/webservice/rest/locallib.php b/webservice/rest/locallib.php
index 075f6b6dd54..99de15f6401 100644
--- a/webservice/rest/locallib.php
+++ b/webservice/rest/locallib.php
@@ -1,5 +1,4 @@
.
+
/**
* REST web service implementation classes and methods.
*
- * @package webservice
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package webservice_rest
+ * @copyright 2009 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
require_once("$CFG->dirroot/webservice/lib.php");
/**
* REST service server implementation.
- * @author Petr Skoda (skodak)
+ *
+ * @package webservice_rest
+ * @copyright 2009 Petr Skoda (skodak)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class webservice_rest_server extends webservice_base_server {
- /** @property string $alt return method (XML / JSON) */
+ /** @var string return method ('xml' or 'json') */
protected $restformat;
/**
* Contructor
+ *
+ * @param string $authmethod authentication method of the web service (WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN, ...)
+ * @param string $restformat Format of the return values: 'xml' or 'json'
*/
public function __construct($authmethod, $restformat = 'xml') {
parent::__construct($authmethod);
@@ -49,8 +55,6 @@ class webservice_rest_server extends webservice_base_server {
* 1/ user authentication - username+password or token (wsusername, wspassword and wstoken parameters)
* 2/ function name (wsfunction parameter)
* 3/ function parameters (all other parameters except those above)
- *
- * @return void
*/
protected function parse_request() {
@@ -83,7 +87,6 @@ class webservice_rest_server extends webservice_base_server {
/**
* Send the result of function call to the WS client
* formatted as XML document.
- * @return void
*/
protected function send_response() {
@@ -121,8 +124,7 @@ class webservice_rest_server extends webservice_base_server {
* formatted as XML document.
* Note: the exception is never passed as null,
* it only matches the abstract function declaration.
- * @param exception $ex
- * @return void
+ * @param exception $ex the exception that we are sending
*/
protected function send_error($ex=null) {
$this->send_headers();
@@ -131,7 +133,7 @@ class webservice_rest_server extends webservice_base_server {
/**
* Build the error information matching the REST returned value format (JSON or XML)
- * @param exception $ex
+ * @param exception $ex the exception we are converting in the server rest format
* @return string the error in the requested REST format
*/
protected function generate_error($ex) {
@@ -157,7 +159,6 @@ class webservice_rest_server extends webservice_base_server {
/**
* Internal implementation - sending of page headers.
- * @return void
*/
protected function send_headers() {
if ($this->restformat == 'json') {
@@ -174,9 +175,10 @@ class webservice_rest_server extends webservice_base_server {
/**
* Internal implementation - recursive function producing XML markup.
- * @param mixed $returns
- * @param $desc
- * @return unknown_type
+ *
+ * @param mixed $returns the returned values
+ * @param external_description $desc
+ * @return string
*/
protected static function xmlize_result($returns, $desc) {
if ($desc === null) {
@@ -217,13 +219,17 @@ class webservice_rest_server extends webservice_base_server {
/**
* REST test client class
+ *
+ * @package webservice_rest
+ * @copyright 2009 Petr Skoda (skodak)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class webservice_rest_test_client implements webservice_test_client_interface {
/**
* Execute test client WS request
- * @param string $serverurl
- * @param string $function
- * @param array $params
+ * @param string $serverurl server url (including token parameter or username/password parameters)
+ * @param string $function function name
+ * @param array $params parameters of the called function
* @return mixed
*/
public function simpletest($serverurl, $function, $params) {
diff --git a/webservice/rest/server.php b/webservice/rest/server.php
index ec97e0563c7..5e9f515179d 100644
--- a/webservice/rest/server.php
+++ b/webservice/rest/server.php
@@ -1,5 +1,4 @@
.
+
/**
* REST web service entry point. The authentication is done via tokens.
*
- * @package webservice
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package webservice_rest
+ * @copyright 2009 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
-// disable moodle specific debug messages and any errors in output
+/**
+ * NO_DEBUG_DISPLAY - disable moodle specific debug messages and any errors in output
+ */
define('NO_DEBUG_DISPLAY', true);
+
+/**
+ * NO_MOODLE_COOKIES - no cookies with web service
+ */
define('NO_MOODLE_COOKIES', true);
require('../../config.php');
diff --git a/webservice/rest/simpleserver.php b/webservice/rest/simpleserver.php
index 7b3069641d7..1bf062b171c 100644
--- a/webservice/rest/simpleserver.php
+++ b/webservice/rest/simpleserver.php
@@ -1,5 +1,4 @@
.
+
/**
- * REST web service entry point. The authentication is done via tokens.
+ * REST web service entry point. The authentication is done via username/password.
*
- * @package webservice
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package webservice_rest
+ * @copyright 2009 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
-// disable moodle specific debug messages and any errors in output
+/**
+ * NO_DEBUG_DISPLAY - disable moodle specific debug messages and any errors in output
+ */
define('NO_DEBUG_DISPLAY', true);
+
+/**
+ * NO_MOODLE_COOKIES - no cookies with web service
+ */
define('NO_MOODLE_COOKIES', true);
require('../../config.php');
diff --git a/webservice/rest/version.php b/webservice/rest/version.php
index e1bef5e4ebe..ab4469ea4e7 100644
--- a/webservice/rest/version.php
+++ b/webservice/rest/version.php
@@ -14,12 +14,12 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see .
+
/**
* Version details
*
- * @package webservice
- * @subpackage rest
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
+ * @package webservice_rest
+ * @copyright 2009 Jerome Mouneyrac
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
diff --git a/webservice/simpletest/testwebservice.php b/webservice/simpletest/testwebservice.php
index 3bf0e86b1da..91bb57b79dc 100644
--- a/webservice/simpletest/testwebservice.php
+++ b/webservice/simpletest/testwebservice.php
@@ -1,5 +1,4 @@
.
+
/**
* Test the different web service protocols.
*
- * @author jerome@moodle.com
- * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
- * @package web service
+ * @package core_webservice
+ * @copyright 2010 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
+
if (!defined('MOODLE_INTERNAL')) {
- /// It must be included from a Moodle page
+ // It must be included from a Moodle page
die('Direct access to this script is forbidden.');
}
/**
- * How to configure this unit tests:
- * 0- Enable the web service you wish to test in the Moodle administration
- * 1- Create a service with all functions in the Moodle administration
- * 2- Create a token associate this service and to an admin (or a user with all required capabilities)
+ * Web service unit test class
+ *
+ * How to configure these unit tests:
+ * 0- Enable the web service you wish to test using Moodle site administration
+ * 1- Create a service with all functions using Moodle site administration
+ * 2- Create a token for this service. The token should be linked to an admin (or a user with all required capabilities)
* 3- Configure setUp() function:
* a- write the token
* b- activate the protocols you wish to test
* c- activate the functions you wish to test (readonlytests and writetests arrays)
- * d- set the number of time the web services are run
- * Do not run WRITE test function on a production site as they impact the DB (even though every
+ * d- set the number of times the web services are run
+ * Do not run the WRITE test function on a production site as they impact the DB (even though every
* test should clean the modified data)
*
* How to write a new function:
* 1- Add the function name to the array readonlytests/writetests
* 2- Set it as false when you commit!
- * 3- write the function - Do not prefix the function name by 'test'
+ * 3- write the function - Do not prefix the function name with 'test'
+ *
+ * @package core_webservice
+ * @copyright 2010 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class webservice_test extends UnitTestCase {
+ /** @var string the token used to call the web service functions during tests */
public $testtoken;
+
+ /** @var bool Set it to true if you want to test the functions with the REST protocol */
public $testrest;
+
+ /** @var bool Set it to true if you want to test the functions with the XML-RPC protocol */
public $testxmlrpc;
+
+ /** @var bool Set it to true if you want to test the functions with the SOAP protocol */
public $testsoap;
+
+ /** @var bool Set it to true if you want to time profile the REST protocol */
public $timerrest;
+
+ /** @var bool Set it to true if you want to time profile the XML-RPC protocol */
public $timerxmlrpc;
+
+ /** @var bool Set it to true if you want to time profile the SOAP protocol */
public $timersoap;
+
+ /** @var bool DB READ-ONLY functions. Only "set to true" functions are run.*/
public $readonlytests;
+
+ /** @var bool DB WRITE functions. Only "set to true" functions are run. */
public $writetests;
+ /**
+ * Test set up
+ */
function setUp() {
//token to test
$this->testtoken = 'acabec9d20933913f14309785324f579';
//protocols to test
- $this->testrest = false; //Does not work till XML => PHP is implemented (MDL-22965)
+ $this->testrest = false; //TODO MDL-30210/MDL-22965 call REST in JSON mode
+ //DO NOT CHANGE
+ //The REST server cannot be tested till the issue ares fixed
$this->testxmlrpc = false;
$this->testsoap = false;
- ////// READ-ONLY DB tests ////
+ // READ-ONLY DB tests
$this->readonlytests = array(
'moodle_group_get_groups' => false,
'moodle_course_get_courses' => false,
@@ -78,7 +107,7 @@ class webservice_test extends UnitTestCase {
'core_course_get_contents' => false
);
- ////// WRITE DB tests ////
+ // WRITE DB tests
$this->writetests = array(
'moodle_user_create_users' => false,
'moodle_course_create_courses' => false,
@@ -105,6 +134,9 @@ class webservice_test extends UnitTestCase {
$this->timersoap = 0;
}
+ /**
+ * Run the tests
+ */
function testRun() {
global $CFG;
@@ -115,7 +147,8 @@ class webservice_test extends UnitTestCase {
if (!empty($this->testtoken)) {
- //Does not work till XML => PHP is implemented (MDL-22965)
+ //TODO MDL-30210/MDL-22965 call REST in JSON mode
+ //The REST cannot be tested till the issue ares fixed
if ($this->testrest) {
$this->timerrest = time();
@@ -205,8 +238,11 @@ class webservice_test extends UnitTestCase {
}
}
- ///// WEB SERVICE TEST FUNCTIONS
-
+ /**
+ * Test moodle_group_get_groups web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ */
function moodle_group_get_groups($client) {
global $DB;
$dbgroups = $DB->get_records('groups');
@@ -221,6 +257,11 @@ class webservice_test extends UnitTestCase {
$this->assertEqual(count($groups), count($groupids));
}
+ /**
+ * Test moodle_webservice_get_siteinfo web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ */
function moodle_webservice_get_siteinfo($client) {
global $SITE, $CFG;
@@ -233,6 +274,11 @@ class webservice_test extends UnitTestCase {
$this->assertEqual($info['siteurl'], $CFG->wwwroot);
}
+ /**
+ * Test moodle_user_get_users_by_id web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ */
function moodle_user_get_users_by_id($client) {
global $DB;
$dbusers = $DB->get_records('user', array('deleted' => 0));
@@ -248,6 +294,11 @@ class webservice_test extends UnitTestCase {
$this->assertEqual(count($users), count($userids));
}
+ /**
+ * Test moodle_group_get_groups web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ */
function core_course_get_contents($client) {
global $DB, $CFG;
$dbcourses = $DB->get_records('course');
@@ -269,10 +320,13 @@ class webservice_test extends UnitTestCase {
}
/**
+ * Test moodle_enrol_manual_enrol_users web service function
* This test will:
* 1- create a user (core call)
* 2- enrol this user in the courses supporting enrolment
* 3- unenrol this user (core call)
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
*/
function moodle_enrol_manual_enrol_users($client) {
global $DB, $CFG;
@@ -349,7 +403,11 @@ class webservice_test extends UnitTestCase {
delete_role($roleid);
}
-
+ /**
+ * Test moodle_enrol_get_enrolled_users web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ */
function moodle_enrol_get_enrolled_users($client) {
global $DB;
@@ -385,6 +443,11 @@ class webservice_test extends UnitTestCase {
}
}
+ /**
+ * Test moodle_course_get_courses web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ */
function moodle_course_get_courses($client) {
global $DB;
@@ -465,10 +528,15 @@ class webservice_test extends UnitTestCase {
}
}
+ /**
+ * Test moodle_course_create_courses web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ */
function moodle_course_create_courses($client) {
global $DB, $CFG;
- ///Test data
+ // Test data
$courseconfig = get_config('moodlecourse');
$themeobjects = get_list_of_themes();
@@ -577,6 +645,11 @@ class webservice_test extends UnitTestCase {
array($dbcourse1->id, $dbcourse2->id));
}
+ /**
+ * Test moodle_user_create_users web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ */
function moodle_user_create_users($client) {
global $DB, $CFG;
@@ -707,6 +780,11 @@ class webservice_test extends UnitTestCase {
array($dbuser1->id, $dbuser2->id));
}
+ /**
+ * Test moodle_user_delete_users web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ */
function moodle_user_delete_users($client) {
global $DB, $CFG;
@@ -813,6 +891,11 @@ class webservice_test extends UnitTestCase {
}
}
+ /**
+ * Test moodle_user_update_users web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ */
function moodle_user_update_users($client) {
global $DB, $CFG;
@@ -994,6 +1077,11 @@ class webservice_test extends UnitTestCase {
}
}
+ /**
+ * Test moodle_role_assign web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ */
function moodle_role_assign($client) {
global $DB, $CFG;
@@ -1048,6 +1136,11 @@ class webservice_test extends UnitTestCase {
}
}
+ /**
+ * Test moodle_role_unassign web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ */
function moodle_role_unassign($client) {
global $DB, $CFG;
@@ -1107,11 +1200,9 @@ class webservice_test extends UnitTestCase {
}
/**
- * READ ONLY test
- * TODO: find a better solution that running web service for each course
- * in the system
- * For each courses, test the number of groups
- * @param object $client
+ * Test moodle_group_get_course_groups web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
*/
function moodle_group_get_course_groups($client) {
global $DB;
@@ -1126,12 +1217,12 @@ class webservice_test extends UnitTestCase {
}
}
-
/**
- * READ ONLY test
+ * Test moodle_group_get_groupmembers web service function
* Test that the same number of members are returned
* for each existing group in the system
- * @param object $client
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
*/
function moodle_group_get_groupmembers($client) {
global $DB;
@@ -1157,6 +1248,11 @@ class webservice_test extends UnitTestCase {
}
+ /**
+ * Test moodle_group_add_groupmembers web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ */
function moodle_group_add_groupmembers($client) {
global $DB, $CFG;
@@ -1247,6 +1343,11 @@ class webservice_test extends UnitTestCase {
}
+ /**
+ * Test moodle_group_delete_groupmembers web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ */
function moodle_group_delete_groupmembers($client) {
global $DB, $CFG;
@@ -1337,6 +1438,11 @@ class webservice_test extends UnitTestCase {
}
+ /**
+ * Test moodle_group_create_groups web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ */
function moodle_group_create_groups($client) {
global $DB, $CFG;
@@ -1431,6 +1537,11 @@ class webservice_test extends UnitTestCase {
}
+ /**
+ * Test moodle_group_delete_groups web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ */
function moodle_group_delete_groups($client) {
global $DB, $CFG;
@@ -1523,6 +1634,12 @@ class webservice_test extends UnitTestCase {
$DB->delete_records('course_categories', array('id' => $category->id));
}
+ /**
+ * Test moodle_message_send_messages web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ * @since Moodle 2.1
+ */
function moodle_message_send_messages($client) {
global $DB;
$function = 'moodle_message_send_messages';
@@ -1540,7 +1657,13 @@ class webservice_test extends UnitTestCase {
$this->assertEqual(count($success), 2);
}
- function moodle_notes_create_notes($client) {
+ /**
+ * Test moodle_notes_create_notes web service function
+ *
+ * @param webservice_rest_client|webservice_soap_client|webservice_xmlrpc_client $client the protocol test client
+ * @since Moodle 2.1
+ */
+ function moodle_notes_create_notes($client) {
global $DB, $CFG;
$note1 = array();
diff --git a/webservice/soap/db/access.php b/webservice/soap/db/access.php
index c855665dde0..a3a90a3e45e 100644
--- a/webservice/soap/db/access.php
+++ b/webservice/soap/db/access.php
@@ -1,4 +1,28 @@
.
+
+
+/**
+ * SOAP server related capabilities
+ *
+ * @package webservice_soap
+ * @category access
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
$capabilities = array(
diff --git a/webservice/soap/lang/en/webservice_soap.php b/webservice/soap/lang/en/webservice_soap.php
index 996130c55b3..403f6db7ae4 100644
--- a/webservice/soap/lang/en/webservice_soap.php
+++ b/webservice/soap/lang/en/webservice_soap.php
@@ -1,5 +1,4 @@
.
+
/**
* Strings for component 'webservice_soap', language 'en', branch 'MOODLE_20_STABLE'
*
- * @package webservice_soap
- * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com}
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package webservice_soap
+ * @category string
+ * @copyright 2010 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
$string['pluginname'] = 'SOAP protocol';
diff --git a/webservice/soap/lib.php b/webservice/soap/lib.php
index b78fa0f1add..e2612a923a8 100644
--- a/webservice/soap/lib.php
+++ b/webservice/soap/lib.php
@@ -1,5 +1,4 @@
.
+
+/**
+ * Moodle SOAP library
+ *
+ * @package webservice_soap
+ * @copyright 2009 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
require_once 'Zend/Soap/Client.php';
/**
- * Moodle SOAP client class
+ * Moodle SOAP client
+ *
+ * It has been implemented for unit testing purpose (all protocols have similar client)
+ *
+ * @package webservice_soap
+ * @copyright 2010 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class webservice_soap_client extends Zend_Soap_Client {
+ /** @var string server url e.g. https://yyyyy.com/server.php */
private $serverurl;
/**
* Constructor
- * @param string $serverurl
- * @param string $token
+ *
+ * @param string $serverurl a Moodle URL
+ * @param string $token the token used to do the web service call
* @param array $options PHP SOAP client options - see php.net
*/
public function __construct($serverurl, $token, $options = null) {
@@ -38,7 +54,8 @@ class webservice_soap_client extends Zend_Soap_Client {
/**
* Set the token used to do the SOAP call
- * @param string $token
+ *
+ * @param string $token the token used to do the web service call
*/
public function set_token($token) {
$wsdl = $this->serverurl . "?wstoken=" . $token . '&wsdl=1';
@@ -46,9 +63,10 @@ class webservice_soap_client extends Zend_Soap_Client {
}
/**
- * Execute client WS request
- * @param string $functionname
- * @param array $params
+ * Execute client WS request with token authentication
+ *
+ * @param string $functionname the function name
+ * @param array $params the parameters of the function
* @return mixed
*/
public function call($functionname, $params) {
diff --git a/webservice/soap/locallib.php b/webservice/soap/locallib.php
index bcc8ecb255a..b75d265a978 100644
--- a/webservice/soap/locallib.php
+++ b/webservice/soap/locallib.php
@@ -1,5 +1,4 @@
.
+
/**
* SOAP web service implementation classes and methods.
*
- * @package webservice
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package webservice_soap
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
require_once("$CFG->dirroot/webservice/lib.php");
@@ -28,16 +28,21 @@ require_once 'Zend/Soap/Server.php';
/**
* The Zend XMLRPC server but with a fault that returns debuginfo
+ *
+ * @package webservice_soap
+ * @copyright 2011 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since 2.2
*/
class moodle_zend_soap_server extends Zend_Soap_Server {
/**
* Generate a server fault
*
- * Note that the arguments are reverse to those of SoapFault.
+ * Note that the arguments are the reverse of those used by SoapFault.
*
* Moodle note: the difference with the Zend server is that we throw a SoapFault exception
- * with the debuginfo integrated to the exception message when DEBUG >= NORMAL
+ * with the debuginfo integrated in the exception message when DEBUG >= NORMAL
*
* If an exception is passed as the first argument, its message and code
* will be used to create the fault object if it has been registered via
@@ -64,12 +69,18 @@ class moodle_zend_soap_server extends Zend_Soap_Server {
/**
* SOAP service server implementation.
- * @author Petr Skoda (skodak)
+ *
+ * @package webservice_soap
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since 2.0
*/
class webservice_soap_server extends webservice_zend_server {
+
/**
* Contructor
- * @param bool $simple use simple authentication
+ *
+ * @param string $authmethod authentication method of the web service (WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN, ...)
*/
public function __construct($authmethod) {
// must not cache wsdl - the list of functions is created on the fly
@@ -87,7 +98,6 @@ class webservice_soap_server extends webservice_zend_server {
/**
* Set up zend service class
- * @return void
*/
protected function init_zend_server() {
global $CFG;
@@ -98,7 +108,7 @@ class webservice_soap_server extends webservice_zend_server {
$username = optional_param('wsusername', '', PARAM_RAW);
$password = optional_param('wspassword', '', PARAM_RAW);
// aparently some clients and zend soap server does not work well with "&" in urls :-(
- //TODO: the zend error has been fixed in the last Zend SOAP version, check that is fixed and remove obsolete code
+ //TODO MDL-31151 the zend error has been fixed in the last Zend SOAP version, check that is fixed and remove obsolete code
$url = $CFG->wwwroot.'/webservice/soap/simpleserver.php/'.urlencode($username).'/'.urlencode($password);
// the Zend server is using this uri directly in xml - weird :-(
$this->zend_server->setUri(htmlentities($url));
@@ -111,7 +121,6 @@ class webservice_soap_server extends webservice_zend_server {
if (!optional_param('wsdl', 0, PARAM_BOOL)) {
$this->zend_server->setReturnResponse(true);
- //TODO: the error handling in Zend Soap server is useless, XML-RPC is much, much better :-(
$this->zend_server->registerFaultException('moodle_exception');
$this->zend_server->registerFaultException('webservice_parameter_exception'); //deprecated since Moodle 2.2 - kept for backward compatibility
$this->zend_server->registerFaultException('invalid_parameter_exception');
@@ -127,9 +136,7 @@ class webservice_soap_server extends webservice_zend_server {
/**
* This method parses the $_POST and $_GET superglobals and looks for
* the following information:
- * 1/ user authentication - username+password or token (wsusername, wspassword and wstoken parameters)
- *
- * @return void
+ * user authentication - username+password or token (wsusername, wspassword and wstoken parameters)
*/
protected function parse_request() {
parent::parse_request();
@@ -146,14 +153,12 @@ class webservice_soap_server extends webservice_zend_server {
/**
* Send the error information to the WS client
- * formatted as XML document.
- * @param exception $ex
- * @return void
+ * formatted as an XML document.
+ *
+ * @param exception $ex the exception to send back
*/
protected function send_error($ex=null) {
- // Zend Soap server fault handling is incomplete compared to XML-RPC :-(
- // we can not use: echo $this->zend_server->fault($ex);
- //TODO: send some better response in XML
+
if ($ex) {
$info = $ex->getMessage();
if (debugging() and isset($ex->debuginfo)) {
@@ -177,6 +182,13 @@ class webservice_soap_server extends webservice_zend_server {
echo $xml;
}
+ /**
+ * Generate 'struct' type name
+ * This type name is the name of a class generated on the fly.
+ *
+ * @param external_single_structure $structdesc
+ * @return string
+ */
protected function generate_simple_struct_class(external_single_structure $structdesc) {
global $USER;
// let's use unique class name, there might be problem in unit tests
@@ -207,13 +219,20 @@ class '.$classname.' {
/**
* SOAP test client class
+ *
+ * @package webservice_soap
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since 2.0
*/
class webservice_soap_test_client implements webservice_test_client_interface {
+
/**
* Execute test client WS request
- * @param string $serverurl
- * @param string $function
- * @param array $params
+ *
+ * @param string $serverurl server url (including token parameter or username/password parameters)
+ * @param string $function function name
+ * @param array $params parameters of the called function
* @return mixed
*/
public function simpletest($serverurl, $function, $params) {
diff --git a/webservice/soap/server.php b/webservice/soap/server.php
index e0ee89ffa60..468c3257e9d 100644
--- a/webservice/soap/server.php
+++ b/webservice/soap/server.php
@@ -1,5 +1,4 @@
.
+
/**
* SOAP web service entry point. The authentication is done via tokens.
*
- * @package webservice
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package webservice_soap
+ * @copyright 2009 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
-// disable moodle specific debug messages and any errors in output
+/**
+ * NO_DEBUG_DISPLAY - disable moodle specific debug messages and any errors in output
+ */
define('NO_DEBUG_DISPLAY', true);
+
+/**
+ * NO_MOODLE_COOKIES - no cookies with web service
+ */
define('NO_MOODLE_COOKIES', true);
require('../../config.php');
diff --git a/webservice/soap/simpleserver.php b/webservice/soap/simpleserver.php
index 9142a2c312b..e9e1bb6c418 100644
--- a/webservice/soap/simpleserver.php
+++ b/webservice/soap/simpleserver.php
@@ -1,5 +1,4 @@
.
+
/**
- * XML-RPC web service entry point. The authentication is done via tokens.
+ * SOAP web service entry point. The authentication is done via username/password.
*
- * @package webservice
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package webservice_soap
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
-// disable moodle specific debug messages and any errors in output
+/**
+ * NO_DEBUG_DISPLAY - disable moodle specific debug messages and any errors in output
+ */
define('NO_DEBUG_DISPLAY', true);
+
+/**
+ * NO_MOODLE_COOKIES - no cookies with web service
+ */
define('NO_MOODLE_COOKIES', true);
require('../../config.php');
diff --git a/webservice/soap/version.php b/webservice/soap/version.php
index 52bfb364e7e..fb2fe266c50 100644
--- a/webservice/soap/version.php
+++ b/webservice/soap/version.php
@@ -14,12 +14,12 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see .
+
/**
* Version details
*
- * @package webservice
- * @subpackage soap
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
+ * @package webservice_soap
+ * @copyright 2009 Petr Skodak
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
diff --git a/webservice/upload.php b/webservice/upload.php
index f566359a415..5e2f6cc0f2f 100644
--- a/webservice/upload.php
+++ b/webservice/upload.php
@@ -14,6 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see .
+
/**
* Accept uploading files by web service token
*
@@ -23,26 +24,33 @@
* [_FILES] => for example you can send the files with ,
* or with curl magic: 'file_1' => '@/path/to/file', or ...
*
- * @package moodlecore
- * @subpackage files
+ * @package core_webservice
* @copyright 2011 Dongsheng Cai
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
+/**
+ * AJAX_SCRIPT - exception will be converted into JSON
+ */
define('AJAX_SCRIPT', true);
+
+/**
+ * NO_MOODLE_COOKIES - we don't want any cookie
+ */
define('NO_MOODLE_COOKIES', true);
+
require_once(dirname(dirname(__FILE__)) . '/config.php');
require_once($CFG->dirroot . '/webservice/lib.php');
$filepath = optional_param('filepath', '/', PARAM_PATH);
echo $OUTPUT->header();
-//authenticate the user
+// authenticate the user
$token = required_param('token', PARAM_ALPHANUM);
$webservicelib = new webservice();
$authenticationinfo = $webservicelib->authenticate_user($token);
-//check the user can manage his own files (can upload)
+// check the user can manage his own files (can upload)
$context = get_context_instance(CONTEXT_USER, $USER->id);
require_capability('moodle/user:manageownfiles', $context);
diff --git a/webservice/wsdoc.php b/webservice/wsdoc.php
index 60114edf377..a0206c2dbae 100644
--- a/webservice/wsdoc.php
+++ b/webservice/wsdoc.php
@@ -1,24 +1,27 @@
.
-///////////////////////////////////////////////////////////////////////////
-// //
-// This file is part of Moodle - http://moodle.org/ //
-// Moodle - Modular Object-Oriented Dynamic Learning Environment //
-// //
-// Moodle is free software: you can redistribute it and/or modify //
-// it under the terms of the GNU General Public License as published by //
-// the Free Software Foundation, either version 3 of the License, or //
-// (at your option) any later version. //
-// //
-// Moodle is distributed in the hope that it will be useful, //
-// but WITHOUT ANY WARRANTY; without even the implied warranty of //
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the //
-// GNU General Public License for more details. //
-// //
-// You should have received a copy of the GNU General Public License //
-// along with Moodle. If not, see . //
-// //
-///////////////////////////////////////////////////////////////////////////
+
+/**
+ * Web services auto-generated documentation
+ *
+ * @package core_webservice
+ * @copyright 2009 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
require_once('../config.php');
require($CFG->dirroot . '/webservice/lib.php');
@@ -29,14 +32,14 @@ require_sesskey();
$usercontext = get_context_instance(CONTEXT_USER, $USER->id);
$tokenid = required_param('id', PARAM_INT);
-//PAGE settings
+// PAGE settings
$PAGE->set_context($usercontext);
$PAGE->set_url('/user/wsdoc.php');
$PAGE->set_title(get_string('documentation', 'webservice'));
$PAGE->set_heading(get_string('documentation', 'webservice'));
$PAGE->set_pagelayout('standard');
-//nav bar
+// nav bar
$PAGE->navbar->ignore_active(true);
$PAGE->navbar->add(get_string('usercurrentsettings'));
$PAGE->navbar->add(get_string('securitykeys', 'webservice'),
@@ -44,13 +47,13 @@ $PAGE->navbar->add(get_string('securitykeys', 'webservice'),
array('id' => $tokenid, 'sesskey' => sesskey())));
$PAGE->navbar->add(get_string('documentation', 'webservice'));
-//check web service are enabled
+// check web service are enabled
if (empty($CFG->enablewsdocumentation)) {
echo get_string('wsdocumentationdisable', 'webservice');
die;
}
-//check that the current user is the token user
+// check that the current user is the token user
$webservice = new webservice();
$token = $webservice->get_token_by_id($tokenid);
if (empty($token) or empty($token->userid) or empty($USER->id)
@@ -67,22 +70,22 @@ foreach ($functions as $function) {
$functiondescs[$function->name] = external_function_info($function);
}
-//get activated protocol
+// get activated protocol
$activatedprotocol = array();
$activatedprotocol['rest'] = webservice_protocol_is_enabled('rest');
$activatedprotocol['xmlrpc'] = webservice_protocol_is_enabled('xmlrpc');
-/// Check if we are in printable mode
+// Check if we are in printable mode
$printableformat = optional_param('print', false, PARAM_BOOL);
-/// OUTPUT
+// OUTPUT
echo $OUTPUT->header();
$renderer = $PAGE->get_renderer('core', 'webservice');
echo $renderer->documentation_html($functiondescs,
$printableformat, $activatedprotocol, array('id' => $tokenid));
-/// trigger browser print operation
+// trigger browser print operation
if (!empty($printableformat)) {
$PAGE->requires->js_function_call('window.print', array());
}
diff --git a/webservice/xmlrpc/db/access.php b/webservice/xmlrpc/db/access.php
index 1c321547b69..1c71a8ce87e 100644
--- a/webservice/xmlrpc/db/access.php
+++ b/webservice/xmlrpc/db/access.php
@@ -1,4 +1,28 @@
.
+
+
+/**
+ * XML-RPC server related capabilities
+ *
+ * @package webservice_xmlrpc
+ * @category access
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
$capabilities = array(
diff --git a/webservice/xmlrpc/lang/en/webservice_xmlrpc.php b/webservice/xmlrpc/lang/en/webservice_xmlrpc.php
index d455c4d126d..b5431ba1db8 100644
--- a/webservice/xmlrpc/lang/en/webservice_xmlrpc.php
+++ b/webservice/xmlrpc/lang/en/webservice_xmlrpc.php
@@ -1,5 +1,4 @@
.
+
/**
* Strings for component 'webservice_xmlrpc', language 'en', branch 'MOODLE_20_STABLE'
*
- * @package webservice_xmlrpc
- * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com}
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package webservice_xmlrpc
+ * @category string
+ * @copyright 2010 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
$string['pluginname'] = 'XML-RPC protocol';
diff --git a/webservice/xmlrpc/lib.php b/webservice/xmlrpc/lib.php
index 5480fee3820..06a5016839e 100644
--- a/webservice/xmlrpc/lib.php
+++ b/webservice/xmlrpc/lib.php
@@ -1,5 +1,4 @@
.
+
+/**
+ * Moodle XML-RPC library
+ *
+ * @package webservice_xmlrpc
+ * @copyright 2009 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
require_once 'Zend/XmlRpc/Client.php';
/**
- * XML-RPC client class
+ * Moodle XML-RPC client
+ *
+ * It has been implemented for unit testing purpose (all protocols have similar client)
+ *
+ * @package webservice_xmlrpc
+ * @copyright 2010 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class webservice_xmlrpc_client extends Zend_XmlRpc_Client {
+ /** @var string server url e.g. https://yyyyy.com/server.php */
private $serverurl;
/**
* Constructor
- * @param string $serverurl
- * @param string $token
+ *
+ * @param string $serverurl a Moodle URL
+ * @param string $token the token used to do the web service call
*/
public function __construct($serverurl, $token) {
$this->serverurl = $serverurl;
@@ -37,16 +53,18 @@ class webservice_xmlrpc_client extends Zend_XmlRpc_Client {
/**
* Set the token used to do the XML-RPC call
- * @param string $token
+ *
+ * @param string $token the token used to do the web service call
*/
public function set_token($token) {
$this->_serverAddress = $this->serverurl . '?wstoken=' . $token;
}
/**
- * Execute client WS request
- * @param string $functionname
- * @param array $params
+ * Execute client WS request with token authentication
+ *
+ * @param string $functionname the function name
+ * @param array $params the parameters of the function
* @return mixed
*/
public function call($functionname, $params) {
diff --git a/webservice/xmlrpc/locallib.php b/webservice/xmlrpc/locallib.php
index d94f249505d..a2a51207e4c 100644
--- a/webservice/xmlrpc/locallib.php
+++ b/webservice/xmlrpc/locallib.php
@@ -1,5 +1,4 @@
.
+
/**
* XML-RPC web service implementation classes and methods.
*
- * @package webservice
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package webservice_xmlrpc
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
require_once("$CFG->dirroot/webservice/lib.php");
@@ -28,6 +28,11 @@ require_once 'Zend/XmlRpc/Server.php';
/**
* The Zend XMLRPC server but with a fault that return debuginfo
+ *
+ * @package webservice_xmlrpc
+ * @copyright 2011 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since 2.2
*/
class moodle_zend_xmlrpc_server extends Zend_XmlRpc_Server {
@@ -57,12 +62,18 @@ class moodle_zend_xmlrpc_server extends Zend_XmlRpc_Server {
/**
* XML-RPC service server implementation.
- * @author Petr Skoda (skodak)
+ *
+ * @package webservice_xmlrpc
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since 2.0
*/
class webservice_xmlrpc_server extends webservice_zend_server {
+
/**
* Contructor
- * @param integer $authmethod authentication method one of WEBSERVICE_AUTHMETHOD_*
+ *
+ * @param string $authmethod authentication method of the web service (WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN, ...)
*/
public function __construct($authmethod) {
require_once 'Zend/XmlRpc/Server.php';
@@ -72,7 +83,6 @@ class webservice_xmlrpc_server extends webservice_zend_server {
/**
* Set up zend service class
- * @return void
*/
protected function init_zend_server() {
parent::init_zend_server();
@@ -89,13 +99,18 @@ class webservice_xmlrpc_server extends webservice_zend_server {
/**
* XML-RPC test client class
+ *
+ * @package webservice_xmlrpc
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since 2.0
*/
class webservice_xmlrpc_test_client implements webservice_test_client_interface {
/**
* Execute test client WS request
- * @param string $serverurl
- * @param string $function
- * @param array $params
+ * @param string $serverurl server url (including token parameter or username/password parameters)
+ * @param string $function function name
+ * @param array $params parameters of the called function
* @return mixed
*/
public function simpletest($serverurl, $function, $params) {
diff --git a/webservice/xmlrpc/server.php b/webservice/xmlrpc/server.php
index ae70ca0286f..b601bdc6c40 100644
--- a/webservice/xmlrpc/server.php
+++ b/webservice/xmlrpc/server.php
@@ -1,5 +1,4 @@
.
+
/**
* XML-RPC web service entry point. The authentication is done via tokens.
*
- * @package webservice
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package webservice_xmlrpc
+ * @copyright 2009 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
-// disable moodle specific debug messages and any errors in output
+/**
+ * NO_DEBUG_DISPLAY - disable moodle specific debug messages and any errors in output
+ */
define('NO_DEBUG_DISPLAY', true);
+
+/**
+ * NO_MOODLE_COOKIES - no cookies with web service
+ */
define('NO_MOODLE_COOKIES', true);
require('../../config.php');
diff --git a/webservice/xmlrpc/simpleserver.php b/webservice/xmlrpc/simpleserver.php
index 6f354750ee7..ca8bbe1bc80 100644
--- a/webservice/xmlrpc/simpleserver.php
+++ b/webservice/xmlrpc/simpleserver.php
@@ -1,5 +1,4 @@
.
+
/**
- * XML-RPC web service entry point. The authentication is done via tokens.
+ * XML-RPC web service entry point. The authentication is done via username/password.
*
- * @package webservice
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package webservice_xmlrpc
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
-// disable moodle specific debug messages and any errors in output
+/**
+ * NO_DEBUG_DISPLAY - disable moodle specific debug messages and any errors in output
+ */
define('NO_DEBUG_DISPLAY', true);
+
+/**
+ * NO_MOODLE_COOKIES - no cookies with web service
+ */
define('NO_MOODLE_COOKIES', true);
require('../../config.php');
diff --git a/webservice/xmlrpc/version.php b/webservice/xmlrpc/version.php
index 0101f67520b..2a6545e88bf 100644
--- a/webservice/xmlrpc/version.php
+++ b/webservice/xmlrpc/version.php
@@ -14,12 +14,12 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see .
+
/**
* Version details
*
- * @package webservice
- * @subpackage xmlrpc
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
+ * @package webservice_xmlrpc
+ * @copyright 2009 Petr Skodak
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/