source: moodle/trunk/fuentes/group/externallib.php @ 1331

Last change on this file since 1331 was 1331, checked in by jrpelegrina, 3 years ago

Updated to moodle 3.0.3

File size: 65.3 KB
Line 
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/>.
16
17
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 */
26
27require_once("$CFG->libdir/externallib.php");
28
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 */
38class core_group_external extends external_api {
39
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                            'descriptionformat' => new external_format_value('description', VALUE_DEFAULT),
56                            'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase', VALUE_OPTIONAL),
57                            'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL)
58                        )
59                    ), 'List of group object. A group has a courseid, a name, a description and an enrolment key.'
60                )
61            )
62        );
63    }
64
65    /**
66     * Create groups
67     *
68     * @param array $groups array of group description arrays (with keys groupname and courseid)
69     * @return array of newly created groups
70     * @since Moodle 2.2
71     */
72    public static function create_groups($groups) {
73        global $CFG, $DB;
74        require_once("$CFG->dirroot/group/lib.php");
75
76        $params = self::validate_parameters(self::create_groups_parameters(), array('groups'=>$groups));
77
78        $transaction = $DB->start_delegated_transaction();
79
80        $groups = array();
81
82        foreach ($params['groups'] as $group) {
83            $group = (object)$group;
84
85            if (trim($group->name) == '') {
86                throw new invalid_parameter_exception('Invalid group name');
87            }
88            if ($DB->get_record('groups', array('courseid'=>$group->courseid, 'name'=>$group->name))) {
89                throw new invalid_parameter_exception('Group with the same name already exists in the course');
90            }
91            if (!empty($group->idnumber) && $DB->count_records('groups', array('idnumber' => $group->idnumber))) {
92                throw new invalid_parameter_exception('Group with the same idnumber already exists');
93            }
94
95            // now security checks
96            $context = context_course::instance($group->courseid, IGNORE_MISSING);
97            try {
98                self::validate_context($context);
99            } catch (Exception $e) {
100                $exceptionparam = new stdClass();
101                $exceptionparam->message = $e->getMessage();
102                $exceptionparam->courseid = $group->courseid;
103                throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
104            }
105            require_capability('moodle/course:managegroups', $context);
106
107            // Validate format.
108            $group->descriptionformat = external_validate_format($group->descriptionformat);
109
110            // finally create the group
111            $group->id = groups_create_group($group, false);
112            if (!isset($group->enrolmentkey)) {
113                $group->enrolmentkey = '';
114            }
115            if (!isset($group->idnumber)) {
116                $group->idnumber = '';
117            }
118
119            $groups[] = (array)$group;
120        }
121
122        $transaction->allow_commit();
123
124        return $groups;
125    }
126
127    /**
128     * Returns description of method result value
129     *
130     * @return external_description
131     * @since Moodle 2.2
132     */
133    public static function create_groups_returns() {
134        return new external_multiple_structure(
135            new external_single_structure(
136                array(
137                    'id' => new external_value(PARAM_INT, 'group record id'),
138                    'courseid' => new external_value(PARAM_INT, 'id of course'),
139                    'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
140                    'description' => new external_value(PARAM_RAW, 'group description text'),
141                    'descriptionformat' => new external_format_value('description'),
142                    'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
143                    'idnumber' => new external_value(PARAM_RAW, 'id number')
144                )
145            ), 'List of group object. A group has an id, a courseid, a name, a description and an enrolment key.'
146        );
147    }
148
149    /**
150     * Returns description of method parameters
151     *
152     * @return external_function_parameters
153     * @since Moodle 2.2
154     */
155    public static function get_groups_parameters() {
156        return new external_function_parameters(
157            array(
158                'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')
159                        ,'List of group id. A group id is an integer.'),
160            )
161        );
162    }
163
164    /**
165     * Get groups definition specified by ids
166     *
167     * @param array $groupids arrays of group ids
168     * @return array of group objects (id, courseid, name, enrolmentkey)
169     * @since Moodle 2.2
170     */
171    public static function get_groups($groupids) {
172        $params = self::validate_parameters(self::get_groups_parameters(), array('groupids'=>$groupids));
173
174        $groups = array();
175        foreach ($params['groupids'] as $groupid) {
176            // validate params
177            $group = groups_get_group($groupid, 'id, courseid, name, idnumber, description, descriptionformat, enrolmentkey', MUST_EXIST);
178
179            // now security checks
180            $context = context_course::instance($group->courseid, IGNORE_MISSING);
181            try {
182                self::validate_context($context);
183            } catch (Exception $e) {
184                $exceptionparam = new stdClass();
185                $exceptionparam->message = $e->getMessage();
186                $exceptionparam->courseid = $group->courseid;
187                throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
188            }
189            require_capability('moodle/course:managegroups', $context);
190
191            list($group->description, $group->descriptionformat) =
192                external_format_text($group->description, $group->descriptionformat,
193                        $context->id, 'group', 'description', $group->id);
194
195            $groups[] = (array)$group;
196        }
197
198        return $groups;
199    }
200
201    /**
202     * Returns description of method result value
203     *
204     * @return external_description
205     * @since Moodle 2.2
206     */
207    public static function get_groups_returns() {
208        return new external_multiple_structure(
209            new external_single_structure(
210                array(
211                    'id' => new external_value(PARAM_INT, 'group record id'),
212                    'courseid' => new external_value(PARAM_INT, 'id of course'),
213                    'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
214                    'description' => new external_value(PARAM_RAW, 'group description text'),
215                    'descriptionformat' => new external_format_value('description'),
216                    'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
217                    'idnumber' => new external_value(PARAM_RAW, 'id number')
218                )
219            )
220        );
221    }
222
223    /**
224     * Returns description of method parameters
225     *
226     * @return external_function_parameters
227     * @since Moodle 2.2
228     */
229    public static function get_course_groups_parameters() {
230        return new external_function_parameters(
231            array(
232                'courseid' => new external_value(PARAM_INT, 'id of course'),
233            )
234        );
235    }
236
237    /**
238     * Get all groups in the specified course
239     *
240     * @param int $courseid id of course
241     * @return array of group objects (id, courseid, name, enrolmentkey)
242     * @since Moodle 2.2
243     */
244    public static function get_course_groups($courseid) {
245        $params = self::validate_parameters(self::get_course_groups_parameters(), array('courseid'=>$courseid));
246
247        // now security checks
248        $context = context_course::instance($params['courseid'], IGNORE_MISSING);
249        try {
250            self::validate_context($context);
251        } catch (Exception $e) {
252                $exceptionparam = new stdClass();
253                $exceptionparam->message = $e->getMessage();
254                $exceptionparam->courseid = $params['courseid'];
255                throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
256        }
257        require_capability('moodle/course:managegroups', $context);
258
259        $gs = groups_get_all_groups($params['courseid'], 0, 0,
260            'g.id, g.courseid, g.name, g.idnumber, g.description, g.descriptionformat, g.enrolmentkey');
261
262        $groups = array();
263        foreach ($gs as $group) {
264            list($group->description, $group->descriptionformat) =
265                external_format_text($group->description, $group->descriptionformat,
266                        $context->id, 'group', 'description', $group->id);
267            $groups[] = (array)$group;
268        }
269
270        return $groups;
271    }
272
273    /**
274     * Returns description of method result value
275     *
276     * @return external_description
277     * @since Moodle 2.2
278     */
279    public static function get_course_groups_returns() {
280        return new external_multiple_structure(
281            new external_single_structure(
282                array(
283                    'id' => new external_value(PARAM_INT, 'group record id'),
284                    'courseid' => new external_value(PARAM_INT, 'id of course'),
285                    'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
286                    'description' => new external_value(PARAM_RAW, 'group description text'),
287                    'descriptionformat' => new external_format_value('description'),
288                    'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
289                    'idnumber' => new external_value(PARAM_RAW, 'id number')
290                )
291            )
292        );
293    }
294
295    /**
296     * Returns description of method parameters
297     *
298     * @return external_function_parameters
299     * @since Moodle 2.2
300     */
301    public static function delete_groups_parameters() {
302        return new external_function_parameters(
303            array(
304                'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')),
305            )
306        );
307    }
308
309    /**
310     * Delete groups
311     *
312     * @param array $groupids array of group ids
313     * @since Moodle 2.2
314     */
315    public static function delete_groups($groupids) {
316        global $CFG, $DB;
317        require_once("$CFG->dirroot/group/lib.php");
318
319        $params = self::validate_parameters(self::delete_groups_parameters(), array('groupids'=>$groupids));
320
321        $transaction = $DB->start_delegated_transaction();
322
323        foreach ($params['groupids'] as $groupid) {
324            // validate params
325            $groupid = validate_param($groupid, PARAM_INT);
326            if (!$group = groups_get_group($groupid, '*', IGNORE_MISSING)) {
327                // silently ignore attempts to delete nonexisting groups
328                continue;
329            }
330
331            // now security checks
332            $context = context_course::instance($group->courseid, IGNORE_MISSING);
333            try {
334                self::validate_context($context);
335            } catch (Exception $e) {
336                $exceptionparam = new stdClass();
337                $exceptionparam->message = $e->getMessage();
338                $exceptionparam->courseid = $group->courseid;
339                throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
340            }
341            require_capability('moodle/course:managegroups', $context);
342
343            groups_delete_group($group);
344        }
345
346        $transaction->allow_commit();
347    }
348
349    /**
350     * Returns description of method result value
351     *
352     * @return null
353     * @since Moodle 2.2
354     */
355    public static function delete_groups_returns() {
356        return null;
357    }
358
359
360    /**
361     * Returns description of method parameters
362     *
363     * @return external_function_parameters
364     * @since Moodle 2.2
365     */
366    public static function get_group_members_parameters() {
367        return new external_function_parameters(
368            array(
369                'groupids' => new external_multiple_structure(new external_value(PARAM_INT, 'Group ID')),
370            )
371        );
372    }
373
374    /**
375     * Return all members for a group
376     *
377     * @param array $groupids array of group ids
378     * @return array with  group id keys containing arrays of user ids
379     * @since Moodle 2.2
380     */
381    public static function get_group_members($groupids) {
382        $members = array();
383
384        $params = self::validate_parameters(self::get_group_members_parameters(), array('groupids'=>$groupids));
385
386        foreach ($params['groupids'] as $groupid) {
387            // validate params
388            $group = groups_get_group($groupid, 'id, courseid, name, enrolmentkey', MUST_EXIST);
389            // now security checks
390            $context = context_course::instance($group->courseid, IGNORE_MISSING);
391            try {
392                self::validate_context($context);
393            } catch (Exception $e) {
394                $exceptionparam = new stdClass();
395                $exceptionparam->message = $e->getMessage();
396                $exceptionparam->courseid = $group->courseid;
397                throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
398            }
399            require_capability('moodle/course:managegroups', $context);
400
401            $groupmembers = groups_get_members($group->id, 'u.id', 'lastname ASC, firstname ASC');
402
403            $members[] = array('groupid'=>$groupid, 'userids'=>array_keys($groupmembers));
404        }
405
406        return $members;
407    }
408
409    /**
410     * Returns description of method result value
411     *
412     * @return external_description
413     * @since Moodle 2.2
414     */
415    public static function get_group_members_returns() {
416        return new external_multiple_structure(
417            new external_single_structure(
418                array(
419                    'groupid' => new external_value(PARAM_INT, 'group record id'),
420                    'userids' => new external_multiple_structure(new external_value(PARAM_INT, 'user id')),
421                )
422            )
423        );
424    }
425
426
427    /**
428     * Returns description of method parameters
429     *
430     * @return external_function_parameters
431     * @since Moodle 2.2
432     */
433    public static function add_group_members_parameters() {
434        return new external_function_parameters(
435            array(
436                'members'=> new external_multiple_structure(
437                    new external_single_structure(
438                        array(
439                            'groupid' => new external_value(PARAM_INT, 'group record id'),
440                            'userid' => new external_value(PARAM_INT, 'user id'),
441                        )
442                    )
443                )
444            )
445        );
446    }
447
448    /**
449     * Add group members
450     *
451     * @param array $members of arrays with keys userid, groupid
452     * @since Moodle 2.2
453     */
454    public static function add_group_members($members) {
455        global $CFG, $DB;
456        require_once("$CFG->dirroot/group/lib.php");
457
458        $params = self::validate_parameters(self::add_group_members_parameters(), array('members'=>$members));
459
460        $transaction = $DB->start_delegated_transaction();
461        foreach ($params['members'] as $member) {
462            // validate params
463            $groupid = $member['groupid'];
464            $userid = $member['userid'];
465
466            $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
467            $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
468
469            // now security checks
470            $context = context_course::instance($group->courseid, IGNORE_MISSING);
471            try {
472                self::validate_context($context);
473            } catch (Exception $e) {
474                $exceptionparam = new stdClass();
475                $exceptionparam->message = $e->getMessage();
476                $exceptionparam->courseid = $group->courseid;
477                throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
478            }
479            require_capability('moodle/course:managegroups', $context);
480
481            // now make sure user is enrolled in course - this is mandatory requirement,
482            // unfortunately this is slow
483            if (!is_enrolled($context, $userid)) {
484                throw new invalid_parameter_exception('Only enrolled users may be members of groups');
485            }
486
487            groups_add_member($group, $user);
488        }
489
490        $transaction->allow_commit();
491    }
492
493    /**
494     * Returns description of method result value
495     *
496     * @return null
497     * @since Moodle 2.2
498     */
499    public static function add_group_members_returns() {
500        return null;
501    }
502
503
504    /**
505     * Returns description of method parameters
506     *
507     * @return external_function_parameters
508     * @since Moodle 2.2
509     */
510    public static function delete_group_members_parameters() {
511        return new external_function_parameters(
512            array(
513                'members'=> new external_multiple_structure(
514                    new external_single_structure(
515                        array(
516                            'groupid' => new external_value(PARAM_INT, 'group record id'),
517                            'userid' => new external_value(PARAM_INT, 'user id'),
518                        )
519                    )
520                )
521            )
522        );
523    }
524
525    /**
526     * Delete group members
527     *
528     * @param array $members of arrays with keys userid, groupid
529     * @since Moodle 2.2
530     */
531    public static function delete_group_members($members) {
532        global $CFG, $DB;
533        require_once("$CFG->dirroot/group/lib.php");
534
535        $params = self::validate_parameters(self::delete_group_members_parameters(), array('members'=>$members));
536
537        $transaction = $DB->start_delegated_transaction();
538
539        foreach ($params['members'] as $member) {
540            // validate params
541            $groupid = $member['groupid'];
542            $userid = $member['userid'];
543
544            $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
545            $user = $DB->get_record('user', array('id'=>$userid, 'deleted'=>0, 'mnethostid'=>$CFG->mnet_localhost_id), '*', MUST_EXIST);
546
547            // now security checks
548            $context = context_course::instance($group->courseid, IGNORE_MISSING);
549            try {
550                self::validate_context($context);
551            } catch (Exception $e) {
552                $exceptionparam = new stdClass();
553                $exceptionparam->message = $e->getMessage();
554                $exceptionparam->courseid = $group->courseid;
555                throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
556            }
557            require_capability('moodle/course:managegroups', $context);
558
559            if (!groups_remove_member_allowed($group, $user)) {
560                throw new moodle_exception('errorremovenotpermitted', 'group', '', fullname($user));
561            }
562            groups_remove_member($group, $user);
563        }
564
565        $transaction->allow_commit();
566    }
567
568    /**
569     * Returns description of method result value
570     *
571     * @return null
572     * @since Moodle 2.2
573     */
574    public static function delete_group_members_returns() {
575        return null;
576    }
577
578    /**
579     * Returns description of method parameters
580     *
581     * @return external_function_parameters
582     * @since Moodle 2.3
583     */
584    public static function create_groupings_parameters() {
585        return new external_function_parameters(
586            array(
587                'groupings' => new external_multiple_structure(
588                    new external_single_structure(
589                        array(
590                            'courseid' => new external_value(PARAM_INT, 'id of course'),
591                            'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
592                            'description' => new external_value(PARAM_RAW, 'grouping description text'),
593                            'descriptionformat' => new external_format_value('description', VALUE_DEFAULT),
594                            'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL)
595                        )
596                    ), 'List of grouping object. A grouping has a courseid, a name and a description.'
597                )
598            )
599        );
600    }
601
602    /**
603     * Create groupings
604     *
605     * @param array $groupings array of grouping description arrays (with keys groupname and courseid)
606     * @return array of newly created groupings
607     * @since Moodle 2.3
608     */
609    public static function create_groupings($groupings) {
610        global $CFG, $DB;
611        require_once("$CFG->dirroot/group/lib.php");
612
613        $params = self::validate_parameters(self::create_groupings_parameters(), array('groupings'=>$groupings));
614
615        $transaction = $DB->start_delegated_transaction();
616
617        $groupings = array();
618
619        foreach ($params['groupings'] as $grouping) {
620            $grouping = (object)$grouping;
621
622            if (trim($grouping->name) == '') {
623                throw new invalid_parameter_exception('Invalid grouping name');
624            }
625            if ($DB->count_records('groupings', array('courseid'=>$grouping->courseid, 'name'=>$grouping->name))) {
626                throw new invalid_parameter_exception('Grouping with the same name already exists in the course');
627            }
628            if (!empty($grouping->idnumber) && $DB->count_records('groupings', array('idnumber' => $grouping->idnumber))) {
629                throw new invalid_parameter_exception('Grouping with the same idnumber already exists');
630            }
631
632            // Now security checks            .
633            $context = context_course::instance($grouping->courseid);
634            try {
635                self::validate_context($context);
636            } catch (Exception $e) {
637                $exceptionparam = new stdClass();
638                $exceptionparam->message = $e->getMessage();
639                $exceptionparam->courseid = $grouping->courseid;
640                throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
641            }
642            require_capability('moodle/course:managegroups', $context);
643
644            $grouping->descriptionformat = external_validate_format($grouping->descriptionformat);
645
646            // Finally create the grouping.
647            $grouping->id = groups_create_grouping($grouping);
648            $groupings[] = (array)$grouping;
649        }
650
651        $transaction->allow_commit();
652
653        return $groupings;
654    }
655
656    /**
657     * Returns description of method result value
658     *
659     * @return external_description
660     * @since Moodle 2.3
661     */
662    public static function create_groupings_returns() {
663        return new external_multiple_structure(
664            new external_single_structure(
665                array(
666                    'id' => new external_value(PARAM_INT, 'grouping record id'),
667                    'courseid' => new external_value(PARAM_INT, 'id of course'),
668                    'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
669                    'description' => new external_value(PARAM_RAW, 'grouping description text'),
670                    'descriptionformat' => new external_format_value('description'),
671                    'idnumber' => new external_value(PARAM_RAW, 'id number')
672                )
673            ), 'List of grouping object. A grouping has an id, a courseid, a name and a description.'
674        );
675    }
676
677    /**
678     * Returns description of method parameters
679     *
680     * @return external_function_parameters
681     * @since Moodle 2.3
682     */
683    public static function update_groupings_parameters() {
684        return new external_function_parameters(
685            array(
686                'groupings' => new external_multiple_structure(
687                    new external_single_structure(
688                        array(
689                            'id' => new external_value(PARAM_INT, 'id of grouping'),
690                            'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
691                            'description' => new external_value(PARAM_RAW, 'grouping description text'),
692                            'descriptionformat' => new external_format_value('description', VALUE_DEFAULT),
693                            'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL)
694                        )
695                    ), 'List of grouping object. A grouping has a courseid, a name and a description.'
696                )
697            )
698        );
699    }
700
701    /**
702     * Update groupings
703     *
704     * @param array $groupings array of grouping description arrays (with keys groupname and courseid)
705     * @return array of newly updated groupings
706     * @since Moodle 2.3
707     */
708    public static function update_groupings($groupings) {
709        global $CFG, $DB;
710        require_once("$CFG->dirroot/group/lib.php");
711
712        $params = self::validate_parameters(self::update_groupings_parameters(), array('groupings'=>$groupings));
713
714        $transaction = $DB->start_delegated_transaction();
715
716        foreach ($params['groupings'] as $grouping) {
717            $grouping = (object)$grouping;
718
719            if (trim($grouping->name) == '') {
720                throw new invalid_parameter_exception('Invalid grouping name');
721            }
722
723            if (! $currentgrouping = $DB->get_record('groupings', array('id'=>$grouping->id))) {
724                throw new invalid_parameter_exception("Grouping $grouping->id does not exist in the course");
725            }
726
727            // Check if the new modified grouping name already exists in the course.
728            if ($grouping->name != $currentgrouping->name and
729                    $DB->count_records('groupings', array('courseid'=>$currentgrouping->courseid, 'name'=>$grouping->name))) {
730                throw new invalid_parameter_exception('A different grouping with the same name already exists in the course');
731            }
732            // Check if the new modified grouping idnumber already exists.
733            if (!empty($grouping->idnumber) && $grouping->idnumber != $currentgrouping->idnumber &&
734                    $DB->count_records('groupings', array('idnumber' => $grouping->idnumber))) {
735                throw new invalid_parameter_exception('A different grouping with the same idnumber already exists');
736            }
737
738            $grouping->courseid = $currentgrouping->courseid;
739
740            // Now security checks.
741            $context = context_course::instance($grouping->courseid);
742            try {
743                self::validate_context($context);
744            } catch (Exception $e) {
745                $exceptionparam = new stdClass();
746                $exceptionparam->message = $e->getMessage();
747                $exceptionparam->courseid = $grouping->courseid;
748                throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
749            }
750            require_capability('moodle/course:managegroups', $context);
751
752            // We must force allways FORMAT_HTML.
753            $grouping->descriptionformat = external_validate_format($grouping->descriptionformat);
754
755            // Finally update the grouping.
756            groups_update_grouping($grouping);
757        }
758
759        $transaction->allow_commit();
760
761        return null;
762    }
763
764    /**
765     * Returns description of method result value
766     *
767     * @return external_description
768     * @since Moodle 2.3
769     */
770    public static function update_groupings_returns() {
771        return null;
772    }
773
774    /**
775     * Returns description of method parameters
776     *
777     * @return external_function_parameters
778     * @since Moodle 2.3
779     */
780    public static function get_groupings_parameters() {
781        return new external_function_parameters(
782            array(
783                'groupingids' => new external_multiple_structure(new external_value(PARAM_INT, 'grouping ID')
784                        , 'List of grouping id. A grouping id is an integer.'),
785                'returngroups' => new external_value(PARAM_BOOL, 'return associated groups', VALUE_DEFAULT, 0)
786            )
787        );
788    }
789
790    /**
791     * Get groupings definition specified by ids
792     *
793     * @param array $groupingids arrays of grouping ids
794     * @param boolean $returngroups return the associated groups if true. The default is false.
795     * @return array of grouping objects (id, courseid, name)
796     * @since Moodle 2.3
797     */
798    public static function get_groupings($groupingids, $returngroups = false) {
799        global $CFG, $DB;
800        require_once("$CFG->dirroot/group/lib.php");
801        require_once("$CFG->libdir/filelib.php");
802
803        $params = self::validate_parameters(self::get_groupings_parameters(),
804                                            array('groupingids' => $groupingids,
805                                                  'returngroups' => $returngroups));
806
807        $groupings = array();
808        foreach ($params['groupingids'] as $groupingid) {
809            // Validate params.
810            $grouping = groups_get_grouping($groupingid, '*', MUST_EXIST);
811
812            // Now security checks.
813            $context = context_course::instance($grouping->courseid);
814            try {
815                self::validate_context($context);
816            } catch (Exception $e) {
817                $exceptionparam = new stdClass();
818                $exceptionparam->message = $e->getMessage();
819                $exceptionparam->courseid = $grouping->courseid;
820                throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
821            }
822            require_capability('moodle/course:managegroups', $context);
823
824            list($grouping->description, $grouping->descriptionformat) =
825                external_format_text($grouping->description, $grouping->descriptionformat,
826                        $context->id, 'grouping', 'description', $grouping->id);
827
828            $groupingarray = (array)$grouping;
829
830            if ($params['returngroups']) {
831                $grouprecords = $DB->get_records_sql("SELECT * FROM {groups} g INNER JOIN {groupings_groups} gg ".
832                                               "ON g.id = gg.groupid WHERE gg.groupingid = ? ".
833                                               "ORDER BY groupid", array($groupingid));
834                if ($grouprecords) {
835                    $groups = array();
836                    foreach ($grouprecords as $grouprecord) {
837                        list($grouprecord->description, $grouprecord->descriptionformat) =
838                        external_format_text($grouprecord->description, $grouprecord->descriptionformat,
839                        $context->id, 'group', 'description', $grouprecord->groupid);
840                        $groups[] = array('id' => $grouprecord->groupid,
841                                          'name' => $grouprecord->name,
842                                          'idnumber' => $grouprecord->idnumber,
843                                          'description' => $grouprecord->description,
844                                          'descriptionformat' => $grouprecord->descriptionformat,
845                                          'enrolmentkey' => $grouprecord->enrolmentkey,
846                                          'courseid' => $grouprecord->courseid
847                                          );
848                    }
849                    $groupingarray['groups'] = $groups;
850                }
851            }
852            $groupings[] = $groupingarray;
853        }
854
855        return $groupings;
856    }
857
858    /**
859     * Returns description of method result value
860     *
861     * @return external_description
862     * @since Moodle 2.3
863     */
864    public static function get_groupings_returns() {
865        return new external_multiple_structure(
866            new external_single_structure(
867                array(
868                    'id' => new external_value(PARAM_INT, 'grouping record id'),
869                    'courseid' => new external_value(PARAM_INT, 'id of course'),
870                    'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
871                    'description' => new external_value(PARAM_RAW, 'grouping description text'),
872                    'descriptionformat' => new external_format_value('description'),
873                    'idnumber' => new external_value(PARAM_RAW, 'id number'),
874                    'groups' => new external_multiple_structure(
875                        new external_single_structure(
876                            array(
877                                'id' => new external_value(PARAM_INT, 'group record id'),
878                                'courseid' => new external_value(PARAM_INT, 'id of course'),
879                                'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
880                                'description' => new external_value(PARAM_RAW, 'group description text'),
881                                'descriptionformat' => new external_format_value('description'),
882                                'enrolmentkey' => new external_value(PARAM_RAW, 'group enrol secret phrase'),
883                                'idnumber' => new external_value(PARAM_RAW, 'id number')
884                            )
885                        ),
886                    'optional groups', VALUE_OPTIONAL)
887                )
888            )
889        );
890    }
891
892    /**
893     * Returns description of method parameters
894     *
895     * @return external_function_parameters
896     * @since Moodle 2.3
897     */
898    public static function get_course_groupings_parameters() {
899        return new external_function_parameters(
900            array(
901                'courseid' => new external_value(PARAM_INT, 'id of course'),
902            )
903        );
904    }
905
906    /**
907     * Get all groupings in the specified course
908     *
909     * @param int $courseid id of course
910     * @return array of grouping objects (id, courseid, name, enrolmentkey)
911     * @since Moodle 2.3
912     */
913    public static function get_course_groupings($courseid) {
914        global $CFG;
915        require_once("$CFG->dirroot/group/lib.php");
916        require_once("$CFG->libdir/filelib.php");
917
918        $params = self::validate_parameters(self::get_course_groupings_parameters(), array('courseid'=>$courseid));
919
920        // Now security checks.
921        $context = context_course::instance($params['courseid']);
922
923        try {
924            self::validate_context($context);
925        } catch (Exception $e) {
926                $exceptionparam = new stdClass();
927                $exceptionparam->message = $e->getMessage();
928                $exceptionparam->courseid = $params['courseid'];
929                throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
930        }
931        require_capability('moodle/course:managegroups', $context);
932
933        $gs = groups_get_all_groupings($params['courseid']);
934
935        $groupings = array();
936        foreach ($gs as $grouping) {
937            list($grouping->description, $grouping->descriptionformat) =
938                external_format_text($grouping->description, $grouping->descriptionformat,
939                        $context->id, 'grouping', 'description', $grouping->id);
940            $groupings[] = (array)$grouping;
941        }
942
943        return $groupings;
944    }
945
946    /**
947     * Returns description of method result value
948     *
949     * @return external_description
950     * @since Moodle 2.3
951     */
952    public static function get_course_groupings_returns() {
953        return new external_multiple_structure(
954            new external_single_structure(
955                array(
956                    'id' => new external_value(PARAM_INT, 'grouping record id'),
957                    'courseid' => new external_value(PARAM_INT, 'id of course'),
958                    'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
959                    'description' => new external_value(PARAM_RAW, 'grouping description text'),
960                    'descriptionformat' => new external_format_value('description'),
961                    'idnumber' => new external_value(PARAM_RAW, 'id number')
962                )
963            )
964        );
965    }
966
967    /**
968     * Returns description of method parameters
969     *
970     * @return external_function_parameters
971     * @since Moodle 2.3
972     */
973    public static function delete_groupings_parameters() {
974        return new external_function_parameters(
975            array(
976                'groupingids' => new external_multiple_structure(new external_value(PARAM_INT, 'grouping ID')),
977            )
978        );
979    }
980
981    /**
982     * Delete groupings
983     *
984     * @param array $groupingids array of grouping ids
985     * @return void
986     * @since Moodle 2.3
987     */
988    public static function delete_groupings($groupingids) {
989        global $CFG, $DB;
990        require_once("$CFG->dirroot/group/lib.php");
991
992        $params = self::validate_parameters(self::delete_groupings_parameters(), array('groupingids'=>$groupingids));
993
994        $transaction = $DB->start_delegated_transaction();
995
996        foreach ($params['groupingids'] as $groupingid) {
997
998            if (!$grouping = groups_get_grouping($groupingid, 'id, courseid', IGNORE_MISSING)) {
999                // Silently ignore attempts to delete nonexisting groupings.
1000                continue;
1001            }
1002
1003            // Now security checks.
1004            $context = context_course::instance($grouping->courseid);
1005            try {
1006                self::validate_context($context);
1007            } catch (Exception $e) {
1008                $exceptionparam = new stdClass();
1009                $exceptionparam->message = $e->getMessage();
1010                $exceptionparam->courseid = $grouping->courseid;
1011                throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
1012            }
1013            require_capability('moodle/course:managegroups', $context);
1014
1015            groups_delete_grouping($grouping);
1016        }
1017
1018        $transaction->allow_commit();
1019    }
1020
1021    /**
1022     * Returns description of method result value
1023     *
1024     * @return external_description
1025     * @since Moodle 2.3
1026     */
1027    public static function delete_groupings_returns() {
1028        return null;
1029    }
1030
1031    /**
1032     * Returns description of method parameters
1033     *
1034     * @return external_function_parameters
1035     * @since Moodle 2.3
1036     */
1037    public static function assign_grouping_parameters() {
1038        return new external_function_parameters(
1039            array(
1040                'assignments'=> new external_multiple_structure(
1041                    new external_single_structure(
1042                        array(
1043                            'groupingid' => new external_value(PARAM_INT, 'grouping record id'),
1044                            'groupid' => new external_value(PARAM_INT, 'group record id'),
1045                        )
1046                    )
1047                )
1048            )
1049        );
1050    }
1051
1052    /**
1053     * Assign a group to a grouping
1054     *
1055     * @param array $assignments of arrays with keys groupid, groupingid
1056     * @return void
1057     * @since Moodle 2.3
1058     */
1059    public static function assign_grouping($assignments) {
1060        global $CFG, $DB;
1061        require_once("$CFG->dirroot/group/lib.php");
1062
1063        $params = self::validate_parameters(self::assign_grouping_parameters(), array('assignments'=>$assignments));
1064
1065        $transaction = $DB->start_delegated_transaction();
1066        foreach ($params['assignments'] as $assignment) {
1067            // Validate params.
1068            $groupingid = $assignment['groupingid'];
1069            $groupid = $assignment['groupid'];
1070
1071            $grouping = groups_get_grouping($groupingid, 'id, courseid', MUST_EXIST);
1072            $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
1073
1074            if ($DB->record_exists('groupings_groups', array('groupingid'=>$groupingid, 'groupid'=>$groupid))) {
1075                // Continue silently if the group is yet assigned to the grouping.
1076                continue;
1077            }
1078
1079            // Now security checks.
1080            $context = context_course::instance($grouping->courseid);
1081            try {
1082                self::validate_context($context);
1083            } catch (Exception $e) {
1084                $exceptionparam = new stdClass();
1085                $exceptionparam->message = $e->getMessage();
1086                $exceptionparam->courseid = $group->courseid;
1087                throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
1088            }
1089            require_capability('moodle/course:managegroups', $context);
1090
1091            groups_assign_grouping($groupingid, $groupid);
1092        }
1093
1094        $transaction->allow_commit();
1095    }
1096
1097    /**
1098     * Returns description of method result value
1099     *
1100     * @return null
1101     * @since Moodle 2.3
1102     */
1103    public static function assign_grouping_returns() {
1104        return null;
1105    }
1106
1107    /**
1108     * Returns description of method parameters
1109     *
1110     * @return external_function_parameters
1111     * @since Moodle 2.3
1112     */
1113    public static function unassign_grouping_parameters() {
1114        return new external_function_parameters(
1115            array(
1116                'unassignments'=> new external_multiple_structure(
1117                    new external_single_structure(
1118                        array(
1119                            'groupingid' => new external_value(PARAM_INT, 'grouping record id'),
1120                            'groupid' => new external_value(PARAM_INT, 'group record id'),
1121                        )
1122                    )
1123                )
1124            )
1125        );
1126    }
1127
1128    /**
1129     * Unassign a group from a grouping
1130     *
1131     * @param array $unassignments of arrays with keys groupid, groupingid
1132     * @return void
1133     * @since Moodle 2.3
1134     */
1135    public static function unassign_grouping($unassignments) {
1136        global $CFG, $DB;
1137        require_once("$CFG->dirroot/group/lib.php");
1138
1139        $params = self::validate_parameters(self::unassign_grouping_parameters(), array('unassignments'=>$unassignments));
1140
1141        $transaction = $DB->start_delegated_transaction();
1142        foreach ($params['unassignments'] as $unassignment) {
1143            // Validate params.
1144            $groupingid = $unassignment['groupingid'];
1145            $groupid = $unassignment['groupid'];
1146
1147            $grouping = groups_get_grouping($groupingid, 'id, courseid', MUST_EXIST);
1148            $group = groups_get_group($groupid, 'id, courseid', MUST_EXIST);
1149
1150            if (!$DB->record_exists('groupings_groups', array('groupingid'=>$groupingid, 'groupid'=>$groupid))) {
1151                // Continue silently if the group is not assigned to the grouping.
1152                continue;
1153            }
1154
1155            // Now security checks.
1156            $context = context_course::instance($grouping->courseid);
1157            try {
1158                self::validate_context($context);
1159            } catch (Exception $e) {
1160                $exceptionparam = new stdClass();
1161                $exceptionparam->message = $e->getMessage();
1162                $exceptionparam->courseid = $group->courseid;
1163                throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
1164            }
1165            require_capability('moodle/course:managegroups', $context);
1166
1167            groups_unassign_grouping($groupingid, $groupid);
1168        }
1169
1170        $transaction->allow_commit();
1171    }
1172
1173    /**
1174     * Returns description of method result value
1175     *
1176     * @return null
1177     * @since Moodle 2.3
1178     */
1179    public static function unassign_grouping_returns() {
1180        return null;
1181    }
1182
1183    /**
1184     * Returns description of method parameters
1185     *
1186     * @return external_function_parameters
1187     * @since Moodle 2.9
1188     */
1189    public static function get_course_user_groups_parameters() {
1190        return new external_function_parameters(
1191            array(
1192                'courseid' => new external_value(PARAM_INT, 'id of course'),
1193                'userid' => new external_value(PARAM_INT, 'id of user'),
1194                'groupingid' => new external_value(PARAM_INT, 'returns only groups in the specified grouping', VALUE_DEFAULT, 0)
1195            )
1196        );
1197    }
1198
1199    /**
1200     * Get all groups in the specified course for the specified user.
1201     *
1202     * @throws moodle_exception
1203     * @param int $courseid id of course.
1204     * @param int $userid id of user.
1205     * @param int $groupingid optional returns only groups in the specified grouping.
1206     * @return array of group objects (id, name, description, format) and possible warnings.
1207     * @since Moodle 2.9
1208     */
1209    public static function get_course_user_groups($courseid, $userid, $groupingid = 0) {
1210        global $USER;
1211
1212        // Warnings array, it can be empty at the end but is mandatory.
1213        $warnings = array();
1214
1215        $params = array(
1216            'courseid' => $courseid,
1217            'userid' => $userid,
1218            'groupingid' => $groupingid
1219        );
1220        $params = self::validate_parameters(self::get_course_user_groups_parameters(), $params);
1221        $courseid = $params['courseid'];
1222        $userid = $params['userid'];
1223        $groupingid = $params['groupingid'];
1224
1225        // Validate course and user. get_course throws an exception if the course does not exists.
1226        $course = get_course($courseid);
1227        $user = core_user::get_user($userid, '*', MUST_EXIST);
1228        core_user::require_active_user($user);
1229
1230        // Security checks.
1231        $context = context_course::instance($course->id);
1232        self::validate_context($context);
1233
1234         // Check if we have permissions for retrieve the information.
1235        if ($user->id != $USER->id) {
1236            if (!has_capability('moodle/course:managegroups', $context)) {
1237                throw new moodle_exception('accessdenied', 'admin');
1238            }
1239            // Validate if the user is enrolled in the course.
1240            if (!is_enrolled($context, $user->id)) {
1241                // We return a warning because the function does not fail for not enrolled users.
1242                $warning['item'] = 'course';
1243                $warning['itemid'] = $course->id;
1244                $warning['warningcode'] = '1';
1245                $warning['message'] = "User $user->id is not enrolled in course $course->id";
1246                $warnings[] = $warning;
1247            }
1248        }
1249
1250        $usergroups = array();
1251        if (empty($warnings)) {
1252            $groups = groups_get_all_groups($course->id, $user->id, 0, 'g.id, g.name, g.description, g.descriptionformat, g.idnumber');
1253
1254            foreach ($groups as $group) {
1255                list($group->description, $group->descriptionformat) =
1256                    external_format_text($group->description, $group->descriptionformat,
1257                            $context->id, 'group', 'description', $group->id);
1258                $group->courseid = $course->id;
1259                $usergroups[] = $group;
1260            }
1261        }
1262
1263        $results = array(
1264            'groups' => $usergroups,
1265            'warnings' => $warnings
1266        );
1267        return $results;
1268    }
1269
1270    /**
1271     * Returns description of method result value.
1272     *
1273     * @return external_description A single structure containing groups and possible warnings.
1274     * @since Moodle 2.9
1275     */
1276    public static function get_course_user_groups_returns() {
1277        return new external_single_structure(
1278            array(
1279                'groups' => new external_multiple_structure(self::group_description()),
1280                'warnings' => new external_warnings(),
1281            )
1282        );
1283    }
1284
1285    /**
1286     * Create group return value description.
1287     *
1288     * @return external_single_structure The group description
1289     */
1290    public static function group_description() {
1291        return new external_single_structure(
1292            array(
1293                'id' => new external_value(PARAM_INT, 'group record id'),
1294                'name' => new external_value(PARAM_TEXT, 'multilang compatible name, course unique'),
1295                'description' => new external_value(PARAM_RAW, 'group description text'),
1296                'descriptionformat' => new external_format_value('description'),
1297                'idnumber' => new external_value(PARAM_RAW, 'id number'),
1298                'courseid' => new external_value(PARAM_INT, 'course id', VALUE_OPTIONAL),
1299            )
1300        );
1301    }
1302
1303    /**
1304     * Returns description of method parameters
1305     *
1306     * @return external_function_parameters
1307     * @since Moodle 3.0
1308     */
1309    public static function get_activity_allowed_groups_parameters() {
1310        return new external_function_parameters(
1311            array(
1312                'cmid' => new external_value(PARAM_INT, 'course module id'),
1313                'userid' => new external_value(PARAM_INT, 'id of user, empty for current user', VALUE_DEFAULT, 0)
1314            )
1315        );
1316    }
1317
1318    /**
1319     * Gets a list of groups that the user is allowed to access within the specified activity.
1320     *
1321     * @throws moodle_exception
1322     * @param int $cmid course module id
1323     * @param int $userid id of user.
1324     * @return array of group objects (id, name, description, format) and possible warnings.
1325     * @since Moodle 3.0
1326     */
1327    public static function get_activity_allowed_groups($cmid, $userid = 0) {
1328        global $USER;
1329
1330        // Warnings array, it can be empty at the end but is mandatory.
1331        $warnings = array();
1332
1333        $params = array(
1334            'cmid' => $cmid,
1335            'userid' => $userid
1336        );
1337        $params = self::validate_parameters(self::get_activity_allowed_groups_parameters(), $params);
1338        $cmid = $params['cmid'];
1339        $userid = $params['userid'];
1340
1341        $cm = get_coursemodule_from_id(null, $cmid, 0, false, MUST_EXIST);
1342
1343        // Security checks.
1344        $context = context_module::instance($cm->id);
1345        $coursecontext = context_course::instance($cm->course);
1346        self::validate_context($context);
1347
1348        if (empty($userid)) {
1349            $userid = $USER->id;
1350        }
1351
1352        $user = core_user::get_user($userid, '*', MUST_EXIST);
1353        core_user::require_active_user($user);
1354
1355         // Check if we have permissions for retrieve the information.
1356        if ($user->id != $USER->id) {
1357            if (!has_capability('moodle/course:managegroups', $context)) {
1358                throw new moodle_exception('accessdenied', 'admin');
1359            }
1360
1361            // Validate if the user is enrolled in the course.
1362            $course = get_course($cm->course);
1363            if (!can_access_course($course, $user, '', true)) {
1364                // We return a warning because the function does not fail for not enrolled users.
1365                $warning = array();
1366                $warning['item'] = 'course';
1367                $warning['itemid'] = $cm->course;
1368                $warning['warningcode'] = '1';
1369                $warning['message'] = "User $user->id cannot access course $cm->course";
1370                $warnings[] = $warning;
1371            }
1372        }
1373
1374        $usergroups = array();
1375        if (empty($warnings)) {
1376            $groups = groups_get_activity_allowed_groups($cm, $user->id);
1377
1378            foreach ($groups as $group) {
1379                list($group->description, $group->descriptionformat) =
1380                    external_format_text($group->description, $group->descriptionformat,
1381                            $coursecontext->id, 'group', 'description', $group->id);
1382                $group->courseid = $cm->course;
1383                $usergroups[] = $group;
1384            }
1385        }
1386
1387        $results = array(
1388            'groups' => $usergroups,
1389            'warnings' => $warnings
1390        );
1391        return $results;
1392    }
1393
1394    /**
1395     * Returns description of method result value.
1396     *
1397     * @return external_description A single structure containing groups and possible warnings.
1398     * @since Moodle 3.0
1399     */
1400    public static function get_activity_allowed_groups_returns() {
1401        return new external_single_structure(
1402            array(
1403                'groups' => new external_multiple_structure(self::group_description()),
1404                'warnings' => new external_warnings(),
1405            )
1406        );
1407    }
1408
1409    /**
1410     * Returns description of method parameters
1411     *
1412     * @return external_function_parameters
1413     * @since Moodle 3.0
1414     */
1415    public static function get_activity_groupmode_parameters() {
1416        return new external_function_parameters(
1417            array(
1418                'cmid' => new external_value(PARAM_INT, 'course module id')
1419            )
1420        );
1421    }
1422
1423    /**
1424     * Returns effective groupmode used in a given activity.
1425     *
1426     * @throws moodle_exception
1427     * @param int $cmid course module id.
1428     * @return array containing the group mode and possible warnings.
1429     * @since Moodle 3.0
1430     * @throws moodle_exception
1431     */
1432    public static function get_activity_groupmode($cmid) {
1433        global $USER;
1434
1435        // Warnings array, it can be empty at the end but is mandatory.
1436        $warnings = array();
1437
1438        $params = array(
1439            'cmid' => $cmid
1440        );
1441        $params = self::validate_parameters(self::get_activity_groupmode_parameters(), $params);
1442        $cmid = $params['cmid'];
1443
1444        $cm = get_coursemodule_from_id(null, $cmid, 0, false, MUST_EXIST);
1445
1446        // Security checks.
1447        $context = context_module::instance($cm->id);
1448        self::validate_context($context);
1449
1450        $groupmode = groups_get_activity_groupmode($cm);
1451
1452        $results = array(
1453            'groupmode' => $groupmode,
1454            'warnings' => $warnings
1455        );
1456        return $results;
1457    }
1458
1459    /**
1460     * Returns description of method result value.
1461     *
1462     * @return external_description
1463     * @since Moodle 3.0
1464     */
1465    public static function get_activity_groupmode_returns() {
1466        return new external_single_structure(
1467            array(
1468                'groupmode' => new external_value(PARAM_INT, 'group mode:
1469                                                    0 for no groups, 1 for separate groups, 2 for visible groups'),
1470                'warnings' => new external_warnings(),
1471            )
1472        );
1473    }
1474
1475}
1476
1477/**
1478 * Deprecated group external functions
1479 *
1480 * @package    core_group
1481 * @copyright  2009 Petr Skodak
1482 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1483 * @since Moodle 2.0
1484 * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
1485 * @see core_group_external
1486 */
1487class moodle_group_external extends external_api {
1488
1489    /**
1490     * Returns description of method parameters
1491     *
1492     * @return external_function_parameters
1493     * @since Moodle 2.0
1494     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1495     * @see core_group_external::create_groups_parameters()
1496     */
1497    public static function create_groups_parameters() {
1498        return core_group_external::create_groups_parameters();
1499    }
1500
1501    /**
1502     * Create groups
1503     *
1504     * @param array $groups array of group description arrays (with keys groupname and courseid)
1505     * @return array of newly created groups
1506     * @since Moodle 2.0
1507     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1508     * @see use core_group_external::create_groups()
1509     */
1510    public static function create_groups($groups) {
1511        return core_group_external::create_groups($groups);
1512    }
1513
1514    /**
1515     * Returns description of method result value
1516     *
1517     * @return external_description
1518     * @since Moodle 2.0
1519     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1520     * @see core_group_external::create_groups_returns()
1521     */
1522    public static function create_groups_returns() {
1523        return core_group_external::create_groups_returns();
1524    }
1525
1526    /**
1527     * Marking the method as deprecated.
1528     *
1529     * @return bool
1530     */
1531    public static function create_groups_is_deprecated() {
1532        return true;
1533    }
1534
1535    /**
1536     * Returns description of method parameters
1537     *
1538     * @return external_function_parameters
1539     * @since Moodle 2.0
1540     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1541     * @see core_group_external::get_groups_parameters()
1542     */
1543    public static function get_groups_parameters() {
1544        return core_group_external::get_groups_parameters();
1545    }
1546
1547    /**
1548     * Get groups definition specified by ids
1549     *
1550     * @param array $groupids arrays of group ids
1551     * @return array of group objects (id, courseid, name, enrolmentkey)
1552     * @since Moodle 2.0
1553     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1554     * @see core_group_external::get_groups()
1555     */
1556    public static function get_groups($groupids) {
1557        return core_group_external::get_groups($groupids);
1558    }
1559
1560    /**
1561     * Returns description of method result value
1562     *
1563     * @return external_description
1564     * @since Moodle 2.0
1565     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1566     * @see core_group_external::get_groups_returns()
1567     */
1568    public static function get_groups_returns() {
1569        return core_group_external::get_groups_returns();
1570    }
1571
1572    /**
1573     * Marking the method as deprecated.
1574     *
1575     * @return bool
1576     */
1577    public static function get_groups_is_deprecated() {
1578        return true;
1579    }
1580
1581    /**
1582     * Returns description of method parameters
1583     *
1584     * @return external_function_parameters
1585     * @since Moodle 2.0
1586     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1587     * @see core_group_external::get_course_groups_parameters()
1588     */
1589    public static function get_course_groups_parameters() {
1590        return core_group_external::get_course_groups_parameters();
1591    }
1592
1593    /**
1594     * Get all groups in the specified course
1595     *
1596     * @param int $courseid id of course
1597     * @return array of group objects (id, courseid, name, enrolmentkey)
1598     * @since Moodle 2.0
1599     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1600     * @see core_group_external::get_course_groups()
1601     */
1602    public static function get_course_groups($courseid) {
1603        return core_group_external::get_course_groups($courseid);
1604    }
1605
1606    /**
1607     * Returns description of method result value
1608     *
1609     * @return external_description
1610     * @since Moodle 2.0
1611     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1612     * @see core_group_external::get_course_groups_returns()
1613     */
1614    public static function get_course_groups_returns() {
1615        return core_group_external::get_course_groups_returns();
1616    }
1617
1618    /**
1619     * Marking the method as deprecated.
1620     *
1621     * @return bool
1622     */
1623    public static function get_course_groups_is_deprecated() {
1624        return true;
1625    }
1626
1627    /**
1628     * Returns description of method parameters
1629     *
1630     * @return external_function_parameters
1631     * @since Moodle 2.0
1632     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1633     * @see core_group_external::delete_group_members_parameters()
1634     */
1635    public static function delete_groups_parameters() {
1636        return core_group_external::delete_groups_parameters();
1637    }
1638
1639    /**
1640     * Delete groups
1641     *
1642     * @param array $groupids array of group ids
1643     * @since Moodle 2.0
1644     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1645     * @see core_group_external::delete_groups()
1646     */
1647    public static function delete_groups($groupids) {
1648        return core_group_external::delete_groups($groupids);
1649    }
1650
1651    /**
1652     * Returns description of method result value
1653     *
1654     * @return null
1655     * @since Moodle 2.0
1656     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1657     * @see core_group_external::delete_group_members_returns()
1658     */
1659    public static function delete_groups_returns() {
1660        return core_group_external::delete_groups_returns();
1661    }
1662
1663    /**
1664     * Marking the method as deprecated.
1665     *
1666     * @return bool
1667     */
1668    public static function delete_groups_is_deprecated() {
1669        return true;
1670    }
1671
1672    /**
1673     * Returns description of method parameters
1674     *
1675     * @return external_function_parameters
1676     * @since Moodle 2.0
1677     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1678     * @see core_group_external::get_group_members_parameters()
1679     */
1680    public static function get_groupmembers_parameters() {
1681        return core_group_external::get_group_members_parameters();
1682    }
1683
1684    /**
1685     * Return all members for a group
1686     *
1687     * @param array $groupids array of group ids
1688     * @return array with  group id keys containing arrays of user ids
1689     * @since Moodle 2.0
1690     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1691     * @see core_group_external::get_group_members()
1692     */
1693    public static function get_groupmembers($groupids) {
1694        return core_group_external::get_group_members($groupids);
1695    }
1696
1697    /**
1698     * Returns description of method result value
1699     *
1700     * @return external_description
1701     * @since Moodle 2.0
1702     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1703     * @see core_group_external::get_group_members_returns()
1704     */
1705    public static function get_groupmembers_returns() {
1706        return core_group_external::get_group_members_returns();
1707    }
1708
1709    /**
1710     * Marking the method as deprecated.
1711     *
1712     * @return bool
1713     */
1714    public static function get_groupmembers_is_deprecated() {
1715        return true;
1716    }
1717
1718    /**
1719     * Returns description of method parameters
1720     *
1721     * @return external_function_parameters
1722     * @since Moodle 2.0
1723     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1724     * @see core_group_external::add_group_members_parameters()
1725     */
1726    public static function add_groupmembers_parameters() {
1727        return core_group_external::add_group_members_parameters();
1728    }
1729
1730    /**
1731     * Add group members
1732     *
1733     * @param array $members of arrays with keys userid, groupid
1734     * @since Moodle 2.0
1735     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1736     * @see use core_group_external::add_group_members()
1737     */
1738    public static function add_groupmembers($members) {
1739        return core_group_external::add_group_members($members);
1740    }
1741
1742    /**
1743     * Returns description of method result value
1744     *
1745     * @return external_description
1746     * @since Moodle 2.0
1747     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1748     * @see core_group_external::add_group_members_returns()
1749     */
1750    public static function add_groupmembers_returns() {
1751        return core_group_external::add_group_members_returns();
1752    }
1753
1754    /**
1755     * Marking the method as deprecated.
1756     *
1757     * @return bool
1758     */
1759    public static function add_groupmembers_is_deprecated() {
1760        return true;
1761    }
1762
1763    /**
1764     * Returns description of method parameters
1765     *
1766     * @return external_function_parameters
1767     * @since Moodle 2.0
1768     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1769     * @see core_group_external::delete_group_members_parameters()
1770     */
1771    public static function delete_groupmembers_parameters() {
1772        return core_group_external::delete_group_members_parameters();
1773    }
1774
1775    /**
1776     * Delete group members
1777     *
1778     * @param array $members of arrays with keys userid, groupid
1779     * @since Moodle 2.0
1780     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1781     * @see core_group_external::delete_group_members()
1782     */
1783    public static function delete_groupmembers($members) {
1784        return core_group_external::delete_group_members($members);
1785    }
1786
1787    /**
1788     * Returns description of method result value
1789     *
1790     * @return external_description
1791     * @since Moodle 2.0
1792     * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1793     * @see core_group_external::delete_group_members_returns()
1794     */
1795    public static function delete_groupmembers_returns() {
1796        return core_group_external::delete_group_members_returns();
1797    }
1798
1799    /**
1800     * Marking the method as deprecated.
1801     *
1802     * @return bool
1803     */
1804    public static function delete_groupmembers_is_deprecated() {
1805        return true;
1806    }
1807
1808}
Note: See TracBrowser for help on using the repository browser.