MDL-50853 mod_chat: New Web Service mod_chat_login_user
[moodle.git] / mod / chat / classes / external.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/>.
17 /**
18  * Chat external API
19  *
20  * @package    mod_chat
21  * @category   external
22  * @copyright  2015 Juan Leyva <juan@moodle.com>
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  * @since      Moodle 3.0
25  */
27 defined('MOODLE_INTERNAL') || die;
29 require_once($CFG->libdir . '/externallib.php');
30 require_once($CFG->dirroot . '/mod/chat/lib.php');
32 /**
33  * Chat external functions
34  *
35  * @package    mod_chat
36  * @category   external
37  * @copyright  2015 Juan Leyva <juan@moodle.com>
38  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
39  * @since      Moodle 3.0
40  */
41 class mod_chat_external extends external_api {
43     /**
44      * Returns description of method parameters
45      *
46      * @return external_function_parameters
47      * @since Moodle 3.0
48      */
49     public static function login_user_parameters() {
50         return new external_function_parameters(
51             array(
52                 'chatid' => new external_value(PARAM_INT, 'chat instance id'),
53                 'groupid' => new external_value(PARAM_INT, 'group id, 0 means that the function will determine the user group',
54                                                 VALUE_DEFAULT, 0),
55             )
56         );
57     }
59     /**
60      * Log the current user into a chat room in the given chat.
61      *
62      * @param int $chatid the chat instance id
63      * @param int $groupid the user group id
64      * @return array of warnings and the chat unique session id
65      * @since Moodle 3.0
66      * @throws moodle_exception
67      */
68     public static function login_user($chatid, $groupid = 0) {
69         global $DB;
71         $params = self::validate_parameters(self::login_user_parameters(),
72                                             array(
73                                                 'chatid' => $chatid,
74                                                 'groupid' => $groupid
75                                             ));
76         $warnings = array();
78         // Request and permission validation.
79         $chat = $DB->get_record('chat', array('id' => $params['chatid']), '*', MUST_EXIST);
80         list($course, $cm) = get_course_and_cm_from_instance($chat, 'chat');
82         $context = context_module::instance($cm->id);
83         self::validate_context($context);
85         require_capability('mod/chat:chat', $context);
87         if (!empty($params['groupid'])) {
88             $groupid = $params['groupid'];
89             // Determine is the group is visible to user.
90             if (!groups_group_visible($groupid, $course, $cm)) {
91                 throw new moodle_exception('notingroup');
92             }
93         } else {
94             // Check to see if groups are being used here.
95             if ($groupmode = groups_get_activity_groupmode($cm)) {
96                 $groupid = groups_get_activity_group($cm);
97                 // Determine is the group is visible to user (this is particullary for the group 0).
98                 if (!groups_group_visible($groupid, $course, $cm)) {
99                     throw new moodle_exception('notingroup');
100                 }
101             } else {
102                 $groupid = 0;
103             }
104         }
106         // Get the unique chat session id.
107         // Since we are going to use the chat via Web Service requests we set the ajax version (since it's the most similar).
108         if (!$chatsid = chat_login_user($chat->id, 'ajax', $groupid, $course)) {
109             throw moodle_exception('cantlogin', 'chat');
110         }
112         $result = array();
113         $result['chatsid'] = $chatsid;
114         $result['warnings'] = $warnings;
115         return $result;
116     }
118     /**
119      * Returns description of method result value
120      *
121      * @return external_description
122      * @since Moodle 3.0
123      */
124     public static function login_user_returns() {
125         return new external_single_structure(
126             array(
127                 'chatsid' => new external_value(PARAM_ALPHANUM, 'unique chat session id'),
128                 'warnings' => new external_warnings()
129             )
130         );
131     }