Search moodle.org's
Developer Documentation
Developer Documentation
- Bug fixes for general core bugs in 4.0.x will end 8 May 2023 (12 months).
- Bug fixes for security issues in 4.0.x will end 13 November 2023 (18 months).
- PHP version: minimum PHP 7.3.0 Note: the minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is also supported.
/webservice/ -> lib.php (source)
Differences Between: [Versions 310 and 400] [Versions 311 and 400] [Versions 39 and 400] [Versions 400 and 401] [Versions 400 and 402] [Versions 400 and 403]
Web services utility functions and classes
| Copyright: | 2009 Jerome Mouneyrac <jerome@moodle.com> |
| License: | http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later |
| File Size: | 1845 lines (74 kb) |
| Included or required: | 1 time |
| Referenced: | 16 times |
| Includes or requires: | 0 files |
Defines 6 classes
webservice:: (31 methods):
authenticate_user()
update_token_lastaccess()
add_ws_authorised_user()
remove_ws_authorised_user()
update_ws_authorised_user()
get_ws_authorised_users()
get_ws_authorised_user()
generate_user_ws_tokens()
get_user_ws_tokens()
get_created_by_user_ws_token()
get_token_by_id_with_details()
get_token_by_id()
delete_user_ws_token()
delete_user_ws_tokens()
delete_service()
get_user_ws_token()
get_external_functions()
get_external_functions_by_enabled_services()
get_not_associated_external_functions()
get_service_required_capabilities()
get_user_capabilities()
get_missing_capabilities_by_users()
get_external_service_by_id()
get_external_service_by_shortname()
get_external_function_by_id()
add_external_function_to_service()
add_external_service()
update_external_service()
service_function_exists()
remove_external_function_from_service()
get_active_tokens()
webservice_access_exception:: (2 methods):
__construct()
webservice_protocol_is_enabled()
webservice_test_client_interface:: (1 method):
simpletest()
webservice_server_interface:: (1 method):
run()
webservice_server:: (4 methods):
__construct()
authenticate_user()
authenticate_by_token()
set_web_service_call_settings()
webservice_base_server:: (11 methods):
run()
exception_handler()
session_cleanup()
load_function_info()
execute()
init_service_class()
generate_simple_struct_class()
get_virtual_method_code()
get_phpdoc_type()
service_class_method_body()
early_ws_exception_handler()
Class: webservice - X-Ref
General web service library| authenticate_user($token) X-Ref |
| Authenticate user (used by download/upload file scripts) return: array - contains the authenticated user, token and service objects param: string $token |
| update_token_lastaccess($token, int $time = 0) X-Ref |
| 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) |
| add_ws_authorised_user($user) X-Ref |
| Allow user to call a service param: stdClass $user a user |
| remove_ws_authorised_user($user, $serviceid) X-Ref |
| Disallow a user to call a service param: stdClass $user a user param: int $serviceid |
| update_ws_authorised_user($user) X-Ref |
| Update allowed user settings (ip restriction, valid until...) param: stdClass $user |
| get_ws_authorised_users($serviceid) X-Ref |
| Return list of allowed users with their options (ip/timecreated / validuntil...) for a given service return: array $users param: int $serviceid the service id to search against |
| get_ws_authorised_user($serviceid, $userid) X-Ref |
| Return an authorised user with their options (ip/timecreated / validuntil...) return: stdClass param: int $serviceid the service id to search against param: int $userid the user to search against |
| generate_user_ws_tokens($userid) X-Ref |
| Generate all tokens of a specific user param: int $userid user id |
| get_user_ws_tokens($userid) X-Ref |
| Return all tokens of a specific user + the service state (enabled/disabled) + the authorised user mode (restricted/not restricted) return: array param: int $userid user id |
| get_created_by_user_ws_token($userid, $tokenid) X-Ref |
| 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 return: stdClass param: int $userid user id param: int $tokenid token id |
| get_token_by_id_with_details($tokenid) X-Ref |
| 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 return: stdClass param: int $tokenid token id |
| get_token_by_id($tokenid) X-Ref |
| Return a database token record for a token id return: object token param: int $tokenid token id |
| delete_user_ws_token($tokenid) X-Ref |
| Delete a token param: int $tokenid token id |
| delete_user_ws_tokens($userid) X-Ref |
| Delete all the tokens belonging to a user. param: int $userid the user id whose tokens must be deleted |
| delete_service($serviceid) X-Ref |
| Delete a service Also delete function references and authorised user references. param: int $serviceid service id |
| get_user_ws_token($token) X-Ref |
| Get a full database token record for a given token value param: string $token |
| get_external_functions($serviceids) X-Ref |
| Get the functions list of a service list (by id) return: array of functions param: array $serviceids service ids |
| get_external_functions_by_enabled_services($serviceshortnames, $enabledonly = true) X-Ref |
| Get the functions of a service list (by shortname). It can return only enabled functions if required. return: array functions param: array $serviceshortnames service shortnames param: bool $enabledonly if true then only return functions for services that have been enabled |
| get_not_associated_external_functions($serviceid) X-Ref |
| Get functions not included in a service return: array functions param: int $serviceid service id |
| get_service_required_capabilities($serviceid) X-Ref |
| 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 ) ) return: array param: int $serviceid service id |
| get_user_capabilities($userid) X-Ref |
| 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 return: array param: int $userid user id |
| get_missing_capabilities_by_users(array $users, int $serviceid) X-Ref |
| 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. return: array List of missing capabilities: (int)userid => array of (string)capabilitynames 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. |
| get_external_service_by_id($serviceid, $strictness=IGNORE_MISSING) X-Ref |
| Get an external service for a given service id return: stdClass external service param: int $serviceid service id param: int $strictness IGNORE_MISSING, MUST_EXIST... |
| get_external_service_by_shortname($shortname, $strictness=IGNORE_MISSING) X-Ref |
| Get an external service for a given shortname return: stdClass external service param: string $shortname service shortname param: int $strictness IGNORE_MISSING, MUST_EXIST... |
| get_external_function_by_id($functionid, $strictness=IGNORE_MISSING) X-Ref |
| Get an external function for a given function id return: stdClass external function param: int $functionid function id param: int $strictness IGNORE_MISSING, MUST_EXIST... |
| add_external_function_to_service($functionname, $serviceid) X-Ref |
| Add a function to a service param: string $functionname function name param: int $serviceid service id |
| add_external_service($service) X-Ref |
| Add a service It generates the timecreated field automatically. return: serviceid integer param: stdClass $service |
| update_external_service($service) X-Ref |
| Update a service It modifies the timemodified automatically. param: stdClass $service |
| service_function_exists($functionname, $serviceid) X-Ref |
| Test whether an external function is already linked to a service return: bool true if a matching function exists for the service, else false. param: string $functionname function name param: int $serviceid service id |
| remove_external_function_from_service($functionname, $serviceid) X-Ref |
| Remove a function from a service param: string $functionname function name param: int $serviceid service id |
| get_active_tokens($userid) X-Ref |
| Return a list with all the valid user tokens for the given user, it only excludes expired tokens. return: array array of token entries param: string $userid user id to retrieve tokens from |
Class: webservice_access_exception - X-Ref
Exception indicating access control problem in web service callThis 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.
| __construct($debuginfo) X-Ref |
| Constructor param: string $debuginfo the debug info |
| webservice_protocol_is_enabled($protocol) X-Ref |
| Check if a protocol is enabled return: bool true if the protocol is enabled param: string $protocol name of WS protocol ('rest', 'soap', 'xmlrpc'...) |
Interface: webservice_test_client_interface - X-Ref
Mandatory interface for all test client classes.| simpletest($serverurl, $function, $params) X-Ref |
| Execute test client WS request return: mixed 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 |
Interface: webservice_server_interface - X-Ref
Mandatory interface for all web service protocol classesClass: webservice_server - X-Ref
Abstract web service base class.| __construct($authmethod) X-Ref |
| Constructor param: integer $authmethod authentication method one of WEBSERVICE_AUTHMETHOD_* |
| authenticate_user() X-Ref |
| Authenticate user using username+password or token. This function sets up $USER global. It is safe to use has_capability() after this. This method also verifies user is allowed to use this server. |
| authenticate_by_token($tokentype) X-Ref |
| User authentication by token return: stdClass the authenticated user param: string $tokentype token type (EXTERNAL_TOKEN_EMBEDDED or EXTERNAL_TOKEN_PERMANENT) |
| set_web_service_call_settings() X-Ref |
| Intercept some moodlewssettingXXX $_GET and $_POST parameter that are related to the web service call and are not the function parameters |
Class: webservice_base_server - X-Ref
Web Service server base class.This class handles both simple and token authentication.
| run() X-Ref |
| Process request from client. |
| exception_handler($ex) X-Ref |
| Specialised exception handler, we can not use the standard one because it can not just print html to output. param: exception $ex |
| session_cleanup($exception=null) X-Ref |
| Future hook needed for emulated sessions. param: exception $exception null means normal termination, $exception received when WS call failed |
| load_function_info() X-Ref |
| Fetches the function description from database, verifies user is allowed to use this function and loads all paremeters and return descriptions. |
| execute() X-Ref |
| Execute previously loaded function using parameters parsed from the request data. |
| init_service_class() X-Ref |
| Load the virtual class needed for the web service. Initialises the virtual class that contains the web service functions that the user is allowed to use. The web service function will be available if the user: - is validly registered in the external_services_users table. - has the required capability. - meets the IP restriction requirement. This virtual class can be used by web service protocols such as SOAP, especially when generating WSDL. |
| generate_simple_struct_class(external_single_structure $structdesc) X-Ref |
| Generates a struct class. return: string The class name of the generated struct class. param: external_single_structure $structdesc The basis of the struct class to be generated. |
| get_virtual_method_code($function) X-Ref |
| Returns a virtual method code for a web service function. return: string The PHP code of the virtual method. param: stdClass $function a record from external_function |
| get_phpdoc_type($keydesc) X-Ref |
| No description |
| service_class_method_body($function, $params) X-Ref |
| Generates the method body of the virtual external function. return: string body of the method for $function ie. everything within the {} of the method declaration. param: stdClass $function a record from external_function. param: array $params web service function parameters. |
| early_ws_exception_handler(Exception $ex) X-Ref |
| Early WS exception handler. It handles exceptions during setup and returns the Exception text in the WS format. If a raise function is found nothing is returned. Throws Exception otherwise. param: Exception $ex Raised exception. |
