Proyectos de Subversion Moodle

<?php

// This file is part of Moodle - http://moodle.org/

//

// 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 <http://www.gnu.org/licenses/>.

/**

 * Web services utility functions and classes

 *

 * @package    core_webservice

 * @copyright  2009 Jerome Mouneyrac <jerome@moodle.com>

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

use core_external\external_api;

use core_external\external_multiple_structure;

use core_external\external_settings;

use core_external\external_single_structure;

use core_external\external_value;

/**

 * 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 <jerome@moodle.com>

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

class webservice {

    /**

     * Only update token last access once per this many seconds. (This constant controls update of

     * the external tokens last access field. There is a similar define LASTACCESS_UPDATE_SECS

     * which controls update of the web site last access fields.)

     *

     * @var int

     */

    const TOKEN_LASTACCESS_UPDATE_SECS = 60;

    /**

     * Authenticate user (used by download/upload file scripts)

     *

     * @param string $token

     * @return array - contains the authenticated user, token and service objects

     */

    public function authenticate_user($token) {

        global $DB, $CFG;

        // web service must be enabled to use this script

        if (!$CFG->enablewebservices) {

            throw new webservice_access_exception('Web services are not enabled in Advanced features.');

        }

        // Obtain token record

        if (!$token = $DB->get_record('external_tokens', array('token' => $token))) {

            //client may want to display login form => moodle_exception

            throw new moodle_exception('invalidtoken', 'webservice');

        }

        $loginfaileddefaultparams = array(

            'other' => array(

                'method' => WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN,

                'reason' => null,

                'tokenid' => $token->id

            )

        );

        // Validate token date

        if ($token->validuntil and $token->validuntil < time()) {

            $params = $loginfaileddefaultparams;

            $params['other']['reason'] = 'token_expired';

            $event = \core\event\webservice_login_failed::create($params);

            $event->add_record_snapshot('external_tokens', $token);

            $event->trigger();

            $DB->delete_records('external_tokens', array('token' => $token->token));

            throw new webservice_access_exception('Invalid token - token expired - check validuntil time for the token');

        }

        // Check ip

        if ($token->iprestriction and !address_in_subnet(getremoteaddr(), $token->iprestriction)) {

            $params = $loginfaileddefaultparams;

            $params['other']['reason'] = 'ip_restricted';

            $event = \core\event\webservice_login_failed::create($params);

            $event->add_record_snapshot('external_tokens', $token);

            $event->trigger();

            throw new webservice_access_exception('Invalid token - IP:' . getremoteaddr()

                    . ' is not supported');

        }

        //retrieve user link to the token

        $user = $DB->get_record('user', array('id' => $token->userid, 'deleted' => 0), '*', MUST_EXIST);

        // let enrol plugins deal with new enrolments if necessary

        enrol_check_plugins($user, false);

        // setup user session to check capability

        \core\session\manager::set_user($user);

        set_login_session_preferences();

        //assumes that if sid is set then there must be a valid associated session no matter the token type

        if ($token->sid) {

            if (!\core\session\manager::session_exists($token->sid)) {

                $DB->delete_records('external_tokens', array('sid' => $token->sid));

                throw new webservice_access_exception('Invalid session based token - session not found or expired');

            }

        }

        // Cannot authenticate unless maintenance access is granted.

        $hasmaintenanceaccess = has_capability('moodle/site:maintenanceaccess', context_system::instance(), $user);

        if (!empty($CFG->maintenance_enabled) and !$hasmaintenanceaccess) {

            //this is usually temporary, client want to implement code logic  => moodle_exception

            throw new moodle_exception('sitemaintenance', 'admin');

        }

        //retrieve web service record

        $service = $DB->get_record('external_services', array('id' => $token->externalserviceid, 'enabled' => 1));

        if (empty($service)) {

            // will throw exception if no token found

            throw new webservice_access_exception('Web service is not available (it doesn\'t exist or might be disabled)');

        }

        //check if there is any required system capability

        if ($service->requiredcapability and !has_capability($service->requiredcapability, context_system::instance(), $user)) {

            throw new webservice_access_exception('The capability ' . $service->requiredcapability . ' is required.');

        }

        //specific checks related to user restricted service

        if ($service->restrictedusers) {

            $authoriseduser = $DB->get_record('external_services_users', array('externalserviceid' => $service->id, 'userid' => $user->id));

            if (empty($authoriseduser)) {

                throw new webservice_access_exception(

                        'The user is not allowed for this service. First you need to allow this user on the '

                        . $service->name . '\'s allowed users administration page.');

            }

            if (!empty($authoriseduser->validuntil) and $authoriseduser->validuntil < time()) {

                throw new webservice_access_exception('Invalid service - service expired - check validuntil time for this allowed user');

            }

            if (!empty($authoriseduser->iprestriction) and !address_in_subnet(getremoteaddr(), $authoriseduser->iprestriction)) {

                throw new webservice_access_exception('Invalid service - IP:' . getremoteaddr()

                    . ' is not supported - check this allowed user');

            }

        }

        //only confirmed user should be able to call web service

        if (empty($user->confirmed)) {

            $params = $loginfaileddefaultparams;

            $params['other']['reason'] = 'user_unconfirmed';

            $event = \core\event\webservice_login_failed::create($params);

            $event->add_record_snapshot('external_tokens', $token);

            $event->trigger();

            throw new moodle_exception('usernotconfirmed', 'moodle', '', $user->username);

        }

        //check the user is suspended

        if (!empty($user->suspended)) {

            $params = $loginfaileddefaultparams;

            $params['other']['reason'] = 'user_suspended';

            $event = \core\event\webservice_login_failed::create($params);

            $event->add_record_snapshot('external_tokens', $token);

            $event->trigger();

            throw new moodle_exception('wsaccessusersuspended', 'moodle', '', $user->username);

        }

        //check if the auth method is nologin (in this case refuse connection)

        if ($user->auth == 'nologin') {

            $params = $loginfaileddefaultparams;

            $params['other']['reason'] = 'nologin';

            $event = \core\event\webservice_login_failed::create($params);

            $event->add_record_snapshot('external_tokens', $token);

            $event->trigger();

            throw new moodle_exception('wsaccessusernologin', 'moodle', '', $user->username);

        }

        //Check if the user password is expired

        $auth = get_auth_plugin($user->auth);

        if (!empty($auth->config->expiration) and $auth->config->expiration == 1) {

            $days2expire = $auth->password_expire($user->username);

            if (intval($days2expire) < 0) {

                $params = $loginfaileddefaultparams;

                $params['other']['reason'] = 'password_expired';

                $event = \core\event\webservice_login_failed::create($params);

                $event->add_record_snapshot('external_tokens', $token);

                $event->trigger();

                throw new moodle_exception('passwordisexpired', 'webservice');

            }

        }

        // log token access

        self::update_token_lastaccess($token);

        return array('user' => $user, 'token' => $token, 'service' => $service);

    }

    /**

     * Updates the last access time for a token.

     *

     * @param \stdClass $token Token object (must include id, lastaccess fields)

     * @param int $time Time of access (0 = use current time)

     * @throws dml_exception If database error

     */

    public static function update_token_lastaccess($token, int $time = 0) {

        global $DB;

        if (!$time) {

            $time = time();

        }

        // Only update the field if it is a different time from previous request,

        // so as not to waste database effort.

        if ($time >= $token->lastaccess + self::TOKEN_LASTACCESS_UPDATE_SECS) {

            $DB->set_field('external_tokens', 'lastaccess', $time, array('id' => $token->id));

        }

    }

    /**

     * Allow user to call a service

     *

     * @param stdClass $user a user

     */

    public function add_ws_authorised_user($user) {

        global $DB;

        $user->timecreated = time();

        $DB->insert_record('external_services_users', $user);

    }

    /**

     * Disallow a user to call a service

     *

     * @param stdClass $user a user

     * @param int $serviceid

     */

    public function remove_ws_authorised_user($user, $serviceid) {

        global $DB;

        $DB->delete_records('external_services_users',

                array('externalserviceid' => $serviceid, 'userid' => $user->id));

    }

    /**

     * Update allowed user settings (ip restriction, valid until...)

     *

     * @param stdClass $user

     */

    public function update_ws_authorised_user($user) {

        global $DB;

        $DB->update_record('external_services_users', $user);

    }

    /**

     * Return list of allowed users with their options (ip/timecreated / validuntil...)

     * for a given service

     *

     * @param int $serviceid the service id to search against

     * @return array $users

     */

    public function get_ws_authorised_users($serviceid) {

        global $DB, $CFG;

        $params = array($CFG->siteguest, $serviceid);

        $userfields = \core_user\fields::for_identity(context_system::instance())->with_name()->excluding('id');

        $fieldsql = $userfields->get_sql('u');

        $sql = " SELECT u.id as id, esu.id as serviceuserid {$fieldsql->selects},

                        esu.iprestriction as iprestriction, esu.validuntil as validuntil,

                        esu.timecreated as timecreated

                   FROM {user} u

                   JOIN {external_services_users} esu ON esu.userid = u.id

                        {$fieldsql->joins}

                  WHERE u.id <> ? AND u.deleted = 0 AND u.confirmed = 1

                        AND esu.externalserviceid = ?";

        $users = $DB->get_records_sql($sql, array_merge($fieldsql->params, $params));

        return $users;

    }

    /**

     * 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;

        $params = array($CFG->siteguest, $serviceid, $userid);

        $sql = " SELECT u.id as id, esu.id as serviceuserid, u.email as email, u.firstname as firstname,

                        u.lastname as lastname,

                        esu.iprestriction as iprestriction, esu.validuntil as validuntil,

                        esu.timecreated as timecreated

                   FROM {user} u, {external_services_users} esu

                  WHERE u.id <> ? AND u.deleted = 0 AND u.confirmed = 1

                        AND esu.userid = u.id

                        AND esu.externalserviceid = ?

                        AND u.id = ?";

        $user = $DB->get_record_sql($sql, $params);

        return $user;

    }

    /**

     * 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

        if (!is_siteadmin() && has_capability('moodle/webservice:createtoken', context_system::instance(), $userid) && !empty($CFG->enablewebservices)) {

            // 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)

            $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)

            $servicesusers = $DB->get_records('external_services_users', array('userid' => $userid));

            foreach ($servicesusers as $serviceuser) {

                if (!in_array($serviceuser->externalserviceid,$serviceidlist)) {

                     $serviceidlist[] = $serviceuser->externalserviceid;

                }

            }

            // 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

            foreach ($serviceidlist as $serviceid) {

                if (!in_array($serviceid, $tokenizedservice)) {

                    // create the token for this service

                    $newtoken = new stdClass();

                    $newtoken->token = md5(uniqid(rand(),1));

                    // check that the user has capability on this service

                    $newtoken->tokentype = EXTERNAL_TOKEN_PERMANENT;

                    $newtoken->userid = $userid;

                    $newtoken->externalserviceid = $serviceid;

                    // TODO MDL-31190 find a way to get the context - UPDATE FOLLOWING LINE

                    $newtoken->contextid = context_system::instance()->id;

                    $newtoken->creatorid = $userid;

                    $newtoken->timecreated = time();

                    $newtoken->name = \core_external\util::generate_token_name();

                    // Generate the private token, it must be transmitted only via https.

                    $newtoken->privatetoken = random_string(64);

                    $DB->insert_record('external_tokens', $newtoken);

                }

            }

        }

    }

    /**

     * 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;

        //here retrieve token list (including linked users firstname/lastname and linked services name)

        $sql = "SELECT

                    t.id, t.creatorid, t.name as tokenname, u.firstname, u.lastname,

                    s.id as wsid, s.name as servicename, s.enabled, s.restrictedusers, t.validuntil, t.lastaccess

                FROM

                    {external_tokens} t, {user} u, {external_services} s

                WHERE

                    t.userid=? AND t.tokentype = ".EXTERNAL_TOKEN_PERMANENT." AND s.id = t.externalserviceid AND t.userid = u.id";

        $tokens = $DB->get_records_sql($sql, array( $userid));

        return $tokens;

    }

    /**

     * 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

     * ->tokenname

     * ->firstname user firstname

     * ->lastname

     * ->externalserviceid

     * ->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;

        $sql = "SELECT

                        t.id, t.token, t.name AS tokenname, u.firstname, u.lastname, t.externalserviceid, s.name

                    FROM

                        {external_tokens} t, {user} u, {external_services} s

                    WHERE

                        t.creatorid=? AND t.id=? AND t.tokentype = "

                . EXTERNAL_TOKEN_PERMANENT

                . " AND s.id = t.externalserviceid AND t.userid = u.id";

        //must be the token creator

        $token = $DB->get_record_sql($sql, array($userid, $tokenid), MUST_EXIST);

        return $token;

    }

    /**

     * Return a token of an arbitrary user by tokenid, including details of the associated user and the service name.

     * 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 $tokenid token id

     * @return stdClass

     */

    public function get_token_by_id_with_details($tokenid) {

        global $DB;

        $sql = "SELECT t.id, t.token, u.id AS userid, u.firstname, u.lastname, s.name, t.creatorid

                  FROM {external_tokens} t

             LEFT JOIN {user} u ON u.id = t.userid

             LEFT JOIN {external_services} s ON s.id = t.externalserviceid

                 WHERE t.id = ? AND t.tokentype = ?";

        return $DB->get_record_sql($sql, [$tokenid, EXTERNAL_TOKEN_PERMANENT], MUST_EXIST);

    }

    /**

     * Return a database token record for a token id

     *

     * @param int $tokenid token id

     * @return object token

     */

    public function get_token_by_id($tokenid) {

        global $DB;

        return $DB->get_record('external_tokens', array('id' => $tokenid));

    }

    /**

     * Delete a token

     *

     * @param int $tokenid token id

     */

    public function delete_user_ws_token($tokenid) {

        global $DB;

        $DB->delete_records('external_tokens', array('id'=>$tokenid));

    }

    /**

     * Delete all the tokens belonging to a user.

     *

     * @param int $userid the user id whose tokens must be deleted

     */

    public static function delete_user_ws_tokens($userid) {

        global $DB;

        $DB->delete_records('external_tokens', array('userid' => $userid));

    }

    /**

     * Delete a service

     * Also delete function references and authorised user references.

     *

     * @param int $serviceid service id

     */

    public function delete_service($serviceid) {

        global $DB;

        $DB->delete_records('external_services_users', array('externalserviceid' => $serviceid));

        $DB->delete_records('external_services_functions', array('externalserviceid' => $serviceid));

        $DB->delete_records('external_tokens', array('externalserviceid' => $serviceid));

        $DB->delete_records('external_services', array('id' => $serviceid));

    }

    /**

     * Get a full database token record for a given token value

     *

     * @param string $token

     * @throws moodle_exception if there is multiple result

     */

    public function get_user_ws_token($token) {

        global $DB;

        return $DB->get_record('external_tokens', array('token'=>$token), '*', MUST_EXIST);

    }

    /**

     * 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;

        if (!empty($serviceids)) {

            list($serviceids, $params) = $DB->get_in_or_equal($serviceids);

            $sql = "SELECT f.*

                      FROM {external_functions} f

                     WHERE f.name IN (SELECT sf.functionname

                                        FROM {external_services_functions} sf

                                       WHERE sf.externalserviceid $serviceids)

                     ORDER BY f.name ASC";

            $functions = $DB->get_records_sql($sql, $params);

        } else {

            $functions = array();

        }

        return $functions;

    }

    /**

     * 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) {

        global $DB;

        if (!empty($serviceshortnames)) {

            $enabledonlysql = $enabledonly?' AND s.enabled = 1 ':'';

            list($serviceshortnames, $params) = $DB->get_in_or_equal($serviceshortnames);

            $sql = "SELECT f.*

                      FROM {external_functions} f

                     WHERE f.name IN (SELECT sf.functionname

                                        FROM {external_services_functions} sf, {external_services} s

                                       WHERE s.shortname $serviceshortnames

                                             AND sf.externalserviceid = s.id

                                             " . $enabledonlysql . ")";

            $functions = $DB->get_records_sql($sql, $params);

        } else {

            $functions = array();

        }

        return $functions;

    }

    /**

     * Get functions not included in a service

     *

     * @param int $serviceid service id

     * @return array functions

     */

    public function get_not_associated_external_functions($serviceid) {

        global $DB;

        $select = "name NOT IN (SELECT s.functionname

                                  FROM {external_services_functions} s

                                 WHERE s.externalserviceid = :sid

                               )";

        $functions = $DB->get_records_select('external_functions',

                        $select, array('sid' => $serviceid), 'name');

        return $functions;

    }

    /**

     * Get list of required capabilities of a service, sorted by functions

     * Example of returned value:

     *  Array

     *  (

     *    [core_group_create_groups] => Array

     *    (

     *       [0] => moodle/course:managegroups

     *    )

     *

     *    [core_enrol_get_enrolled_users] => Array

     *    (

     *       [0] => moodle/user:viewdetails

     *       [1] => moodle/user:viewhiddendetails

     *       [2] => moodle/course:useremail

     *       [3] => moodle/user:update

     *       [4] => moodle/site:accessallgroups

     *    )

     *  )

     * @param int $serviceid service id

     * @return array

     */

    public function get_service_required_capabilities($serviceid) {

        $functions = $this->get_external_functions(array($serviceid));

        $requiredusercaps = array();

        foreach ($functions as $function) {

            $functioncaps = explode(',', $function->capabilities);

            if (!empty($functioncaps) and !empty($functioncaps[0])) {

                foreach ($functioncaps as $functioncap) {

                    $requiredusercaps[$function->name][] = trim($functioncap);

                }

            }

        }

        return $requiredusercaps;

    }

    /**

     * Get user capabilities (with context)

     * Only useful for documentation purpose

     * WARNING: do not use this "broken" function. It was created in the goal to display some capabilities

     * required by users. In theory we should not need to display this kind of information

     * as the front end does not display it itself. In pratice,

     * admins would like the info, for more info you can follow: MDL-29962

     *

     * @deprecated since Moodle 3.11 in MDL-67748 without a replacement.

     * @todo MDL-70187 Please delete this method completely in Moodle 4.3, thank you.

     * @param int $userid user id

     * @return array

     */

    public function get_user_capabilities($userid) {

        global $DB;

        debugging('webservice::get_user_capabilities() has been deprecated.', DEBUG_DEVELOPER);

        //retrieve the user capabilities

        $sql = "SELECT DISTINCT rc.id, rc.capability FROM {role_capabilities} rc, {role_assignments} ra

            WHERE rc.roleid=ra.roleid AND ra.userid= ? AND rc.permission = ?";

        $dbusercaps = $DB->get_records_sql($sql, array($userid, CAP_ALLOW));

        $usercaps = array();

        foreach ($dbusercaps as $usercap) {

            $usercaps[$usercap->capability] = true;

        }

        return $usercaps;

    }

    /**

     * Get missing user capabilities for the given service's functions.

     *

     * Every external function can declare some required capabilities to allow for easier setup of the web services.

     * However, that is supposed to be used for informational admin report only. There is no automatic evaluation of

     * the declared capabilities and the context of the capability evaluation is ignored. Also, actual capability

     * evaluation is much more complex as it allows for overrides etc.

     *

     * Returned are capabilities that the given users do not seem to have assigned anywhere at the site and that should

     * be checked by the admin.

     *

     * Do not use this method for anything else, particularly not for any security related checks. See MDL-29962 for the

     * background of why we have this - there are arguments for dropping this feature completely.

     *

     * @param array $users List of users to check, consisting of objects, arrays or integer ids.

     * @param int $serviceid The id of the external service to check.

     * @return array List of missing capabilities: (int)userid => array of (string)capabilitynames

     */

    public function get_missing_capabilities_by_users(array $users, int $serviceid): array {

        global $DB;

        // The following are default capabilities for all authenticated users and we will assume them granted.

        $commoncaps = get_default_capabilities('user');

        // Get the list of additional capabilities required by the service.

        $servicecaps = [];

        foreach ($this->get_service_required_capabilities($serviceid) as $service => $caps) {

            foreach ($caps as $cap) {

                if (empty($commoncaps[$cap])) {

                    $servicecaps[$cap] = true;

                }

            }

        }

        // Bail out early if there's nothing to process.

        if (empty($users) || empty($servicecaps)) {

            return [];

        }

        // Prepare a list of user ids we want to check.

        $userids = [];

        foreach ($users as $user) {

            if (is_object($user) && isset($user->id)) {

                $userids[$user->id] = true;

            } else if (is_array($user) && isset($user['id'])) {

                $userids[$user['id']] = true;

            } else {

                throw new coding_exception('Unexpected format of users list in webservice::get_missing_capabilities_by_users().');

            }

        }

        // Prepare a matrix of missing capabilities x users - consider them all missing by default.

        foreach (array_keys($userids) as $userid) {

            foreach (array_keys($servicecaps) as $capname) {

                $matrix[$userid][$capname] = true;

            }

        }

        list($capsql, $capparams) = $DB->get_in_or_equal(array_keys($servicecaps), SQL_PARAMS_NAMED, 'paramcap');

        list($usersql, $userparams) = $DB->get_in_or_equal(array_keys($userids), SQL_PARAMS_NAMED, 'paramuser');

        $sql = "SELECT c.name AS capability, u.id AS userid

                  FROM {capabilities} c

                  JOIN {role_capabilities} rc ON c.name = rc.capability

                  JOIN {role_assignments} ra ON ra.roleid = rc.roleid

                  JOIN {user} u ON ra.userid = u.id

                 WHERE rc.permission = :capallow

                   AND c.name {$capsql}

                   AND u.id {$usersql}";

        $params = $capparams + $userparams + [

            'capallow' => CAP_ALLOW,

        ];

        $rs = $DB->get_recordset_sql($sql, $params);

        foreach ($rs as $record) {

            // If there was a potential role assignment found that might grant the user the given capability,

            // remove it from the matrix. Again, we ignore all the contexts, prohibits, prevents and other details

            // of the permissions evaluations. See the function docblock for details.

            unset($matrix[$record->userid][$record->capability]);

        }

        $rs->close();

        foreach ($matrix as $userid => $caps) {

            $matrix[$userid] = array_keys($caps);

            if (empty($matrix[$userid])) {

                unset($matrix[$userid]);

            }

        }

        return $matrix;

    }

    /**

     * 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;

        $service = $DB->get_record('external_services',

                        array('id' => $serviceid), '*', $strictness);

        return $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;

        $service = $DB->get_record('external_services',

                        array('shortname' => $shortname), '*', $strictness);

        return $service;

    }

    /**

     * 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;

        $function = $DB->get_record('external_functions',

                            array('id' => $functionid), '*', $strictness);

        return $function;

    }

    /**

     * Add a function to a service

     *

     * @param string $functionname function name

     * @param int $serviceid service id

     */

    public function add_external_function_to_service($functionname, $serviceid) {

        global $DB;

        $addedfunction = new stdClass();

        $addedfunction->externalserviceid = $serviceid;

        $addedfunction->functionname = $functionname;

        $DB->insert_record('external_services_functions', $addedfunction);

    }

    /**

     * Add a service

     * It generates the timecreated field automatically.

     *

     * @param stdClass $service

     * @return serviceid integer

     */

    public function add_external_service($service) {

        global $DB;

        $service->timecreated = time();

        $serviceid = $DB->insert_record('external_services', $service);

        return $serviceid;

    }

    /**

     * Update a service

     * It modifies the timemodified automatically.

     *

     * @param stdClass $service

     */

    public function update_external_service($service) {

        global $DB;

        $service->timemodified = time();

        $DB->update_record('external_services', $service);

    }

    /**

     * 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

     */

    public function service_function_exists($functionname, $serviceid) {

        global $DB;

        return $DB->record_exists('external_services_functions',

                            array('externalserviceid' => $serviceid,

                                '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',

                    array('externalserviceid' => $serviceid, 'functionname' => $functionname));

    }

    /**

     * Return a list with all the valid user tokens for the given user, it only excludes expired tokens.

     *

     * @param  string $userid user id to retrieve tokens from

     * @return array array of token entries

     * @since Moodle 3.2

     */

    public static function get_active_tokens($userid) {

        global $DB;

        $sql = 'SELECT t.id, t.creatorid, t.externalserviceid, t.name AS tokenname, t.validuntil, s.name AS servicename

                  FROM {external_tokens} t

                  JOIN {external_services} s ON t.externalserviceid = s.id

                 WHERE t.userid = :userid AND (COALESCE(t.validuntil, 0) = 0 OR t.validuntil > :now)';

        $params = array('userid' => $userid, 'now' => time());

        return $DB->get_records_sql($sql, $params);

    }

}

