MDL-50853 mod_chat: New Web Service mod_chat_send_chat_message
[moodle.git] / mod / chat / classes / external.php
CommitLineData
1ca4cdf3
JL
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 * 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 */
26
27defined('MOODLE_INTERNAL') || die;
28
29require_once($CFG->libdir . '/externallib.php');
30require_once($CFG->dirroot . '/mod/chat/lib.php');
31
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 */
41class mod_chat_external extends external_api {
42
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 }
58
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;
70
71 $params = self::validate_parameters(self::login_user_parameters(),
72 array(
73 'chatid' => $chatid,
74 'groupid' => $groupid
75 ));
76 $warnings = array();
77
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');
81
82 $context = context_module::instance($cm->id);
83 self::validate_context($context);
84
85 require_capability('mod/chat:chat', $context);
86
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 }
105
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 }
111
112 $result = array();
113 $result['chatsid'] = $chatsid;
114 $result['warnings'] = $warnings;
115 return $result;
116 }
117
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 }
132
e4076a6e
JL
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 }
146
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;
157
158 $params = self::validate_parameters(self::get_chat_users_parameters(),
159 array(
160 'chatsid' => $chatsid
161 ));
162 $warnings = array();
163
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');
170
171 $context = context_module::instance($cm->id);
172 self::validate_context($context);
173
174 require_capability('mod/chat:chat', $context);
175
176 // First, delete old users from the chats.
177 chat_delete_old_users();
178
179 $users = chat_get_users($chatuser->chatid, $chatuser->groupid, $cm->groupingid);
180 $returnedusers = array();
181
182 foreach ($users as $user) {
183 $usercontext = context_user::instance($user->id, IGNORE_MISSING);
184 $profileimageurl = '';
185
186 if ($usercontext) {
187 $profileimageurl = moodle_url::make_webservice_pluginfile_url(
188 $usercontext->id, 'user', 'icon', null, '/', 'f1')->out(false);
189 }
190
191 $returnedusers[] = array(
192 'id' => $user->id,
193 'fullname' => fullname($user),
194 'profileimageurl' => $profileimageurl
195 );
196 }
197
198 $result = array();
199 $result['users'] = $returnedusers;
200 $result['warnings'] = $warnings;
201 return $result;
202 }
203
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 }
227
874aa80f
JL
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, ''),
240
241 )
242 );
243 }
244
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;
257
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();
265
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');
272
273 $context = context_module::instance($cm->id);
274 self::validate_context($context);
275
276 require_capability('mod/chat:chat', $context);
277
278 $chatmessage = clean_text($params['messagetext'], FORMAT_MOODLE);
279
280 if (!empty($params['beepid'])) {
281 $chatmessage = 'beep ' . $params['beepid'];
282 }
283
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 }
293
294 $result = array();
295 $result['messageid'] = $messageid;
296 $result['warnings'] = $warnings;
297 return $result;
298 }
299
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 }
314
1ca4cdf3 315}