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 class moodle_webservice_external extends external_api {
  27
  28     public static function get_siteinfo_parameters() {
  29         return new external_function_parameters(
  30             array('serviceshortnames' => new external_multiple_structure (
  31                 new external_value(
  32                     PARAM_ALPHANUMEXT,
  33                     'service shortname'),
  34                     'service shortnames - by default, if the list is empty and mobile web services are enabled,
  35                     we return the mobile service functions',
  36                     VALUE_DEFAULT,
  37                     array()
  38                 ),
  39             )
  40         );
  41     }
  42
  43     /**
  44      * Return user information including profile picture + basic site information
  45      * Note:
  46      * - no capability checking because we return just known information by logged user
  47      * @param array $serviceshortnames of service shortnames - the functions of these services will be returned
  48      * @return array
  49      */
  50     function get_siteinfo($serviceshortnames = array()) {
  51         global $USER, $SITE, $CFG;
  52
  53         $params = self::validate_parameters(self::get_siteinfo_parameters(),
  54                       array('serviceshortnames'=>$serviceshortnames));
  55
  56         $profileimageurl = moodle_url::make_pluginfile_url(
  57                 get_context_instance(CONTEXT_USER, $USER->id)->id, 'user', 'icon', NULL, '/', 'f1');
  58
  59         require_once($CFG->dirroot . "/webservice/lib.php");
  60         $webservice = new webservice();
  61
  62         //If no service listed always return the mobile one by default
  63         if (empty($params['serviceshortnames']) and $CFG->enablewebservices) {
  64            $mobileservice = $webservice->get_external_service_by_shortname(MOODLE_OFFICIAL_MOBILE_SERVICE);
  65            if ($mobileservice->enabled) {
  66                $params['serviceshortnames'] = array(MOODLE_OFFICIAL_MOBILE_SERVICE); //return mobile service by default
  67            }
  68         }
  69
  70         //retrieve the functions related to the services
  71         $functions = $webservice->get_external_functions_by_enabled_services($params['serviceshortnames']);
  72
  73         //built up the returned values of the list of functions
  74         $componentversions = array();
  75         $avalaiblefunctions = array();
  76         foreach ($functions as $function) {
  77             $functioninfo = array();
  78             $functioninfo['name'] = $function->name;
  79             if ($function->component == 'moodle') {
  80                 $version = $CFG->version; //moodle version
  81             } else {
  82                 $versionpath = get_component_directory($function->component).'/version.php';
  83                 if (is_readable($versionpath)) {
  84                     //we store the component version once retrieved (so we don't load twice the version.php)
  85                     if (!isset($componentversions[$function->component])) {
  86                         include($versionpath);
  87                         $componentversions[$function->component] = $plugin->version;
  88                         $version = $plugin->version;
  89                     } else {
  90                         $version = $componentversions[$function->component];
  91                     }
  92                 } else {
  93                     //function component should always have a version.php,
  94                     //otherwise the function should have been described with component => 'moodle'
  95                     throw new moodle_exception('missingversionfile', 'webservice', '', $function->component);
  96                 }
  97             }
  98             $functioninfo['version'] = $version;
  99             $avalaiblefunctions[] = $functioninfo;
 100         }
 101
 102         return array(
 103             'sitename' => $SITE->fullname,
 104             'siteurl' => $CFG->wwwroot,
 105             'username' => $USER->username,
 106             'firstname' => $USER->firstname,
 107             'lastname' => $USER->lastname,
 108             'fullname' => fullname($USER),
 109             'userid' => $USER->id,
 110             'userpictureurl' => $profileimageurl->out(false),
 111             'functions' => $avalaiblefunctions
 112         );
 113     }
 114
 115     public static function get_siteinfo_returns() {
 116         return new external_single_structure(
 117             array(
 118                 'sitename'       => new external_value(PARAM_RAW, 'site name'),
 119                 'username'       => new external_value(PARAM_RAW, 'username'),
 120                 'firstname'      => new external_value(PARAM_TEXT, 'first name'),
 121                 'lastname'       => new external_value(PARAM_TEXT, 'last name'),
 122                 'fullname'       => new external_value(PARAM_TEXT, 'user full name'),
 123                 'userid'         => new external_value(PARAM_INT, 'user id'),
 124                 'siteurl'        => new external_value(PARAM_RAW, 'site url'),
 125                 'userpictureurl' => new external_value(PARAM_URL, 'the user profile picture'),
 126                 'functions'      => new external_multiple_structure(
 127                     new external_single_structure(
 128                         array(
 129                             'name' => new external_value(PARAM_RAW, 'function name'),
 130                             'version' => new external_value(PARAM_FLOAT, 'The version number of moodle site/local plugin linked to the function')
 131                         ), 'functions that are available')
 132                     ),
 133             )
 134         );
 135     }
 136 }