/**

 * Exception indicating access control problem in web service call

 * This exception should return general errors about web service setup.

 * Errors related to the user like wrong username/password should not use it,

 * you should not use this exception if you want to let the client implement

 * some code logic against an access error.

 *

 * @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);

    }

}

/**

 * Check if a protocol is enabled

 *

 * @param string $protocol name of WS protocol ('rest', 'soap', ...)

 * @return bool true if the protocol is enabled

 */

function webservice_protocol_is_enabled($protocol) {

    global $CFG;

    if (empty($CFG->enablewebservices) || empty($CFG->webserviceprotocols)) {

        return false;

    }

    $active = explode(',', $CFG->webserviceprotocols);

    return(in_array($protocol, $active));

}

/**

 * Mandatory interface for all test client classes.

 *

 * @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 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);

}

/**

 * Mandatory interface for all web service protocol classes

 *

 * @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.

     */

    public function run();

}

/**

 * Abstract web service base class.

 *

 * @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 {

    /** @var string Name of the web server plugin */

    protected $wsname = null;

    /** @var string Name of local user */

    protected $username = null;

    /** @var string Password of the local user */

    protected $password = null;

    /** @var int The local user */

    protected $userid = null;

    /** @var integer Authentication method one of WEBSERVICE_AUTHMETHOD_* */

    protected $authmethod;

    /** @var string Authentication token*/

    protected $token = null;

    /** @var stdClass Restricted context */

    protected $restricted_context;

    /** @var int Restrict call to one service id*/

    protected $restricted_serviceid = null;

    /**

     * Constructor

     *

     * @param integer $authmethod authentication method one of WEBSERVICE_AUTHMETHOD_*

     */

    public function __construct($authmethod) {

        $this->authmethod = $authmethod;

    }

    /**

     * Authenticate user using username+password or token.

     * This function sets up $USER global.