MDL-50853 mod_chat: New Web Service mod_chat_send_chat_message
[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     }
133     /**
134      * Returns description of method parameters
135      *
136      * @return external_function_parameters
137      * @since Moodle 3.0
138      */
139     public static function get_chat_users_parameters() {
140         return new external_function_parameters(
141             array(
142                 'chatsid' => new external_value(PARAM_ALPHANUM, 'chat session id (obtained via mod_chat_login_user)')
143             )
144         );
145     }
147     /**
148      * Get the list of users in the given chat session.
149      *
150      * @param int $chatsid the chat session id
151      * @return array of warnings and the user lists
152      * @since Moodle 3.0
153      * @throws moodle_exception
154      */
155     public static function get_chat_users($chatsid) {
156         global $DB;
158         $params = self::validate_parameters(self::get_chat_users_parameters(),
159                                             array(
160                                                 'chatsid' => $chatsid
161                                             ));
162         $warnings = array();
164         // Request and permission validation.
165         if (!$chatuser = $DB->get_record('chat_users', array('sid' => $params['chatsid']))) {
166             throw new moodle_exception('notlogged', 'chat');
167         }
168         $chat = $DB->get_record('chat', array('id' => $chatuser->chatid), '*', MUST_EXIST);
169         list($course, $cm) = get_course_and_cm_from_instance($chat, 'chat');
171         $context = context_module::instance($cm->id);
172         self::validate_context($context);
174         require_capability('mod/chat:chat', $context);
176         // First, delete old users from the chats.
177         chat_delete_old_users();
179         $users = chat_get_users($chatuser->chatid, $chatuser->groupid, $cm->groupingid);
180         $returnedusers = array();
182         foreach ($users as $user) {
183             $usercontext = context_user::instance($user->id, IGNORE_MISSING);
184             $profileimageurl = '';
186             if ($usercontext) {
187                 $profileimageurl = moodle_url::make_webservice_pluginfile_url(
188                                     $usercontext->id, 'user', 'icon', null, '/', 'f1')->out(false);
189             }
191             $returnedusers[] = array(
192                 'id' => $user->id,
193                 'fullname' => fullname($user),
194                 'profileimageurl' => $profileimageurl
195             );
196         }
198         $result = array();
199         $result['users'] = $returnedusers;
200         $result['warnings'] = $warnings;
201         return $result;
202     }
204     /**
205      * Returns description of method result value
206      *
207      * @return external_description
208      * @since Moodle 3.0
209      */
210     public static function get_chat_users_returns() {
211         return new external_single_structure(
212             array(
213                 'users' => new external_multiple_structure(
214                     new external_single_structure(
215                         array(
216                             'id' => new external_value(PARAM_INT, 'user id'),
217                             'fullname' => new external_value(PARAM_NOTAGS, 'user full name'),
218                             'profileimageurl' => new external_value(PARAM_URL, 'user picture URL'),
219                         )
220                     ),
221                     'list of users'
222                 ),
223                 'warnings' => new external_warnings()
224             )
225         );
226     }
228     /**
229      * Returns description of method parameters
230      *
231      * @return external_function_parameters
232      * @since Moodle 3.0
233      */
234     public static function send_chat_message_parameters() {
235         return new external_function_parameters(
236             array(
237                 'chatsid' => new external_value(PARAM_ALPHANUM, 'chat session id (obtained via mod_chat_login_user)'),
238                 'messagetext' => new external_value(PARAM_RAW, 'the message text'),
239                 'beepid' => new external_value(PARAM_RAW, 'the beep id', VALUE_DEFAULT, ''),
241             )
242         );
243     }
245     /**
246      * Send a message on the given chat session.
247      *
248      * @param int $chatsid the chat session id
249      * @param string $messagetext the message text
250      * @param string $beepid the beep message id
251      * @return array of warnings and the new message id (0 if the message was empty)
252      * @since Moodle 3.0
253      * @throws moodle_exception
254      */
255     public static function send_chat_message($chatsid, $messagetext, $beepid = '') {
256         global $DB;
258         $params = self::validate_parameters(self::send_chat_message_parameters(),
259                                             array(
260                                                 'chatsid' => $chatsid,
261                                                 'messagetext' => $messagetext,
262                                                 'beepid' => $beepid
263                                             ));
264         $warnings = array();
266         // Request and permission validation.
267         if (!$chatuser = $DB->get_record('chat_users', array('sid' => $params['chatsid']))) {
268             throw new moodle_exception('notlogged', 'chat');
269         }
270         $chat = $DB->get_record('chat', array('id' => $chatuser->chatid), '*', MUST_EXIST);
271         list($course, $cm) = get_course_and_cm_from_instance($chat, 'chat');
273         $context = context_module::instance($cm->id);
274         self::validate_context($context);
276         require_capability('mod/chat:chat', $context);
278         $chatmessage = clean_text($params['messagetext'], FORMAT_MOODLE);
280         if (!empty($params['beepid'])) {
281             $chatmessage = 'beep ' . $params['beepid'];
282         }
284         if (!empty($chatmessage)) {
285             // Send the message.
286             $messageid = chat_send_chatmessage($chatuser, $chatmessage, 0, $cm);
287             // Update ping time.
288             $chatuser->lastmessageping = time() - 2;
289             $DB->update_record('chat_users', $chatuser);
290         } else {
291             $messageid = 0;
292         }
294         $result = array();
295         $result['messageid'] = $messageid;
296         $result['warnings'] = $warnings;
297         return $result;
298     }
300     /**
301      * Returns description of method result value
302      *
303      * @return external_description
304      * @since Moodle 3.0
305      */
306     public static function send_chat_message_returns() {
307         return new external_single_structure(
308             array(
309                 'messageid' => new external_value(PARAM_INT, 'message sent id'),
310                 'warnings' => new external_warnings()
311             )
312         );
313     }