Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

MDL-30986 external API, check and update DocBlock

Conflicts:

	group/externallib.php
  • Loading branch information...
commit 4615817d1c31673ba9b3c702f7da63619e0e8ce2 1 parent aa753ac
@mouneyrac mouneyrac authored
View
87 course/externallib.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -15,12 +14,13 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
+
/**
* External course API
*
- * @package core
- * @subpackage course
- * @copyright 2010 Moodle Pty Ltd (http://moodle.com)
+ * @package core_course
+ * @category external
+ * @copyright 2009 Petr Skodak
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
@@ -29,13 +29,21 @@
require_once("$CFG->libdir/externallib.php");
/**
- * Course functions
+ * Course external functions
+ *
+ * @package core_course
+ * @category external
+ * @copyright 2011 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.2
*/
class core_course_external extends external_api {
/**
* Returns description of method parameters
+ *
* @return external_function_parameters
+ * @since Moodle 2.2
*/
public static function get_course_contents_parameters() {
return new external_function_parameters(
@@ -52,9 +60,11 @@ public static function get_course_contents_parameters() {
/**
* Get course contents
- * @param int $courseid
- * @param array $options, not used yet, might be used in later version
+ *
+ * @param int $courseid course id
+ * @param array $options These options are not used yet, might be used in later version
* @return array
+ * @since Moodle 2.2
*/
public static function get_course_contents($courseid, $options) {
global $CFG, $DB;
@@ -183,7 +193,9 @@ public static function get_course_contents($courseid, $options) {
/**
* Returns description of method result value
+ *
* @return external_description
+ * @since Moodle 2.2
*/
public static function get_course_contents_returns() {
return new external_multiple_structure(
@@ -238,7 +250,9 @@ public static function get_course_contents_returns() {
/**
* Returns description of method parameters
+ *
* @return external_function_parameters
+ * @since Moodle 2.2
*/
public static function get_courses_parameters() {
return new external_function_parameters(
@@ -255,8 +269,10 @@ public static function get_courses_parameters() {
/**
* Get courses
- * @param array $options
+ *
+ * @param array $options It contains an array (list of ids)
* @return array
+ * @since Moodle 2.2
*/
public static function get_courses($options) {
global $CFG, $DB;
@@ -336,7 +352,9 @@ public static function get_courses($options) {
/**
* Returns description of method result value
+ *
* @return external_description
+ * @since Moodle 2.2
*/
public static function get_courses_returns() {
return new external_multiple_structure(
@@ -402,7 +420,9 @@ public static function get_courses_returns() {
/**
* Returns description of method parameters
+ *
* @return external_function_parameters
+ * @since Moodle 2.2
*/
public static function create_courses_parameters() {
$courseconfig = get_config('moodlecourse'); //needed for many default values
@@ -471,8 +491,10 @@ public static function create_courses_parameters() {
/**
* Create courses
+ *
* @param array $courses
* @return array courses (id and shortname only)
+ * @since Moodle 2.2
*/
public static function create_courses($courses) {
global $CFG, $DB;
@@ -556,7 +578,9 @@ public static function create_courses($courses) {
/**
* Returns description of method result value
+ *
* @return external_description
+ * @since Moodle 2.2
*/
public static function create_courses_returns() {
return new external_multiple_structure(
@@ -572,15 +596,26 @@ public static function create_courses_returns() {
}
/**
- * Deprecated course functions
- * @deprecated since Moodle 2.2 please use core_course_external instead
+ * Deprecated course external functions
+ *
+ * @package core_course
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_course_external
*/
class moodle_course_external extends external_api {
/**
* Returns description of method parameters
- * @deprecated since Moodle 2.2 please use core_course_external::get_courses_parameters instead
+ *
* @return external_function_parameters
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_course_external::get_courses_parameters()
*/
public static function get_courses_parameters() {
return core_course_external::get_courses_parameters();
@@ -588,9 +623,13 @@ public static function get_courses_parameters() {
/**
* Get courses
+ *
* @param array $options
- * @deprecated since Moodle 2.2 please use core_course_external::get_courses instead
* @return array
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_course_external::get_courses()
*/
public static function get_courses($options) {
return core_course_external::get_courses($options);
@@ -598,8 +637,12 @@ public static function get_courses($options) {
/**
* Returns description of method result value
- * @deprecated since Moodle 2.2 please use core_course_external::get_courses_returns instead
+ *
* @return external_description
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_course_external::get_courses_returns()
*/
public static function get_courses_returns() {
return core_course_external::get_courses_returns();
@@ -607,8 +650,12 @@ public static function get_courses_returns() {
/**
* Returns description of method parameters
- * @deprecated since Moodle 2.2 please use core_course_external::create_courses_parameters instead
+ *
* @return external_function_parameters
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_course_external::create_courses_parameters()
*/
public static function create_courses_parameters() {
return core_course_external::create_courses_parameters();
@@ -616,9 +663,13 @@ public static function create_courses_parameters() {
/**
* Create courses
- * @deprecated since Moodle 2.2 please use core_course_external::create_courses instead
+ *
* @param array $courses
* @return array courses (id and shortname only)
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_course_external::create_courses()
*/
public static function create_courses($courses) {
return core_course_external::create_courses($courses);
@@ -626,8 +677,12 @@ public static function create_courses($courses) {
/**
* Returns description of method result value
- * @deprecated since Moodle 2.2 please use core_course_external::create_courses_returns instead
+ *
* @return external_description
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_course_external::create_courses_returns()
*/
public static function create_courses_returns() {
return core_course_external::create_courses_returns();
View
143 enrol/externallib.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -15,15 +14,16 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
+
/**
* External course participation api.
*
* This api is mostly read only, the actual enrol and unenrol
* support is in each enrol plugin.
*
- * @package core
- * @subpackage enrol
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
+ * @package core_enrol
+ * @category external
+ * @copyright 2010 Jerome Mouneyrac
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
@@ -32,12 +32,19 @@
require_once("$CFG->libdir/externallib.php");
/**
- * Enrol functions
+ * Enrol external functions
+ *
+ * @package core_enrol
+ * @category external
+ * @copyright 2011 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.2
*/
class core_enrol_external extends external_api {
/**
* Returns description of method parameters
+ *
* @return external_function_parameters
*/
public static function get_users_courses_parameters() {
@@ -50,7 +57,6 @@ public static function get_users_courses_parameters() {
/**
* Get list of courses user is enrolled in (only active enrolments are returned).
- *
* Please note the current user must be able to access the course, otherwise the course is not included.
*
* @param int $userid
@@ -92,6 +98,7 @@ public static function get_users_courses($userid) {
/**
* Returns description of method result value
+ *
* @return external_description
*/
public static function get_users_courses_returns() {
@@ -111,6 +118,7 @@ public static function get_users_courses_returns() {
/**
* Returns description of method parameters
+ *
* @return external_function_parameters
*/
public static function get_enrolled_users_parameters() {
@@ -136,11 +144,12 @@ public static function get_enrolled_users_parameters() {
/**
* Get course participants details
+ *
* @param int $courseid course id
* @param array $options options {
- * 'name' => option name
- * 'value' => option value
- * }
+ * 'name' => option name
+ * 'value' => option value
+ * }
* @return array An array of users
*/
public static function get_enrolled_users($courseid, $options) {
@@ -241,6 +250,7 @@ public static function get_enrolled_users($courseid, $options) {
/**
* Returns description of method result value
+ *
* @return external_description
*/
public static function get_enrolled_users_returns() {
@@ -322,12 +332,19 @@ public static function get_enrolled_users_returns() {
}
/**
- * Role functions
+ * Role external functions
+ *
+ * @package core_role
+ * @category external
+ * @copyright 2011 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.2
*/
class core_role_external extends external_api {
/**
* Returns description of method parameters
+ *
* @return external_function_parameters
*/
public static function assign_roles_parameters() {
@@ -349,8 +366,7 @@ public static function assign_roles_parameters() {
/**
* Manual role assignments to users
*
- * @param array $assignment An array of manual role assignment
- * @return null
+ * @param array $assignments An array of manual role assignment
*/
public static function assign_roles($assignments) {
global $DB;
@@ -382,7 +398,8 @@ public static function assign_roles($assignments) {
/**
* Returns description of method result value
- * @return external_description
+ *
+ * @return null
*/
public static function assign_roles_returns() {
return null;
@@ -391,6 +408,7 @@ public static function assign_roles_returns() {
/**
* Returns description of method parameters
+ *
* @return external_function_parameters
*/
public static function unassign_roles_parameters() {
@@ -412,8 +430,7 @@ public static function unassign_roles_parameters() {
/**
* Unassign roles from users
*
- * @param array $unassignment An array of unassignment
- * @return null
+ * @param array $unassignments An array of unassignment
*/
public static function unassign_roles($unassignments) {
global $DB;
@@ -444,6 +461,7 @@ public static function unassign_roles($unassignments) {
/**
* Returns description of method result value
+ *
* @return null
*/
public static function unassign_roles_returns() {
@@ -453,16 +471,28 @@ public static function unassign_roles_returns() {
/**
- * Deprecated enroll and role functions
- * @deprecated since Moodle 2.2 please use core_enrol_external or core_role_external instead
+ * Deprecated enrol and role external functions
+ *
+ * @package core_enrol
+ * @copyright 2010 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_enrol_external
+ * @see core_role_external
*/
class moodle_enrol_external extends external_api {
/**
* Returns description of method parameters
- * @deprecated since Moodle 2.2 please use core_enrol_external::get_enrolled_users_parameters() instead
+ *
* @return external_function_parameters
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_enrol_external::get_enrolled_users_parameters()
*/
public static function get_enrolled_users_parameters() {
return new external_function_parameters(
@@ -477,12 +507,16 @@ public static function get_enrolled_users_parameters() {
/**
* Get list of course participants.
- * @deprecated since Moodle 2.2 please use core_enrol_external::get_enrolled_users() instead
+ *
* @param int $courseid
* @param text $withcapability
* @param int $groupid
* @param bool $onlyactive
* @return array of course participants
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_enrol_external::get_enrolled_users()
*/
public static function get_enrolled_users($courseid, $withcapability = null, $groupid = null, $onlyactive = false) {
global $DB, $CFG, $USER;
@@ -568,8 +602,12 @@ public static function get_enrolled_users($courseid, $withcapability = null, $gr
/**
* Returns description of method result value
- * @deprecated since Moodle 2.2 please use core_enrol_external::get_enrolled_users_returns() instead
+ *
* @return external_description
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_enrol_external::get_enrolled_users_returns()
*/
public static function get_enrolled_users_returns() {
return new external_multiple_structure(
@@ -590,8 +628,12 @@ public static function get_enrolled_users_returns() {
/**
* Returns description of method parameters
- * @deprecated since Moodle 2.2 please use core_enrol_external::get_users_courses_parameters() instead
+ *
* @return external_function_parameters
+ * @since Moodle 2.1
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_enrol_external::get_users_courses_parameters()
*/
public static function get_users_courses_parameters() {
return core_enrol_external::get_users_courses_parameters();
@@ -599,11 +641,14 @@ public static function get_users_courses_parameters() {
/**
* Get list of courses user is enrolled in (only active enrolments are returned).
- *
* Please note the current user must be able to access the course, otherwise the course is not included.
- * @deprecated since Moodle 2.2 please use core_enrol_external::get_users_courses() instead
+ *
* @param int $userid
* @return array of courses
+ * @since Moodle 2.1
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see use core_enrol_external::get_users_courses()
*/
public static function get_users_courses($userid) {
return core_enrol_external::get_users_courses($userid);
@@ -611,8 +656,12 @@ public static function get_users_courses($userid) {
/**
* Returns description of method result value
- * @deprecated since Moodle 2.2 please use core_enrol_external::get_users_courses_returns() instead
+ *
* @return external_description
+ * @since Moodle 2.1
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_enrol_external::get_users_courses_returns()
*/
public static function get_users_courses_returns() {
return core_enrol_external::get_users_courses_returns();
@@ -621,8 +670,12 @@ public static function get_users_courses_returns() {
/**
* Returns description of method parameters
- * @deprecated since Moodle 2.2 please use core_role_external::assign_roles_parameters() instead
+ *
* @return external_function_parameters
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_role_external::assign_roles_parameters()
*/
public static function role_assign_parameters() {
return core_role_external::assign_roles_parameters();
@@ -630,9 +683,12 @@ public static function role_assign_parameters() {
/**
* Manual role assignments to users
- * @deprecated since Moodle 2.2 please use core_role_external::assign_roles() instead
- * @param array $assignment An array of manual role assignment
- * @return null
+ *
+ * @param array $assignments An array of manual role assignment
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_role_external::assign_roles()
*/
public static function role_assign($assignments) {
return core_role_external::assign_roles($assignments);
@@ -640,8 +696,12 @@ public static function role_assign($assignments) {
/**
* Returns description of method result value
- * @deprecated since Moodle 2.2 please use core_role_external::assign_roles_returns() instead
- * @return external_description
+ *
+ * @return null
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_role_external::assign_roles_returns()
*/
public static function role_assign_returns() {
return core_role_external::assign_roles_returns();
@@ -650,8 +710,12 @@ public static function role_assign_returns() {
/**
* Returns description of method parameters
- * @deprecated since Moodle 2.2 please use core_role_external::unassign_roles_parameters() instead
+ *
* @return external_function_parameters
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_role_external::unassign_roles_parameters()
*/
public static function role_unassign_parameters() {
return core_role_external::unassign_roles_parameters();
@@ -659,9 +723,12 @@ public static function role_unassign_parameters() {
/**
* Unassign roles from users
- * @deprecated since Moodle 2.2 please use core_role_external::unassign_roles() instead
- * @param array $unassignment An array of unassignment
- * @return null
+ *
+ * @param array $unassignments An array of unassignment
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_role_external::unassign_roles()
*/
public static function role_unassign($unassignments) {
return core_role_external::unassign_roles($unassignments);
@@ -669,8 +736,12 @@ public static function role_unassign($unassignments) {
/**
* Returns description of method result value
- * @deprecated since Moodle 2.2 please use core_role_external::unassign_roles_returns() instead
- * @return external_description
+ *
+ * @return null
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_role_external::unassign_roles_returns()
*/
public static function role_unassign_returns() {
return core_role_external::unassign_roles_returns();
View
55 enrol/manual/externallib.php
@@ -14,29 +14,39 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
+
/**
* External course participation api.
*
* This api is mostly read only, the actual enrol and unenrol
* support is in each enrol plugin.
*
- * @package enrol
- * @subpackage manual
- * @copyright 2011 Moodle Pty Ltd (http://moodle.com)
+ * @package enrol_manual
+ * @category external
+ * @copyright 2011 Jerome Mouneyrac
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
+
defined('MOODLE_INTERNAL') || die();
require_once("$CFG->libdir/externallib.php");
/**
- * Manual enrolment functions
+ * Manual enrolment external functions
+ *
+ * @package enrol_manual
+ * @category external
+ * @copyright 2011 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.2
*/
class enrol_manual_external extends external_api {
/**
* Returns description of method parameters
+ *
* @return external_function_parameters
+ * @since Moodle 2.2
*/
public static function enrol_users_parameters() {
return new external_function_parameters(
@@ -59,9 +69,10 @@ public static function enrol_users_parameters() {
/**
* Enrolment of users
+ *
* Function throw an exception at the first error encountered.
* @param array $enrolments An array of user enrolment
- * @return null
+ * @since Moodle 2.2
*/
public static function enrol_users($enrolments) {
global $DB, $CFG;
@@ -137,7 +148,9 @@ public static function enrol_users($enrolments) {
/**
* Returns description of method result value
+ *
* @return null
+ * @since Moodle 2.2
*/
public static function enrol_users_returns() {
return null;
@@ -146,15 +159,26 @@ public static function enrol_users_returns() {
}
/**
- * Deprecated manual enrolment functions
- * @deprecated since Moodle 2.2 please use enrol_manual_external instead
+ * Deprecated manual enrolment external functions
+ *
+ * @package enrol_manual
+ * @copyright 2011 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see enrol_manual_external
*/
class moodle_enrol_manual_external extends external_api {
/**
* Returns description of method parameters
- * @deprecated since Moodle 2.2 please use enrol_manual_external::enrol_users_parameters instead
+ *
* @return external_function_parameters
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see enrol_manual_external::enrol_users_parameters()
*/
public static function manual_enrol_users_parameters() {
return enrol_manual_external::enrol_users_parameters();
@@ -163,9 +187,12 @@ public static function manual_enrol_users_parameters() {
/**
* Enrolment of users
* Function throw an exception at the first error encountered.
- * @deprecated since Moodle 2.2 please use enrol_manual_external::enrol_users instead
+ *
* @param array $enrolments An array of user enrolment
- * @return null
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see enrol_manual_external::enrol_users()
*/
public static function manual_enrol_users($enrolments) {
return enrol_manual_external::enrol_users($enrolments);
@@ -173,8 +200,12 @@ public static function manual_enrol_users($enrolments) {
/**
* Returns description of method result value
- * @deprecated since Moodle 2.2 please use enrol_manual_external::enrol_users_returns instead
- * @return external_description
+ *
+ * @return nul
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see enrol_manual_external::enrol_users_returns()
*/
public static function manual_enrol_users_returns() {
return enrol_manual_external::enrol_users_returns();
View
112 files/externallib.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -15,12 +14,13 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
+
/**
* External files API
*
- * @package moodlecore
- * @subpackage webservice
- * @copyright 2010 Dongsheng Cai <dongsheng@moodle.com>
+ * @package core_files
+ * @category external
+ * @copyright 2010 Dongsheng Cai
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
@@ -28,13 +28,21 @@
require_once("$CFG->libdir/filelib.php");
/**
- * Files functions
+ * Files external functions
+ *
+ * @package core_files
+ * @category external
+ * @copyright 2011 Jerome Mouneyrac
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.2
*/
class core_files_external extends external_api {
/**
* Returns description of get_files parameters
+ *
* @return external_function_parameters
+ * @since Moodle 2.2
*/
public static function get_files_parameters() {
return new external_function_parameters(
@@ -51,13 +59,15 @@ public static function get_files_parameters() {
/**
* Return moodle files listing
- * @param int $contextid
- * @param int $component
- * @param int $filearea
- * @param int $itemid
- * @param string $filepath
- * @param string $filename
+ *
+ * @param int $contextid context id
+ * @param int $component component
+ * @param int $filearea file aera
+ * @param int $itemid item id
+ * @param string $filepath file path
+ * @param string $filename file name
* @return array
+ * @since Moodle 2.2
*/
public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename) {
global $CFG, $USER, $OUTPUT;
@@ -136,7 +146,9 @@ public static function get_files($contextid, $component, $filearea, $itemid, $fi
/**
* Returns description of get_files returns
- * @return external_multiple_structure
+ *
+ * @return external_single_structure
+ * @since Moodle 2.2
*/
public static function get_files_returns() {
return new external_single_structure(
@@ -173,7 +185,9 @@ public static function get_files_returns() {
/**
* Returns description of upload parameters
+ *
* @return external_function_parameters
+ * @since Moodle 2.2
*/
public static function upload_parameters() {
return new external_function_parameters(
@@ -192,14 +206,15 @@ public static function upload_parameters() {
/**
* Uploading a file to moodle
*
- * @param int $contextid
- * @param string $component
- * @param string $filearea
- * @param int $itemid
- * @param string $filepath
- * @param string $filename
- * @param string $filecontent
+ * @param int $contextid context id
+ * @param string $component component
+ * @param string $filearea file aera
+ * @param int $itemid item id
+ * @param string $filepath file path
+ * @param string $filename file name
+ * @param string $filecontent file content
* @return array
+ * @since Moodle 2.2
*/
public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
global $USER, $CFG;
@@ -235,7 +250,7 @@ public static function upload($contextid, $component, $filearea, $itemid, $filep
}
if (isset($fileinfo['itemid'])) {
- // TODO: in user private area, itemid is always 0
+ // TODO MDL-31116 in user private area, itemid is always 0
$itemid = 0;
} else {
throw new coding_exception('itemid cannot be empty');
@@ -250,7 +265,7 @@ public static function upload($contextid, $component, $filearea, $itemid, $filep
if (!($fileinfo['component'] == 'user' and $fileinfo['filearea'] == 'private')) {
throw new coding_exception('File can be uploaded to user private area only');
} else {
- // TODO: hard-coded to use user_private area
+ // TODO MDL-31116 hard-coded to use user_private area
$component = 'user';
$filearea = 'private';
}
@@ -283,7 +298,9 @@ public static function upload($contextid, $component, $filearea, $itemid, $filep
/**
* Returns description of upload returns
- * @return external_multiple_structure
+ *
+ * @return external_single_structure
+ * @since Moodle 2.2
*/
public static function upload_returns() {
return new external_single_structure(
@@ -301,15 +318,26 @@ public static function upload_returns() {
}
/**
- * Deprecated files functions
- * @deprecated since Moodle 2.2 please use core_files_external instead
+ * Deprecated files external functions
+ *
+ * @package core_files
+ * @copyright 2010 Dongsheng Cai
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_files_external
*/
class moodle_file_external extends external_api {
/**
* Returns description of get_files parameters
- * @deprecated since Moodle 2.2 please use core_files_external::get_files_parameters instead
+ *
* @return external_function_parameters
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_files_external::get_files_parameters()
*/
public static function get_files_parameters() {
return core_files_external::get_files_parameters();
@@ -317,7 +345,7 @@ public static function get_files_parameters() {
/**
* Return moodle files listing
- * @deprecated since Moodle 2.2 please use core_files_external::get_files instead
+ *
* @param int $contextid
* @param int $component
* @param int $filearea
@@ -325,6 +353,10 @@ public static function get_files_parameters() {
* @param string $filepath
* @param string $filename
* @return array
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_files_external::get_files()
*/
public static function get_files($contextid, $component, $filearea, $itemid, $filepath, $filename) {
return core_files_external::get_files($contextid, $component, $filearea, $itemid, $filepath, $filename);
@@ -332,8 +364,12 @@ public static function get_files($contextid, $component, $filearea, $itemid, $fi
/**
* Returns description of get_files returns
- * @deprecated since Moodle 2.2 please use core_files_external::get_files_returns instead
- * @return external_multiple_structure
+ *
+ * @return external_single_structure
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_files_external::get_files_returns()
*/
public static function get_files_returns() {
return core_files_external::get_files_returns();
@@ -341,8 +377,12 @@ public static function get_files_returns() {
/**
* Returns description of upload parameters
- * @deprecated since Moodle 2.2 please use core_files_external::upload_parameters instead
+ *
* @return external_function_parameters
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_files_external::upload_parameters()
*/
public static function upload_parameters() {
return core_files_external::upload_parameters();
@@ -350,7 +390,7 @@ public static function upload_parameters() {
/**
* Uploading a file to moodle
- * @deprecated since Moodle 2.2 please use core_files_external::upload instead
+ *
* @param int $contextid
* @param string $component
* @param string $filearea
@@ -359,6 +399,10 @@ public static function upload_parameters() {
* @param string $filename
* @param string $filecontent
* @return array
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_files_external::upload()
*/
public static function upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent) {
return core_files_external::upload($contextid, $component, $filearea, $itemid, $filepath, $filename, $filecontent);
@@ -366,8 +410,12 @@ public static function upload($contextid, $component, $filearea, $itemid, $filep
/**
* Returns description of upload returns
- * @deprecated since Moodle 2.2 please use core_files_external::upload_returns instead
- * @return external_multiple_structure
+ *
+ * @return external_single_structure
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_files_external::upload_returns()
*/
public static function upload_returns() {
return core_files_external::upload_returns();
View
223 group/externallib.php
@@ -14,28 +14,34 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
+
/**
* External groups API
*
* @package core_group
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
+ * @category external
+ * @copyright 2009 Petr Skodak
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
require_once("$CFG->libdir/externallib.php");
/**
- * Group functions
+ * Group external functions
*
* @package core_group
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
+ * @category external
+ * @copyright 2011 Jerome Mouneyrac
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.2
*/
class core_group_external extends external_api {
/**
* Returns description of method parameters
+ *
* @return external_function_parameters
+ * @since Moodle 2.2
*/
public static function create_groups_parameters() {
return new external_function_parameters(
@@ -56,8 +62,10 @@ public static function create_groups_parameters() {
/**
* Create groups
+ *
* @param array $groups array of group description arrays (with keys groupname and courseid)
* @return array of newly created groups
+ * @since Moodle 2.2
*/
public static function create_groups($groups) {
global $CFG, $DB;
@@ -104,7 +112,9 @@ public static function create_groups($groups) {
/**
* Returns description of method result value
- * @return external_multiple_structure
+ *
+ * @return external_description
+ * @since Moodle 2.2
*/
public static function create_groups_returns() {
return new external_multiple_structure(
@@ -122,7 +132,9 @@ public static function create_groups_returns() {
/**
* Returns description of method parameters
+ *
* @return external_function_parameters
+ * @since Moodle 2.2
*/
public static function get_groups_parameters() {
return new external_function_parameters(
@@ -135,8 +147,10 @@ public static function get_groups_parameters() {
/**
* Get groups definition specified by ids
+ *
* @param array $groupids arrays of group ids
* @return array of group objects (id, courseid, name, enrolmentkey)
+ * @since Moodle 2.2
*/
public static function get_groups($groupids) {
$params = self::validate_parameters(self::get_groups_parameters(), array('groupids'=>$groupids));
@@ -167,7 +181,9 @@ public static function get_groups($groupids) {
/**
* Returns description of method result value
- * @return external_multiple_structure
+ *
+ * @return external_description
+ * @since Moodle 2.2
*/
public static function get_groups_returns() {
return new external_multiple_structure(
@@ -185,7 +201,9 @@ public static function get_groups_returns() {
/**
* Returns description of method parameters
+ *
* @return external_function_parameters
+ * @since Moodle 2.2
*/
public static function get_course_groups_parameters() {
return new external_function_parameters(
@@ -197,8 +215,10 @@ public static function get_course_groups_parameters() {
/**
* Get all groups in the specified course
+ *
* @param int $courseid id of course
* @return array of group objects (id, courseid, name, enrolmentkey)
+ * @since Moodle 2.2
*/
public static function get_course_groups($courseid) {
$params = self::validate_parameters(self::get_course_groups_parameters(), array('courseid'=>$courseid));
@@ -228,7 +248,9 @@ public static function get_course_groups($courseid) {
/**
* Returns description of method result value
- * @return external_multiple_structure
+ *
+ * @return external_description
+ * @since Moodle 2.2
*/
public static function get_course_groups_returns() {
return new external_multiple_structure(
@@ -246,7 +268,9 @@ public static function get_course_groups_returns() {
/**
* Returns description of method parameters
+ *
* @return external_function_parameters
+ * @since Moodle 2.2
*/
public static function delete_groups_parameters() {
return new external_function_parameters(
@@ -258,8 +282,9 @@ public static function delete_groups_parameters() {
/**
* Delete groups
+ *
* @param array $groupids array of group ids
- * @return void
+ * @since Moodle 2.2
*/
public static function delete_groups($groupids) {
global $CFG, $DB;
@@ -298,7 +323,9 @@ public static function delete_groups($groupids) {
/**
* Returns description of method result value
- * @return external_description
+ *
+ * @return null
+ * @since Moodle 2.2
*/
public static function delete_groups_returns() {
return null;
@@ -307,7 +334,9 @@ public static function delete_groups_returns() {
/**
* Returns description of method parameters
+ *
* @return external_function_parameters
+ * @since Moodle 2.2
*/
public static function get_group_members_parameters() {
return new external_function_parameters(
@@ -319,8 +348,10 @@ public static function get_group_members_parameters() {
/**
* Return all members for a group
+ *
* @param array $groupids array of group ids
* @return array with group id keys containing arrays of user ids
+ * @since Moodle 2.2
*/
public static function get_group_members($groupids) {
$members = array();
@@ -353,7 +384,9 @@ public static function get_group_members($groupids) {
/**
* Returns description of method result value
+ *
* @return external_description
+ * @since Moodle 2.2
*/
public static function get_group_members_returns() {
return new external_multiple_structure(
@@ -369,7 +402,9 @@ public static function get_group_members_returns() {
/**
* Returns description of method parameters
+ *
* @return external_function_parameters
+ * @since Moodle 2.2
*/
public static function add_group_members_parameters() {
return new external_function_parameters(
@@ -388,7 +423,9 @@ public static function add_group_members_parameters() {
/**
* Add group members
+ *
* @param array $members of arrays with keys userid, groupid
+ * @since Moodle 2.2
*/
public static function add_group_members($members) {
global $CFG, $DB;
@@ -432,7 +469,9 @@ public static function add_group_members($members) {
/**
* Returns description of method result value
+ *
* @return null
+ * @since Moodle 2.2
*/
public static function add_group_members_returns() {
return null;
@@ -441,7 +480,9 @@ public static function add_group_members_returns() {
/**
* Returns description of method parameters
+ *
* @return external_function_parameters
+ * @since Moodle 2.2
*/
public static function delete_group_members_parameters() {
return new external_function_parameters(
@@ -460,7 +501,9 @@ public static function delete_group_members_parameters() {
/**
* Delete group members
+ *
* @param array $members of arrays with keys userid, groupid
+ * @since Moodle 2.2
*/
public static function delete_group_members($members) {
global $CFG, $DB;
@@ -499,7 +542,9 @@ public static function delete_group_members($members) {
/**
* Returns description of method result value
+ *
* @return null
+ * @since Moodle 2.2
*/
public static function delete_group_members_returns() {
return null;
@@ -508,17 +553,26 @@ public static function delete_group_members_returns() {
}
/**
- * Deprecated group functions
- * @deprecated since Moodle 2.2 please do not call this class any more.
- * @see core_group_external()
+ * Deprecated group external functions
+ *
+ * @package core_group
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external
*/
class moodle_group_external extends external_api {
/**
* Returns description of method parameters
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::create_groups_parameters()
+ *
* @return external_function_parameters
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::create_groups_parameters()
*/
public static function create_groups_parameters() {
return core_group_external::create_groups_parameters();
@@ -526,10 +580,13 @@ public static function create_groups_parameters() {
/**
* Create groups
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::create_groups()
+ *
* @param array $groups array of group description arrays (with keys groupname and courseid)
* @return array of newly created groups
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see use core_group_external::create_groups()
*/
public static function create_groups($groups) {
return core_group_external::create_groups($groups);
@@ -537,9 +594,12 @@ public static function create_groups($groups) {
/**
* Returns description of method result value
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::create_groups_returns()
+ *
* @return external_description
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::create_groups_returns()
*/
public static function create_groups_returns() {
return core_group_external::create_groups_returns();
@@ -547,9 +607,12 @@ public static function create_groups_returns() {
/**
* Returns description of method parameters
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::get_groups_parameters()
+ *
* @return external_function_parameters
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::get_groups_parameters()
*/
public static function get_groups_parameters() {
return core_group_external::get_groups_parameters();
@@ -557,10 +620,13 @@ public static function get_groups_parameters() {
/**
* Get groups definition specified by ids
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::get_groups()
+ *
* @param array $groupids arrays of group ids
* @return array of group objects (id, courseid, name, enrolmentkey)
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::get_groups()
*/
public static function get_groups($groupids) {
return core_group_external::get_groups($groupids);
@@ -568,9 +634,12 @@ public static function get_groups($groupids) {
/**
* Returns description of method result value
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::get_groups_returns()
+ *
* @return external_description
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::get_groups_returns()
*/
public static function get_groups_returns() {
return core_group_external::get_groups_returns();
@@ -578,9 +647,12 @@ public static function get_groups_returns() {
/**
* Returns description of method parameters
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::get_course_groups_parameters()
+ *
* @return external_function_parameters
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::get_course_groups_parameters()
*/
public static function get_course_groups_parameters() {
return core_group_external::get_course_groups_parameters();
@@ -588,10 +660,13 @@ public static function get_course_groups_parameters() {
/**
* Get all groups in the specified course
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::get_course_groups()
+ *
* @param int $courseid id of course
* @return array of group objects (id, courseid, name, enrolmentkey)
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::get_course_groups()
*/
public static function get_course_groups($courseid) {
return core_group_external::get_course_groups($courseid);
@@ -599,9 +674,12 @@ public static function get_course_groups($courseid) {
/**
* Returns description of method result value
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::get_course_groups_returns()
+ *
* @return external_description
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::get_course_groups_returns()
*/
public static function get_course_groups_returns() {
return core_group_external::get_course_groups_returns();
@@ -609,9 +687,12 @@ public static function get_course_groups_returns() {
/**
* Returns description of method parameters
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::delete_group_members_parameters()
+ *
* @return external_function_parameters
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::delete_group_members_parameters()
*/
public static function delete_groups_parameters() {
return core_group_external::delete_group_members_parameters();
@@ -619,10 +700,12 @@ public static function delete_groups_parameters() {
/**
* Delete groups
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::delete_groups()
+ *
* @param array $groupids array of group ids
- * @return void
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::delete_groups()
*/
public static function delete_groups($groupids) {
return core_group_external::delete_groups($groupids);
@@ -630,9 +713,12 @@ public static function delete_groups($groupids) {
/**
* Returns description of method result value
- * @deprecated since Moodle 2.2 please do not call this function any more.
+ *
+ * @return null
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
* @see core_group_external::delete_group_members_returns()
- * @return external_description
*/
public static function delete_groups_returns() {
return core_group_external::delete_group_members_returns();
@@ -641,9 +727,12 @@ public static function delete_groups_returns() {
/**
* Returns description of method parameters
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::get_group_members_parameters()
+ *
* @return external_function_parameters
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::get_group_members_parameters()
*/
public static function get_groupmembers_parameters() {
return core_group_external::get_group_members_parameters();
@@ -651,10 +740,13 @@ public static function get_groupmembers_parameters() {
/**
* Return all members for a group
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::get_group_members()
+ *
* @param array $groupids array of group ids
* @return array with group id keys containing arrays of user ids
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::get_group_members()
*/
public static function get_groupmembers($groupids) {
return core_group_external::get_group_members($groupids);
@@ -662,9 +754,12 @@ public static function get_groupmembers($groupids) {
/**
* Returns description of method result value
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::get_group_members_returns()
+ *
* @return external_description
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::get_group_members_returns()
*/
public static function get_groupmembers_returns() {
return core_group_external::get_group_members_returns();
@@ -673,9 +768,12 @@ public static function get_groupmembers_returns() {
/**
* Returns description of method parameters
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::add_group_members_parameters()
+ *
* @return external_function_parameters
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::add_group_members_parameters()
*/
public static function add_groupmembers_parameters() {
return core_group_external::add_group_members_parameters();
@@ -683,10 +781,12 @@ public static function add_groupmembers_parameters() {
/**
* Add group members
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::add_group_members()
+ *
* @param array $members of arrays with keys userid, groupid
- * @return void
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see use core_group_external::add_group_members()
*/
public static function add_groupmembers($members) {
return core_group_external::add_group_members($members);
@@ -694,9 +794,12 @@ public static function add_groupmembers($members) {
/**
* Returns description of method result value
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::add_group_members_returns()
+ *
* @return external_description
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::add_group_members_returns()
*/
public static function add_groupmembers_returns() {
return core_group_external::add_group_members_returns();
@@ -705,9 +808,12 @@ public static function add_groupmembers_returns() {
/**
* Returns description of method parameters
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::delete_group_members_parameters()
+ *
* @return external_function_parameters
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::delete_group_members_parameters()
*/
public static function delete_groupmembers_parameters() {
return core_group_external::delete_group_members_parameters();
@@ -715,10 +821,12 @@ public static function delete_groupmembers_parameters() {
/**
* Delete group members
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::delete_group_members()
+ *
* @param array $members of arrays with keys userid, groupid
- * @return void
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::delete_group_members()
*/
public static function delete_groupmembers($members) {
return core_group_external::delete_group_members($members);
@@ -726,9 +834,12 @@ public static function delete_groupmembers($members) {
/**
* Returns description of method result value
- * @deprecated since Moodle 2.2 please do not call this function any more.
- * @see core_group_external::delete_group_members_returns()
+ *
* @return external_description
+ * @since Moodle 2.0
+ * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
+ * @todo MDL-31194 This will be deleted in Moodle 2.5.
+ * @see core_group_external::delete_group_members_returns()
*/
public static function delete_groupmembers_returns() {
return core_group_external::delete_group_members_returns();
View
118 lib/externallib.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -15,12 +14,12 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
+
/**
* Support for external API
*
- * @package core
- * @subpackage webservice
- * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
+ * @package core_webservice
+ * @copyright 2009 Petr Skodak
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
@@ -28,10 +27,12 @@
/**
* Returns detailed function information
+ *
* @param string|object $function name of external function or record from external_function
* @param int $strictness IGNORE_MISSING means compatible mode, false returned if record not found, debug message if more found;
* MUST_EXIST means throw exception if no record or multiple records found
- * @return object description or false if not found or exception thrown
+ * @return stdClass description or false if not found or exception thrown
+ * @since Moodle 2.0
*/
function external_function_info($function, $strictness=MUST_EXIST) {
global $DB, $CFG;
@@ -77,7 +78,7 @@ function external_function_info($function, $strictness=MUST_EXIST) {
}
//now get the function description
- //TODO: use localised lang pack descriptions, it would be nice to have
+ //TODO MDL-31115 use localised lang pack descriptions, it would be nice to have
// easy to understand descriptions in admin UI,
// on the other hand this is still a bit in a flux and we need to find some new naming
// conventions for these descriptions in lang packs
@@ -98,12 +99,18 @@ function external_function_info($function, $strictness=MUST_EXIST) {
}
/**
- * Exception indicating user is not allowed to use external function in
- * the current context.
+ * Exception indicating user is not allowed to use external function in the current context.
+ *
+ * @package core_webservice
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
*/
class restricted_context_exception extends moodle_exception {
/**
* Constructor
+ *
+ * @since Moodle 2.0
*/
function __construct() {
parent::__construct('restrictedcontextexception', 'error');
@@ -112,14 +119,22 @@ function __construct() {
/**
* Base class for external api methods.
+ *
+ * @package core_webservice
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
*/
class external_api {
+
+ /** @var stdClass context where the function calls will be restricted */
private static $contextrestriction;
/**
* Set context restriction for all following subsequent function calls.
- * @param stdClass $contex
- * @return void
+ *
+ * @param stdClass $context the context restriction
+ * @since Moodle 2.0
*/
public static function set_context_restriction($context) {
self::$contextrestriction = $context;
@@ -130,7 +145,7 @@ public static function set_context_restriction($context) {
* that takes a longer time to finish!
*
* @param int $seconds max expected time the next operation needs
- * @return void
+ * @since Moodle 2.0
*/
public static function set_timeout($seconds=360) {
$seconds = ($seconds < 300) ? 300 : $seconds;
@@ -142,9 +157,11 @@ public static function set_timeout($seconds=360) {
* invalid_parameter_exception is thrown.
* This is a simple recursive method which is intended to be called from
* each implementation method of external API.
+ *
* @param external_description $description description of parameters
* @param mixed $params the actual parameters
* @return mixed params with added defaults for optional items, invalid_parameters_exception thrown if any problem found
+ * @since Moodle 2.0
*/
public static function validate_parameters(external_description $description, $params) {
if ($description instanceof external_value) {
@@ -220,9 +237,12 @@ public static function validate_parameters(external_description $description, $p
* If a response attribute is incorrect, invalid_response_exception is thrown.
* Note: this function is similar to validate parameters, however it is distinct because
* parameters validation must be distinct from cleaning return values.
+ *
* @param external_description $description description of the return values
* @param mixed $response the actual response
* @return mixed response with added defaults for optional items, invalid_response_exception thrown if any problem found
+ * @author 2010 Jerome Mouneyrac
+ * @since Moodle 2.0
*/
public static function clean_returnvalue(external_description $description, $response) {
if ($description instanceof external_value) {
@@ -297,8 +317,9 @@ public static function clean_returnvalue(external_description $description, $res
/**
* Makes sure user may execute functions in this context.
- * @param object $context
- * @return void
+ *
+ * @param stdClass $context
+ * @since Moodle 2.0
*/
protected static function validate_context($context) {
global $CFG;
@@ -333,20 +354,29 @@ protected static function validate_context($context) {
/**
* Common ancestor of all parameter description classes
+ *
+ * @package core_webservice
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
*/
abstract class external_description {
- /** @var string $description description of element */
+ /** @var string Description of element */
public $desc;
- /** @var bool $required element value required, null not allowed */
+
+ /** @var bool Element value required, null not allowed */
public $required;
- /** @var mixed $default default value */
+
+ /** @var mixed Default value */
public $default;
/**
* Contructor
+ *
* @param string $desc
* @param bool $required
* @param mixed $default
+ * @since Moodle 2.0
*/
public function __construct($desc, $required, $default) {
$this->desc = $desc;
@@ -356,21 +386,30 @@ public function __construct($desc, $required, $default) {
}
/**
- * Scalar alue description class
+ * Scalar value description class
+ *
+ * @package core_webservice
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
*/
class external_value extends external_description {
- /** @var mixed $type value type PARAM_XX */
+
+ /** @var mixed Value type PARAM_XX */
public $type;
- /** @var bool $allownull allow null values */
+
+ /** @var bool Allow null values */
public $allownull;
/**
* Constructor
+ *
* @param mixed $type
* @param string $desc
* @param bool $required
* @param mixed $default
* @param bool $allownull
+ * @since Moodle 2.0
*/
public function __construct($type, $desc='', $required=VALUE_REQUIRED,
$default=null, $allownull=NULL_ALLOWED) {
@@ -382,17 +421,25 @@ public function __construct($type, $desc='', $required=VALUE_REQUIRED,
/**
* Associative array description class
+ *
+ * @package core_webservice
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
*/
class external_single_structure extends external_description {
- /** @var array $keys description of array keys key=>external_description */
+
+ /** @var array Description of array keys key=>external_description */
public $keys;
/**
* Constructor
+ *
* @param array $keys
* @param string $desc
* @param bool $required
* @param array $default
+ * @since Moodle 2.0
*/
public function __construct(array $keys, $desc='',
$required=VALUE_REQUIRED, $default=null) {
@@ -403,17 +450,25 @@ public function __construct(array $keys, $desc='',
/**
* Bulk array description class.
+ *
+ * @package core_webservice
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
*/
class external_multiple_structure extends external_description {
- /** @var external_description $content */
+
+ /** @var external_description content */
public $content;
/**
* Constructor
+ *
* @param external_description $content
* @param string $desc
* @param bool $required
* @param array $default
+ * @since Moodle 2.0
*/
public function __construct(external_description $content, $desc='',
$required=VALUE_REQUIRED, $default=null) {
@@ -424,12 +479,28 @@ public function __construct(external_description $content, $desc='',
/**
* Description of top level - PHP function parameters.
- * @author skodak
*
+ * @package core_webservice
+ * @copyright 2009 Petr Skodak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
*/
class external_function_parameters extends external_single_structure {
}
+/**
+ * Generate a token
+ *
+ * @param string $tokentype EXTERNAL_TOKEN_EMBEDDED|EXTERNAL_TOKEN_PERMANENT
+ * @param stdClass|int $serviceorid service linked to the token
+ * @param int $userid user linked to the token
+ * @param stdClass|int $contextorid
+ * @param int $validuntil date when the token expired
+ * @param string $iprestriction allowed ip - if 0 or empty then all ips are allowed
+ * @return string generated token