MDL-32662 Added get_groupings method
[moodle.git] / group / externallib.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
18 /**
19  * External groups API
20  *
21  * @package    core_group
22  * @category   external
23  * @copyright  2009 Petr Skodak
24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25  */
27 require_once("$CFG->libdir/externallib.php");
29 /**
30  * Group external functions
31  *
32  * @package    core_group
33  * @category   external
34  * @copyright  2011 Jerome Mouneyrac
35  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36  * @since Moodle 2.2
37  */
38 class core_group_external extends external_api {
40     /**
41      * Returns description of method parameters
42      *
43      * @return external_function_parameters
44      * @since Moodle 2.2
45      */
46     public static function create_groups_parameters() {
47         return new external_function_parameters(
48             array(
49                 'groups' => new external_multiple_structure(
50                     new external_single_structure(
51                         array(
52                             'courseid' => new external_value(PARAM_INT, 'id of course'),
53                             'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
54                             'description' => new external_value(PARAM_RAW, 'group description text'),
55                             'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
56                         )
57                     ), 'List of group object. A group has a courseid, a name, a description and an enrolment key.'
58                 )
59             )
60         );
61     }
63     /**
64      * Create groups
65      *
66      * @param array $groups array of group description arrays (with keys groupname and courseid)
67      * @return array of newly created groups
68      * @since Moodle 2.2
69      */
70     public static function create_groups($groups) {
71         global $CFG, $DB;
72         require_once("$CFG->dirroot/group/lib.php");
74         $params = self::validate_parameters(self::create_groups_parameters(), array('groups'=>$groups));
76         $transaction = $DB->start_delegated_transaction();
78         $groups = array();
80         foreach ($params['groups'] as $group) {
81             $group = (object)$group;
83             if (trim($group->name) == '') {
84                 throw new invalid_parameter_exception('Invalid group name');
85             }
86             if ($DB->get_record('groups', array('courseid'=>$group->courseid, 'name'=>$group->name))) {
87                 throw new invalid_parameter_exception('Group with the same name already exists in the course');
88             }
90             // now security checks
91             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
92             try {
93                 self::validate_context($context);
94             } catch (Exception $e) {
95                 $exceptionparam = new stdClass();
96                 $exceptionparam->message = $e->getMessage();
97                 $exceptionparam->courseid = $group->courseid;
98                 throw new moodle_exception(
99                         get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
100             }
101             require_capability('moodle/course:managegroups', $context);
103             // finally create the group
104             $group->id = groups_create_group($group, false);
105             $groups[] = (array)$group;
106         }
108         $transaction->allow_commit();
110         return $groups;
111     }
113     /**
114      * Returns description of method result value
115      *
116      * @return external_description
117      * @since Moodle 2.2
118      */
119     public static function create_groups_returns() {
120         return new external_multiple_structure(
121             new external_single_structure(
122                 array(
123                     'id' => new external_value(PARAM_INT, 'group record id'),
124                     'courseid' => new external_value(PARAM_INT, 'id of course'),
125                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
126                     'description' => new external_value(PARAM_RAW, 'group description text'),
127                     'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
128                 )
129             ), 'List of group object. A group has an id, a courseid, a name, a description and an enrolment key.'
130         );
131     }
133     /**
134      * Returns description of method parameters
135      *
136      * @return external_function_parameters
137      * @since Moodle 2.2
138      */
139     public static function get_groups_parameters() {
140         return new external_function_parameters(
141             array(
142                 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')
143                         ,'List of group id. A group id is an integer.'),
144             )
145         );
146     }
148     /**
149      * Get groups definition specified by ids
150      *
151      * @param array $groupids arrays of group ids
152      * @return array of group objects (id, courseid, name, enrolmentkey)
153      * @since Moodle 2.2
154      */
155     public static function get_groups($groupids) {
156         $params = self::validate_parameters(self::get_groups_parameters(), array('groupids'=>$groupids));
158         $groups = array();
159         foreach ($params['groupids'] as $groupid) {
160             // validate params
161             $group = groups_get_group($groupid, 'id, courseid, name, description, enrolmentkey', MUST_EXIST);
163             // now security checks
164             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
165             try {
166                 self::validate_context($context);
167             } catch (Exception $e) {
168                 $exceptionparam = new stdClass();
169                 $exceptionparam->message = $e->getMessage();
170                 $exceptionparam->courseid = $group->courseid;
171                 throw new moodle_exception(
172                         get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
173             }
174             require_capability('moodle/course:managegroups', $context);
176             $groups[] = (array)$group;
177         }
179         return $groups;
180     }
182     /**
183      * Returns description of method result value
184      *
185      * @return external_description
186      * @since Moodle 2.2
187      */
188     public static function get_groups_returns() {
189         return new external_multiple_structure(
190             new external_single_structure(
191                 array(
192                     'id' => new external_value(PARAM_INT, 'group record id'),
193                     'courseid' => new external_value(PARAM_INT, 'id of course'),
194                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
195                     'description' => new external_value(PARAM_RAW, 'group description text'),
196                     'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
197                 )
198             )
199         );
200     }
202     /**
203      * Returns description of method parameters
204      *
205      * @return external_function_parameters
206      * @since Moodle 2.2
207      */
208     public static function get_course_groups_parameters() {
209         return new external_function_parameters(
210             array(
211                 'courseid' => new external_value(PARAM_INT, 'id of course'),
212             )
213         );
214     }
216     /**
217      * Get all groups in the specified course
218      *
219      * @param int $courseid id of course
220      * @return array of group objects (id, courseid, name, enrolmentkey)
221      * @since Moodle 2.2
222      */
223     public static function get_course_groups($courseid) {
224         $params = self::validate_parameters(self::get_course_groups_parameters(), array('courseid'=>$courseid));
226         // now security checks
227         $context = get_context_instance(CONTEXT_COURSE, $params['courseid']);
228         try {
229             self::validate_context($context);
230         } catch (Exception $e) {
231                 $exceptionparam = new stdClass();
232                 $exceptionparam->message = $e->getMessage();
233                 $exceptionparam->courseid = $params['courseid'];
234                 throw new moodle_exception(
235                         get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
236         }
237         require_capability('moodle/course:managegroups', $context);
239         $gs = groups_get_all_groups($params['courseid'], 0, 0, 'g.id, g.courseid, g.name, g.description, g.enrolmentkey');
241         $groups = array();
242         foreach ($gs as $group) {
243             $groups[] = (array)$group;
244         }
246         return $groups;
247     }
249     /**
250      * Returns description of method result value
251      *
252      * @return external_description
253      * @since Moodle 2.2
254      */
255     public static function get_course_groups_returns() {
256         return new external_multiple_structure(
257             new external_single_structure(
258                 array(
259                     'id' => new external_value(PARAM_INT, 'group record id'),
260                     'courseid' => new external_value(PARAM_INT, 'id of course'),
261                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
262                     'description' => new external_value(PARAM_RAW, 'group description text'),
263                     'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
264                 )
265             )
266         );
267     }
269     /**
270      * Returns description of method parameters
271      *
272      * @return external_function_parameters
273      * @since Moodle 2.2
274      */
275     public static function delete_groups_parameters() {
276         return new external_function_parameters(
277             array(
278                 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')),
279             )
280         );
281     }
283     /**
284      * Delete groups
285      *
286      * @param array $groupids array of group ids
287      * @since Moodle 2.2
288      */
289     public static function delete_groups($groupids) {
290         global $CFG, $DB;
291         require_once("$CFG->dirroot/group/lib.php");
293         $params = self::validate_parameters(self::delete_groups_parameters(), array('groupids'=>$groupids));
295         $transaction = $DB->start_delegated_transaction();
297         foreach ($params['groupids'] as $groupid) {
298             // validate params
299             $groupid = validate_param($groupid, PARAM_INTEGER);
300             if (!$group = groups_get_group($groupid, 'id, courseid', IGNORE_MISSING)) {
301                 // silently ignore attempts to delete nonexisting groups
302                 continue;
303             }
305             // now security checks
306             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
307             try {
308                 self::validate_context($context);
309             } catch (Exception $e) {
310                 $exceptionparam = new stdClass();
311                 $exceptionparam->message = $e->getMessage();
312                 $exceptionparam->courseid = $group->courseid;
313                 throw new moodle_exception(
314                         get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
315             }
316             require_capability('moodle/course:managegroups', $context);
318             groups_delete_group($group);
319         }
321         $transaction->allow_commit();
322     }
324     /**
325      * Returns description of method result value
326      *
327      * @return null
328      * @since Moodle 2.2
329      */
330     public static function delete_groups_returns() {
331         return null;
332     }
335     /**
336      * Returns description of method parameters
337      *
338      * @return external_function_parameters
339      * @since Moodle 2.2
340      */
341     public static function get_group_members_parameters() {
342         return new external_function_parameters(
343             array(
344                 'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')),
345             )
346         );
347     }
349     /**
350      * Return all members for a group
351      *
352      * @param array $groupids array of group ids
353      * @return array with  group id keys containing arrays of user ids
354      * @since Moodle 2.2
355      */
356     public static function get_group_members($groupids) {
357         $members = array();
359         $params = self::validate_parameters(self::get_group_members_parameters(), array('groupids'=>$groupids));
361         foreach ($params['groupids'] as $groupid) {
362             // validate params
363             $group = groups_get_group($groupid, 'id, courseid, name, enrolmentkey', MUST_EXIST);
364             // now security checks
365             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
366             try {
367                 self::validate_context($context);
368             } catch (Exception $e) {
369                 $exceptionparam = new stdClass();
370                 $exceptionparam->message = $e->getMessage();
371                 $exceptionparam->courseid = $group->courseid;
372                 throw new moodle_exception(
373                         get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
374             }
375             require_capability('moodle/course:managegroups', $context);
377             $groupmembers = groups_get_members($group->id, 'u.id', 'lastname ASC, firstname ASC');
379             $members[] = array('groupid'=>$groupid, 'userids'=>array_keys($groupmembers));
380         }
382         return $members;
383     }
385     /**
386      * Returns description of method result value
387      *
388      * @return external_description
389      * @since Moodle 2.2
390      */
391     public static function get_group_members_returns() {
392         return new external_multiple_structure(
393             new external_single_structure(
394                 array(
395                     'groupid' => new external_value(PARAM_INT, 'group record id'),
396                     'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user id')),
397                 )
398             )
399         );
400     }
403     /**
404      * Returns description of method parameters
405      *
406      * @return external_function_parameters
407      * @since Moodle 2.2
408      */
409     public static function add_group_members_parameters() {
410         return new external_function_parameters(
411             array(
412                 'members'=> new external_multiple_structure(
413                     new external_single_structure(
414                         array(
415                             'groupid' => new external_value(PARAM_INT, 'group record id'),
416                             'userid' => new external_value(PARAM_INT, 'user id'),
417                         )
418                     )
419                 )
420             )
421         );
422     }
424     /**
425      * Add group members
426      *
427      * @param array $members of arrays with keys userid, groupid
428      * @since Moodle 2.2
429      */
430     public static function add_group_members($members) {
431         global $CFG, $DB;
432         require_once("$CFG->dirroot/group/lib.php");
434         $params = self::validate_parameters(self::add_group_members_parameters(), array('members'=>$members));
436         $transaction = $DB->start_delegated_transaction();
437         foreach ($params['members'] as $member) {
438             // validate params
439             $groupid = $member['groupid'];
440             $userid = $member['userid'];
442             $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
443             $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
445             // now security checks
446             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
447             try {
448                 self::validate_context($context);
449             } catch (Exception $e) {
450                 $exceptionparam = new stdClass();
451                 $exceptionparam->message = $e->getMessage();
452                 $exceptionparam->courseid = $group->courseid;
453                 throw new moodle_exception(
454                         get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
455             }
456             require_capability('moodle/course:managegroups', $context);
458             // now make sure user is enrolled in course - this is mandatory requirement,
459             // unfortunately this is slow
460             if (!is_enrolled($context, $userid)) {
461                 throw new invalid_parameter_exception('Only enrolled users may be members of groups');
462             }
464             groups_add_member($group, $user);
465         }
467         $transaction->allow_commit();
468     }
470     /**
471      * Returns description of method result value
472      *
473      * @return null
474      * @since Moodle 2.2
475      */
476     public static function add_group_members_returns() {
477         return null;
478     }
481     /**
482      * Returns description of method parameters
483      *
484      * @return external_function_parameters
485      * @since Moodle 2.2
486      */
487     public static function delete_group_members_parameters() {
488         return new external_function_parameters(
489             array(
490                 'members'=> new external_multiple_structure(
491                     new external_single_structure(
492                         array(
493                             'groupid' => new external_value(PARAM_INT, 'group record id'),
494                             'userid' => new external_value(PARAM_INT, 'user id'),
495                         )
496                     )
497                 )
498             )
499         );
500     }
502     /**
503      * Delete group members
504      *
505      * @param array $members of arrays with keys userid, groupid
506      * @since Moodle 2.2
507      */
508     public static function delete_group_members($members) {
509         global $CFG, $DB;
510         require_once("$CFG->dirroot/group/lib.php");
512         $params = self::validate_parameters(self::delete_group_members_parameters(), array('members'=>$members));
514         $transaction = $DB->start_delegated_transaction();
516         foreach ($params['members'] as $member) {
517             // validate params
518             $groupid = $member['groupid'];
519             $userid = $member['userid'];
521             $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
522             $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
524             // now security checks
525             $context = get_context_instance(CONTEXT_COURSE, $group->courseid);
526             try {
527                 self::validate_context($context);
528             } catch (Exception $e) {
529                 $exceptionparam = new stdClass();
530                 $exceptionparam->message = $e->getMessage();
531                 $exceptionparam->courseid = $group->courseid;
532                 throw new moodle_exception(
533                         get_string('errorcoursecontextnotvalid' , 'webservice', $exceptionparam));
534             }
535             require_capability('moodle/course:managegroups', $context);
537             groups_remove_member($group, $user);
538         }
540         $transaction->allow_commit();
541     }
543     /**
544      * Returns description of method result value
545      *
546      * @return null
547      * @since Moodle 2.2
548      */
549     public static function delete_group_members_returns() {
550         return null;
551     }
553     /**
554      * Returns description of method parameters
555      * @return external_function_parameters
556      */
557     public static function create_groupings_parameters() {
558         return new external_function_parameters(
559             array(
560                 'groupings' => new external_multiple_structure(
561                     new external_single_structure(
562                         array(
563                             'courseid' => new external_value(PARAM_INT, 'id of course'),
564                             'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
565                             'description' => new external_value(PARAM_RAW, 'grouping description text')
566                         )
567                     ), 'List of grouping object. A grouping has a courseid, a name and a description.'
568                 )
569             )
570         );
571     }
573     /**
574      * Create groupings
575      * @param array $groupings array of grouping description arrays (with keys groupname and courseid)
576      * @return array of newly created groupings
577      */
578     public static function create_groupings($groupings) {
579         global $CFG, $DB;
580         require_once("$CFG->dirroot/group/lib.php");
582         $params = self::validate_parameters(self::create_groupings_parameters(), array('groupings'=>$groupings));
584         $transaction = $DB->start_delegated_transaction();
586         $groupings = array();
588         foreach ($params['groupings'] as $grouping) {
589             $grouping = (object)$grouping;
591             if (trim($grouping->name) == '') {
592                 throw new invalid_parameter_exception('Invalid grouping name');
593             }
594             if ($DB->get_record('groupings', array('courseid'=>$grouping->courseid, 'name'=>$grouping->name))) {
595                 throw new invalid_parameter_exception('Grouping with the same name already exists in the course');
596             }
598             // Now security checks            .
599             $context = context_course::instance($grouping->courseid);
600             try {
601                 self::validate_context($context);
602             } catch (Exception $e) {
603                 $exceptionparam = new stdClass();
604                 $exceptionparam->message = $e->getMessage();
605                 $exceptionparam->courseid = $grouping->courseid;
606                 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
607             }
608             require_capability('moodle/course:managegroups', $context);
610             // We must force allways FORMAT_HTML.
611             $grouping->descriptionformat = FORMAT_HTML;
613             // Finally create the grouping.
614             $grouping->id = groups_create_grouping($grouping);
615             $groupings[] = (array)$grouping;
616         }
618         $transaction->allow_commit();
620         return $groupings;
621     }
623     /**
624      * Returns description of method result value
625      * @return external_description
626      */
627     public static function create_groupings_returns() {
628         return new external_multiple_structure(
629             new external_single_structure(
630                 array(
631                     'id' => new external_value(PARAM_INT, 'grouping record id'),
632                     'courseid' => new external_value(PARAM_INT, 'id of course'),
633                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
634                     'description' => new external_value(PARAM_CLEANHTML, 'grouping description text')
635                 )
636             ), 'List of grouping object. A grouping has an id, a courseid, a name and a description.'
637         );
638     }
640     /**
641      * Returns description of method parameters
642      * @return external_function_parameters
643      */
644     public static function update_groupings_parameters() {
645         return new external_function_parameters(
646             array(
647                 'groupings' => new external_multiple_structure(
648                     new external_single_structure(
649                         array(
650                             'id' => new external_value(PARAM_INT, 'id of grouping'),
651                             'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
652                             'description' => new external_value(PARAM_RAW, 'grouping description text')
653                         )
654                     ), 'List of grouping object. A grouping has a courseid, a name and a description.'
655                 )
656             )
657         );
658     }
660     /**
661      * Update groupings
662      * @param array $groupings array of grouping description arrays (with keys groupname and courseid)
663      * @return array of newly updated groupings
664      */
665     public static function update_groupings($groupings) {
666         global $CFG, $DB;
667         require_once("$CFG->dirroot/group/lib.php");
669         $params = self::validate_parameters(self::update_groupings_parameters(), array('groupings'=>$groupings));
671         $transaction = $DB->start_delegated_transaction();
673         $groupings = array();
675         foreach ($params['groupings'] as $grouping) {
676             $grouping = (object)$grouping;
678             if (trim($grouping->name) == '') {
679                 throw new invalid_parameter_exception('Invalid grouping name');
680             }
682             if (! $currentgrouping = $DB->get_record('groupings', array('id'=>$grouping->id))) {
683                 throw new invalid_parameter_exception("Grouping $grouping->id does not exist in the course");
684             }
685             $grouping->courseid = $currentgrouping->courseid;
687             // Now security checks.
688             $context = context_course::instance($grouping->courseid);
689             try {
690                 self::validate_context($context);
691             } catch (Exception $e) {
692                 $exceptionparam = new stdClass();
693                 $exceptionparam->message = $e->getMessage();
694                 $exceptionparam->courseid = $grouping->courseid;
695                 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
696             }
697             require_capability('moodle/course:managegroups', $context);
699             // We must force allways FORMAT_HTML.
700             $grouping->descriptionformat = FORMAT_HTML;
702             // Finally update the grouping.
703             groups_update_grouping($grouping);
704             $groupings[] = (array)$grouping;
705         }
707         $transaction->allow_commit();
709         return $groupings;
710     }
712    /**
713      * Returns description of method result value
714      * @return external_description
715      */
716     public static function update_groupings_returns() {
717         return new external_multiple_structure(
718             new external_single_structure(
719                 array(
720                     'id' => new external_value(PARAM_INT, 'grouping record id'),
721                     'courseid' => new external_value(PARAM_INT, 'id of course'),
722                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
723                     'description' => new external_value(PARAM_CLEANHTML, 'grouping description text')
724                 )
725             ), 'List of grouping object. A grouping has an id, a courseid, a name and a description.'
726         );
727     }
729     /**
730      * Returns description of method parameters
731      * @return external_function_parameters
732      */
733     public static function get_groupings_parameters() {
734         return new external_function_parameters(
735             array(
736                 'groupingids' => new external_multiple_structure(new external_value(PARAM_INT, 'grouping ID')
737                         ,'List of grouping id. A grouping id is an integer.'),
738             )
739         );
740     }
742     /**
743      * Get groupings definition specified by ids
744      * @param array $groupingids arrays of grouping ids
745      * @return array of grouping objects (id, courseid, name)
746      */
747     public static function get_groupings($groupingids) {
748         global $CFG;
749         require_once("$CFG->dirroot/group/lib.php");
751         $params = self::validate_parameters(self::get_groupings_parameters(), array('groupingids'=>$groupingids));
753         $groupings = array();
754         foreach ($params['groupingids'] as $groupingid) {
755             // Validate params.
756             $grouping = groups_get_grouping($groupingid, '*', MUST_EXIST);
758             // Now security checks.
759             $context = context_course::instance($grouping->courseid);
760             try {
761                 self::validate_context($context);
762             } catch (Exception $e) {
763                 $exceptionparam = new stdClass();
764                 $exceptionparam->message = $e->getMessage();
765                 $exceptionparam->courseid = $grouping->courseid;
766                 throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
767             }
768             require_capability('moodle/course:managegroups', $context);
770             $grouping->description = file_rewrite_pluginfile_urls($grouping->description, 'webservice/pluginfile.php', $context->id, 'grouping', 'description', $grouping->id);
772             $options = new stdClass;
773             $options->noclean = true;
774             $options->para = false;
775             $grouping->description = format_text($grouping->description, FORMAT_HTML, $options);
777             $groupings[] = (array)$grouping;
778         }
780         return $groupings;
781     }
783    /**
784      * Returns description of method result value
785      * @return external_description
786      */
787     public static function get_groupings_returns() {
788         return new external_multiple_structure(
789             new external_single_structure(
790                 array(
791                     'id' => new external_value(PARAM_INT, 'grouping record id'),
792                     'courseid' => new external_value(PARAM_INT, 'id of course'),
793                     'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
794                     'description' => new external_value(PARAM_CLEANHTML, 'grouping description text')
795                 )
796             )
797         );
798     }
802 /**
803  * Deprecated group external functions
804  *
805  * @package    core_group
806  * @copyright  2009 Petr Skodak
807  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
808  * @since Moodle 2.0
809  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
810  * @todo MDL-31194 This will be deleted in Moodle 2.5.
811  * @see core_group_external
812  */
813 class moodle_group_external extends external_api {
815     /**
816      * Returns description of method parameters
817      *
818      * @return external_function_parameters
819      * @since Moodle 2.0
820      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
821      * @todo MDL-31194 This will be deleted in Moodle 2.5.
822      * @see core_group_external::create_groups_parameters()
823      */
824     public static function create_groups_parameters() {
825         return core_group_external::create_groups_parameters();
826     }
828     /**
829      * Create groups
830      *
831      * @param array $groups array of group description arrays (with keys groupname and courseid)
832      * @return array of newly created groups
833      * @since Moodle 2.0
834      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
835      * @todo MDL-31194 This will be deleted in Moodle 2.5.
836      * @see use core_group_external::create_groups()
837      */
838     public static function create_groups($groups) {
839         return core_group_external::create_groups($groups);
840     }
842     /**
843      * Returns description of method result value
844      *
845      * @return external_description
846      * @since Moodle 2.0
847      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
848      * @todo MDL-31194 This will be deleted in Moodle 2.5.
849      * @see core_group_external::create_groups_returns()
850      */
851     public static function create_groups_returns() {
852         return core_group_external::create_groups_returns();
853     }
855     /**
856      * Returns description of method parameters
857      *
858      * @return external_function_parameters
859      * @since Moodle 2.0
860      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
861      * @todo MDL-31194 This will be deleted in Moodle 2.5.
862      * @see core_group_external::get_groups_parameters()
863      */
864     public static function get_groups_parameters() {
865         return core_group_external::get_groups_parameters();
866     }
868     /**
869      * Get groups definition specified by ids
870      *
871      * @param array $groupids arrays of group ids
872      * @return array of group objects (id, courseid, name, enrolmentkey)
873      * @since Moodle 2.0
874      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
875      * @todo MDL-31194 This will be deleted in Moodle 2.5.
876      * @see core_group_external::get_groups()
877      */
878     public static function get_groups($groupids) {
879         return core_group_external::get_groups($groupids);
880     }
882     /**
883      * Returns description of method result value
884      *
885      * @return external_description
886      * @since Moodle 2.0
887      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
888      * @todo MDL-31194 This will be deleted in Moodle 2.5.
889      * @see core_group_external::get_groups_returns()
890      */
891     public static function get_groups_returns() {
892         return core_group_external::get_groups_returns();
893     }
895     /**
896      * Returns description of method parameters
897      *
898      * @return external_function_parameters
899      * @since Moodle 2.0
900      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
901      * @todo MDL-31194 This will be deleted in Moodle 2.5.
902      * @see core_group_external::get_course_groups_parameters()
903      */
904     public static function get_course_groups_parameters() {
905         return core_group_external::get_course_groups_parameters();
906     }
908     /**
909      * Get all groups in the specified course
910      *
911      * @param int $courseid id of course
912      * @return array of group objects (id, courseid, name, enrolmentkey)
913      * @since Moodle 2.0
914      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
915      * @todo MDL-31194 This will be deleted in Moodle 2.5.
916      * @see core_group_external::get_course_groups()
917      */
918     public static function get_course_groups($courseid) {
919         return core_group_external::get_course_groups($courseid);
920     }
922     /**
923      * Returns description of method result value
924      *
925      * @return external_description
926      * @since Moodle 2.0
927      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
928      * @todo MDL-31194 This will be deleted in Moodle 2.5.
929      * @see core_group_external::get_course_groups_returns()
930      */
931     public static function get_course_groups_returns() {
932         return core_group_external::get_course_groups_returns();
933     }
935     /**
936      * Returns description of method parameters
937      *
938      * @return external_function_parameters
939      * @since Moodle 2.0
940      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
941      * @todo MDL-31194 This will be deleted in Moodle 2.5.
942      * @see core_group_external::delete_group_members_parameters()
943      */
944     public static function delete_groups_parameters() {
945         return core_group_external::delete_group_members_parameters();
946     }
948     /**
949      * Delete groups
950      *
951      * @param array $groupids array of group ids
952      * @since Moodle 2.0
953      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
954      * @todo MDL-31194 This will be deleted in Moodle 2.5.
955      * @see core_group_external::delete_groups()
956      */
957     public static function delete_groups($groupids) {
958         return core_group_external::delete_groups($groupids);
959     }
961     /**
962      * Returns description of method result value
963      *
964      * @return null
965      * @since Moodle 2.0
966      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
967      * @todo MDL-31194 This will be deleted in Moodle 2.5.
968      * @see core_group_external::delete_group_members_returns()
969      */
970     public static function delete_groups_returns() {
971         return core_group_external::delete_group_members_returns();
972     }
975     /**
976      * Returns description of method parameters
977      *
978      * @return external_function_parameters
979      * @since Moodle 2.0
980      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
981      * @todo MDL-31194 This will be deleted in Moodle 2.5.
982      * @see core_group_external::get_group_members_parameters()
983      */
984     public static function get_groupmembers_parameters() {
985         return core_group_external::get_group_members_parameters();
986     }
988     /**
989      * Return all members for a group
990      *
991      * @param array $groupids array of group ids
992      * @return array with  group id keys containing arrays of user ids
993      * @since Moodle 2.0
994      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
995      * @todo MDL-31194 This will be deleted in Moodle 2.5.
996      * @see core_group_external::get_group_members()
997      */
998     public static function get_groupmembers($groupids) {
999         return core_group_external::get_group_members($groupids);
1000     }
1002     /**
1003      * Returns description of method result value
1004      *
1005      * @return external_description
1006      * @since Moodle 2.0
1007      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1008      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1009      * @see core_group_external::get_group_members_returns()
1010      */
1011     public static function get_groupmembers_returns() {
1012         return core_group_external::get_group_members_returns();
1013     }
1016     /**
1017      * Returns description of method parameters
1018      *
1019      * @return external_function_parameters
1020      * @since Moodle 2.0
1021      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1022      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1023      * @see core_group_external::add_group_members_parameters()
1024      */
1025     public static function add_groupmembers_parameters() {
1026         return core_group_external::add_group_members_parameters();
1027     }
1029     /**
1030      * Add group members
1031      *
1032      * @param array $members of arrays with keys userid, groupid
1033      * @since Moodle 2.0
1034      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1035      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1036      * @see use core_group_external::add_group_members()
1037      */
1038     public static function add_groupmembers($members) {
1039         return core_group_external::add_group_members($members);
1040     }
1042     /**
1043      * Returns description of method result value
1044      *
1045      * @return external_description
1046      * @since Moodle 2.0
1047      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1048      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1049      * @see core_group_external::add_group_members_returns()
1050      */
1051     public static function add_groupmembers_returns() {
1052         return core_group_external::add_group_members_returns();
1053     }
1056     /**
1057      * Returns description of method parameters
1058      *
1059      * @return external_function_parameters
1060      * @since Moodle 2.0
1061      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1062      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1063      * @see core_group_external::delete_group_members_parameters()
1064      */
1065     public static function delete_groupmembers_parameters() {
1066         return core_group_external::delete_group_members_parameters();
1067     }
1069     /**
1070      * Delete group members
1071      *
1072      * @param array $members of arrays with keys userid, groupid
1073      * @since Moodle 2.0
1074      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1075      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1076      * @see core_group_external::delete_group_members()
1077      */
1078     public static function delete_groupmembers($members) {
1079         return core_group_external::delete_group_members($members);
1080     }
1082     /**
1083      * Returns description of method result value
1084      *
1085      * @return external_description
1086      * @since Moodle 2.0
1087      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1088      * @todo MDL-31194 This will be deleted in Moodle 2.5.
1089      * @see core_group_external::delete_group_members_returns()
1090      */
1091     public static function delete_groupmembers_returns() {
1092         return core_group_external::delete_group_members_returns();
1093     }