From 839bd5a204d6d89bb3f17331a44f0849652ef017 Mon Sep 17 00:00:00 2001
From: jerome <jerome>
Date: Thu, 26 Feb 2009 08:18:28 +0000
Subject: [PATCH] web service MDL-12886 documentation: better display, test if
 web services are enable, display return type

---
 group/external.php           |  14 ++--
 lang/en_utf8/webservice.php  |  22 ++++---
 user/external.php            |  56 ++++++++--------
 webservice/documentation.php | 120 ++++++++++++++++++++++++-----------
 4 files changed, 132 insertions(+), 80 deletions(-)

diff --git a/group/external.php b/group/external.php
index 98a9dc3a82..b1bf8f36ed 100644
--- a/group/external.php
+++ b/group/external.php
@@ -43,14 +43,14 @@ final class group_external {
     }
 
     /**
-     * add a group member
+     * Get a group member
      * @param array $params
      * @subparam integer $params->groupid
-     * @return array $group
-     * @subreturn integer $group->id
-     * @subreturn integer $group->courseid
-     * @subreturn string $group->name
-     * @subreturn string $group->enrolmentkey
+     * @return array $return
+     * @subreturn integer $return->group->id
+     * @subreturn integer $return->group->courseid
+     * @subreturn string $return->group->name
+     * @subreturn string $return->group->enrolmentkey
      */
 	static function tmp_get_group($params){
 
@@ -97,7 +97,7 @@ final class group_external {
 	}
 
     /**
-     *
+     * Add a member to a group
      * @param array $params
      * @subparam integer $params->groupid
      * @subparam integer $params->userid
diff --git a/lang/en_utf8/webservice.php b/lang/en_utf8/webservice.php
index 37a2f46080..26533c5414 100644
--- a/lang/en_utf8/webservice.php
+++ b/lang/en_utf8/webservice.php
@@ -1,33 +1,39 @@
 <?php // $Id$
 $string['soapdocumentation'] = '<H2>SOAP Manual</H2>
-        <b>1.</b> Call the method <b>tmp_get_token</b> on \"<i>http://remotemoodle/webservice/soap/zend_soap_server.php?wsdl</i>\"<br>
-        Function parameter is an array: in PHP it would be array(\"username\" => \"wsuser\", \"password\" => \"wspassword\")<br>
+        <b>1.</b> Call the method <b>tmp_get_token</b> on \"<i>http://remotemoodle/webservice/soap/server.php?wsdl</i>\"<br>
+        The function parameter is an array: in PHP it would be array(\"username\" => \"wsuser\", \"password\" => \"wspassword\")<br>
         Return value is a token (integer)<br>
         <br>
-        <b>2.</b> Then call a moodle web service method on \"<i>http://remotemoodle/webservice/soap/zend_soap_server.php?token=the_received_token&classpath=the_moodle_path&wsdl</i>\"<br>
+        <b>2.</b> Then call a moodle web service method on \"<i>http://remotemoodle/webservice/soap/server.php?token=the_received_token&classpath=the_moodle_path&wsdl</i>\"<br>
         Every method has only one parameter which is an array.<br>
         <br>
         For example in PHP for this specific function:<br>
         Moodle path: <b>user</b><br>
-        <b>tmp_delete_user</b>( string username, integer mnethostid,   )<br>
+        <b>tmp_delete_user</b>( string username , integer mnethostid )<br>
         You will call something like:<br>
         your_client->tmp_delete_user(array(\"username\" => \"username_to_delete\",\"mnethostid\" => 1))<br><br>
 ';
 $string['xmlrpcdocumentation'] = '<H2>XMLRPC Manual</H2>
-        <b>1.</b> Call the method <b>authentication.tmp_get_token</b> on \"<i>http://remotemoodle/webservice/xmlrpc/zend_xmlrpc_server.php</i>\"<br>
-        Function parameter is an array: in PHP it would be array(\"username\" => \"wsuser\", \"password\" => \"wspassword\")<br>
+        <b>1.</b> Call the method <b>authentication.tmp_get_token</b> on \"<i>http://remotemoodle/webservice/xmlrpc/server.php</i>\"<br>
+        The function parameter is an array: in PHP it would be array(\"username\" => \"wsuser\", \"password\" => \"wspassword\")<br>
         Return value is a token (integer)<br>
         <br>
-        <b>2.</b> Then call a moodle web service method on \"<i>http://remotemoodle/webservice/xmlrpc/zend_xmlrpc_server.php?classpath=the_moodle_path&token=the_received_token</i>\"<br>
+        <b>2.</b> Then call a moodle web service method on \"<i>http://remotemoodle/webservice/xmlrpc/server.php?classpath=the_moodle_path&token=the_received_token</i>\"<br>
         Every method has only one parameter which is an array.<br>
         <br>
         For example in PHP for this specific function:<br>
         Moodle path: <b>user</b><br>
-        <b>tmp_delete_user</b>( string username, integer mnethostid,   )<br>
+        <b>tmp_delete_user</b>( string username , integer mnethostid )<br>
         You will call something like:<br>
         your_client->call(\"user.tmp_delete_user\", array(array(\"username\" => \"username_to_delete\",\"mnethostid\" => 1)))<br>
 
 ';
 $string['functionlist'] = 'list of web service functions';
 $string['moodlepath'] = 'Moodle path';
+$string['wspagetitle'] = 'Web services documentation';
+$string['webservicesenable'] = 'Web services enable';
+$string['protocolenable'] = '$a[0] protocol enable';
+$string['ok'] = 'OK';
+$string['fail'] = 'FAIL';
+$string['wsuserreminder'] = 'Reminder: the Moodle administrator of this site needs to give you moodle/site:usewebservices capability.';
 ?>
diff --git a/user/external.php b/user/external.php
index 8f2db86772..bae11f6a36 100644
--- a/user/external.php
+++ b/user/external.php
@@ -23,20 +23,20 @@ final class user_external {
      * @subparam string $params:searches->search2 optional - the string to search
      * @subparam string $params:searches->search3 - the string to search
      * @subparam string $params:airport->planes:plane->company->employees:employee->name - name of a employee of a company of a plane of an airport
-     * @return array users  
-     * @subreturn integer $users:user->id
-     * @subreturn integer $users:user->auth
-     * @subreturn integer $users:user->confirmed
-     * @subreturn string $users:user->username
-     * @subreturn string $users:user->idnumber
-     * @subreturn string $users:user->firstname
-     * @subreturn string $users:user->lastname
-     * @subreturn string $users:user->email
-     * @subreturn string $users:user->emailstop
-     * @subreturn string $users:user->lang
-     * @subreturn string $users:user->theme
-     * @subreturn string $users:user->timezone
-     * @subreturn string $users:user->mailformat
+     * @return array $return
+     * @subreturn integer $return:user->id
+     * @subreturn integer $return:user->auth
+     * @subreturn integer $return:user->confirmed
+     * @subreturn string $return:user->username
+     * @subreturn string $return:user->idnumber
+     * @subreturn string $return:user->firstname
+     * @subreturn string $return:user->lastname
+     * @subreturn string $return:user->email
+     * @subreturn string $return:user->emailstop
+     * @subreturn string $return:user->lang
+     * @subreturn string $return:user->theme
+     * @subreturn string $return:user->timezone
+     * @subreturn string $return:user->mailformat
      */
     static function tmp_do_multiple_user_searches($params) {
         global $USER;
@@ -59,20 +59,20 @@ final class user_external {
      * Retrieve all user
      * @param array|struct $params - need to be define as struct for XMLRPC
      * @subparam string $params->search - the string to search
-     * @return object users 
-     * @subreturn integer $users:user->id
-     * @subreturn integer $users:user->auth
-     * @subreturn integer $users:user->confirmed
-     * @subreturn string $users:user->username
-     * @subreturn string $users:user->idnumber
-     * @subreturn string $users:user->firstname
-     * @subreturn string $users:user->lastname
-     * @subreturn string $users:user->email
-     * @subreturn string $users:user->emailstop
-     * @subreturn string $users:user->lang
-     * @subreturn string $users:user->theme
-     * @subreturn string $users:user->timezone
-     * @subreturn string $users:user->mailformat
+     * @return array $return
+     * @subreturn integer $return:user->id
+     * @subreturn integer $return:user->auth
+     * @subreturn integer $return:user->confirmed
+     * @subreturn string $return:user->username
+     * @subreturn string $return:user->idnumber
+     * @subreturn string $return:user->firstname
+     * @subreturn string $return:user->lastname
+     * @subreturn string $return:user->email
+     * @subreturn string $return:user->emailstop
+     * @subreturn string $return:user->lang
+     * @subreturn string $return:user->theme
+     * @subreturn string $return:user->timezone
+     * @subreturn string $return:user->mailformat
      */
     static function tmp_get_users($params) {
         global $USER;
diff --git a/webservice/documentation.php b/webservice/documentation.php
index 29f3e07213..4e9a809662 100644
--- a/webservice/documentation.php
+++ b/webservice/documentation.php
@@ -30,9 +30,40 @@
 require_once('../config.php');
 require_once('lib.php');
 $protocol = optional_param('protocol',"soap",PARAM_ALPHA);
+
+print_header(get_string('wspagetitle','webservice'), get_string('wspagetitle','webservice').":", true);
+check_webservices($protocol);
 generate_documentation($protocol);
 generate_functionlist();
+print_footer();
+
+
+function check_webservices($protocol){
+    global $CFG;
+
+    echo get_string('webservicesenable','webservice').": ";
+    if (empty($CFG->enablewebservices)) {
+        echo "<strong style=\"color:red\">".get_string('fail','webservice')."</strong>";
+    } else {
+        echo "<strong style=\"color:green\">".get_string('ok','webservice')."</strong>";
+    }
+    echo "<br/>";
+
+    foreach(webservice_lib::get_list_protocols() as $wsprotocol) {
+        if (strtolower($wsprotocol->get_protocolname()) == strtolower($protocol)) {
+            echo get_string('protocolenable','webservice',array($wsprotocol->get_protocolname())).": ";
+            if ( get_config($wsprotocol-> get_protocolname(), "enable")) {
+                echo "<strong style=\"color:green\">".get_string('ok','webservice')."</strong>";
+            } else {
+                echo "<strong style=\"color:red\">".get_string('fail','webservice')."</strong>";
+            }
+            echo "<br/>";
+            continue;
+        }
+    }
 
+    
+}
 
 /**
  *
@@ -51,6 +82,8 @@ function generate_documentation($protocol) {
             break;
     }
     echo $documentation;
+    echo "<strong style=\"color:orange\">".get_string('wsuserreminder','webservice')."</strong>";
+
 }
 
 
@@ -75,41 +108,54 @@ function generate_functionlist () {
         $classpath = str_replace('/','_',$classpath); //convert all / into _
         $classname = $classpath."_external";
         $api = new $classname();
-        $documentation .= "<H3>".get_string('moodlepath','webservice').": ".$classpath."</H3>";
+        $documentation .= "<H3><u>".get_string('moodlepath','webservice').": ".$classpath."</u></H3><ul>";
 
         $description = webservice_lib::generate_webservice_description($file, $classname);
 
         foreach ($description as $functionname => $functiondescription) {
             $documentation .= <<<EOF
-        <b>{$functionname}(</b>
+        <li><b>{$functionname}(</b>
 EOF;
             $arrayparams = array();
+            $comma="";
             foreach($functiondescription['params'] as $param => $type) {
+
                 $documentation .= <<<EOF
-        {$type} {$param},
+                {$comma} {$type} {$param}
 EOF;
+                 if (empty($comma)) {
+                    $comma = ',';
+                }
             }
-                $documentation .= <<<EOF
-        <b>)</b><br/>
+            $documentation .= <<<EOF
+        <b>)</b> :
 EOF;
-             foreach($functiondescription['params'] as $param => $type) {
+          foreach($functiondescription['return'] as $return => $type) {
+            $documentation .= <<<EOF
+            {$type} <br/>
+EOF;
+          }
+            foreach($functiondescription['params'] as $param => $type) {
 
-                 if (is_array($type)) {
-                     $arraytype = "<pre>".print_r($type, true)."</pre>";
-                      $documentation .= <<<EOF
+                if (is_array($type)) {
+                    $arraytype = "<pre>".print_r($type, true)."</pre>";
+                    $documentation .= <<<EOF
          <u>{$param}</u> : {$arraytype} <br>
 EOF;
-                 }
-               
-                 }
-            
+                }
+
             }
 
         }
+        $documentation .= <<<EOF
+        </ul>
+EOF;
+  
+    }
 
-        echo $documentation;
+    echo $documentation;
 
-    }
+}
 
 
  /**
@@ -118,33 +164,33 @@ EOF;
  * @param <type> $directorypath
  * @return boolean result true if n
  */
-    function setListApiFiles( &$files, $directorypath )
-    {
-        if(is_dir($directorypath)){ //check that we are browsing a folder not a file
+function setListApiFiles( &$files, $directorypath )
+{
+    if(is_dir($directorypath)){ //check that we are browsing a folder not a file
 
-            if( $dh = opendir($directorypath))
+        if( $dh = opendir($directorypath))
+        {
+            while( false !== ($file = readdir($dh)))
             {
-                while( false !== ($file = readdir($dh)))
-                {
-
-                    if( $file == '.' || $file == '..') {   // Skip '.' and '..'
-                        continue;
-                    }
-                    $path = $directorypath . '/' . $file;
-                    ///browse the subfolder
-                    if( is_dir($path) ) {
-                        setListApiFiles($files, $path);
-                    }
-                    ///retrieve api.php file
-                    else if ($file == "external.php") {
-                        $files[] = $path;
-                    }
-                }
-                closedir($dh);
 
+                if( $file == '.' || $file == '..') {   // Skip '.' and '..'
+                    continue;
+                }
+                $path = $directorypath . '/' . $file;
+                ///browse the subfolder
+                if( is_dir($path) ) {
+                    setListApiFiles($files, $path);
+                }
+                ///retrieve api.php file
+                else if ($file == "external.php") {
+                    $files[] = $path;
+                }
             }
+            closedir($dh);
+
         }
     }
+}
 
 
-    ?>
+?>
-- 
2.39.5