Moodle APIs 3.9
Moodle 3.9.13+ (Build: 20220325)
|
Files | |
file | externallib.php |
external API for core library | |
file | externallib.php |
Support for external API. | |
file | externallib.php |
external API for mobile web services | |
file | helpers.php |
This file contains helper classes for testing the web service and external files. | |
file | renderer.php |
Web service documentation renderer. | |
file | services.php |
Core external functions and service definitions. | |
file | testclient_forms.php |
Base class for implementations of WS test client forms. | |
file | token_table.php |
Contains the class used for the displaying the tokens table. | |
Namespaces | |
namespace | core_webservice\privacy |
| |
namespace | webservice |
| |
Classes | |
class | core_course_create_categories_testclient_form |
Form class for create_categories() web service function test. More... | |
class | core_course_delete_categories_testclient_form |
Form class for delete_categories() web service function test. More... | |
class | core_course_update_categories_testclient_form |
Form class for create_categories() web service function test. More... | |
class | core_external |
class | core_fetch_notifications_testclient_form |
Test class for WS function core_fetch_notifications. More... | |
class | core_get_string_testclient_form |
Test class for WS function core_get_string. More... | |
class | core_webservice\privacy\provider |
Data provider class. More... | |
class | core_webservice_external |
class | core_webservice_get_site_info_testclient_form |
Test class for WS function get_site_info. More... | |
class | core_webservice_renderer |
class | external_api |
Base class for external api methods. More... | |
class | external_description |
Common ancestor of all parameter description classes. More... | |
class | external_files |
External structure representing a set of files. More... | |
class | external_format_value |
A pre-filled external_value class for text format. More... | |
class | external_function_parameters |
Description of top level - PHP function parameters. More... | |
class | external_multiple_structure |
Bulk array description class. More... | |
class | external_settings |
Singleton to handle the external settings. More... | |
class | external_single_structure |
Associative array description class. More... | |
class | external_util |
Utility functions for the external API. More... | |
class | external_value |
Scalar value description class. More... | |
class | external_warnings |
Standard Moodle web service warnings. More... | |
class | externallib_advanced_testcase |
Helper base class for external tests. More... | |
class | restricted_context_exception |
Exception indicating user is not allowed to use external function in the current context. More... | |
class | webservice |
General web service library. More... | |
class | webservice\token_table |
Class for the displaying the participants table. More... | |
class | webservice_access_exception |
Exception indicating access control problem in web service call This exception should return general errors about web service setup. More... | |
class | webservice_server |
Abstract web service base class. More... | |
interface | webservice_server_interface |
Mandatory interface for all web service protocol classes. More... | |
class | webservice_test_client_base_form |
class | webservice_test_client_form |
interface | webservice_test_client_interface |
Mandatory interface for all test client classes. More... | |
Functions | |
webservice_server::__construct ($authmethod) | |
Constructor. More... | |
webservice_access_exception::__construct ($debuginfo) | |
Constructor. More... | |
webservice::add_external_function_to_service ($functionname, $serviceid) | |
Add a function to a service. More... | |
webservice::add_external_service ($service) | |
Add a service It generates the timecreated field automatically. More... | |
webservice::add_ws_authorised_user ($user) | |
Allow user to call a service. More... | |
webservice_server::authenticate_by_token ($tokentype) | |
User authentication by token. More... | |
webservice::authenticate_user ($token) | |
Authenticate user (used by download/upload file scripts) More... | |
webservice_server::authenticate_user () | |
Authenticate user using username+password or token. More... | |
webservice::delete_service ($serviceid) | |
Delete a service Also delete function references and authorised user references. More... | |
webservice::delete_user_ws_token ($tokenid) | |
Delete a token. More... | |
static | webservice::delete_user_ws_tokens ($userid) |
Delete all the tokens belonging to a user. More... | |
external_create_service_token ($servicename, $context) | |
Create and return a session linked token. More... | |
external_delete_descriptions ($component) | |
Delete all pre-built services (+ related tokens) and external functions information defined in the specified component. More... | |
external_format_string ($str, $contextorid, $striplinks=true, $options=array()) | |
Format the string to be returned properly as requested by the either the web service server, either by an internally call. More... | |
external_format_text ($text, $textformat, $contextorid, $component=null, $filearea=null, $itemid=null, $options=null) | |
Format the text to be returned properly as requested by the either the web service server, either by an internally call. More... | |
external_generate_token ($tokentype, $serviceorid, $userid, $contextorid, $validuntil=0, $iprestriction='') | |
Generate a token. More... | |
external_generate_token_for_current_user ($service) | |
Generate or return an existing token for the current authenticated user. More... | |
external_log_token_request ($token) | |
Set the last time a token was sent and trigger the core::event::webservice_token_sent event. More... | |
external_validate_format ($format) | |
Validate text field format against known FORMAT_XXX. More... | |
webservice::generate_user_ws_tokens ($userid) | |
Generate all tokens of a specific user. More... | |
static | webservice::get_active_tokens ($userid) |
Return a list with all the valid user tokens for the given user, it only excludes expired tokens. More... | |
webservice::get_created_by_user_ws_token ($userid, $tokenid) | |
Return a token that has been created by the user (i.e. More... | |
webservice::get_external_function_by_id ($functionid, $strictness=IGNORE_MISSING) | |
Get an external function for a given function id. More... | |
webservice::get_external_functions ($serviceids) | |
Get the functions list of a service list (by id) More... | |
webservice::get_external_functions_by_enabled_services ($serviceshortnames, $enabledonly=true) | |
Get the functions of a service list (by shortname). More... | |
webservice::get_external_service_by_id ($serviceid, $strictness=IGNORE_MISSING) | |
Get an external service for a given service id. More... | |
webservice::get_external_service_by_shortname ($shortname, $strictness=IGNORE_MISSING) | |
Get an external service for a given shortname. More... | |
webservice::get_missing_capabilities_by_users ($users, $serviceid) | |
Get missing user capabilities for a given service WARNING: do not use this "broken" function. More... | |
webservice::get_not_associated_external_functions ($serviceid) | |
Get functions not included in a service. More... | |
webservice::get_service_required_capabilities ($serviceid) | |
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 ) More... | |
webservice::get_token_by_id ($tokenid) | |
Return a database token record for a token id. More... | |
webservice::get_token_by_id_with_details ($tokenid) | |
Return a token of an arbitrary user by tokenid, including details of the associated user and the service name. More... | |
webservice::get_user_capabilities ($userid) | |
Get user capabilities (with context) Only useful for documentation purpose WARNING: do not use this "broken" function. More... | |
webservice::get_user_ws_token ($token) | |
Get a full database token record for a given token value. More... | |
webservice::get_user_ws_tokens ($userid) | |
Return all tokens of a specific user. More... | |
webservice::get_ws_authorised_user ($serviceid, $userid) | |
Return an authorised user with their options (ip/timecreated / validuntil...) More... | |
webservice::get_ws_authorised_users ($serviceid) | |
Return list of allowed users with their options (ip/timecreated / validuntil...) for a given service. More... | |
webservice::remove_external_function_from_service ($functionname, $serviceid) | |
Remove a function from a service. More... | |
webservice::remove_ws_authorised_user ($user, $serviceid) | |
Disallow a user to call a service. More... | |
webservice_server_interface::run () | |
Process request from client. | |
webservice::service_function_exists ($functionname, $serviceid) | |
Test whether an external function is already linked to a service. More... | |
webservice_server::set_web_service_call_settings () | |
Intercept some moodlewssettingXXX $_GET and $_POST parameter that are related to the web service call and are not the function parameters. | |
webservice_test_client_interface::simpletest ($serverurl, $function, $params) | |
Execute test client WS request. More... | |
webservice::update_external_service ($service) | |
Update a service It modifies the timemodified automatically. More... | |
static | webservice::update_token_lastaccess ($token, int $time=0) |
Updates the last access time for a token. More... | |
webservice::update_ws_authorised_user ($user) | |
Update allowed user settings (ip restriction, valid until...) More... | |
webservice_protocol_is_enabled ($protocol) | |
Check if a protocol is enabled. More... | |
Variables | |
integer | webservice_server::$authmethod |
Authentication method one of WEBSERVICE_AUTHMETHOD_*. | |
$functions | |
string | webservice_server::$password = null |
Password of the local user. | |
stdClass | webservice_server::$restricted_context |
Restricted context. | |
int | webservice_server::$restricted_serviceid = null |
Restrict call to one service id. | |
$services | |
string | webservice_server::$token = null |
Authentication token. | |
int | webservice_server::$userid = null |
The local user. | |
string | webservice_server::$username = null |
Name of local user. | |
string | webservice_server::$wsname = null |
Name of the web server plugin. | |
int const | webservice::TOKEN_LASTACCESS_UPDATE_SECS = 60 |
Only update token last access once per this many seconds. More... | |
const | WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN 1 |
WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN - most common token authentication (external app, mobile app...) | |
const | WEBSERVICE_AUTHMETHOD_SESSION_TOKEN 2 |
WEBSERVICE_AUTHMETHOD_SESSION_TOKEN - token for embedded application (requires Moodle session) | |
const | WEBSERVICE_AUTHMETHOD_USERNAME 0 |
WEBSERVICE_AUTHMETHOD_USERNAME - username/password authentication (also called simple authentication) | |
webservice_server::__construct | ( | $authmethod | ) |
Constructor.
integer | $authmethod | authentication method one of WEBSERVICE_AUTHMETHOD_* |
webservice_access_exception::__construct | ( | $debuginfo | ) |
Constructor.
string | $debuginfo | the debug info |
webservice::add_external_function_to_service | ( | $functionname, | |
$serviceid | |||
) |
Add a function to a service.
string | $functionname | function name |
int | $serviceid | service id |
webservice::add_external_service | ( | $service | ) |
Add a service It generates the timecreated field automatically.
stdClass | $service |
serviceid | integer |
webservice::add_ws_authorised_user | ( | $user | ) |
Allow user to call a service.
stdClass | $user | a user |
|
protected |
User authentication by token.
string | $tokentype | token type (EXTERNAL_TOKEN_EMBEDDED or EXTERNAL_TOKEN_PERMANENT) |
stdClass | the authenticated user |
webservice_access_exception |
webservice::authenticate_user | ( | $token | ) |
Authenticate user (used by download/upload file scripts)
string | $token |
array | - contains the authenticated user, token and service objects |
|
protected |
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.
webservice::delete_service | ( | $serviceid | ) |
Delete a service Also delete function references and authorised user references.
int | $serviceid | service id |
webservice::delete_user_ws_token | ( | $tokenid | ) |
Delete a token.
int | $tokenid | token id |
|
static |
Delete all the tokens belonging to a user.
int | $userid | the user id whose tokens must be deleted |
external_create_service_token | ( | $servicename, | |
$context | |||
) |
Create and return a session linked token.
Token to be used for html embedded client apps that want to communicate with the Moodle server through web services. The token is linked to the current session for the current page request. It is expected this will be called in the script generating the html page that is embedding the client app and that the returned token will be somehow passed into the client app being embedded in the page.
string | $servicename | name of the web service. Service name as defined in db/services.php |
int | $context | context within which the web service can operate. |
int | returns token id. |
external_delete_descriptions | ( | $component | ) |
Delete all pre-built services (+ related tokens) and external functions information defined in the specified component.
string | $component | name of component (moodle, mod_assignment, etc.) |
external_format_string | ( | $str, | |
$contextorid, | |||
$striplinks = true , |
|||
$options = array() |
|||
) |
Format the string to be returned properly as requested by the either the web service server, either by an internally call.
The caller can change the format (raw) with the external_settings singleton All web service servers must set this singleton when parsing the $_GET and $_POST.
Options are the same that in with some changes: filter : Can be set to false to force filters off, else observes .
string | $str | The string to be filtered. Should be plain text, expect possibly for multilang tags. |
boolean | $striplinks | To strip any link in the result text. Moodle 1.8 default changed from false to true! MDL-8713 |
context | int | $contextorid | The id of the context for the string or the context (affects filters). |
array | $options | options array/object or courseid |
string | text |
external_format_text | ( | $text, | |
$textformat, | |||
$contextorid, | |||
$component = null , |
|||
$filearea = null , |
|||
$itemid = null , |
|||
$options = null |
|||
) |
Format the text to be returned properly as requested by the either the web service server, either by an internally call.
The caller can change the format (raw, filter, file, fileurl) with the external_settings singleton All web service servers must set this singleton when parsing the $_GET and $_POST.
Options are the same that in with some changes in defaults to provide backwards compatibility: trusted : If true the string won't be cleaned. Default false. noclean : If true the string won't be cleaned only if trusted is also true. Default false. nocache : If true the string will not be cached and will be formatted every call. Default false. filter : Can be set to false to force filters off, else observes . para : If true then the returned string will be wrapped in div tags. Default (different from format_text) false. Default changed because div tags are not commonly needed. newlines : If true then lines newline breaks will be converted to HTML newline breaks. Default true. context : Not used! Using contextid parameter instead. overflowdiv : If set to true the formatted text will be encased in a div with the class no-overflow before being returned. Default false. allowid : If true then id attributes will not be removed, even when using htmlpurifier. Default (different from format_text) true. Default changed id attributes are commonly needed. blanktarget : If true all tags will have target="_blank" added unless target is explicitly specified.
string | $text | The content that may contain ULRs in need of rewriting. |
int | $textformat | The text format. |
context | int | $contextorid | This parameter and the next two identify the file area to use. |
string | $component | |
string | $filearea | helps identify the file area. |
int | $itemid | helps identify the file area. |
object/array | $options text formatting options |
array | text + textformat |
external_generate_token | ( | $tokentype, | |
$serviceorid, | |||
$userid, | |||
$contextorid, | |||
$validuntil = 0 , |
|||
$iprestriction = '' |
|||
) |
Generate a token.
string | $tokentype | EXTERNAL_TOKEN_EMBEDDED|EXTERNAL_TOKEN_PERMANENT |
stdClass | int | $serviceorid | service linked to the token |
int | $userid | user linked to the token |
stdClass | int | $contextorid | |
int | $validuntil | date when the token expired |
string | $iprestriction | allowed ip - if 0 or empty then all ips are allowed |
string | generated token |
external_generate_token_for_current_user | ( | $service | ) |
Generate or return an existing token for the current authenticated user.
This function is used for creating a valid token for users authenticathing via login/token.php or admin/tool/mobile/launch.php.
stdClass | $service | external service object |
stdClass | token object |
moodle_exception |
external_log_token_request | ( | $token | ) |
Set the last time a token was sent and trigger the core::event::webservice_token_sent event.
This function is used when a token is generated by the user via login/token.php or admin/tool/mobile/launch.php. In order to protect the privatetoken, we remove it from the event params.
stdClass | $token | token object |
external_validate_format | ( | $format | ) |
Validate text field format against known FORMAT_XXX.
array | $format | the format to validate |
the | validated format |
coding_exception |
webservice::generate_user_ws_tokens | ( | $userid | ) |
Generate all tokens of a specific user.
int | $userid | user id |
|
static |
Return a list with all the valid user tokens for the given user, it only excludes expired tokens.
string | $userid | user id to retrieve tokens from |
array | array of token entries |
webservice::get_created_by_user_ws_token | ( | $userid, | |
$tokenid | |||
) |
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
int | $userid | user id |
int | $tokenid | token id |
stdClass |
webservice::get_external_function_by_id | ( | $functionid, | |
$strictness = IGNORE_MISSING |
|||
) |
Get an external function for a given function id.
int | $functionid | function id |
int | $strictness | IGNORE_MISSING, MUST_EXIST... |
stdClass | external function |
webservice::get_external_functions | ( | $serviceids | ) |
Get the functions list of a service list (by id)
array | $serviceids | service ids |
array | of functions |
webservice::get_external_functions_by_enabled_services | ( | $serviceshortnames, | |
$enabledonly = true |
|||
) |
Get the functions of a service list (by shortname).
It can return only enabled functions if required.
array | $serviceshortnames | service shortnames |
bool | $enabledonly | if true then only return functions for services that have been enabled |
array | functions |
webservice::get_external_service_by_id | ( | $serviceid, | |
$strictness = IGNORE_MISSING |
|||
) |
Get an external service for a given service id.
int | $serviceid | service id |
int | $strictness | IGNORE_MISSING, MUST_EXIST... |
stdClass | external service |
webservice::get_external_service_by_shortname | ( | $shortname, | |
$strictness = IGNORE_MISSING |
|||
) |
Get an external service for a given shortname.
string | $shortname | service shortname |
int | $strictness | IGNORE_MISSING, MUST_EXIST... |
stdClass | external service |
webservice::get_missing_capabilities_by_users | ( | $users, | |
$serviceid | |||
) |
Get missing user capabilities for a given service 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
array | $users | users |
int | $serviceid | service id |
array | of missing capabilities, keys being the user ids |
webservice::get_not_associated_external_functions | ( | $serviceid | ) |
Get functions not included in a service.
int | $serviceid | service id |
array | functions |
webservice::get_service_required_capabilities | ( | $serviceid | ) |
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 ) )
int | $serviceid | service id |
array |
webservice::get_token_by_id | ( | $tokenid | ) |
Return a database token record for a token id.
int | $tokenid | token id |
object | token |
webservice::get_token_by_id_with_details | ( | $tokenid | ) |
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
int | $tokenid | token id |
stdClass |
webservice::get_user_capabilities | ( | $userid | ) |
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
int | $userid | user id |
array |
webservice::get_user_ws_token | ( | $token | ) |
Get a full database token record for a given token value.
string | $token |
moodle_exception | if there is multiple result |
webservice::get_user_ws_tokens | ( | $userid | ) |
Return all tokens of a specific user.
int | $userid | user id |
array |
webservice::get_ws_authorised_user | ( | $serviceid, | |
$userid | |||
) |
Return an authorised user with their options (ip/timecreated / validuntil...)
int | $serviceid | the service id to search against |
int | $userid | the user to search against |
stdClass |
webservice::get_ws_authorised_users | ( | $serviceid | ) |
Return list of allowed users with their options (ip/timecreated / validuntil...) for a given service.
int | $serviceid | the service id to search against |
array::$users |
webservice::remove_external_function_from_service | ( | $functionname, | |
$serviceid | |||
) |
Remove a function from a service.
string | $functionname | function name |
int | $serviceid | service id |
webservice::remove_ws_authorised_user | ( | $user, | |
$serviceid | |||
) |
Disallow a user to call a service.
stdClass | $user | a user |
int | $serviceid |
webservice::service_function_exists | ( | $functionname, | |
$serviceid | |||
) |
Test whether an external function is already linked to a service.
string | $functionname | function name |
int | $serviceid | service id |
bool | true if a matching function exists for the service, else false. |
dml_exception | if error |
webservice_test_client_interface::simpletest | ( | $serverurl, | |
$function, | |||
$params | |||
) |
Execute test client WS request.
string | $serverurl | server url (including the token param) |
string | $function | web service function name |
array | $params | parameters of the web service function |
mixed |
Implemented in webservice_rest_test_client, webservice_soap_test_client, and webservice_xmlrpc_test_client.
webservice::update_external_service | ( | $service | ) |
Update a service It modifies the timemodified automatically.
stdClass | $service |
|
static |
Updates the last access time for a token.
stdClass | $token | Token object (must include id, lastaccess fields) |
int | $time | Time of access (0 = use current time) |
dml_exception | If database error |
webservice::update_ws_authorised_user | ( | $user | ) |
Update allowed user settings (ip restriction, valid until...)
stdClass | $user |
webservice_protocol_is_enabled | ( | $protocol | ) |
Check if a protocol is enabled.
string | $protocol | name of WS protocol ('rest', 'soap', 'xmlrpc'...) |
bool | true if the protocol is enabled |
$services |
int const webservice::TOKEN_LASTACCESS_UPDATE_SECS = 60 |
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.)