MDL-54687 core_message: remove contact from DOM if no messages remain
[moodle.git] / message / externallib.php
CommitLineData
a623b6b8 1<?php
a623b6b8
JM
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
4615817d 17
a623b6b8
JM
18/**
19 * External message API
20 *
6fbd60ef 21 * @package core_message
4615817d
JM
22 * @category external
23 * @copyright 2011 Jerome Mouneyrac
a623b6b8
JM
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
4615817d 26
a623b6b8 27require_once("$CFG->libdir/externallib.php");
705afe6f 28require_once($CFG->dirroot . "/message/lib.php");
a623b6b8 29
5d1017e1 30/**
4615817d 31 * Message external functions
6fbd60ef
AD
32 *
33 * @package core_message
4615817d
JM
34 * @category external
35 * @copyright 2011 Jerome Mouneyrac
75e4f98c 36 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
4615817d 37 * @since Moodle 2.2
5d1017e1
JM
38 */
39class core_message_external extends external_api {
a623b6b8
JM
40
41 /**
42 * Returns description of method parameters
4615817d 43 *
a623b6b8 44 * @return external_function_parameters
4615817d 45 * @since Moodle 2.2
a623b6b8 46 */
5d1017e1 47 public static function send_instant_messages_parameters() {
a623b6b8
JM
48 return new external_function_parameters(
49 array(
50 'messages' => new external_multiple_structure(
51 new external_single_structure(
52 array(
53 'touserid' => new external_value(PARAM_INT, 'id of the user to send the private message'),
93ce0e82
JM
54 'text' => new external_value(PARAM_RAW, 'the text of the message'),
55 'textformat' => new external_format_value('text', VALUE_DEFAULT),
a623b6b8
JM
56 'clientmsgid' => new external_value(PARAM_ALPHANUMEXT, 'your own client id for the message. If this id is provided, the fail message id will be returned to you', VALUE_OPTIONAL),
57 )
58 )
59 )
60 )
61 );
62 }
63
64 /**
65 * Send private messages from the current USER to other users
66 *
4615817d
JM
67 * @param array $messages An array of message to send.
68 * @return array
69 * @since Moodle 2.2
a623b6b8 70 */
5d1017e1 71 public static function send_instant_messages($messages = array()) {
a623b6b8 72 global $CFG, $USER, $DB;
a623b6b8 73
436bbf89 74 // Check if messaging is enabled.
a623b6b8
JM
75 if (!$CFG->messaging) {
76 throw new moodle_exception('disabled', 'message');
77 }
78
79 // Ensure the current user is allowed to run this function
bf0f06b1 80 $context = context_system::instance();
a623b6b8
JM
81 self::validate_context($context);
82 require_capability('moodle/site:sendmessage', $context);
83
5d1017e1 84 $params = self::validate_parameters(self::send_instant_messages_parameters(), array('messages' => $messages));
a623b6b8
JM
85
86 //retrieve all tousers of the messages
4de00da7 87 $receivers = array();
a623b6b8 88 foreach($params['messages'] as $message) {
4de00da7 89 $receivers[] = $message['touserid'];
a623b6b8 90 }
4de00da7 91 list($sqluserids, $sqlparams) = $DB->get_in_or_equal($receivers, SQL_PARAMS_NAMED, 'userid_');
a623b6b8 92 $tousers = $DB->get_records_select("user", "id " . $sqluserids . " AND deleted = 0", $sqlparams);
4de00da7
DC
93 $blocklist = array();
94 $contactlist = array();
a623b6b8 95 $sqlparams['contactid'] = $USER->id;
4de00da7
DC
96 $rs = $DB->get_recordset_sql("SELECT *
97 FROM {message_contacts}
98 WHERE userid $sqluserids
99 AND contactid = :contactid", $sqlparams);
100 foreach ($rs as $record) {
101 if ($record->blocked) {
102 // $record->userid is blocking current user
103 $blocklist[$record->userid] = true;
104 } else {
105 // $record->userid have current user as contact
106 $contactlist[$record->userid] = true;
107 }
108 }
109 $rs->close();
a623b6b8
JM
110
111 $canreadallmessages = has_capability('moodle/site:readallmessages', $context);
112
113 $resultmessages = array();
114 foreach ($params['messages'] as $message) {
a623b6b8
JM
115 $resultmsg = array(); //the infos about the success of the operation
116
117 //we are going to do some checking
118 //code should match /messages/index.php checks
119 $success = true;
120
121 //check the user exists
122 if (empty($tousers[$message['touserid']])) {
123 $success = false;
124 $errormessage = get_string('touserdoesntexist', 'message', $message['touserid']);
125 }
126
127 //check that the touser is not blocking the current user
4de00da7 128 if ($success and !empty($blocklist[$message['touserid']]) and !$canreadallmessages) {
a623b6b8
JM
129 $success = false;
130 $errormessage = get_string('userisblockingyou', 'message');
131 }
132
78736e5d 133 // Check if the user is a contact
4615817d 134 //TODO MDL-31118 performance improvement - edit the function so we can pass an array instead userid
4de00da7
DC
135 $blocknoncontacts = get_user_preferences('message_blocknoncontacts', NULL, $message['touserid']);
136 // message_blocknoncontacts option is on and current user is not in contact list
137 if ($success && empty($contactlist[$message['touserid']]) && !empty($blocknoncontacts)) {
78736e5d
SH
138 // The user isn't a contact and they have selected to block non contacts so this message won't be sent.
139 $success = false;
126a4bc4
CS
140 $errormessage = get_string('userisblockingyounoncontact', 'message',
141 fullname(core_user::get_user($message['touserid'])));
a623b6b8
JM
142 }
143
144 //now we can send the message (at least try)
145 if ($success) {
4615817d 146 //TODO MDL-31118 performance improvement - edit the function so we can pass an array instead one touser object
93ce0e82
JM
147 $success = message_post_message($USER, $tousers[$message['touserid']],
148 $message['text'], external_validate_format($message['textformat']));
a623b6b8
JM
149 }
150
151 //build the resultmsg
152 if (isset($message['clientmsgid'])) {
78736e5d 153 $resultmsg['clientmsgid'] = $message['clientmsgid'];
a623b6b8
JM
154 }
155 if ($success) {
156 $resultmsg['msgid'] = $success;
157 } else {
93ce0e82
JM
158 // WARNINGS: for backward compatibility we return this errormessage.
159 // We should have thrown exceptions as these errors prevent results to be returned.
160 // See http://docs.moodle.org/dev/Errors_handling_in_web_services#When_to_send_a_warning_on_the_server_side .
a623b6b8
JM
161 $resultmsg['msgid'] = -1;
162 $resultmsg['errormessage'] = $errormessage;
163 }
164
165 $resultmessages[] = $resultmsg;
166 }
167
168 return $resultmessages;
169 }
170
171 /**
172 * Returns description of method result value
4615817d 173 *
a623b6b8 174 * @return external_description
4615817d 175 * @since Moodle 2.2
a623b6b8 176 */
5d1017e1 177 public static function send_instant_messages_returns() {
a623b6b8
JM
178 return new external_multiple_structure(
179 new external_single_structure(
180 array(
78736e5d 181 'msgid' => new external_value(PARAM_INT, 'test this to know if it succeeds: id of the created message if it succeeded, -1 when failed'),
4de00da7 182 'clientmsgid' => new external_value(PARAM_ALPHANUMEXT, 'your own id for the message', VALUE_OPTIONAL),
78736e5d 183 'errormessage' => new external_value(PARAM_TEXT, 'error message - if it failed', VALUE_OPTIONAL)
a623b6b8
JM
184 )
185 )
186 );
187 }
188
d6731600
FM
189 /**
190 * Create contacts parameters description.
191 *
192 * @return external_function_parameters
5bcfd504 193 * @since Moodle 2.5
d6731600
FM
194 */
195 public static function create_contacts_parameters() {
196 return new external_function_parameters(
197 array(
198 'userids' => new external_multiple_structure(
199 new external_value(PARAM_INT, 'User ID'),
200 'List of user IDs'
34c2f347
MN
201 ),
202 'userid' => new external_value(PARAM_INT, 'The id of the user we are creating the contacts for, 0 for the
203 current user', VALUE_DEFAULT, 0)
d6731600
FM
204 )
205 );
206 }
207
208 /**
209 * Create contacts.
210 *
211 * @param array $userids array of user IDs.
34c2f347 212 * @param int $userid The id of the user we are creating the contacts for
d6731600 213 * @return external_description
5bcfd504 214 * @since Moodle 2.5
d6731600 215 */
34c2f347 216 public static function create_contacts($userids, $userid = 0) {
436bbf89
DM
217 global $CFG;
218
219 // Check if messaging is enabled.
220 if (!$CFG->messaging) {
221 throw new moodle_exception('disabled', 'message');
222 }
223
34c2f347 224 $params = array('userids' => $userids, 'userid' => $userid);
d6731600
FM
225 $params = self::validate_parameters(self::create_contacts_parameters(), $params);
226
227 $warnings = array();
228 foreach ($params['userids'] as $id) {
34c2f347 229 if (!message_add_contact($id, 0, $userid)) {
d6731600
FM
230 $warnings[] = array(
231 'item' => 'user',
232 'itemid' => $id,
233 'warningcode' => 'contactnotcreated',
234 'message' => 'The contact could not be created'
235 );
236 }
237 }
238 return $warnings;
239 }
240
241 /**
242 * Create contacts return description.
243 *
244 * @return external_description
5bcfd504 245 * @since Moodle 2.5
d6731600
FM
246 */
247 public static function create_contacts_returns() {
248 return new external_warnings();
249 }
250
251 /**
252 * Delete contacts parameters description.
253 *
254 * @return external_function_parameters
5bcfd504 255 * @since Moodle 2.5
d6731600
FM
256 */
257 public static function delete_contacts_parameters() {
258 return new external_function_parameters(
259 array(
260 'userids' => new external_multiple_structure(
261 new external_value(PARAM_INT, 'User ID'),
262 'List of user IDs'
34c2f347
MN
263 ),
264 'userid' => new external_value(PARAM_INT, 'The id of the user we are deleting the contacts for, 0 for the
265 current user', VALUE_DEFAULT, 0)
d6731600
FM
266 )
267 );
268 }
269
270 /**
271 * Delete contacts.
272 *
273 * @param array $userids array of user IDs.
34c2f347 274 * @param int $userid The id of the user we are deleting the contacts for
d6731600 275 * @return null
5bcfd504 276 * @since Moodle 2.5
d6731600 277 */
34c2f347 278 public static function delete_contacts($userids, $userid = 0) {
436bbf89
DM
279 global $CFG;
280
281 // Check if messaging is enabled.
282 if (!$CFG->messaging) {
283 throw new moodle_exception('disabled', 'message');
284 }
285
34c2f347 286 $params = array('userids' => $userids, 'userid' => $userid);
d6731600
FM
287 $params = self::validate_parameters(self::delete_contacts_parameters(), $params);
288
289 foreach ($params['userids'] as $id) {
34c2f347 290 message_remove_contact($id, $userid);
d6731600
FM
291 }
292
293 return null;
294 }
295
296 /**
297 * Delete contacts return description.
298 *
299 * @return external_description
5bcfd504 300 * @since Moodle 2.5
d6731600
FM
301 */
302 public static function delete_contacts_returns() {
303 return null;
304 }
305
306 /**
307 * Block contacts parameters description.
308 *
309 * @return external_function_parameters
5bcfd504 310 * @since Moodle 2.5
d6731600
FM
311 */
312 public static function block_contacts_parameters() {
313 return new external_function_parameters(
314 array(
315 'userids' => new external_multiple_structure(
316 new external_value(PARAM_INT, 'User ID'),
317 'List of user IDs'
34c2f347
MN
318 ),
319 'userid' => new external_value(PARAM_INT, 'The id of the user we are blocking the contacts for, 0 for the
320 current user', VALUE_DEFAULT, 0)
d6731600
FM
321 )
322 );
323 }
324
325 /**
326 * Block contacts.
327 *
328 * @param array $userids array of user IDs.
34c2f347 329 * @param int $userid The id of the user we are blocking the contacts for
d6731600 330 * @return external_description
5bcfd504 331 * @since Moodle 2.5
d6731600 332 */
34c2f347 333 public static function block_contacts($userids, $userid = 0) {
436bbf89
DM
334 global $CFG;
335
336 // Check if messaging is enabled.
337 if (!$CFG->messaging) {
338 throw new moodle_exception('disabled', 'message');
339 }
340
34c2f347 341 $params = array('userids' => $userids, 'userid' => $userid);
d6731600
FM
342 $params = self::validate_parameters(self::block_contacts_parameters(), $params);
343
344 $warnings = array();
345 foreach ($params['userids'] as $id) {
34c2f347 346 if (!message_block_contact($id, $userid)) {
d6731600
FM
347 $warnings[] = array(
348 'item' => 'user',
349 'itemid' => $id,
350 'warningcode' => 'contactnotblocked',
351 'message' => 'The contact could not be blocked'
352 );
353 }
354 }
355 return $warnings;
356 }
357
358 /**
359 * Block contacts return description.
360 *
361 * @return external_description
5bcfd504 362 * @since Moodle 2.5
d6731600
FM
363 */
364 public static function block_contacts_returns() {
365 return new external_warnings();
366 }
367
368 /**
369 * Unblock contacts parameters description.
370 *
371 * @return external_function_parameters
5bcfd504 372 * @since Moodle 2.5
d6731600
FM
373 */
374 public static function unblock_contacts_parameters() {
375 return new external_function_parameters(
376 array(
377 'userids' => new external_multiple_structure(
378 new external_value(PARAM_INT, 'User ID'),
379 'List of user IDs'
34c2f347
MN
380 ),
381 'userid' => new external_value(PARAM_INT, 'The id of the user we are unblocking the contacts for, 0 for the
382 current user', VALUE_DEFAULT, 0)
d6731600
FM
383 )
384 );
385 }
386
387 /**
388 * Unblock contacts.
389 *
390 * @param array $userids array of user IDs.
34c2f347 391 * @param int $userid The id of the user we are unblocking the contacts for
d6731600 392 * @return null
5bcfd504 393 * @since Moodle 2.5
d6731600 394 */
34c2f347 395 public static function unblock_contacts($userids, $userid = 0) {
436bbf89
DM
396 global $CFG;
397
398 // Check if messaging is enabled.
399 if (!$CFG->messaging) {
400 throw new moodle_exception('disabled', 'message');
401 }
402
34c2f347 403 $params = array('userids' => $userids, 'userid' => $userid);
d6731600
FM
404 $params = self::validate_parameters(self::unblock_contacts_parameters(), $params);
405
406 foreach ($params['userids'] as $id) {
34c2f347 407 message_unblock_contact($id, $userid);
d6731600
FM
408 }
409
410 return null;
411 }
412
413 /**
414 * Unblock contacts return description.
415 *
416 * @return external_description
5bcfd504 417 * @since Moodle 2.5
d6731600
FM
418 */
419 public static function unblock_contacts_returns() {
420 return null;
421 }
422
9aa012b5 423 /**
49aaadc3 424 * The messagearea conversations parameters.
9aa012b5
MN
425 *
426 * @return external_function_parameters
49aaadc3 427 * @since 3.2
9aa012b5
MN
428 */
429 public static function data_for_messagearea_conversations_parameters() {
430 return new external_function_parameters(
431 array(
432 'userid' => new external_value(PARAM_INT, 'The id of the user who we are viewing conversations for'),
433 'limitfrom' => new external_value(PARAM_INT, 'Limit from', VALUE_DEFAULT, 0),
434 'limitnum' => new external_value(PARAM_INT, 'Limit number', VALUE_DEFAULT, 0)
435 )
436 );
437 }
438
439 /**
440 * Get messagearea conversations.
441 *
442 * @param int $userid The id of the user who we are viewing conversations for
443 * @param int $limitfrom
444 * @param int $limitnum
49aaadc3
MN
445 * @return stdClass
446 * @throws moodle_exception
447 * @since 3.2
9aa012b5
MN
448 */
449 public static function data_for_messagearea_conversations($userid, $limitfrom = 0, $limitnum = 0) {
450 global $CFG, $PAGE;
451
452 // Check if messaging is enabled.
453 if (!$CFG->messaging) {
454 throw new moodle_exception('disabled', 'message');
455 }
456
457 $params = array(
458 'userid' => $userid,
459 'limitfrom' => $limitfrom,
460 'limitnum' => $limitnum
461 );
462 self::validate_parameters(self::data_for_messagearea_conversations_parameters(), $params);
463
464 self::validate_context(context_user::instance($userid));
465
466 $contacts = \core_message\api::get_conversations($userid, 0, $limitfrom, $limitnum);
467
468 $renderer = $PAGE->get_renderer('core_message');
469 return $contacts->export_for_template($renderer);
470 }
471
472 /**
49aaadc3 473 * The messagearea conversations return structure.
9aa012b5 474 *
49aaadc3
MN
475 * @return external_single_structure
476 * @since 3.2
9aa012b5
MN
477 */
478 public static function data_for_messagearea_conversations_returns() {
49aaadc3 479 return new external_single_structure(
9aa012b5
MN
480 array(
481 'userid' => new external_value(PARAM_INT, 'The id of the user who we are viewing conversations for'),
9aa012b5
MN
482 'contacts' => new external_multiple_structure(
483 new external_single_structure(
484 array(
485 'userid' => new external_value(PARAM_INT, 'The user\'s id'),
486 'fullname' => new external_value(PARAM_NOTAGS, 'The user\'s name'),
487 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL'),
488 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL'),
49aaadc3
MN
489 'lastmessage' => new external_value(PARAM_RAW, 'The user\'s last message, null if none.'),
490 'isonline' => new external_value(PARAM_BOOL, 'The user\'s online status'),
491 'isread' => new external_value(PARAM_BOOL, 'If the user has read the message'),
9aa012b5
MN
492 )
493 )
494 )
495 )
496 );
497 }
498
499 /**
49aaadc3 500 * The messagearea contacts return parameters.
9aa012b5
MN
501 *
502 * @return external_function_parameters
49aaadc3 503 * @since 3.2
9aa012b5
MN
504 */
505 public static function data_for_messagearea_contacts_parameters() {
506 return self::data_for_messagearea_conversations_parameters();
507 }
508
509 /**
510 * Get messagearea contacts parameters.
511 *
512 * @param int $userid The id of the user who we are viewing conversations for
513 * @param int $limitfrom
514 * @param int $limitnum
49aaadc3
MN
515 * @return stdClass
516 * @throws moodle_exception
517 * @since 3.2
9aa012b5
MN
518 */
519 public static function data_for_messagearea_contacts($userid, $limitfrom = 0, $limitnum = 0) {
520 global $CFG, $PAGE;
521
522 // Check if messaging is enabled.
523 if (!$CFG->messaging) {
524 throw new moodle_exception('disabled', 'message');
525 }
526
527 $params = array(
528 'userid' => $userid,
529 'limitfrom' => $limitfrom,
530 'limitnum' => $limitnum
531 );
532 self::validate_parameters(self::data_for_messagearea_contacts_parameters(), $params);
533
534 self::validate_context(context_user::instance($userid));
535
536 $contacts = \core_message\api::get_contacts($userid, $limitfrom, $limitnum);
537
538 $renderer = $PAGE->get_renderer('core_message');
539 return $contacts->export_for_template($renderer);
540 }
541
542 /**
49aaadc3 543 * The messagearea contacts return structure.
9aa012b5 544 *
49aaadc3
MN
545 * @return external_single_structure
546 * @since 3.2
9aa012b5
MN
547 */
548 public static function data_for_messagearea_contacts_returns() {
549 return self::data_for_messagearea_conversations_returns();
550 }
551
3cd13828 552 /**
49aaadc3 553 * The messagearea messages parameters.
3cd13828
MN
554 *
555 * @return external_function_parameters
49aaadc3 556 * @since 3.2
3cd13828
MN
557 */
558 public static function data_for_messagearea_messages_parameters() {
559 return new external_function_parameters(
560 array(
561 'currentuserid' => new external_value(PARAM_INT, 'The current user\'s id'),
562 'otheruserid' => new external_value(PARAM_INT, 'The other user\'s id'),
563 'limitfrom' => new external_value(PARAM_INT, 'Limit from', VALUE_DEFAULT, 0),
8ec78c48
MN
564 'limitnum' => new external_value(PARAM_INT, 'Limit number', VALUE_DEFAULT, 0),
565 'newest' => new external_value(PARAM_BOOL, 'Newest first?', VALUE_DEFAULT, false),
3cd13828
MN
566 )
567 );
568 }
569
570 /**
571 * Get messagearea messages.
572 *
573 * @param int $currentuserid The current user's id
574 * @param int $otheruserid The other user's id
575 * @param int $limitfrom
576 * @param int $limitnum
8ec78c48 577 * @param boolean $newest
49aaadc3
MN
578 * @return stdClass
579 * @throws moodle_exception
580 * @since 3.2
3cd13828 581 */
8ec78c48 582 public static function data_for_messagearea_messages($currentuserid, $otheruserid, $limitfrom = 0, $limitnum = 0, $newest = false) {
3cd13828
MN
583 global $CFG, $PAGE;
584
585 // Check if messaging is enabled.
586 if (!$CFG->messaging) {
587 throw new moodle_exception('disabled', 'message');
588 }
589
590 $params = array(
591 'currentuserid' => $currentuserid,
592 'otheruserid' => $otheruserid,
593 'limitfrom' => $limitfrom,
8ec78c48
MN
594 'limitnum' => $limitnum,
595 'newest' => $newest
3cd13828
MN
596 );
597 self::validate_parameters(self::data_for_messagearea_messages_parameters(), $params);
598
599 self::validate_context(context_user::instance($currentuserid));
600
8ec78c48
MN
601 if ($newest) {
602 $sort = 'timecreated DESC';
603 } else {
604 $sort = 'timecreated ASC';
605 }
606 $messages = \core_message\api::get_messages($currentuserid, $otheruserid, $limitfrom, $limitnum, $sort);
3cd13828
MN
607
608 $renderer = $PAGE->get_renderer('core_message');
609 return $messages->export_for_template($renderer);
610 }
611
612 /**
49aaadc3 613 * The messagearea messages return structure.
3cd13828 614 *
49aaadc3
MN
615 * @return external_single_structure
616 * @since 3.2
3cd13828
MN
617 */
618 public static function data_for_messagearea_messages_returns() {
49aaadc3 619 return new external_single_structure(
3cd13828
MN
620 array(
621 'iscurrentuser' => new external_value(PARAM_BOOL, 'Is the currently logged in user the user we are viewing the messages on behalf of?'),
622 'currentuserid' => new external_value(PARAM_INT, 'The current user\'s id'),
623 'otheruserid' => new external_value(PARAM_INT, 'The other user\'s id'),
624 'otheruserfullname' => new external_value(PARAM_NOTAGS, 'The other user\'s fullname'),
625 'messages' => new external_multiple_structure(
626 new external_single_structure(
627 array(
3090f52f 628 'id' => new external_value(PARAM_INT, 'The id of the message'),
3cd13828 629 'text' => new external_value(PARAM_RAW, 'The text of the message'),
3090f52f 630 'displayblocktime' => new external_value(PARAM_BOOL, 'Should we display the block time?'),
3cd13828
MN
631 'blocktime' => new external_value(PARAM_NOTAGS, 'The time to display above the message'),
632 'position' => new external_value(PARAM_ALPHA, 'The position of the text'),
633 'timesent' => new external_value(PARAM_NOTAGS, 'The time the message was sent'),
3090f52f 634 'isread' => new external_value(PARAM_INT, 'Determines if the message was read or not'),
3cd13828
MN
635 )
636 )
637 )
638 )
639 );
640 }
641
c060cd49 642 /**
49aaadc3 643 * The get most recent message return parameters.
c060cd49
MN
644 *
645 * @return external_function_parameters
49aaadc3 646 * @since 3.2
c060cd49
MN
647 */
648 public static function data_for_messagearea_get_most_recent_message_parameters() {
649 return new external_function_parameters(
650 array(
651 'currentuserid' => new external_value(PARAM_INT, 'The current user\'s id'),
652 'otheruserid' => new external_value(PARAM_INT, 'The other user\'s id'),
653 )
654 );
655 }
656
657 /**
658 * Get the most recent message in a conversation.
659 *
660 * @param int $currentuserid The current user's id
661 * @param int $otheruserid The other user's id
49aaadc3
MN
662 * @return stdClass
663 * @throws moodle_exception
664 * @since 3.2
c060cd49
MN
665 */
666 public static function data_for_messagearea_get_most_recent_message($currentuserid, $otheruserid) {
667 global $CFG, $PAGE;
668
669 // Check if messaging is enabled.
670 if (!$CFG->messaging) {
671 throw new moodle_exception('disabled', 'message');
672 }
673
674 $params = array(
675 'currentuserid' => $currentuserid,
676 'otheruserid' => $otheruserid
677 );
678 self::validate_parameters(self::data_for_messagearea_get_most_recent_message_parameters(), $params);
679
680 self::validate_context(context_user::instance($currentuserid));
681
682 $message = \core_message\api::get_most_recent_message($currentuserid, $otheruserid);
683
684 $renderer = $PAGE->get_renderer('core_message');
685 return $message->export_for_template($renderer);
686 }
687
688 /**
49aaadc3 689 * The get most recent message return structure.
c060cd49
MN
690 *
691 * @return external_single_structure
49aaadc3 692 * @since 3.2
c060cd49
MN
693 */
694 public static function data_for_messagearea_get_most_recent_message_returns() {
695 return new external_single_structure(
696 array(
3090f52f 697 'id' => new external_value(PARAM_INT, 'The id of the message'),
c060cd49 698 'text' => new external_value(PARAM_RAW, 'The text of the message'),
3090f52f 699 'displayblocktime' => new external_value(PARAM_BOOL, 'Should we display the block time?'),
c060cd49
MN
700 'blocktime' => new external_value(PARAM_NOTAGS, 'The time to display above the message'),
701 'position' => new external_value(PARAM_ALPHA, 'The position of the text'),
702 'timesent' => new external_value(PARAM_NOTAGS, 'The time the message was sent'),
3090f52f 703 'isread' => new external_value(PARAM_INT, 'Determines if the message was read or not'),
c060cd49
MN
704 )
705 );
706 }
707
c6e97f54
MN
708 /**
709 * The get profile parameters.
710 *
711 * @return external_function_parameters
49aaadc3 712 * @since 3.2
c6e97f54
MN
713 */
714 public static function data_for_messagearea_get_profile_parameters() {
715 return new external_function_parameters(
716 array(
717 'currentuserid' => new external_value(PARAM_INT, 'The current user\'s id'),
718 'otheruserid' => new external_value(PARAM_INT, 'The id of the user whose profile we want to view'),
719 )
720 );
721 }
722
723 /**
724 * Get the profile information for a contact.
725 *
726 * @param int $currentuserid The current user's id
727 * @param int $otheruserid The id of the user whose profile we are viewing
49aaadc3
MN
728 * @return stdClass
729 * @throws moodle_exception
730 * @since 3.2
c6e97f54
MN
731 */
732 public static function data_for_messagearea_get_profile($currentuserid, $otheruserid) {
733 global $CFG, $PAGE;
734
735 // Check if messaging is enabled.
736 if (!$CFG->messaging) {
737 throw new moodle_exception('disabled', 'message');
738 }
739
740 $params = array(
741 'currentuserid' => $currentuserid,
742 'otheruserid' => $otheruserid
743 );
744 self::validate_parameters(self::data_for_messagearea_get_profile_parameters(), $params);
745
746 self::validate_context(context_user::instance($otheruserid));
747
748 $profile = \core_message\api::get_profile($currentuserid, $otheruserid);
749
750 $renderer = $PAGE->get_renderer('core_message');
751 return $profile->export_for_template($renderer);
752 }
753
754 /**
49aaadc3 755 * The get profile return structure.
c6e97f54
MN
756 *
757 * @return external_single_structure
49aaadc3 758 * @since 3.2
c6e97f54
MN
759 */
760 public static function data_for_messagearea_get_profile_returns() {
761 return new external_single_structure(
762 array(
763 'iscurrentuser' => new external_value(PARAM_BOOL, 'Is the currently logged in user the user we are viewing the profile on behalf of?'),
764 'currentuserid' => new external_value(PARAM_INT, 'The current user\'s id'),
765 'otheruserid' => new external_value(PARAM_INT, 'The id of the user whose profile we are viewing'),
766 'email' => new external_value(core_user::get_property_type('email'), 'An email address'),
767 'country' => new external_value(core_user::get_property_type('country'), 'Home country code of the user'),
768 'city' => new external_value(core_user::get_property_type('city'), 'Home city of the user'),
769 'fullname' => new external_value(PARAM_NOTAGS, 'The user\'s name'),
770 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL'),
771 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL'),
772 'isblocked' => new external_value(PARAM_BOOL, 'Is the user blocked?'),
773 'iscontact' => new external_value(PARAM_BOOL, 'Is the user a contact?')
774 )
775 );
776 }
777
d6731600
FM
778 /**
779 * Get contacts parameters description.
780 *
781 * @return external_function_parameters
5bcfd504 782 * @since Moodle 2.5
d6731600
FM
783 */
784 public static function get_contacts_parameters() {
785 return new external_function_parameters(array());
786 }
787
788 /**
789 * Get contacts.
790 *
791 * @param array $userids array of user IDs.
792 * @return external_description
5bcfd504 793 * @since Moodle 2.5
d6731600
FM
794 */
795 public static function get_contacts() {
d85bedf7 796 global $CFG, $PAGE;
436bbf89
DM
797
798 // Check if messaging is enabled.
799 if (!$CFG->messaging) {
800 throw new moodle_exception('disabled', 'message');
801 }
802
d6731600
FM
803 require_once($CFG->dirroot . '/user/lib.php');
804
805 list($online, $offline, $strangers) = message_get_contacts();
806 $allcontacts = array('online' => $online, 'offline' => $offline, 'strangers' => $strangers);
807 foreach ($allcontacts as $mode => $contacts) {
808 foreach ($contacts as $key => $contact) {
809 $newcontact = array(
810 'id' => $contact->id,
811 'fullname' => fullname($contact),
812 'unread' => $contact->messagecount
813 );
814
d85bedf7
JL
815 $userpicture = new user_picture($contact);
816 $userpicture->size = 1; // Size f1.
817 $newcontact['profileimageurl'] = $userpicture->get_url($PAGE)->out(false);
818 $userpicture->size = 0; // Size f2.
819 $newcontact['profileimageurlsmall'] = $userpicture->get_url($PAGE)->out(false);
d6731600
FM
820
821 $allcontacts[$mode][$key] = $newcontact;
822 }
823 }
824 return $allcontacts;
825 }
826
827 /**
828 * Get contacts return description.
829 *
830 * @return external_description
5bcfd504 831 * @since Moodle 2.5
d6731600
FM
832 */
833 public static function get_contacts_returns() {
834 return new external_single_structure(
835 array(
836 'online' => new external_multiple_structure(
837 new external_single_structure(
838 array(
839 'id' => new external_value(PARAM_INT, 'User ID'),
840 'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
841 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL),
842 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL', VALUE_OPTIONAL),
843 'unread' => new external_value(PARAM_INT, 'Unread message count')
844 )
845 ),
846 'List of online contacts'
847 ),
848 'offline' => new external_multiple_structure(
849 new external_single_structure(
850 array(
851 'id' => new external_value(PARAM_INT, 'User ID'),
852 'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
853 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL),
854 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL', VALUE_OPTIONAL),
855 'unread' => new external_value(PARAM_INT, 'Unread message count')
856 )
857 ),
858 'List of offline contacts'
859 ),
860 'strangers' => new external_multiple_structure(
861 new external_single_structure(
862 array(
863 'id' => new external_value(PARAM_INT, 'User ID'),
864 'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
865 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL),
866 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL', VALUE_OPTIONAL),
867 'unread' => new external_value(PARAM_INT, 'Unread message count')
868 )
869 ),
870 'List of users that are not in the user\'s contact list but have sent a message'
871 )
872 )
873 );
874 }
875
876 /**
877 * Search contacts parameters description.
878 *
879 * @return external_function_parameters
5bcfd504 880 * @since Moodle 2.5
d6731600
FM
881 */
882 public static function search_contacts_parameters() {
883 return new external_function_parameters(
884 array(
885 'searchtext' => new external_value(PARAM_CLEAN, 'String the user\'s fullname has to match to be found'),
886 'onlymycourses' => new external_value(PARAM_BOOL, 'Limit search to the user\'s courses',
887 VALUE_DEFAULT, false)
888 )
889 );
890 }
891
892 /**
893 * Search contacts.
894 *
895 * @param string $searchtext query string.
896 * @param bool $onlymycourses limit the search to the user's courses only.
897 * @return external_description
5bcfd504 898 * @since Moodle 2.5
d6731600
FM
899 */
900 public static function search_contacts($searchtext, $onlymycourses = false) {
d85bedf7 901 global $CFG, $USER, $PAGE;
11d83ab3 902 require_once($CFG->dirroot . '/user/lib.php');
436bbf89
DM
903
904 // Check if messaging is enabled.
905 if (!$CFG->messaging) {
906 throw new moodle_exception('disabled', 'message');
907 }
908
d6731600
FM
909 require_once($CFG->libdir . '/enrollib.php');
910
911 $params = array('searchtext' => $searchtext, 'onlymycourses' => $onlymycourses);
912 $params = self::validate_parameters(self::search_contacts_parameters(), $params);
913
914 // Extra validation, we do not allow empty queries.
915 if ($params['searchtext'] === '') {
916 throw new moodle_exception('querystringcannotbeempty');
917 }
918
919 $courseids = array();
920 if ($params['onlymycourses']) {
921 $mycourses = enrol_get_my_courses(array('id'));
922 foreach ($mycourses as $mycourse) {
923 $courseids[] = $mycourse->id;
924 }
925 } else {
926 $courseids[] = SITEID;
927 }
928
929 // Retrieving the users matching the query.
930 $users = message_search_users($courseids, $params['searchtext']);
931 $results = array();
932 foreach ($users as $user) {
933 $results[$user->id] = $user;
934 }
935
936 // Reorganising information.
937 foreach ($results as &$user) {
938 $newuser = array(
939 'id' => $user->id,
940 'fullname' => fullname($user)
941 );
942
943 // Avoid undefined property notice as phone not specified.
944 $user->phone1 = null;
945 $user->phone2 = null;
946
d85bedf7
JL
947 $userpicture = new user_picture($user);
948 $userpicture->size = 1; // Size f1.
949 $newuser['profileimageurl'] = $userpicture->get_url($PAGE)->out(false);
950 $userpicture->size = 0; // Size f2.
951 $newuser['profileimageurlsmall'] = $userpicture->get_url($PAGE)->out(false);
d6731600
FM
952
953 $user = $newuser;
954 }
955
956 return $results;
957 }
958
959 /**
960 * Search contacts return description.
961 *
962 * @return external_description
5bcfd504 963 * @since Moodle 2.5
d6731600
FM
964 */
965 public static function search_contacts_returns() {
966 return new external_multiple_structure(
967 new external_single_structure(
968 array(
969 'id' => new external_value(PARAM_INT, 'User ID'),
970 'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
971 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL),
972 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL', VALUE_OPTIONAL)
973 )
974 ),
975 'List of contacts'
976 );
977 }
aff9da17
JL
978
979 /**
980 * Get messages parameters description.
981 *
982 * @return external_function_parameters
193edf7f 983 * @since 2.8
aff9da17
JL
984 */
985 public static function get_messages_parameters() {
986 return new external_function_parameters(
987 array(
6ff4464b 988 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
127ef540
SH
989 'useridfrom' => new external_value(
990 PARAM_INT, 'the user id who send the message, 0 for any user. -10 or -20 for no-reply or support user',
991 VALUE_DEFAULT, 0),
992 'type' => new external_value(
993 PARAM_ALPHA, 'type of message to return, expected values are: notifications, conversations and both',
994 VALUE_DEFAULT, 'both'),
6ff4464b 995 'read' => new external_value(PARAM_BOOL, 'true for getting read messages, false for unread', VALUE_DEFAULT, true),
127ef540
SH
996 'newestfirst' => new external_value(
997 PARAM_BOOL, 'true for ordering by newest first, false for oldest first',
998 VALUE_DEFAULT, true),
aff9da17 999 'limitfrom' => new external_value(PARAM_INT, 'limit from', VALUE_DEFAULT, 0),
127ef540
SH
1000 'limitnum' => new external_value(PARAM_INT, 'limit number', VALUE_DEFAULT, 0)
1001 )
aff9da17
JL
1002 );
1003 }
1004
1005 /**
1006 * Get messages function implementation.
127ef540
SH
1007 *
1008 * @since 2.8
1009 * @throws invalid_parameter_exception
1010 * @throws moodle_exception
6ff4464b
JL
1011 * @param int $useridto the user id who received the message
1012 * @param int $useridfrom the user id who send the message. -10 or -20 for no-reply or support user
193edf7f 1013 * @param string $type type of message to return, expected values: notifications, conversations and both
aff9da17 1014 * @param bool $read true for retreiving read messages, false for unread
6ff4464b 1015 * @param bool $newestfirst true for ordering by newest first, false for oldest first
aff9da17
JL
1016 * @param int $limitfrom limit from
1017 * @param int $limitnum limit num
1018 * @return external_description
aff9da17 1019 */
193edf7f 1020 public static function get_messages($useridto, $useridfrom = 0, $type = 'both', $read = true,
aff9da17 1021 $newestfirst = true, $limitfrom = 0, $limitnum = 0) {
127ef540 1022 global $CFG, $USER;
aff9da17
JL
1023
1024 $warnings = array();
1025
1026 $params = array(
1027 'useridto' => $useridto,
6ff4464b 1028 'useridfrom' => $useridfrom,
aff9da17
JL
1029 'type' => $type,
1030 'read' => $read,
aff9da17
JL
1031 'newestfirst' => $newestfirst,
1032 'limitfrom' => $limitfrom,
1033 'limitnum' => $limitnum
1034 );
1035
1036 $params = self::validate_parameters(self::get_messages_parameters(), $params);
1037
1038 $context = context_system::instance();
1039 self::validate_context($context);
1040
1041 $useridto = $params['useridto'];
6ff4464b 1042 $useridfrom = $params['useridfrom'];
aff9da17
JL
1043 $type = $params['type'];
1044 $read = $params['read'];
aff9da17
JL
1045 $newestfirst = $params['newestfirst'];
1046 $limitfrom = $params['limitfrom'];
1047 $limitnum = $params['limitnum'];
1048
1049 $allowedvalues = array('notifications', 'conversations', 'both');
1050 if (!in_array($type, $allowedvalues)) {
1051 throw new invalid_parameter_exception('Invalid value for type parameter (value: ' . $type . '),' .
1052 'allowed values are: ' . implode(',', $allowedvalues));
1053 }
1054
1055 // Check if private messaging between users is allowed.
1056 if (empty($CFG->messaging)) {
1057 // If we are retreiving only conversations, and messaging is disabled, throw an exception.
aff9da17
JL
1058 if ($type == "conversations") {
1059 throw new moodle_exception('disabled', 'message');
1060 }
1061 if ($type == "both") {
1062 $warning = array();
1063 $warning['item'] = 'message';
1064 $warning['itemid'] = $USER->id;
1065 $warning['warningcode'] = '1';
1066 $warning['message'] = 'Private messages (conversations) are not enabled in this site.
1067 Only notifications will be returned';
1068 $warnings[] = $warning;
1069 }
1070 }
1071
1072 if (!empty($useridto)) {
6ff4464b
JL
1073 if (core_user::is_real_user($useridto)) {
1074 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
1075 } else {
1076 throw new moodle_exception('invaliduser');
1077 }
aff9da17
JL
1078 }
1079
1080 if (!empty($useridfrom)) {
1081 // We use get_user here because the from user can be the noreply or support user.
1082 $userfrom = core_user::get_user($useridfrom, '*', MUST_EXIST);
1083 }
1084
1085 // Check if the current user is the sender/receiver or just a privileged user.
1086 if ($useridto != $USER->id and $useridfrom != $USER->id and
1087 !has_capability('moodle/site:readallmessages', $context)) {
1088 throw new moodle_exception('accessdenied', 'admin');
1089 }
1090
127ef540 1091 // Which type of messages to retrieve.
193edf7f 1092 $notifications = -1;
aff9da17 1093 if ($type != 'both') {
193edf7f 1094 $notifications = ($type == 'notifications') ? 1 : 0;
aff9da17
JL
1095 }
1096
aff9da17 1097 $orderdirection = $newestfirst ? 'DESC' : 'ASC';
193edf7f 1098 $sort = "mr.timecreated $orderdirection";
aff9da17 1099
193edf7f 1100 if ($messages = message_get_messages($useridto, $useridfrom, $notifications, $read, $sort, $limitfrom, $limitnum)) {
aff9da17
JL
1101 $canviewfullname = has_capability('moodle/site:viewfullnames', $context);
1102
1103 // In some cases, we don't need to get the to/from user objects from the sql query.
1104 $userfromfullname = '';
1105 $usertofullname = '';
1106
1107 // In this case, the useridto field is not empty, so we can get the user destinatary fullname from there.
1108 if (!empty($useridto)) {
1109 $usertofullname = fullname($userto, $canviewfullname);
1110 // The user from may or may not be filled.
1111 if (!empty($useridfrom)) {
1112 $userfromfullname = fullname($userfrom, $canviewfullname);
1113 }
1114 } else {
1115 // If the useridto field is empty, the useridfrom must be filled.
1116 $userfromfullname = fullname($userfrom, $canviewfullname);
1117 }
aff9da17
JL
1118 foreach ($messages as $mid => $message) {
1119
ea21d637
JL
1120 // Do not return deleted messages.
1121 if (($useridto == $USER->id and $message->timeusertodeleted) or
1122 ($useridfrom == $USER->id and $message->timeuserfromdeleted)) {
1123
1124 unset($messages[$mid]);
1125 continue;
1126 }
1127
aff9da17
JL
1128 // We need to get the user from the query.
1129 if (empty($userfromfullname)) {
6ff4464b
JL
1130 // Check for non-reply and support users.
1131 if (core_user::is_real_user($message->useridfrom)) {
127ef540 1132 $user = new stdClass();
6ff4464b
JL
1133 $user = username_load_fields_from_object($user, $message, 'userfrom');
1134 $message->userfromfullname = fullname($user, $canviewfullname);
1135 } else {
1136 $user = core_user::get_user($message->useridfrom);
1137 $message->userfromfullname = fullname($user, $canviewfullname);
1138 }
aff9da17
JL
1139 } else {
1140 $message->userfromfullname = $userfromfullname;
1141 }
1142
1143 // We need to get the user from the query.
1144 if (empty($usertofullname)) {
127ef540 1145 $user = new stdClass();
aff9da17
JL
1146 $user = username_load_fields_from_object($user, $message, 'userto');
1147 $message->usertofullname = fullname($user, $canviewfullname);
1148 } else {
1149 $message->usertofullname = $usertofullname;
1150 }
1151
193edf7f 1152 // This field is only available in the message_read table.
aff9da17
JL
1153 if (!isset($message->timeread)) {
1154 $message->timeread = 0;
1155 }
1156
aff9da17 1157 $message->text = message_format_message_text($message);
aff9da17
JL
1158 $messages[$mid] = (array) $message;
1159 }
1160 }
1161
1162 $results = array(
1163 'messages' => $messages,
1164 'warnings' => $warnings
1165 );
1166
1167 return $results;
1168 }
1169
1170 /**
1171 * Get messages return description.
1172 *
6ff4464b 1173 * @return external_single_structure
193edf7f 1174 * @since 2.8
aff9da17
JL
1175 */
1176 public static function get_messages_returns() {
1177 return new external_single_structure(
1178 array(
1179 'messages' => new external_multiple_structure(
1180 new external_single_structure(
1181 array(
193edf7f 1182 'id' => new external_value(PARAM_INT, 'Message id'),
aff9da17
JL
1183 'useridfrom' => new external_value(PARAM_INT, 'User from id'),
1184 'useridto' => new external_value(PARAM_INT, 'User to id'),
1185 'subject' => new external_value(PARAM_TEXT, 'The message subject'),
1186 'text' => new external_value(PARAM_RAW, 'The message text formated'),
1187 'fullmessage' => new external_value(PARAM_RAW, 'The message'),
193edf7f 1188 'fullmessageformat' => new external_format_value('fullmessage'),
aff9da17
JL
1189 'fullmessagehtml' => new external_value(PARAM_RAW, 'The message in html'),
1190 'smallmessage' => new external_value(PARAM_RAW, 'The shorten message'),
1191 'notification' => new external_value(PARAM_INT, 'Is a notification?'),
1192 'contexturl' => new external_value(PARAM_RAW, 'Context URL'),
1193 'contexturlname' => new external_value(PARAM_TEXT, 'Context URL link name'),
1194 'timecreated' => new external_value(PARAM_INT, 'Time created'),
1195 'timeread' => new external_value(PARAM_INT, 'Time read'),
1196 'usertofullname' => new external_value(PARAM_TEXT, 'User to full name'),
1197 'userfromfullname' => new external_value(PARAM_TEXT, 'User from full name')
1198 ), 'message'
1199 )
1200 ),
1201 'warnings' => new external_warnings()
1202 )
1203 );
3274d5ca
RW
1204 }
1205
1206 /**
ada7695d 1207 * Get popup notifications parameters description.
3274d5ca
RW
1208 *
1209 * @return external_function_parameters
1210 * @since 3.2
1211 */
ada7695d 1212 public static function get_popup_notifications_parameters() {
3274d5ca
RW
1213 return new external_function_parameters(
1214 array(
1215 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
3274d5ca
RW
1216 'status' => new external_value(
1217 PARAM_ALPHA, 'filter the results to just "read" or "unread" notifications',
1218 VALUE_DEFAULT, ''),
c5dd16a1
RW
1219 'embedpreference' => new external_value(
1220 PARAM_BOOL, 'true for returning user\'s preference for the notification',
1221 VALUE_DEFAULT, false),
3274d5ca
RW
1222 'embeduserto' => new external_value(
1223 PARAM_BOOL, 'true for returning user details for the recipient in each notification',
1224 VALUE_DEFAULT, false),
1225 'embeduserfrom' => new external_value(
1226 PARAM_BOOL, 'true for returning user details for the sender in each notification',
1227 VALUE_DEFAULT, false),
1228 'newestfirst' => new external_value(
1229 PARAM_BOOL, 'true for ordering by newest first, false for oldest first',
1230 VALUE_DEFAULT, true),
1231 'markasread' => new external_value(
1232 PARAM_BOOL, 'mark notifications as read when they are returned by this function',
1233 VALUE_DEFAULT, false),
1234 'limit' => new external_value(PARAM_INT, 'the number of results to return', VALUE_DEFAULT, 0),
1235 'offset' => new external_value(PARAM_INT, 'offset the result set by a given amount', VALUE_DEFAULT, 0)
1236 )
1237 );
1238 }
1239
1240 /**
1241 * Get notifications function.
1242 *
1243 * @since 3.2
1244 * @throws invalid_parameter_exception
1245 * @throws moodle_exception
c5dd16a1 1246 * @param int $useridto the user id who received the message
c5dd16a1
RW
1247 * @param string $status filter the results to only read or unread notifications
1248 * @param bool $embedpreference true to embed the recipient user details in the record for each notification
1249 * @param bool $embeduserto true to embed the recipient user details in the record for each notification
1250 * @param bool $embeduserfrom true to embed the send user details in the record for each notification
1251 * @param bool $newestfirst true for ordering by newest first, false for oldest first
1252 * @param bool $markasread mark notifications as read when they are returned by this function
1253 * @param int $limit the number of results to return
1254 * @param int $offset offset the result set by a given amount
3274d5ca
RW
1255 * @return external_description
1256 */
ada7695d 1257 public static function get_popup_notifications($useridto, $status, $embedpreference,
c5dd16a1 1258 $embeduserto, $embeduserfrom, $newestfirst, $markasread, $limit, $offset) {
24a76780 1259 global $CFG, $USER, $PAGE;
3274d5ca
RW
1260
1261 $params = self::validate_parameters(
ada7695d 1262 self::get_popup_notifications_parameters(),
3274d5ca
RW
1263 array(
1264 'useridto' => $useridto,
3274d5ca 1265 'status' => $status,
c5dd16a1 1266 'embedpreference' => $embedpreference,
3274d5ca
RW
1267 'embeduserto' => $embeduserto,
1268 'embeduserfrom' => $embeduserfrom,
1269 'newestfirst' => $newestfirst,
1270 'markasread' => $markasread,
1271 'limit' => $limit,
1272 'offset' => $offset,
1273 )
1274 );
1275
1276 $context = context_system::instance();
1277 self::validate_context($context);
1278
1279 $useridto = $params['useridto'];
3274d5ca 1280 $status = $params['status'];
c5dd16a1 1281 $embedpreference = $params['embedpreference'];
3274d5ca
RW
1282 $embeduserto = $params['embeduserto'];
1283 $embeduserfrom = $params['embeduserfrom'];
1284 $newestfirst = $params['newestfirst'];
1285 $markasread = $params['markasread'];
1286 $limit = $params['limit'];
1287 $offset = $params['offset'];
c5dd16a1 1288 $issuperuser = has_capability('moodle/site:readallmessages', $context);
24a76780 1289 $renderer = $PAGE->get_renderer('core_message');
3274d5ca
RW
1290
1291 if (!empty($useridto)) {
1292 if (core_user::is_real_user($useridto)) {
1293 if ($embeduserto) {
1294 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
1295 }
1296 } else {
1297 throw new moodle_exception('invaliduser');
1298 }
1299 }
1300
3274d5ca 1301 // Check if the current user is the sender/receiver or just a privileged user.
ada7695d 1302 if ($useridto != $USER->id and !$issuperuser) {
3274d5ca
RW
1303 throw new moodle_exception('accessdenied', 'admin');
1304 }
1305
1306 $sort = $newestfirst ? 'DESC' : 'ASC';
ada7695d 1307 $notifications = message_get_popup_notifications($useridto, $status, $embeduserto, $embeduserfrom, $sort, $limit, $offset);
24a76780 1308 $notificationcontexts = [];
3274d5ca
RW
1309
1310 if ($notifications) {
ada7695d 1311 // In some cases, we don't need to get the to user objects from the sql query.
3274d5ca
RW
1312 $usertofullname = '';
1313
1314 // In this case, the useridto field is not empty, so we can get the user destinatary fullname from there.
1315 if (!empty($useridto) && $embeduserto) {
1316 $usertofullname = fullname($userto);
3274d5ca
RW
1317 }
1318
1319 foreach ($notifications as $notification) {
1320
24a76780
RW
1321 $notificationoutput = new \core_message\output\popup_notification($notification, $embeduserto,
1322 $embeduserfrom, $embedpreference, $usertofullname);
3274d5ca 1323
24a76780
RW
1324 $notificationcontext = $notificationoutput->export_for_template($renderer);
1325 $notificationcontexts[] = $notificationcontext;
c5dd16a1 1326
24a76780
RW
1327 if ($markasread && !$notificationcontext->read) {
1328 message_mark_message_read($notification, time());
3274d5ca
RW
1329 }
1330 }
1331 }
1332
1333 return array(
24a76780 1334 'notifications' => $notificationcontexts,
ada7695d 1335 'unreadcount' => message_count_unread_popup_notifications($useridto),
3274d5ca
RW
1336 );
1337 }
1338
1339 /**
1340 * Get notifications return description.
1341 *
1342 * @return external_single_structure
1343 * @since 3.2
1344 */
ada7695d 1345 public static function get_popup_notifications_returns() {
3274d5ca
RW
1346 return new external_single_structure(
1347 array(
1348 'notifications' => new external_multiple_structure(
1349 new external_single_structure(
1350 array(
1351 'id' => new external_value(PARAM_INT, 'Notification id (this is not guaranteed to be unique within this result set)'),
1352 'useridfrom' => new external_value(PARAM_INT, 'User from id'),
1353 'useridto' => new external_value(PARAM_INT, 'User to id'),
1354 'subject' => new external_value(PARAM_TEXT, 'The notification subject'),
1355 'text' => new external_value(PARAM_RAW, 'The message text formated'),
1356 'fullmessage' => new external_value(PARAM_RAW, 'The message'),
1357 'fullmessageformat' => new external_format_value('fullmessage'),
1358 'fullmessagehtml' => new external_value(PARAM_RAW, 'The message in html'),
1359 'smallmessage' => new external_value(PARAM_RAW, 'The shorten message'),
1360 'contexturl' => new external_value(PARAM_RAW, 'Context URL'),
1361 'contexturlname' => new external_value(PARAM_TEXT, 'Context URL link name'),
1362 'timecreated' => new external_value(PARAM_INT, 'Time created'),
1363 'timecreatedpretty' => new external_value(PARAM_TEXT, 'Time created in a pretty format'),
1364 'timeread' => new external_value(PARAM_INT, 'Time read'),
1365 'usertofullname' => new external_value(PARAM_TEXT, 'User to full name', VALUE_OPTIONAL),
1366 'userfromfullname' => new external_value(PARAM_TEXT, 'User from full name', VALUE_OPTIONAL),
1367 'userfromprofileurl' => new external_value(PARAM_URL, 'User from profile url', VALUE_OPTIONAL),
1368 'read' => new external_value(PARAM_BOOL, 'notification read status'),
1369 'deleted' => new external_value(PARAM_BOOL, 'notification deletion status'),
1370 'iconurl' => new external_value(PARAM_URL, 'URL for notification icon'),
1371 'component' => new external_value(PARAM_TEXT, 'The component that generated the notification', VALUE_OPTIONAL),
1372 'eventtype' => new external_value(PARAM_TEXT, 'The type of notification', VALUE_OPTIONAL),
c5dd16a1
RW
1373 'preference' => new external_single_structure(
1374 array (
1375 'key' => new external_value(PARAM_TEXT, 'The preference key'),
1376 'loggedin' => new external_value(PARAM_TEXT, 'The logged in preference setting'),
1377 'loggedoff' => new external_value(PARAM_TEXT, 'The logged off preference setting'),
1378 ),
1379 'The preference configuration',
1380 VALUE_OPTIONAL
1381 ),
3274d5ca
RW
1382 ), 'message'
1383 )
1384 ),
1385 'unreadcount' => new external_value(PARAM_INT, 'the user whose blocked users we want to retrieve'),
1386 )
1387 );
1388 }
1389
1390 /**
1391 * Mark all notifications as read parameters description.
1392 *
1393 * @return external_function_parameters
1394 * @since 3.2
1395 */
1396 public static function mark_all_notifications_as_read_parameters() {
1397 return new external_function_parameters(
1398 array(
1399 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
1400 'useridfrom' => new external_value(
1401 PARAM_INT, 'the user id who send the message, 0 for any user. -10 or -20 for no-reply or support user',
1402 VALUE_DEFAULT, 0),
1403 )
1404 );
1405 }
1406
1407 /**
1408 * Mark all notifications as read function.
1409 *
1410 * @since 3.2
1411 * @throws invalid_parameter_exception
1412 * @throws moodle_exception
1413 * @param int $useridto the user id who received the message
1414 * @param int $useridfrom the user id who send the message. -10 or -20 for no-reply or support user
1415 * @return external_description
1416 */
1417 public static function mark_all_notifications_as_read($useridto, $useridfrom) {
1418 global $CFG, $USER;
1419
1420 $params = self::validate_parameters(
1421 self::mark_all_notifications_as_read_parameters(),
1422 array(
1423 'useridto' => $useridto,
1424 'useridfrom' => $useridfrom,
1425 )
1426 );
1427
1428 $context = context_system::instance();
1429 self::validate_context($context);
1430
1431 $useridto = $params['useridto'];
1432 $useridfrom = $params['useridfrom'];
1433
1434 if (!empty($useridto)) {
1435 if (core_user::is_real_user($useridto)) {
1436 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
1437 } else {
1438 throw new moodle_exception('invaliduser');
1439 }
1440 }
1441
1442 if (!empty($useridfrom)) {
1443 // We use get_user here because the from user can be the noreply or support user.
1444 $userfrom = core_user::get_user($useridfrom, '*', MUST_EXIST);
1445 }
1446
1447 // Check if the current user is the sender/receiver or just a privileged user.
1448 if ($useridto != $USER->id and $useridfrom != $USER->id and
1449 // deleteanymessage seems more reasonable here than readallmessages.
1450 !has_capability('moodle/site:deleteanymessage', $context)) {
1451 throw new moodle_exception('accessdenied', 'admin');
1452 }
1453
8c55bd6c 1454 message_mark_all_read_for_user($useridto, $useridfrom, MESSAGE_TYPE_NOTIFICATION);
3274d5ca
RW
1455
1456 return true;
1457 }
1458
1459 /**
1460 * Mark all notifications as read return description.
1461 *
1462 * @return external_single_structure
1463 * @since 3.2
1464 */
1465 public static function mark_all_notifications_as_read_returns() {
1466 return new external_value(PARAM_BOOL, 'True if the messages were marked read, false otherwise');
1467 }
1468
1469 /**
1470 * Get unread notification count parameters description.
1471 *
1472 * @return external_function_parameters
1473 * @since 3.2
1474 */
ada7695d 1475 public static function get_unread_popup_notification_count_parameters() {
3274d5ca
RW
1476 return new external_function_parameters(
1477 array(
1478 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
3274d5ca
RW
1479 )
1480 );
1481 }
1482
1483 /**
1484 * Get unread notification count function.
1485 *
1486 * @since 3.2
1487 * @throws invalid_parameter_exception
1488 * @throws moodle_exception
1489 * @param int $useridto the user id who received the message
3274d5ca
RW
1490 * @return external_description
1491 */
ada7695d 1492 public static function get_unread_popup_notification_count($useridto) {
3274d5ca
RW
1493 global $CFG, $USER;
1494
1495 $params = self::validate_parameters(
ada7695d
RW
1496 self::get_unread_popup_notification_count_parameters(),
1497 array('useridto' => $useridto)
3274d5ca
RW
1498 );
1499
1500 $context = context_system::instance();
1501 self::validate_context($context);
1502
1503 $useridto = $params['useridto'];
3274d5ca
RW
1504
1505 if (!empty($useridto)) {
1506 if (core_user::is_real_user($useridto)) {
1507 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
1508 } else {
1509 throw new moodle_exception('invaliduser');
1510 }
1511 }
1512
3274d5ca 1513 // Check if the current user is the sender/receiver or just a privileged user.
ada7695d 1514 if ($useridto != $USER->id and !has_capability('moodle/site:readallmessages', $context)) {
3274d5ca
RW
1515 throw new moodle_exception('accessdenied', 'admin');
1516 }
1517
ada7695d 1518 return message_count_unread_popup_notifications($useridto);
3274d5ca
RW
1519 }
1520
1521 /**
ada7695d 1522 * Get unread popup notification count return description.
3274d5ca
RW
1523 *
1524 * @return external_single_structure
1525 * @since 3.2
1526 */
ada7695d 1527 public static function get_unread_popup_notification_count_returns() {
8c55bd6c
RW
1528 return new external_value(PARAM_INT, 'The count of unread popup notifications');
1529 }
1530
1531 /**
1532 * Get unread conversations count parameters description.
1533 *
1534 * @return external_function_parameters
1535 * @since 3.2
1536 */
1537 public static function get_unread_conversations_count_parameters() {
1538 return new external_function_parameters(
1539 array(
1540 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
1541 )
1542 );
1543 }
1544
1545 /**
1546 * Get unread messages count function.
1547 *
1548 * @since 3.2
1549 * @throws invalid_parameter_exception
1550 * @throws moodle_exception
1551 * @param int $useridto the user id who received the message
1552 * @return external_description
1553 */
1554 public static function get_unread_conversations_count($useridto) {
1555 global $USER;
1556
1557 $params = self::validate_parameters(
1558 self::get_unread_conversations_count_parameters(),
1559 array('useridto' => $useridto)
1560 );
1561
1562 $context = context_system::instance();
1563 self::validate_context($context);
1564
1565 $useridto = $params['useridto'];
1566
1567 if (!empty($useridto)) {
1568 if (core_user::is_real_user($useridto)) {
1569 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
1570 } else {
1571 throw new moodle_exception('invaliduser');
1572 }
1573 } else {
1574 $useridto = $USER->id;
1575 }
1576
1577 // Check if the current user is the receiver or just a privileged user.
1578 if ($useridto != $USER->id and !has_capability('moodle/site:readallmessages', $context)) {
1579 throw new moodle_exception('accessdenied', 'admin');
1580 }
1581
1582 return message_count_unread_conversations($userto);
1583 }
1584
1585 /**
1586 * Get unread conversations count return description.
1587 *
1588 * @return external_single_structure
1589 * @since 3.2
1590 */
1591 public static function get_unread_conversations_count_returns() {
1592 return new external_value(PARAM_INT, 'The count of unread messages for the user');
aff9da17
JL
1593 }
1594
60ab2e1b
JL
1595 /**
1596 * Get blocked users parameters description.
1597 *
1598 * @return external_function_parameters
1599 * @since 2.9
1600 */
1601 public static function get_blocked_users_parameters() {
1602 return new external_function_parameters(
1603 array(
1604 'userid' => new external_value(PARAM_INT,
1605 'the user whose blocked users we want to retrieve',
1606 VALUE_REQUIRED),
1607 )
1608 );
1609 }
1610
1611 /**
1612 * Retrieve a list of users blocked
1613 *
1614 * @param int $userid the user whose blocked users we want to retrieve
1615 * @return external_description
1616 * @since 2.9
1617 */
1618 public static function get_blocked_users($userid) {
d85bedf7 1619 global $CFG, $USER, $PAGE;
60ab2e1b
JL
1620
1621 // Warnings array, it can be empty at the end but is mandatory.
1622 $warnings = array();
1623
1624 // Validate params.
1625 $params = array(
1626 'userid' => $userid
1627 );
1628 $params = self::validate_parameters(self::get_blocked_users_parameters(), $params);
1629 $userid = $params['userid'];
1630
1631 // Validate context.
1632 $context = context_system::instance();
1633 self::validate_context($context);
1634
1635 // Check if private messaging between users is allowed.
1636 if (empty($CFG->messaging)) {
1637 throw new moodle_exception('disabled', 'message');
1638 }
1639
4485f7c5
JL
1640 $user = core_user::get_user($userid, '*', MUST_EXIST);
1641 core_user::require_active_user($user);
60ab2e1b
JL
1642
1643 // Check if we have permissions for retrieve the information.
1644 if ($userid != $USER->id and !has_capability('moodle/site:readallmessages', $context)) {
1645 throw new moodle_exception('accessdenied', 'admin');
1646 }
1647
1648 // Now, we can get safely all the blocked users.
1649 $users = message_get_blocked_users($user);
1650
1651 $blockedusers = array();
1652 foreach ($users as $user) {
1653 $newuser = array(
1654 'id' => $user->id,
1655 'fullname' => fullname($user),
1656 );
0b074e88 1657
d85bedf7
JL
1658 $userpicture = new user_picture($user);
1659 $userpicture->size = 1; // Size f1.
1660 $newuser['profileimageurl'] = $userpicture->get_url($PAGE)->out(false);
60ab2e1b
JL
1661
1662 $blockedusers[] = $newuser;
1663 }
1664
1665 $results = array(
1666 'users' => $blockedusers,
1667 'warnings' => $warnings
1668 );
1669 return $results;
1670 }
1671
1672 /**
1673 * Get blocked users return description.
1674 *
1675 * @return external_single_structure
1676 * @since 2.9
1677 */
1678 public static function get_blocked_users_returns() {
1679 return new external_single_structure(
1680 array(
1681 'users' => new external_multiple_structure(
1682 new external_single_structure(
1683 array(
1684 'id' => new external_value(PARAM_INT, 'User ID'),
1685 'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
1686 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL)
1687 )
1688 ),
1689 'List of blocked users'
1690 ),
1691 'warnings' => new external_warnings()
1692 )
1693 );
1694 }
1695
31c474da
JL
1696 /**
1697 * Returns description of method parameters
1698 *
1699 * @return external_function_parameters
1700 * @since 2.9
1701 */
1702 public static function mark_message_read_parameters() {
1703 return new external_function_parameters(
1704 array(
1705 'messageid' => new external_value(PARAM_INT, 'id of the message (in the message table)'),
1706 'timeread' => new external_value(PARAM_INT, 'timestamp for when the message should be marked read')
1707 )
1708 );
1709 }
1710
1711 /**
1712 * Mark a single message as read, trigger message_viewed event
1713 *
1714 * @param int $messageid id of the message (in the message table)
1715 * @param int $timeread timestamp for when the message should be marked read
1716 * @return external_description
1717 * @throws invalid_parameter_exception
1718 * @throws moodle_exception
1719 * @since 2.9
1720 */
1721 public static function mark_message_read($messageid, $timeread) {
1722 global $CFG, $DB, $USER;
31c474da
JL
1723
1724 // Check if private messaging between users is allowed.
1725 if (empty($CFG->messaging)) {
1726 throw new moodle_exception('disabled', 'message');
1727 }
1728
1729 // Warnings array, it can be empty at the end but is mandatory.
1730 $warnings = array();
1731
1732 // Validate params.
1733 $params = array(
1734 'messageid' => $messageid,
1735 'timeread' => $timeread
1736 );
1737 $params = self::validate_parameters(self::mark_message_read_parameters(), $params);
1738
1739 // Validate context.
1740 $context = context_system::instance();
1741 self::validate_context($context);
1742
1743 $message = $DB->get_record('message', array('id' => $params['messageid']), '*', MUST_EXIST);
1744
1745 if ($message->useridto != $USER->id) {
1746 throw new invalid_parameter_exception('Invalid messageid, you don\'t have permissions to mark this message as read');
1747 }
1748
1749 $messageid = message_mark_message_read($message, $params['timeread']);
1750
1751 $results = array(
1752 'messageid' => $messageid,
1753 'warnings' => $warnings
1754 );
1755 return $results;
1756 }
1757
1758 /**
1759 * Returns description of method result value
1760 *
1761 * @return external_description
1762 * @since 2.9
1763 */
1764 public static function mark_message_read_returns() {
1765 return new external_single_structure(
1766 array(
1767 'messageid' => new external_value(PARAM_INT, 'the id of the message in the message_read table'),
1768 'warnings' => new external_warnings()
1769 )
1770 );
1771 }
1772
8c55bd6c
RW
1773 /**
1774 * Mark all messages as read parameters description.
1775 *
1776 * @return external_function_parameters
1777 * @since 3.2
1778 */
1779 public static function mark_all_messages_as_read_parameters() {
1780 return new external_function_parameters(
1781 array(
1782 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
1783 'useridfrom' => new external_value(
1784 PARAM_INT, 'the user id who send the message, 0 for any user. -10 or -20 for no-reply or support user',
1785 VALUE_DEFAULT, 0),
1786 )
1787 );
1788 }
1789
1790 /**
1791 * Mark all notifications as read function.
1792 *
1793 * @since 3.2
1794 * @throws invalid_parameter_exception
1795 * @throws moodle_exception
1796 * @param int $useridto the user id who received the message
1797 * @param int $useridfrom the user id who send the message. -10 or -20 for no-reply or support user
1798 * @return external_description
1799 */
1800 public static function mark_all_messages_as_read($useridto, $useridfrom) {
1801 global $CFG, $USER;
1802
1803 $params = self::validate_parameters(
1804 self::mark_all_messages_as_read_parameters(),
1805 array(
1806 'useridto' => $useridto,
1807 'useridfrom' => $useridfrom,
1808 )
1809 );
1810
1811 $context = context_system::instance();
1812 self::validate_context($context);
1813
1814 $useridto = $params['useridto'];
1815 $useridfrom = $params['useridfrom'];
1816
1817 if (!empty($useridto)) {
1818 if (core_user::is_real_user($useridto)) {
1819 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
1820 } else {
1821 throw new moodle_exception('invaliduser');
1822 }
1823 }
1824
1825 if (!empty($useridfrom)) {
1826 // We use get_user here because the from user can be the noreply or support user.
1827 $userfrom = core_user::get_user($useridfrom, '*', MUST_EXIST);
1828 }
1829
1830 // Check if the current user is the sender/receiver or just a privileged user.
1831 if ($useridto != $USER->id and $useridfrom != $USER->id and
1832 // deleteanymessage seems more reasonable here than readallmessages.
1833 !has_capability('moodle/site:deleteanymessage', $context)) {
1834 throw new moodle_exception('accessdenied', 'admin');
1835 }
1836
1837 message_mark_all_read_for_user($useridto, $useridfrom, MESSAGE_TYPE_MESSAGE);
1838
1839 return true;
1840 }
1841
1842 /**
1843 * Mark all notifications as read return description.
1844 *
1845 * @return external_single_structure
1846 * @since 3.2
1847 */
1848 public static function mark_all_messages_as_read_returns() {
1849 return new external_value(PARAM_BOOL, 'True if the messages were marked read, false otherwise');
1850 }
1851
dec0cd99
MN
1852 /**
1853 * Returns description of method parameters.
1854 *
1855 * @return external_function_parameters
1856 * @since 3.2
1857 */
1858 public static function delete_conversation_parameters() {
1859 return new external_function_parameters(
1860 array(
1861 'userid' => new external_value(PARAM_INT, 'The user id of who we want to delete the conversation for'),
1862 'otheruserid' => new external_value(PARAM_INT, 'The user id of the other user in the conversation'),
1863 )
1864 );
1865 }
1866
1867 /**
1868 * Deletes a conversation.
1869 *
1870 * @param int $userid The user id of who we want to delete the conversation for
1871 * @param int $otheruserid The user id of the other user in the conversation
1872 * @return array
1873 * @throws moodle_exception
1874 * @since 3.2
1875 */
1876 public static function delete_conversation($userid, $otheruserid) {
1877 global $CFG;
1878
1879 // Check if private messaging between users is allowed.
1880 if (empty($CFG->messaging)) {
1881 throw new moodle_exception('disabled', 'message');
1882 }
1883
1884 // Warnings array, it can be empty at the end but is mandatory.
1885 $warnings = array();
1886
1887 // Validate params.
1888 $params = array(
1889 'userid' => $userid,
1890 'otheruserid' => $otheruserid,
1891 );
1892 $params = self::validate_parameters(self::delete_conversation_parameters(), $params);
1893
1894 // Validate context.
1895 $context = context_system::instance();
1896 self::validate_context($context);
1897
1898 $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
1899 core_user::require_active_user($user);
1900
1901 if (\core_message\api::can_delete_conversation($user->id)) {
1902 $status = \core_message\api::delete_conversation($user->id, $otheruserid);
1903 } else {
1904 throw new moodle_exception('You do not have permission to delete messages');
1905 }
1906
1907 $results = array(
1908 'status' => $status,
1909 'warnings' => $warnings
1910 );
1911
1912 return $results;
1913 }
1914
1915 /**
1916 * Returns description of method result value.
1917 *
1918 * @return external_description
1919 * @since 3.2
1920 */
1921 public static function delete_conversation_returns() {
1922 return new external_single_structure(
1923 array(
1924 'status' => new external_value(PARAM_BOOL, 'True if the conversation was deleted, false otherwise'),
1925 'warnings' => new external_warnings()
1926 )
1927 );
1928 }
1929
419b1128
JL
1930 /**
1931 * Returns description of method parameters
1932 *
1933 * @return external_function_parameters
1934 * @since 3.1
1935 */
1936 public static function delete_message_parameters() {
1937 return new external_function_parameters(
1938 array(
1939 'messageid' => new external_value(PARAM_INT, 'The message id'),
1940 'userid' => new external_value(PARAM_INT, 'The user id of who we want to delete the message for'),
1941 'read' => new external_value(PARAM_BOOL, 'If is a message read', VALUE_DEFAULT, true)
1942 )
1943 );
1944 }
1945
1946 /**
1947 * Deletes a message
1948 *
1949 * @param int $messageid the message id
1950 * @param int $userid the user id of who we want to delete the message for
1951 * @param bool $read if is a message read (default to true)
1952 * @return external_description
1953 * @throws moodle_exception
1954 * @since 3.1
1955 */
1956 public static function delete_message($messageid, $userid, $read = true) {
1957 global $CFG, $DB;
419b1128
JL
1958
1959 // Check if private messaging between users is allowed.
1960 if (empty($CFG->messaging)) {
1961 throw new moodle_exception('disabled', 'message');
1962 }
1963
1964 // Warnings array, it can be empty at the end but is mandatory.
1965 $warnings = array();
1966
1967 // Validate params.
1968 $params = array(
1969 'messageid' => $messageid,
1970 'userid' => $userid,
1971 'read' => $read
1972 );
1973 $params = self::validate_parameters(self::delete_message_parameters(), $params);
1974
1975 // Validate context.
1976 $context = context_system::instance();
1977 self::validate_context($context);
1978
1979 $messagestable = $params['read'] ? 'message_read' : 'message';
1980 $message = $DB->get_record($messagestable, array('id' => $params['messageid']), '*', MUST_EXIST);
1981
1982 $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
1983 core_user::require_active_user($user);
1984
1985 $status = false;
1986 if (message_can_delete_message($message, $user->id)) {
1987 $status = message_delete_message($message, $user->id);;
1988 } else {
1989 throw new moodle_exception('You do not have permission to delete this message');
1990 }
1991
1992 $results = array(
1993 'status' => $status,
1994 'warnings' => $warnings
1995 );
1996 return $results;
1997 }
1998
1999 /**
2000 * Returns description of method result value
2001 *
2002 * @return external_description
2003 * @since 3.1
2004 */
2005 public static function delete_message_returns() {
2006 return new external_single_structure(
2007 array(
2008 'status' => new external_value(PARAM_BOOL, 'True if the message was deleted, false otherwise'),
2009 'warnings' => new external_warnings()
2010 )
2011 );
2012 }
2013
a0eabdd3
RW
2014 /**
2015 * Returns description of method parameters
2016 *
2017 * @return external_function_parameters
2018 * @since 3.2
2019 */
2020 public static function message_processor_config_form_parameters() {
2021 return new external_function_parameters(
2022 array(
2023 'userid' => new external_value(PARAM_INT, 'id of the user, 0 for current user', VALUE_REQUIRED),
2024 'name' => new external_value(PARAM_TEXT, 'The name of the message processor'),
2025 'formvalues' => new external_multiple_structure(
2026 new external_single_structure(
2027 array(
2028 'name' => new external_value(PARAM_TEXT, 'name of the form element', VALUE_REQUIRED),
2029 'value' => new external_value(PARAM_RAW, 'value of the form element', VALUE_REQUIRED),
2030 )
2031 ),
2032 'Config form values',
2033 VALUE_REQUIRED
2034 ),
2035 )
2036 );
2037 }
2038
2039 /**
2040 * Processes a message processor config form.
2041 *
2042 * @param int $userid the user id
2043 * @param string $name the name of the processor
2044 * @param array $formvalues the form values
2045 * @return external_description
2046 * @throws moodle_exception
2047 * @since 3.2
2048 */
2049 public static function message_processor_config_form($userid, $name, $formvalues) {
2050 $params = self::validate_parameters(
2051 self::message_processor_config_form_parameters(),
2052 array(
2053 'userid' => $userid,
2054 'name' => $name,
2055 'formvalues' => $formvalues,
2056 )
2057 );
2058
2059 if (empty($params['userid'])) {
2060 $params['userid'] = $USER->id;
2061 }
2062
2063 $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
2064 core_user::require_active_user($user);
2065
2066 $processor = get_message_processor($name);
2067 $preferences = [];
2068 $form = new stdClass();
2069
2070 foreach ($formvalues as $formvalue) {
2071 $form->$formvalue['name'] = $formvalue['value'];
2072 }
2073
2074 $processor->process_form($form, $preferences);
2075
2076 if (!empty($preferences)) {
2077 set_user_preferences($preferences, $userid);
2078 }
2079 }
2080
2081 /**
2082 * Returns description of method result value
2083 *
2084 * @return external_description
2085 * @since 3.2
2086 */
2087 public static function message_processor_config_form_returns() {
2088 return null;
2089 }
a623b6b8 2090}