webservice/externallib.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * external API for mobile web services
  19  *
  20  * @package    core
  21  * @subpackage webservice
  22  * @copyright  2011 Moodle Pty Ltd (http://moodle.com)
  23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24  */
  25
  26 /**
  27  * Web service related functions
  28  */
  29 class core_webservice_external extends external_api {
  30
  31     /**
  32      * Returns description of method parameters
  33      * @return external_function_parameters
  34      */
  35     public static function get_site_info_parameters() {
  36         return new external_function_parameters(
  37             array('serviceshortnames' => new external_multiple_structure (
  38                 new external_value(
  39                     PARAM_ALPHANUMEXT,
  40                     'service shortname'),
  41                     'DEPRECATED PARAMETER - it was a design error in the original implementation. It is ignored now. (parameter kept for backward compatibility)',
  42                     VALUE_DEFAULT,
  43                     array()
  44                 ),
  45             )
  46         );
  47     }
  48
  49     /**
  50      * Return user information including profile picture + basic site information
  51      * Note:
  52      * - no capability checking because we return just known information by logged user
  53      * @param array $serviceshortnames - DEPRECATED PARAMETER - values will be ignored - it was an original design error, we keep for backward compatibility.
  54      * @return array
  55      */
  56     public function get_site_info($serviceshortnames = array()) {
  57         global $USER, $SITE, $CFG, $DB;
  58
  59         $params = self::validate_parameters(self::get_site_info_parameters(),
  60                       array('serviceshortnames'=>$serviceshortnames));
  61
  62         $profileimageurl = moodle_url::make_pluginfile_url(
  63                 get_context_instance(CONTEXT_USER, $USER->id)->id, 'user', 'icon', NULL, '/', 'f1');
  64
  65         //site information
  66         $siteinfo =  array(
  67             'sitename' => $SITE->fullname,
  68             'siteurl' => $CFG->wwwroot,
  69             'username' => $USER->username,
  70             'firstname' => $USER->firstname,
  71             'lastname' => $USER->lastname,
  72             'fullname' => fullname($USER),
  73             'userid' => $USER->id,
  74             'userpictureurl' => $profileimageurl->out(false)
  75         );
  76
  77         //Retrieve the service and functions from the web service linked to the token
  78         //If you call this function directly from external (not a web service call),
  79         //then it will still return site info without information about a service
  80         //Note: wsusername/wspassword ws authentication is not supported.
  81         $functions = array();
  82         if ($CFG->enablewebservices) { //no need to check token if web service are disabled and not a ws call
  83             $token = optional_param('wstoken', '', PARAM_ALPHANUM);
  84
  85             if (!empty($token)) { //no need to run if not a ws call
  86                 //retrieve service shortname
  87                 $servicesql = 'SELECT s.*
  88                                FROM {external_services} s, {external_tokens} t
  89                                WHERE t.externalserviceid = s.id AND token = ? AND t.userid = ? AND s.enabled = 1';
  90                 $service = $DB->get_record_sql($servicesql, array($token, $USER->id));
  91
  92                 $siteinfo['downloadfiles'] = $service->downloadfiles;
  93
  94                 if (!empty($service)) {
  95                     //retrieve the functions
  96                     $functionssql = "SELECT f.*
  97                             FROM {external_functions} f, {external_services_functions} sf
  98                             WHERE f.name = sf.functionname AND sf.externalserviceid = ?";
  99                     $functions = $DB->get_records_sql($functionssql, array($service->id));
 100                 } else {
 101                     throw new coding_exception('No service found in get_site_info: something is buggy, it should have fail at the ws server authentication layer.');
 102                 }
 103             }
 104         }
 105
 106         //built up the returned values of the list of functions
 107         $componentversions = array();
 108         $avalaiblefunctions = array();
 109         foreach ($functions as $function) {
 110             $functioninfo = array();
 111             $functioninfo['name'] = $function->name;
 112             if ($function->component == 'moodle') {
 113                 $version = $CFG->version; //moodle version
 114             } else {
 115                 $versionpath = get_component_directory($function->component).'/version.php';
 116                 if (is_readable($versionpath)) {
 117                     //we store the component version once retrieved (so we don't load twice the version.php)
 118                     if (!isset($componentversions[$function->component])) {
 119                         include($versionpath);
 120                         $componentversions[$function->component] = $plugin->version;
 121                         $version = $plugin->version;
 122                     } else {
 123                         $version = $componentversions[$function->component];
 124                     }
 125                 } else {
 126                     //function component should always have a version.php,
 127                     //otherwise the function should have been described with component => 'moodle'
 128                     throw new moodle_exception('missingversionfile', 'webservice', '', $function->component);
 129                 }
 130             }
 131             $functioninfo['version'] = $version;
 132             $avalaiblefunctions[] = $functioninfo;
 133         }
 134
 135         $siteinfo['functions'] = $avalaiblefunctions;
 136
 137         return $siteinfo;
 138     }
 139
 140     /**
 141      * Returns description of method result value
 142      * @return external_single_structure
 143      */
 144     public static function get_site_info_returns() {
 145         return new external_single_structure(
 146             array(
 147                 'sitename'       => new external_value(PARAM_RAW, 'site name'),
 148                 'username'       => new external_value(PARAM_RAW, 'username'),
 149                 'firstname'      => new external_value(PARAM_TEXT, 'first name'),
 150                 'lastname'       => new external_value(PARAM_TEXT, 'last name'),
 151                 'fullname'       => new external_value(PARAM_TEXT, 'user full name'),
 152                 'userid'         => new external_value(PARAM_INT, 'user id'),
 153                 'siteurl'        => new external_value(PARAM_RAW, 'site url'),
 154                 'userpictureurl' => new external_value(PARAM_URL, 'the user profile picture'),
 155                 'functions'      => new external_multiple_structure(
 156                     new external_single_structure(
 157                         array(
 158                             'name' => new external_value(PARAM_RAW, 'function name'),
 159                             'version' => new external_value(PARAM_FLOAT, 'The version number of moodle site/local plugin linked to the function')
 160                         ), 'functions that are available')
 161                     ),
 162                 'downloadfiles'  => new external_value(PARAM_INT, '1 if users are allowed to download files, 0 if not', VALUE_OPTIONAL),
 163             )
 164         );
 165     }
 166 }
 167
 168 /**
 169  * Deprecated web service related functions
 170  * @deprecated since Moodle 2.2 please use core_webservice_external instead
 171  */
 172 class moodle_webservice_external extends external_api {
 173
 174     /**
 175      * Returns description of method parameters
 176      * @deprecated since Moodle 2.2 please use core_webservice_external::get_site_info_parameters instead
 177      * @return external_function_parameters
 178      */
 179     public static function get_siteinfo_parameters() {
 180         return core_webservice_external::get_site_info_parameters();
 181     }
 182
 183     /**
 184      * Return user information including profile picture + basic site information
 185      * Note:
 186      * - no capability checking because we return just known information by logged user
 187      * @deprecated since Moodle 2.2 please use core_webservice_external::get_site_info instead
 188      * @param array $serviceshortnames of service shortnames - the functions of these services will be returned
 189      * @return array
 190      */
 191     public function get_siteinfo($serviceshortnames = array()) {
 192         return core_webservice_external::get_site_info($serviceshortnames);
 193     }
 194
 195     /**
 196      * Returns description of method result value
 197      * @deprecated since Moodle 2.2 please use core_webservice_external::get_site_info_returns instead
 198      * @return external_single_structure
 199      */
 200     public static function get_siteinfo_returns() {
 201         return core_webservice_external::get_site_info_returns();
 202     }
 203 }