MDL-56514 core_message: add missing is messaging enabled checks
[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 54 'text' => new external_value(PARAM_RAW, 'the text of the message'),
14968ca9 55 'textformat' => new external_format_value('text', VALUE_DEFAULT, FORMAT_MOODLE),
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.
837941e9 75 if (empty($CFG->messaging)) {
a623b6b8
JM
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) {
343ba16c 217 global $CFG, $USER;
436bbf89
DM
218
219 // Check if messaging is enabled.
837941e9 220 if (empty($CFG->messaging)) {
436bbf89
DM
221 throw new moodle_exception('disabled', 'message');
222 }
223
343ba16c
SL
224 if (empty($userid)) {
225 $userid = $USER->id;
226 }
227
228 // Validate context.
229 $context = context_system::instance();
230 self::validate_context($context);
231
232 $capability = 'moodle/site:manageallmessaging';
233 if (($USER->id != $userid) && !has_capability($capability, $context)) {
234 throw new required_capability_exception($context, $capability, 'nopermissions', '');
235 }
236
34c2f347 237 $params = array('userids' => $userids, 'userid' => $userid);
d6731600
FM
238 $params = self::validate_parameters(self::create_contacts_parameters(), $params);
239
240 $warnings = array();
241 foreach ($params['userids'] as $id) {
34c2f347 242 if (!message_add_contact($id, 0, $userid)) {
d6731600
FM
243 $warnings[] = array(
244 'item' => 'user',
245 'itemid' => $id,
246 'warningcode' => 'contactnotcreated',
247 'message' => 'The contact could not be created'
248 );
249 }
250 }
251 return $warnings;
252 }
253
254 /**
255 * Create contacts return description.
256 *
257 * @return external_description
5bcfd504 258 * @since Moodle 2.5
d6731600
FM
259 */
260 public static function create_contacts_returns() {
261 return new external_warnings();
262 }
263
264 /**
265 * Delete contacts parameters description.
266 *
267 * @return external_function_parameters
5bcfd504 268 * @since Moodle 2.5
d6731600
FM
269 */
270 public static function delete_contacts_parameters() {
271 return new external_function_parameters(
272 array(
273 'userids' => new external_multiple_structure(
274 new external_value(PARAM_INT, 'User ID'),
275 'List of user IDs'
34c2f347
MN
276 ),
277 'userid' => new external_value(PARAM_INT, 'The id of the user we are deleting the contacts for, 0 for the
278 current user', VALUE_DEFAULT, 0)
d6731600
FM
279 )
280 );
281 }
282
283 /**
284 * Delete contacts.
285 *
286 * @param array $userids array of user IDs.
34c2f347 287 * @param int $userid The id of the user we are deleting the contacts for
d6731600 288 * @return null
5bcfd504 289 * @since Moodle 2.5
d6731600 290 */
34c2f347 291 public static function delete_contacts($userids, $userid = 0) {
343ba16c 292 global $CFG, $USER;
436bbf89
DM
293
294 // Check if messaging is enabled.
837941e9 295 if (empty($CFG->messaging)) {
436bbf89
DM
296 throw new moodle_exception('disabled', 'message');
297 }
298
343ba16c
SL
299 if (empty($userid)) {
300 $userid = $USER->id;
301 }
302
303 // Validate context.
304 $context = context_system::instance();
305 self::validate_context($context);
306
307 $capability = 'moodle/site:manageallmessaging';
308 if (($USER->id != $userid) && !has_capability($capability, $context)) {
309 throw new required_capability_exception($context, $capability, 'nopermissions', '');
310 }
311
34c2f347 312 $params = array('userids' => $userids, 'userid' => $userid);
d6731600
FM
313 $params = self::validate_parameters(self::delete_contacts_parameters(), $params);
314
315 foreach ($params['userids'] as $id) {
34c2f347 316 message_remove_contact($id, $userid);
d6731600
FM
317 }
318
319 return null;
320 }
321
322 /**
323 * Delete contacts return description.
324 *
325 * @return external_description
5bcfd504 326 * @since Moodle 2.5
d6731600
FM
327 */
328 public static function delete_contacts_returns() {
329 return null;
330 }
331
332 /**
333 * Block contacts parameters description.
334 *
335 * @return external_function_parameters
5bcfd504 336 * @since Moodle 2.5
d6731600
FM
337 */
338 public static function block_contacts_parameters() {
339 return new external_function_parameters(
340 array(
341 'userids' => new external_multiple_structure(
342 new external_value(PARAM_INT, 'User ID'),
343 'List of user IDs'
34c2f347
MN
344 ),
345 'userid' => new external_value(PARAM_INT, 'The id of the user we are blocking the contacts for, 0 for the
346 current user', VALUE_DEFAULT, 0)
d6731600
FM
347 )
348 );
349 }
350
351 /**
352 * Block contacts.
353 *
354 * @param array $userids array of user IDs.
34c2f347 355 * @param int $userid The id of the user we are blocking the contacts for
d6731600 356 * @return external_description
5bcfd504 357 * @since Moodle 2.5
d6731600 358 */
34c2f347 359 public static function block_contacts($userids, $userid = 0) {
343ba16c 360 global $CFG, $USER;
436bbf89
DM
361
362 // Check if messaging is enabled.
837941e9 363 if (empty($CFG->messaging)) {
436bbf89
DM
364 throw new moodle_exception('disabled', 'message');
365 }
366
343ba16c
SL
367 if (empty($userid)) {
368 $userid = $USER->id;
369 }
370
371 // Validate context.
372 $context = context_system::instance();
373 self::validate_context($context);
374
375 $capability = 'moodle/site:manageallmessaging';
376 if (($USER->id != $userid) && !has_capability($capability, $context)) {
377 throw new required_capability_exception($context, $capability, 'nopermissions', '');
378 }
379
34c2f347 380 $params = array('userids' => $userids, 'userid' => $userid);
d6731600
FM
381 $params = self::validate_parameters(self::block_contacts_parameters(), $params);
382
383 $warnings = array();
384 foreach ($params['userids'] as $id) {
34c2f347 385 if (!message_block_contact($id, $userid)) {
d6731600
FM
386 $warnings[] = array(
387 'item' => 'user',
388 'itemid' => $id,
389 'warningcode' => 'contactnotblocked',
390 'message' => 'The contact could not be blocked'
391 );
392 }
393 }
394 return $warnings;
395 }
396
397 /**
398 * Block contacts return description.
399 *
400 * @return external_description
5bcfd504 401 * @since Moodle 2.5
d6731600
FM
402 */
403 public static function block_contacts_returns() {
404 return new external_warnings();
405 }
406
407 /**
408 * Unblock contacts parameters description.
409 *
410 * @return external_function_parameters
5bcfd504 411 * @since Moodle 2.5
d6731600
FM
412 */
413 public static function unblock_contacts_parameters() {
414 return new external_function_parameters(
415 array(
416 'userids' => new external_multiple_structure(
417 new external_value(PARAM_INT, 'User ID'),
418 'List of user IDs'
34c2f347
MN
419 ),
420 'userid' => new external_value(PARAM_INT, 'The id of the user we are unblocking the contacts for, 0 for the
421 current user', VALUE_DEFAULT, 0)
d6731600
FM
422 )
423 );
424 }
425
426 /**
427 * Unblock contacts.
428 *
429 * @param array $userids array of user IDs.
34c2f347 430 * @param int $userid The id of the user we are unblocking the contacts for
d6731600 431 * @return null
5bcfd504 432 * @since Moodle 2.5
d6731600 433 */
34c2f347 434 public static function unblock_contacts($userids, $userid = 0) {
343ba16c 435 global $CFG, $USER;
436bbf89
DM
436
437 // Check if messaging is enabled.
837941e9 438 if (empty($CFG->messaging)) {
436bbf89
DM
439 throw new moodle_exception('disabled', 'message');
440 }
441
343ba16c
SL
442 if (empty($userid)) {
443 $userid = $USER->id;
444 }
445
446 // Validate context.
447 $context = context_system::instance();
448 self::validate_context($context);
449
450 $capability = 'moodle/site:manageallmessaging';
451 if (($USER->id != $userid) && !has_capability($capability, $context)) {
452 throw new required_capability_exception($context, $capability, 'nopermissions', '');
453 }
454
34c2f347 455 $params = array('userids' => $userids, 'userid' => $userid);
d6731600
FM
456 $params = self::validate_parameters(self::unblock_contacts_parameters(), $params);
457
458 foreach ($params['userids'] as $id) {
34c2f347 459 message_unblock_contact($id, $userid);
d6731600
FM
460 }
461
462 return null;
463 }
464
465 /**
466 * Unblock contacts return description.
467 *
468 * @return external_description
5bcfd504 469 * @since Moodle 2.5
d6731600
FM
470 */
471 public static function unblock_contacts_returns() {
472 return null;
473 }
474
a3e3a3a1
MN
475 /**
476 * Return the structure of a message area contact.
477 *
478 * @return external_single_structure
479 * @since Moodle 3.2
480 */
481 private static function get_messagearea_contact_structure() {
482 return new external_single_structure(
483 array(
484 'userid' => new external_value(PARAM_INT, 'The user\'s id'),
485 'fullname' => new external_value(PARAM_NOTAGS, 'The user\'s name'),
486 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL'),
487 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL'),
5bf0ff27 488 'ismessaging' => new external_value(PARAM_BOOL, 'If we are messaging the user'),
89a70ba1 489 'sentfromcurrentuser' => new external_value(PARAM_BOOL, 'Was the last message sent from the current user?'),
a3e3a3a1
MN
490 'lastmessage' => new external_value(PARAM_NOTAGS, 'The user\'s last message'),
491 'messageid' => new external_value(PARAM_INT, 'The unique search message id', VALUE_DEFAULT, null),
492 'isonline' => new external_value(PARAM_BOOL, 'The user\'s online status'),
493 'isread' => new external_value(PARAM_BOOL, 'If the user has read the message'),
dd0c1403 494 'isblocked' => new external_value(PARAM_BOOL, 'If the user has been blocked'),
a3e3a3a1
MN
495 'unreadcount' => new external_value(PARAM_INT, 'The number of unread messages in this conversation',
496 VALUE_DEFAULT, null),
497 )
498 );
499 }
500
94e1db61
MN
501 /**
502 * Return the structure of a message area message.
503 *
504 * @return external_single_structure
505 * @since Moodle 3.2
506 */
507 private static function get_messagearea_message_structure() {
508 return new external_single_structure(
509 array(
510 'id' => new external_value(PARAM_INT, 'The id of the message'),
89a70ba1
MN
511 'useridfrom' => new external_value(PARAM_INT, 'The id of the user who sent the message'),
512 'useridto' => new external_value(PARAM_INT, 'The id of the user who received the message'),
94e1db61
MN
513 'text' => new external_value(PARAM_RAW, 'The text of the message'),
514 'displayblocktime' => new external_value(PARAM_BOOL, 'Should we display the block time?'),
515 'blocktime' => new external_value(PARAM_NOTAGS, 'The time to display above the message'),
516 'position' => new external_value(PARAM_ALPHA, 'The position of the text'),
517 'timesent' => new external_value(PARAM_NOTAGS, 'The time the message was sent'),
518 'isread' => new external_value(PARAM_INT, 'Determines if the message was read or not'),
519 )
520 );
521 }
522
cd03b8d7 523 /**
48e8bdba 524 * Get messagearea search users in course parameters.
cd03b8d7
MN
525 *
526 * @return external_function_parameters
527 * @since 3.2
528 */
48e8bdba 529 public static function data_for_messagearea_search_users_in_course_parameters() {
cd03b8d7
MN
530 return new external_function_parameters(
531 array(
532 'userid' => new external_value(PARAM_INT, 'The id of the user who is performing the search'),
533 'courseid' => new external_value(PARAM_INT, 'The id of the course'),
534 'search' => new external_value(PARAM_RAW, 'The string being searched'),
535 'limitfrom' => new external_value(PARAM_INT, 'Limit from', VALUE_DEFAULT, 0),
536 'limitnum' => new external_value(PARAM_INT, 'Limit number', VALUE_DEFAULT, 0)
537 )
538 );
539 }
540
541 /**
48e8bdba 542 * Get messagearea search users in course results.
cd03b8d7
MN
543 *
544 * @param int $userid The id of the user who is performing the search
545 * @param int $courseid The id of the course
546 * @param string $search The string being searched
547 * @param int $limitfrom
548 * @param int $limitnum
549 * @return stdClass
550 * @throws moodle_exception
551 * @since 3.2
552 */
48e8bdba 553 public static function data_for_messagearea_search_users_in_course($userid, $courseid, $search, $limitfrom = 0,
de55cb1b 554 $limitnum = 0) {
837941e9 555 global $CFG, $PAGE, $USER;
cd03b8d7
MN
556
557 // Check if messaging is enabled.
837941e9 558 if (empty($CFG->messaging)) {
cd03b8d7
MN
559 throw new moodle_exception('disabled', 'message');
560 }
561
837941e9
MN
562 $systemcontext = context_system::instance();
563
cd03b8d7
MN
564 $params = array(
565 'userid' => $userid,
566 'courseid' => $courseid,
567 'search' => $search,
568 'limitfrom' => $limitfrom,
569 'limitnum' => $limitnum
570 );
48e8bdba 571 self::validate_parameters(self::data_for_messagearea_search_users_in_course_parameters(), $params);
837941e9 572 self::validate_context($systemcontext);
cd03b8d7 573
837941e9
MN
574 if (($USER->id != $userid) && !has_capability('moodle/site:readallmessages', $systemcontext)) {
575 throw new moodle_exception('You do not have permission to perform this action.');
576 }
cd03b8d7 577
de55cb1b
MN
578 $users = \core_message\api::search_users_in_course($userid, $courseid, $search, $limitfrom, $limitnum);
579 $results = new \core_message\output\messagearea\user_search_results($users);
cd03b8d7
MN
580
581 $renderer = $PAGE->get_renderer('core_message');
de55cb1b 582 return $results->export_for_template($renderer);
cd03b8d7
MN
583 }
584
585 /**
48e8bdba 586 * Get messagearea search users in course returns.
cd03b8d7
MN
587 *
588 * @return external_single_structure
589 * @since 3.2
590 */
48e8bdba 591 public static function data_for_messagearea_search_users_in_course_returns() {
cd03b8d7
MN
592 return new external_single_structure(
593 array(
cd03b8d7 594 'contacts' => new external_multiple_structure(
a3e3a3a1 595 self::get_messagearea_contact_structure()
cd03b8d7
MN
596 ),
597 )
598 );
599 }
600
601 /**
48e8bdba 602 * Get messagearea search users parameters.
cd03b8d7
MN
603 *
604 * @return external_function_parameters
605 * @since 3.2
606 */
48e8bdba 607 public static function data_for_messagearea_search_users_parameters() {
cd03b8d7
MN
608 return new external_function_parameters(
609 array(
610 'userid' => new external_value(PARAM_INT, 'The id of the user who is performing the search'),
611 'search' => new external_value(PARAM_RAW, 'The string being searched'),
612 'limitnum' => new external_value(PARAM_INT, 'Limit number', VALUE_DEFAULT, 0)
613 )
614 );
615 }
616
617 /**
48e8bdba 618 * Get messagearea search users results.
cd03b8d7
MN
619 *
620 * @param int $userid The id of the user who is performing the search
621 * @param string $search The string being searched
622 * @param int $limitnum
623 * @return stdClass
624 * @throws moodle_exception
625 * @since 3.2
626 */
48e8bdba 627 public static function data_for_messagearea_search_users($userid, $search, $limitnum = 0) {
837941e9 628 global $CFG, $PAGE, $USER;
cd03b8d7
MN
629
630 // Check if messaging is enabled.
837941e9 631 if (empty($CFG->messaging)) {
cd03b8d7
MN
632 throw new moodle_exception('disabled', 'message');
633 }
634
837941e9
MN
635 $systemcontext = context_system::instance();
636
cd03b8d7
MN
637 $params = array(
638 'userid' => $userid,
639 'search' => $search,
640 'limitnum' => $limitnum
641 );
48e8bdba 642 self::validate_parameters(self::data_for_messagearea_search_users_parameters(), $params);
837941e9 643 self::validate_context($systemcontext);
cd03b8d7 644
837941e9
MN
645 if (($USER->id != $userid) && !has_capability('moodle/site:readallmessages', $systemcontext)) {
646 throw new moodle_exception('You do not have permission to perform this action.');
647 }
cd03b8d7 648
de55cb1b
MN
649 list($contacts, $courses, $noncontacts) = \core_message\api::search_users($userid, $search, $limitnum);
650 $search = new \core_message\output\messagearea\user_search_results($contacts, $courses, $noncontacts);
cd03b8d7
MN
651
652 $renderer = $PAGE->get_renderer('core_message');
653 return $search->export_for_template($renderer);
654 }
655
656 /**
48e8bdba 657 * Get messagearea search users returns.
cd03b8d7
MN
658 *
659 * @return external_single_structure
660 * @since 3.2
661 */
48e8bdba 662 public static function data_for_messagearea_search_users_returns() {
cd03b8d7
MN
663 return new external_single_structure(
664 array(
cd03b8d7 665 'contacts' => new external_multiple_structure(
a3e3a3a1 666 self::get_messagearea_contact_structure()
cd03b8d7 667 ),
cd03b8d7
MN
668 'courses' => new external_multiple_structure(
669 new external_single_structure(
670 array(
671 'id' => new external_value(PARAM_INT, 'The course id'),
672 'shortname' => new external_value(PARAM_NOTAGS, 'The course shortname'),
673 'fullname' => new external_value(PARAM_NOTAGS, 'The course fullname'),
674 )
675 )
676 ),
cd03b8d7 677 'noncontacts' => new external_multiple_structure(
a3e3a3a1 678 self::get_messagearea_contact_structure()
cd03b8d7
MN
679 )
680 )
681 );
682 }
683
684 /**
685 * Get messagearea search messages parameters.
686 *
687 * @return external_function_parameters
688 * @since 3.2
689 */
690 public static function data_for_messagearea_search_messages_parameters() {
691 return new external_function_parameters(
692 array(
693 'userid' => new external_value(PARAM_INT, 'The id of the user who is performing the search'),
694 'search' => new external_value(PARAM_RAW, 'The string being searched'),
695 'limitfrom' => new external_value(PARAM_INT, 'Limit from', VALUE_DEFAULT, 0),
696 'limitnum' => new external_value(PARAM_INT, 'Limit number', VALUE_DEFAULT, 0)
697 )
698 );
699 }
700
701 /**
702 * Get messagearea search messages results.
703 *
704 * @param int $userid The id of the user who is performing the search
705 * @param string $search The string being searched
706 * @param int $limitfrom
707 * @param int $limitnum
708 * @return stdClass
709 * @throws moodle_exception
710 * @since 3.2
711 */
712 public static function data_for_messagearea_search_messages($userid, $search, $limitfrom = 0, $limitnum = 0) {
837941e9 713 global $CFG, $PAGE, $USER;
cd03b8d7
MN
714
715 // Check if messaging is enabled.
837941e9 716 if (empty($CFG->messaging)) {
cd03b8d7
MN
717 throw new moodle_exception('disabled', 'message');
718 }
719
837941e9
MN
720 $systemcontext = context_system::instance();
721
cd03b8d7
MN
722 $params = array(
723 'userid' => $userid,
724 'search' => $search,
725 'limitfrom' => $limitfrom,
726 'limitnum' => $limitnum
727
728 );
729 self::validate_parameters(self::data_for_messagearea_search_messages_parameters(), $params);
837941e9 730 self::validate_context($systemcontext);
cd03b8d7 731
837941e9
MN
732 if (($USER->id != $userid) && !has_capability('moodle/site:readallmessages', $systemcontext)) {
733 throw new moodle_exception('You do not have permission to perform this action.');
734 }
cd03b8d7 735
de55cb1b
MN
736 $messages = \core_message\api::search_messages($userid, $search, $limitfrom, $limitnum);
737 $results = new \core_message\output\messagearea\message_search_results($messages);
cd03b8d7
MN
738
739 $renderer = $PAGE->get_renderer('core_message');
de55cb1b 740 return $results->export_for_template($renderer);
cd03b8d7
MN
741 }
742
743 /**
744 * Get messagearea search messages returns.
745 *
746 * @return external_single_structure
747 * @since 3.2
748 */
749 public static function data_for_messagearea_search_messages_returns() {
750 return new external_single_structure(
751 array(
cd03b8d7 752 'contacts' => new external_multiple_structure(
a3e3a3a1 753 self::get_messagearea_contact_structure()
cd03b8d7
MN
754 )
755 )
756 );
757 }
758
9aa012b5 759 /**
49aaadc3 760 * The messagearea conversations parameters.
9aa012b5
MN
761 *
762 * @return external_function_parameters
49aaadc3 763 * @since 3.2
9aa012b5
MN
764 */
765 public static function data_for_messagearea_conversations_parameters() {
766 return new external_function_parameters(
767 array(
768 'userid' => new external_value(PARAM_INT, 'The id of the user who we are viewing conversations for'),
769 'limitfrom' => new external_value(PARAM_INT, 'Limit from', VALUE_DEFAULT, 0),
770 'limitnum' => new external_value(PARAM_INT, 'Limit number', VALUE_DEFAULT, 0)
771 )
772 );
773 }
774
775 /**
776 * Get messagearea conversations.
777 *
778 * @param int $userid The id of the user who we are viewing conversations for
779 * @param int $limitfrom
780 * @param int $limitnum
49aaadc3
MN
781 * @return stdClass
782 * @throws moodle_exception
783 * @since 3.2
9aa012b5
MN
784 */
785 public static function data_for_messagearea_conversations($userid, $limitfrom = 0, $limitnum = 0) {
837941e9 786 global $CFG, $PAGE, $USER;
9aa012b5
MN
787
788 // Check if messaging is enabled.
837941e9 789 if (empty($CFG->messaging)) {
9aa012b5
MN
790 throw new moodle_exception('disabled', 'message');
791 }
792
837941e9
MN
793 $systemcontext = context_system::instance();
794
9aa012b5
MN
795 $params = array(
796 'userid' => $userid,
797 'limitfrom' => $limitfrom,
798 'limitnum' => $limitnum
799 );
800 self::validate_parameters(self::data_for_messagearea_conversations_parameters(), $params);
837941e9 801 self::validate_context($systemcontext);
9aa012b5 802
837941e9
MN
803 if (($USER->id != $userid) && !has_capability('moodle/site:readallmessages', $systemcontext)) {
804 throw new moodle_exception('You do not have permission to perform this action.');
805 }
9aa012b5 806
de55cb1b
MN
807 $conversations = \core_message\api::get_conversations($userid, $limitfrom, $limitnum);
808 $conversations = new \core_message\output\messagearea\contacts(null, $conversations);
9aa012b5
MN
809
810 $renderer = $PAGE->get_renderer('core_message');
de55cb1b 811 return $conversations->export_for_template($renderer);
9aa012b5
MN
812 }
813
814 /**
49aaadc3 815 * The messagearea conversations return structure.
9aa012b5 816 *
49aaadc3
MN
817 * @return external_single_structure
818 * @since 3.2
9aa012b5
MN
819 */
820 public static function data_for_messagearea_conversations_returns() {
49aaadc3 821 return new external_single_structure(
9aa012b5 822 array(
9aa012b5 823 'contacts' => new external_multiple_structure(
a3e3a3a1 824 self::get_messagearea_contact_structure()
9aa012b5
MN
825 )
826 )
827 );
828 }
829
830 /**
49aaadc3 831 * The messagearea contacts return parameters.
9aa012b5
MN
832 *
833 * @return external_function_parameters
49aaadc3 834 * @since 3.2
9aa012b5
MN
835 */
836 public static function data_for_messagearea_contacts_parameters() {
837 return self::data_for_messagearea_conversations_parameters();
838 }
839
840 /**
841 * Get messagearea contacts parameters.
842 *
843 * @param int $userid The id of the user who we are viewing conversations for
844 * @param int $limitfrom
845 * @param int $limitnum
49aaadc3
MN
846 * @return stdClass
847 * @throws moodle_exception
848 * @since 3.2
9aa012b5
MN
849 */
850 public static function data_for_messagearea_contacts($userid, $limitfrom = 0, $limitnum = 0) {
837941e9 851 global $CFG, $PAGE, $USER;
9aa012b5
MN
852
853 // Check if messaging is enabled.
837941e9 854 if (empty($CFG->messaging)) {
9aa012b5
MN
855 throw new moodle_exception('disabled', 'message');
856 }
857
837941e9
MN
858 $systemcontext = context_system::instance();
859
9aa012b5
MN
860 $params = array(
861 'userid' => $userid,
862 'limitfrom' => $limitfrom,
863 'limitnum' => $limitnum
864 );
865 self::validate_parameters(self::data_for_messagearea_contacts_parameters(), $params);
837941e9 866 self::validate_context($systemcontext);
9aa012b5 867
837941e9
MN
868 if (($USER->id != $userid) && !has_capability('moodle/site:readallmessages', $systemcontext)) {
869 throw new moodle_exception('You do not have permission to perform this action.');
870 }
9aa012b5
MN
871
872 $contacts = \core_message\api::get_contacts($userid, $limitfrom, $limitnum);
de55cb1b 873 $contacts = new \core_message\output\messagearea\contacts(null, $contacts);
9aa012b5
MN
874
875 $renderer = $PAGE->get_renderer('core_message');
876 return $contacts->export_for_template($renderer);
877 }
878
879 /**
49aaadc3 880 * The messagearea contacts return structure.
9aa012b5 881 *
49aaadc3
MN
882 * @return external_single_structure
883 * @since 3.2
9aa012b5
MN
884 */
885 public static function data_for_messagearea_contacts_returns() {
886 return self::data_for_messagearea_conversations_returns();
887 }
888
3cd13828 889 /**
49aaadc3 890 * The messagearea messages parameters.
3cd13828
MN
891 *
892 * @return external_function_parameters
49aaadc3 893 * @since 3.2
3cd13828
MN
894 */
895 public static function data_for_messagearea_messages_parameters() {
896 return new external_function_parameters(
897 array(
898 'currentuserid' => new external_value(PARAM_INT, 'The current user\'s id'),
899 'otheruserid' => new external_value(PARAM_INT, 'The other user\'s id'),
900 'limitfrom' => new external_value(PARAM_INT, 'Limit from', VALUE_DEFAULT, 0),
8ec78c48
MN
901 'limitnum' => new external_value(PARAM_INT, 'Limit number', VALUE_DEFAULT, 0),
902 'newest' => new external_value(PARAM_BOOL, 'Newest first?', VALUE_DEFAULT, false),
3cd13828
MN
903 )
904 );
905 }
906
907 /**
908 * Get messagearea messages.
909 *
910 * @param int $currentuserid The current user's id
911 * @param int $otheruserid The other user's id
912 * @param int $limitfrom
913 * @param int $limitnum
8ec78c48 914 * @param boolean $newest
49aaadc3
MN
915 * @return stdClass
916 * @throws moodle_exception
917 * @since 3.2
3cd13828 918 */
7b55aaa1
MN
919 public static function data_for_messagearea_messages($currentuserid, $otheruserid, $limitfrom = 0, $limitnum = 0,
920 $newest = false) {
837941e9 921 global $CFG, $PAGE, $USER;
3cd13828
MN
922
923 // Check if messaging is enabled.
837941e9 924 if (empty($CFG->messaging)) {
3cd13828
MN
925 throw new moodle_exception('disabled', 'message');
926 }
927
837941e9
MN
928 $systemcontext = context_system::instance();
929
3cd13828
MN
930 $params = array(
931 'currentuserid' => $currentuserid,
932 'otheruserid' => $otheruserid,
933 'limitfrom' => $limitfrom,
8ec78c48
MN
934 'limitnum' => $limitnum,
935 'newest' => $newest
3cd13828
MN
936 );
937 self::validate_parameters(self::data_for_messagearea_messages_parameters(), $params);
837941e9 938 self::validate_context($systemcontext);
3cd13828 939
837941e9
MN
940 if (($USER->id != $currentuserid) && !has_capability('moodle/site:readallmessages', $systemcontext)) {
941 throw new moodle_exception('You do not have permission to perform this action.');
942 }
3cd13828 943
8ec78c48
MN
944 if ($newest) {
945 $sort = 'timecreated DESC';
946 } else {
947 $sort = 'timecreated ASC';
948 }
949 $messages = \core_message\api::get_messages($currentuserid, $otheruserid, $limitfrom, $limitnum, $sort);
de55cb1b 950 $messages = new \core_message\output\messagearea\messages($currentuserid, $otheruserid, $messages);
3cd13828
MN
951
952 $renderer = $PAGE->get_renderer('core_message');
953 return $messages->export_for_template($renderer);
954 }
955
956 /**
49aaadc3 957 * The messagearea messages return structure.
3cd13828 958 *
49aaadc3
MN
959 * @return external_single_structure
960 * @since 3.2
3cd13828
MN
961 */
962 public static function data_for_messagearea_messages_returns() {
49aaadc3 963 return new external_single_structure(
3cd13828 964 array(
7b55aaa1
MN
965 'iscurrentuser' => new external_value(PARAM_BOOL, 'Is the currently logged in user the user we are viewing
966 the messages on behalf of?'),
3cd13828
MN
967 'currentuserid' => new external_value(PARAM_INT, 'The current user\'s id'),
968 'otheruserid' => new external_value(PARAM_INT, 'The other user\'s id'),
969 'otheruserfullname' => new external_value(PARAM_NOTAGS, 'The other user\'s fullname'),
bf58081d 970 'isonline' => new external_value(PARAM_BOOL, 'The user\'s online status'),
3cd13828 971 'messages' => new external_multiple_structure(
94e1db61 972 self::get_messagearea_message_structure()
3cd13828
MN
973 )
974 )
975 );
976 }
977
c060cd49 978 /**
49aaadc3 979 * The get most recent message return parameters.
c060cd49
MN
980 *
981 * @return external_function_parameters
49aaadc3 982 * @since 3.2
c060cd49
MN
983 */
984 public static function data_for_messagearea_get_most_recent_message_parameters() {
985 return new external_function_parameters(
986 array(
987 'currentuserid' => new external_value(PARAM_INT, 'The current user\'s id'),
988 'otheruserid' => new external_value(PARAM_INT, 'The other user\'s id'),
989 )
990 );
991 }
992
993 /**
994 * Get the most recent message in a conversation.
995 *
996 * @param int $currentuserid The current user's id
997 * @param int $otheruserid The other user's id
49aaadc3
MN
998 * @return stdClass
999 * @throws moodle_exception
1000 * @since 3.2
c060cd49
MN
1001 */
1002 public static function data_for_messagearea_get_most_recent_message($currentuserid, $otheruserid) {
837941e9 1003 global $CFG, $PAGE, $USER;
c060cd49
MN
1004
1005 // Check if messaging is enabled.
837941e9 1006 if (empty($CFG->messaging)) {
c060cd49
MN
1007 throw new moodle_exception('disabled', 'message');
1008 }
1009
837941e9
MN
1010 $systemcontext = context_system::instance();
1011
c060cd49
MN
1012 $params = array(
1013 'currentuserid' => $currentuserid,
1014 'otheruserid' => $otheruserid
1015 );
1016 self::validate_parameters(self::data_for_messagearea_get_most_recent_message_parameters(), $params);
837941e9 1017 self::validate_context($systemcontext);
c060cd49 1018
837941e9
MN
1019 if (($USER->id != $currentuserid) && !has_capability('moodle/site:readallmessages', $systemcontext)) {
1020 throw new moodle_exception('You do not have permission to perform this action.');
1021 }
c060cd49
MN
1022
1023 $message = \core_message\api::get_most_recent_message($currentuserid, $otheruserid);
de55cb1b 1024 $message = new \core_message\output\messagearea\message($message);
c060cd49
MN
1025
1026 $renderer = $PAGE->get_renderer('core_message');
1027 return $message->export_for_template($renderer);
1028 }
1029
1030 /**
49aaadc3 1031 * The get most recent message return structure.
c060cd49
MN
1032 *
1033 * @return external_single_structure
49aaadc3 1034 * @since 3.2
c060cd49
MN
1035 */
1036 public static function data_for_messagearea_get_most_recent_message_returns() {
94e1db61 1037 return self::get_messagearea_message_structure();
c060cd49
MN
1038 }
1039
c6e97f54
MN
1040 /**
1041 * The get profile parameters.
1042 *
1043 * @return external_function_parameters
49aaadc3 1044 * @since 3.2
c6e97f54
MN
1045 */
1046 public static function data_for_messagearea_get_profile_parameters() {
1047 return new external_function_parameters(
1048 array(
1049 'currentuserid' => new external_value(PARAM_INT, 'The current user\'s id'),
1050 'otheruserid' => new external_value(PARAM_INT, 'The id of the user whose profile we want to view'),
1051 )
1052 );
1053 }
1054
1055 /**
1056 * Get the profile information for a contact.
1057 *
1058 * @param int $currentuserid The current user's id
1059 * @param int $otheruserid The id of the user whose profile we are viewing
49aaadc3
MN
1060 * @return stdClass
1061 * @throws moodle_exception
1062 * @since 3.2
c6e97f54
MN
1063 */
1064 public static function data_for_messagearea_get_profile($currentuserid, $otheruserid) {
837941e9 1065 global $CFG, $PAGE, $USER;
c6e97f54
MN
1066
1067 // Check if messaging is enabled.
837941e9 1068 if (empty($CFG->messaging)) {
c6e97f54
MN
1069 throw new moodle_exception('disabled', 'message');
1070 }
1071
837941e9
MN
1072 $systemcontext = context_system::instance();
1073
c6e97f54
MN
1074 $params = array(
1075 'currentuserid' => $currentuserid,
1076 'otheruserid' => $otheruserid
1077 );
1078 self::validate_parameters(self::data_for_messagearea_get_profile_parameters(), $params);
837941e9 1079 self::validate_context($systemcontext);
c6e97f54 1080
837941e9
MN
1081 if (($USER->id != $currentuserid) && !has_capability('moodle/site:readallmessages', $systemcontext)) {
1082 throw new moodle_exception('You do not have permission to perform this action.');
1083 }
c6e97f54
MN
1084
1085 $profile = \core_message\api::get_profile($currentuserid, $otheruserid);
de55cb1b 1086 $profile = new \core_message\output\messagearea\profile($profile);
c6e97f54
MN
1087
1088 $renderer = $PAGE->get_renderer('core_message');
1089 return $profile->export_for_template($renderer);
1090 }
1091
1092 /**
49aaadc3 1093 * The get profile return structure.
c6e97f54
MN
1094 *
1095 * @return external_single_structure
49aaadc3 1096 * @since 3.2
c6e97f54
MN
1097 */
1098 public static function data_for_messagearea_get_profile_returns() {
1099 return new external_single_structure(
1100 array(
de55cb1b 1101 'userid' => new external_value(PARAM_INT, 'The id of the user whose profile we are viewing'),
c6e97f54 1102 'email' => new external_value(core_user::get_property_type('email'), 'An email address'),
cc22b515 1103 'country' => new external_value(PARAM_TEXT, 'Home country of the user'),
c6e97f54
MN
1104 'city' => new external_value(core_user::get_property_type('city'), 'Home city of the user'),
1105 'fullname' => new external_value(PARAM_NOTAGS, 'The user\'s name'),
1106 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL'),
1107 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL'),
bf58081d 1108 'isonline' => new external_value(PARAM_BOOL, 'The user\'s online status'),
c6e97f54
MN
1109 'isblocked' => new external_value(PARAM_BOOL, 'Is the user blocked?'),
1110 'iscontact' => new external_value(PARAM_BOOL, 'Is the user a contact?')
1111 )
1112 );
1113 }
1114
d6731600
FM
1115 /**
1116 * Get contacts parameters description.
1117 *
1118 * @return external_function_parameters
5bcfd504 1119 * @since Moodle 2.5
d6731600
FM
1120 */
1121 public static function get_contacts_parameters() {
1122 return new external_function_parameters(array());
1123 }
1124
1125 /**
1126 * Get contacts.
1127 *
d6731600 1128 * @return external_description
5bcfd504 1129 * @since Moodle 2.5
d6731600
FM
1130 */
1131 public static function get_contacts() {
d85bedf7 1132 global $CFG, $PAGE;
436bbf89
DM
1133
1134 // Check if messaging is enabled.
837941e9 1135 if (empty($CFG->messaging)) {
436bbf89
DM
1136 throw new moodle_exception('disabled', 'message');
1137 }
1138
d6731600
FM
1139 require_once($CFG->dirroot . '/user/lib.php');
1140
1141 list($online, $offline, $strangers) = message_get_contacts();
1142 $allcontacts = array('online' => $online, 'offline' => $offline, 'strangers' => $strangers);
1143 foreach ($allcontacts as $mode => $contacts) {
1144 foreach ($contacts as $key => $contact) {
1145 $newcontact = array(
1146 'id' => $contact->id,
1147 'fullname' => fullname($contact),
1148 'unread' => $contact->messagecount
1149 );
1150
d85bedf7
JL
1151 $userpicture = new user_picture($contact);
1152 $userpicture->size = 1; // Size f1.
1153 $newcontact['profileimageurl'] = $userpicture->get_url($PAGE)->out(false);
1154 $userpicture->size = 0; // Size f2.
1155 $newcontact['profileimageurlsmall'] = $userpicture->get_url($PAGE)->out(false);
d6731600
FM
1156
1157 $allcontacts[$mode][$key] = $newcontact;
1158 }
1159 }
1160 return $allcontacts;
1161 }
1162
1163 /**
1164 * Get contacts return description.
1165 *
1166 * @return external_description
5bcfd504 1167 * @since Moodle 2.5
d6731600
FM
1168 */
1169 public static function get_contacts_returns() {
1170 return new external_single_structure(
1171 array(
1172 'online' => new external_multiple_structure(
1173 new external_single_structure(
1174 array(
1175 'id' => new external_value(PARAM_INT, 'User ID'),
1176 'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
1177 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL),
1178 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL', VALUE_OPTIONAL),
1179 'unread' => new external_value(PARAM_INT, 'Unread message count')
1180 )
1181 ),
1182 'List of online contacts'
1183 ),
1184 'offline' => new external_multiple_structure(
1185 new external_single_structure(
1186 array(
1187 'id' => new external_value(PARAM_INT, 'User ID'),
1188 'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
1189 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL),
1190 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL', VALUE_OPTIONAL),
1191 'unread' => new external_value(PARAM_INT, 'Unread message count')
1192 )
1193 ),
1194 'List of offline contacts'
1195 ),
1196 'strangers' => new external_multiple_structure(
1197 new external_single_structure(
1198 array(
1199 'id' => new external_value(PARAM_INT, 'User ID'),
1200 'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
1201 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL),
1202 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL', VALUE_OPTIONAL),
1203 'unread' => new external_value(PARAM_INT, 'Unread message count')
1204 )
1205 ),
1206 'List of users that are not in the user\'s contact list but have sent a message'
1207 )
1208 )
1209 );
1210 }
1211
1212 /**
1213 * Search contacts parameters description.
1214 *
1215 * @return external_function_parameters
5bcfd504 1216 * @since Moodle 2.5
d6731600
FM
1217 */
1218 public static function search_contacts_parameters() {
1219 return new external_function_parameters(
1220 array(
1221 'searchtext' => new external_value(PARAM_CLEAN, 'String the user\'s fullname has to match to be found'),
1222 'onlymycourses' => new external_value(PARAM_BOOL, 'Limit search to the user\'s courses',
1223 VALUE_DEFAULT, false)
1224 )
1225 );
1226 }
1227
1228 /**
1229 * Search contacts.
1230 *
1231 * @param string $searchtext query string.
1232 * @param bool $onlymycourses limit the search to the user's courses only.
1233 * @return external_description
5bcfd504 1234 * @since Moodle 2.5
d6731600
FM
1235 */
1236 public static function search_contacts($searchtext, $onlymycourses = false) {
d85bedf7 1237 global $CFG, $USER, $PAGE;
11d83ab3 1238 require_once($CFG->dirroot . '/user/lib.php');
436bbf89
DM
1239
1240 // Check if messaging is enabled.
837941e9 1241 if (empty($CFG->messaging)) {
436bbf89
DM
1242 throw new moodle_exception('disabled', 'message');
1243 }
1244
d6731600
FM
1245 require_once($CFG->libdir . '/enrollib.php');
1246
1247 $params = array('searchtext' => $searchtext, 'onlymycourses' => $onlymycourses);
1248 $params = self::validate_parameters(self::search_contacts_parameters(), $params);
1249
1250 // Extra validation, we do not allow empty queries.
1251 if ($params['searchtext'] === '') {
1252 throw new moodle_exception('querystringcannotbeempty');
1253 }
1254
1255 $courseids = array();
1256 if ($params['onlymycourses']) {
1257 $mycourses = enrol_get_my_courses(array('id'));
1258 foreach ($mycourses as $mycourse) {
1259 $courseids[] = $mycourse->id;
1260 }
1261 } else {
1262 $courseids[] = SITEID;
1263 }
1264
1265 // Retrieving the users matching the query.
1266 $users = message_search_users($courseids, $params['searchtext']);
1267 $results = array();
1268 foreach ($users as $user) {
1269 $results[$user->id] = $user;
1270 }
1271
1272 // Reorganising information.
1273 foreach ($results as &$user) {
1274 $newuser = array(
1275 'id' => $user->id,
1276 'fullname' => fullname($user)
1277 );
1278
1279 // Avoid undefined property notice as phone not specified.
1280 $user->phone1 = null;
1281 $user->phone2 = null;
1282
d85bedf7
JL
1283 $userpicture = new user_picture($user);
1284 $userpicture->size = 1; // Size f1.
1285 $newuser['profileimageurl'] = $userpicture->get_url($PAGE)->out(false);
1286 $userpicture->size = 0; // Size f2.
1287 $newuser['profileimageurlsmall'] = $userpicture->get_url($PAGE)->out(false);
d6731600
FM
1288
1289 $user = $newuser;
1290 }
1291
1292 return $results;
1293 }
1294
1295 /**
1296 * Search contacts return description.
1297 *
1298 * @return external_description
5bcfd504 1299 * @since Moodle 2.5
d6731600
FM
1300 */
1301 public static function search_contacts_returns() {
1302 return new external_multiple_structure(
1303 new external_single_structure(
1304 array(
1305 'id' => new external_value(PARAM_INT, 'User ID'),
1306 'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
1307 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL),
1308 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL', VALUE_OPTIONAL)
1309 )
1310 ),
1311 'List of contacts'
1312 );
1313 }
aff9da17
JL
1314
1315 /**
1316 * Get messages parameters description.
1317 *
1318 * @return external_function_parameters
193edf7f 1319 * @since 2.8
aff9da17
JL
1320 */
1321 public static function get_messages_parameters() {
1322 return new external_function_parameters(
1323 array(
6ff4464b 1324 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
127ef540
SH
1325 'useridfrom' => new external_value(
1326 PARAM_INT, 'the user id who send the message, 0 for any user. -10 or -20 for no-reply or support user',
1327 VALUE_DEFAULT, 0),
1328 'type' => new external_value(
1329 PARAM_ALPHA, 'type of message to return, expected values are: notifications, conversations and both',
1330 VALUE_DEFAULT, 'both'),
6ff4464b 1331 'read' => new external_value(PARAM_BOOL, 'true for getting read messages, false for unread', VALUE_DEFAULT, true),
127ef540
SH
1332 'newestfirst' => new external_value(
1333 PARAM_BOOL, 'true for ordering by newest first, false for oldest first',
1334 VALUE_DEFAULT, true),
aff9da17 1335 'limitfrom' => new external_value(PARAM_INT, 'limit from', VALUE_DEFAULT, 0),
127ef540
SH
1336 'limitnum' => new external_value(PARAM_INT, 'limit number', VALUE_DEFAULT, 0)
1337 )
aff9da17
JL
1338 );
1339 }
1340
1341 /**
1342 * Get messages function implementation.
127ef540
SH
1343 *
1344 * @since 2.8
1345 * @throws invalid_parameter_exception
1346 * @throws moodle_exception
6ff4464b
JL
1347 * @param int $useridto the user id who received the message
1348 * @param int $useridfrom the user id who send the message. -10 or -20 for no-reply or support user
193edf7f 1349 * @param string $type type of message to return, expected values: notifications, conversations and both
aff9da17 1350 * @param bool $read true for retreiving read messages, false for unread
6ff4464b 1351 * @param bool $newestfirst true for ordering by newest first, false for oldest first
aff9da17
JL
1352 * @param int $limitfrom limit from
1353 * @param int $limitnum limit num
1354 * @return external_description
aff9da17 1355 */
193edf7f 1356 public static function get_messages($useridto, $useridfrom = 0, $type = 'both', $read = true,
aff9da17 1357 $newestfirst = true, $limitfrom = 0, $limitnum = 0) {
127ef540 1358 global $CFG, $USER;
aff9da17
JL
1359
1360 $warnings = array();
1361
1362 $params = array(
1363 'useridto' => $useridto,
6ff4464b 1364 'useridfrom' => $useridfrom,
aff9da17
JL
1365 'type' => $type,
1366 'read' => $read,
aff9da17
JL
1367 'newestfirst' => $newestfirst,
1368 'limitfrom' => $limitfrom,
1369 'limitnum' => $limitnum
1370 );
1371
1372 $params = self::validate_parameters(self::get_messages_parameters(), $params);
1373
1374 $context = context_system::instance();
1375 self::validate_context($context);
1376
1377 $useridto = $params['useridto'];
6ff4464b 1378 $useridfrom = $params['useridfrom'];
aff9da17
JL
1379 $type = $params['type'];
1380 $read = $params['read'];
aff9da17
JL
1381 $newestfirst = $params['newestfirst'];
1382 $limitfrom = $params['limitfrom'];
1383 $limitnum = $params['limitnum'];
1384
1385 $allowedvalues = array('notifications', 'conversations', 'both');
1386 if (!in_array($type, $allowedvalues)) {
1387 throw new invalid_parameter_exception('Invalid value for type parameter (value: ' . $type . '),' .
1388 'allowed values are: ' . implode(',', $allowedvalues));
1389 }
1390
1391 // Check if private messaging between users is allowed.
1392 if (empty($CFG->messaging)) {
1393 // If we are retreiving only conversations, and messaging is disabled, throw an exception.
aff9da17
JL
1394 if ($type == "conversations") {
1395 throw new moodle_exception('disabled', 'message');
1396 }
1397 if ($type == "both") {
1398 $warning = array();
1399 $warning['item'] = 'message';
1400 $warning['itemid'] = $USER->id;
1401 $warning['warningcode'] = '1';
1402 $warning['message'] = 'Private messages (conversations) are not enabled in this site.
1403 Only notifications will be returned';
1404 $warnings[] = $warning;
1405 }
1406 }
1407
1408 if (!empty($useridto)) {
6ff4464b
JL
1409 if (core_user::is_real_user($useridto)) {
1410 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
1411 } else {
1412 throw new moodle_exception('invaliduser');
1413 }
aff9da17
JL
1414 }
1415
1416 if (!empty($useridfrom)) {
1417 // We use get_user here because the from user can be the noreply or support user.
1418 $userfrom = core_user::get_user($useridfrom, '*', MUST_EXIST);
1419 }
1420
1421 // Check if the current user is the sender/receiver or just a privileged user.
1422 if ($useridto != $USER->id and $useridfrom != $USER->id and
1423 !has_capability('moodle/site:readallmessages', $context)) {
1424 throw new moodle_exception('accessdenied', 'admin');
1425 }
1426
127ef540 1427 // Which type of messages to retrieve.
193edf7f 1428 $notifications = -1;
aff9da17 1429 if ($type != 'both') {
193edf7f 1430 $notifications = ($type == 'notifications') ? 1 : 0;
aff9da17
JL
1431 }
1432
aff9da17 1433 $orderdirection = $newestfirst ? 'DESC' : 'ASC';
193edf7f 1434 $sort = "mr.timecreated $orderdirection";
aff9da17 1435
193edf7f 1436 if ($messages = message_get_messages($useridto, $useridfrom, $notifications, $read, $sort, $limitfrom, $limitnum)) {
aff9da17
JL
1437 $canviewfullname = has_capability('moodle/site:viewfullnames', $context);
1438
1439 // In some cases, we don't need to get the to/from user objects from the sql query.
1440 $userfromfullname = '';
1441 $usertofullname = '';
1442
1443 // In this case, the useridto field is not empty, so we can get the user destinatary fullname from there.
1444 if (!empty($useridto)) {
1445 $usertofullname = fullname($userto, $canviewfullname);
1446 // The user from may or may not be filled.
1447 if (!empty($useridfrom)) {
1448 $userfromfullname = fullname($userfrom, $canviewfullname);
1449 }
1450 } else {
1451 // If the useridto field is empty, the useridfrom must be filled.
1452 $userfromfullname = fullname($userfrom, $canviewfullname);
1453 }
aff9da17
JL
1454 foreach ($messages as $mid => $message) {
1455
ea21d637
JL
1456 // Do not return deleted messages.
1457 if (($useridto == $USER->id and $message->timeusertodeleted) or
1458 ($useridfrom == $USER->id and $message->timeuserfromdeleted)) {
1459
1460 unset($messages[$mid]);
1461 continue;
1462 }
1463
aff9da17
JL
1464 // We need to get the user from the query.
1465 if (empty($userfromfullname)) {
6ff4464b
JL
1466 // Check for non-reply and support users.
1467 if (core_user::is_real_user($message->useridfrom)) {
127ef540 1468 $user = new stdClass();
6ff4464b
JL
1469 $user = username_load_fields_from_object($user, $message, 'userfrom');
1470 $message->userfromfullname = fullname($user, $canviewfullname);
1471 } else {
1472 $user = core_user::get_user($message->useridfrom);
1473 $message->userfromfullname = fullname($user, $canviewfullname);
1474 }
aff9da17
JL
1475 } else {
1476 $message->userfromfullname = $userfromfullname;
1477 }
1478
1479 // We need to get the user from the query.
1480 if (empty($usertofullname)) {
127ef540 1481 $user = new stdClass();
aff9da17
JL
1482 $user = username_load_fields_from_object($user, $message, 'userto');
1483 $message->usertofullname = fullname($user, $canviewfullname);
1484 } else {
1485 $message->usertofullname = $usertofullname;
1486 }
1487
193edf7f 1488 // This field is only available in the message_read table.
aff9da17
JL
1489 if (!isset($message->timeread)) {
1490 $message->timeread = 0;
1491 }
1492
aff9da17 1493 $message->text = message_format_message_text($message);
aff9da17
JL
1494 $messages[$mid] = (array) $message;
1495 }
1496 }
1497
1498 $results = array(
1499 'messages' => $messages,
1500 'warnings' => $warnings
1501 );
1502
1503 return $results;
1504 }
1505
1506 /**
1507 * Get messages return description.
1508 *
6ff4464b 1509 * @return external_single_structure
193edf7f 1510 * @since 2.8
aff9da17
JL
1511 */
1512 public static function get_messages_returns() {
1513 return new external_single_structure(
1514 array(
1515 'messages' => new external_multiple_structure(
1516 new external_single_structure(
1517 array(
193edf7f 1518 'id' => new external_value(PARAM_INT, 'Message id'),
aff9da17
JL
1519 'useridfrom' => new external_value(PARAM_INT, 'User from id'),
1520 'useridto' => new external_value(PARAM_INT, 'User to id'),
1521 'subject' => new external_value(PARAM_TEXT, 'The message subject'),
1522 'text' => new external_value(PARAM_RAW, 'The message text formated'),
1523 'fullmessage' => new external_value(PARAM_RAW, 'The message'),
193edf7f 1524 'fullmessageformat' => new external_format_value('fullmessage'),
aff9da17
JL
1525 'fullmessagehtml' => new external_value(PARAM_RAW, 'The message in html'),
1526 'smallmessage' => new external_value(PARAM_RAW, 'The shorten message'),
1527 'notification' => new external_value(PARAM_INT, 'Is a notification?'),
1528 'contexturl' => new external_value(PARAM_RAW, 'Context URL'),
1529 'contexturlname' => new external_value(PARAM_TEXT, 'Context URL link name'),
1530 'timecreated' => new external_value(PARAM_INT, 'Time created'),
1531 'timeread' => new external_value(PARAM_INT, 'Time read'),
1532 'usertofullname' => new external_value(PARAM_TEXT, 'User to full name'),
1533 'userfromfullname' => new external_value(PARAM_TEXT, 'User from full name')
1534 ), 'message'
1535 )
1536 ),
1537 'warnings' => new external_warnings()
1538 )
1539 );
3274d5ca
RW
1540 }
1541
3274d5ca
RW
1542 /**
1543 * Mark all notifications as read parameters description.
1544 *
1545 * @return external_function_parameters
1546 * @since 3.2
1547 */
1548 public static function mark_all_notifications_as_read_parameters() {
1549 return new external_function_parameters(
1550 array(
1551 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
1552 'useridfrom' => new external_value(
1553 PARAM_INT, 'the user id who send the message, 0 for any user. -10 or -20 for no-reply or support user',
1554 VALUE_DEFAULT, 0),
1555 )
1556 );
1557 }
1558
1559 /**
1560 * Mark all notifications as read function.
1561 *
1562 * @since 3.2
1563 * @throws invalid_parameter_exception
1564 * @throws moodle_exception
1565 * @param int $useridto the user id who received the message
1566 * @param int $useridfrom the user id who send the message. -10 or -20 for no-reply or support user
1567 * @return external_description
1568 */
1569 public static function mark_all_notifications_as_read($useridto, $useridfrom) {
837941e9 1570 global $USER;
3274d5ca
RW
1571
1572 $params = self::validate_parameters(
1573 self::mark_all_notifications_as_read_parameters(),
1574 array(
1575 'useridto' => $useridto,
1576 'useridfrom' => $useridfrom,
1577 )
1578 );
1579
1580 $context = context_system::instance();
1581 self::validate_context($context);
1582
1583 $useridto = $params['useridto'];
1584 $useridfrom = $params['useridfrom'];
1585
1586 if (!empty($useridto)) {
1587 if (core_user::is_real_user($useridto)) {
1588 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
1589 } else {
1590 throw new moodle_exception('invaliduser');
1591 }
1592 }
1593
1594 if (!empty($useridfrom)) {
1595 // We use get_user here because the from user can be the noreply or support user.
1596 $userfrom = core_user::get_user($useridfrom, '*', MUST_EXIST);
1597 }
1598
1599 // Check if the current user is the sender/receiver or just a privileged user.
1600 if ($useridto != $USER->id and $useridfrom != $USER->id and
7b55aaa1 1601 // The deleteanymessage cap seems more reasonable here than readallmessages.
3274d5ca
RW
1602 !has_capability('moodle/site:deleteanymessage', $context)) {
1603 throw new moodle_exception('accessdenied', 'admin');
1604 }
1605
79f6c36c 1606 \core_message\api::mark_all_read_for_user($useridto, $useridfrom, MESSAGE_TYPE_NOTIFICATION);
3274d5ca
RW
1607
1608 return true;
1609 }
1610
1611 /**
1612 * Mark all notifications as read return description.
1613 *
1614 * @return external_single_structure
1615 * @since 3.2
1616 */
1617 public static function mark_all_notifications_as_read_returns() {
1618 return new external_value(PARAM_BOOL, 'True if the messages were marked read, false otherwise');
1619 }
1620
8c55bd6c
RW
1621 /**
1622 * Get unread conversations count parameters description.
1623 *
1624 * @return external_function_parameters
1625 * @since 3.2
1626 */
1627 public static function get_unread_conversations_count_parameters() {
1628 return new external_function_parameters(
1629 array(
1630 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
1631 )
1632 );
1633 }
1634
1635 /**
1636 * Get unread messages count function.
1637 *
1638 * @since 3.2
1639 * @throws invalid_parameter_exception
1640 * @throws moodle_exception
1641 * @param int $useridto the user id who received the message
1642 * @return external_description
1643 */
1644 public static function get_unread_conversations_count($useridto) {
a2c7227a
SL
1645 global $USER, $CFG;
1646
1647 // Check if messaging is enabled.
1648 if (empty($CFG->messaging)) {
1649 throw new moodle_exception('disabled', 'message');
1650 }
8c55bd6c
RW
1651
1652 $params = self::validate_parameters(
1653 self::get_unread_conversations_count_parameters(),
1654 array('useridto' => $useridto)
1655 );
1656
1657 $context = context_system::instance();
1658 self::validate_context($context);
1659
1660 $useridto = $params['useridto'];
1661
1662 if (!empty($useridto)) {
1663 if (core_user::is_real_user($useridto)) {
1664 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
1665 } else {
1666 throw new moodle_exception('invaliduser');
1667 }
1668 } else {
1669 $useridto = $USER->id;
1670 }
1671
1672 // Check if the current user is the receiver or just a privileged user.
1673 if ($useridto != $USER->id and !has_capability('moodle/site:readallmessages', $context)) {
1674 throw new moodle_exception('accessdenied', 'admin');
1675 }
1676
79f6c36c 1677 return \core_message\api::count_unread_conversations($userto);
8c55bd6c
RW
1678 }
1679
1680 /**
1681 * Get unread conversations count return description.
1682 *
1683 * @return external_single_structure
1684 * @since 3.2
1685 */
1686 public static function get_unread_conversations_count_returns() {
1687 return new external_value(PARAM_INT, 'The count of unread messages for the user');
aff9da17
JL
1688 }
1689
60ab2e1b
JL
1690 /**
1691 * Get blocked users parameters description.
1692 *
1693 * @return external_function_parameters
1694 * @since 2.9
1695 */
1696 public static function get_blocked_users_parameters() {
1697 return new external_function_parameters(
1698 array(
1699 'userid' => new external_value(PARAM_INT,
1700 'the user whose blocked users we want to retrieve',
1701 VALUE_REQUIRED),
1702 )
1703 );
1704 }
1705
1706 /**
1707 * Retrieve a list of users blocked
1708 *
1709 * @param int $userid the user whose blocked users we want to retrieve
1710 * @return external_description
1711 * @since 2.9
1712 */
1713 public static function get_blocked_users($userid) {
d85bedf7 1714 global $CFG, $USER, $PAGE;
60ab2e1b 1715
a2c7227a
SL
1716 // Check if messaging is enabled.
1717 if (empty($CFG->messaging)) {
1718 throw new moodle_exception('disabled', 'message');
1719 }
1720
60ab2e1b
JL
1721 // Warnings array, it can be empty at the end but is mandatory.
1722 $warnings = array();
1723
1724 // Validate params.
1725 $params = array(
1726 'userid' => $userid
1727 );
1728 $params = self::validate_parameters(self::get_blocked_users_parameters(), $params);
1729 $userid = $params['userid'];
1730
1731 // Validate context.
1732 $context = context_system::instance();
1733 self::validate_context($context);
1734
1735 // Check if private messaging between users is allowed.
1736 if (empty($CFG->messaging)) {
1737 throw new moodle_exception('disabled', 'message');
1738 }
1739
4485f7c5
JL
1740 $user = core_user::get_user($userid, '*', MUST_EXIST);
1741 core_user::require_active_user($user);
60ab2e1b
JL
1742
1743 // Check if we have permissions for retrieve the information.
343ba16c
SL
1744 $capability = 'moodle/site:manageallmessaging';
1745 if (($USER->id != $userid) && !has_capability($capability, $context)) {
1746 throw new required_capability_exception($context, $capability, 'nopermissions', '');
60ab2e1b
JL
1747 }
1748
1749 // Now, we can get safely all the blocked users.
1750 $users = message_get_blocked_users($user);
1751
1752 $blockedusers = array();
1753 foreach ($users as $user) {
1754 $newuser = array(
1755 'id' => $user->id,
1756 'fullname' => fullname($user),
1757 );
0b074e88 1758
d85bedf7
JL
1759 $userpicture = new user_picture($user);
1760 $userpicture->size = 1; // Size f1.
1761 $newuser['profileimageurl'] = $userpicture->get_url($PAGE)->out(false);
60ab2e1b
JL
1762
1763 $blockedusers[] = $newuser;
1764 }
1765
1766 $results = array(
1767 'users' => $blockedusers,
1768 'warnings' => $warnings
1769 );
1770 return $results;
1771 }
1772
1773 /**
1774 * Get blocked users return description.
1775 *
1776 * @return external_single_structure
1777 * @since 2.9
1778 */
1779 public static function get_blocked_users_returns() {
1780 return new external_single_structure(
1781 array(
1782 'users' => new external_multiple_structure(
1783 new external_single_structure(
1784 array(
1785 'id' => new external_value(PARAM_INT, 'User ID'),
1786 'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
1787 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL)
1788 )
1789 ),
1790 'List of blocked users'
1791 ),
1792 'warnings' => new external_warnings()
1793 )
1794 );
1795 }
1796
31c474da
JL
1797 /**
1798 * Returns description of method parameters
1799 *
1800 * @return external_function_parameters
1801 * @since 2.9
1802 */
1803 public static function mark_message_read_parameters() {
1804 return new external_function_parameters(
1805 array(
1806 'messageid' => new external_value(PARAM_INT, 'id of the message (in the message table)'),
7b55aaa1
MN
1807 'timeread' => new external_value(PARAM_INT, 'timestamp for when the message should be marked read',
1808 VALUE_DEFAULT, 0)
31c474da
JL
1809 )
1810 );
1811 }
1812
1813 /**
1814 * Mark a single message as read, trigger message_viewed event
1815 *
1816 * @param int $messageid id of the message (in the message table)
1817 * @param int $timeread timestamp for when the message should be marked read
1818 * @return external_description
1819 * @throws invalid_parameter_exception
1820 * @throws moodle_exception
1821 * @since 2.9
1822 */
1823 public static function mark_message_read($messageid, $timeread) {
1824 global $CFG, $DB, $USER;
31c474da
JL
1825
1826 // Check if private messaging between users is allowed.
1827 if (empty($CFG->messaging)) {
1828 throw new moodle_exception('disabled', 'message');
1829 }
1830
1831 // Warnings array, it can be empty at the end but is mandatory.
1832 $warnings = array();
1833
1834 // Validate params.
1835 $params = array(
1836 'messageid' => $messageid,
1837 'timeread' => $timeread
1838 );
1839 $params = self::validate_parameters(self::mark_message_read_parameters(), $params);
1840
0b19d048
RW
1841 if (empty($params['timeread'])) {
1842 $timeread = time();
1843 } else {
1844 $timeread = $params['timeread'];
1845 }
1846
31c474da
JL
1847 // Validate context.
1848 $context = context_system::instance();
1849 self::validate_context($context);
1850
1851 $message = $DB->get_record('message', array('id' => $params['messageid']), '*', MUST_EXIST);
1852
1853 if ($message->useridto != $USER->id) {
1854 throw new invalid_parameter_exception('Invalid messageid, you don\'t have permissions to mark this message as read');
1855 }
1856
0b19d048 1857 $messageid = message_mark_message_read($message, $timeread);
31c474da
JL
1858
1859 $results = array(
1860 'messageid' => $messageid,
1861 'warnings' => $warnings
1862 );
1863 return $results;
1864 }
1865
1866 /**
1867 * Returns description of method result value
1868 *
1869 * @return external_description
1870 * @since 2.9
1871 */
1872 public static function mark_message_read_returns() {
1873 return new external_single_structure(
1874 array(
1875 'messageid' => new external_value(PARAM_INT, 'the id of the message in the message_read table'),
1876 'warnings' => new external_warnings()
1877 )
1878 );
1879 }
1880
8c55bd6c
RW
1881 /**
1882 * Mark all messages as read parameters description.
1883 *
1884 * @return external_function_parameters
1885 * @since 3.2
1886 */
1887 public static function mark_all_messages_as_read_parameters() {
1888 return new external_function_parameters(
1889 array(
1890 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
1891 'useridfrom' => new external_value(
1892 PARAM_INT, 'the user id who send the message, 0 for any user. -10 or -20 for no-reply or support user',
1893 VALUE_DEFAULT, 0),
1894 )
1895 );
1896 }
1897
1898 /**
1899 * Mark all notifications as read function.
1900 *
1901 * @since 3.2
1902 * @throws invalid_parameter_exception
1903 * @throws moodle_exception
1904 * @param int $useridto the user id who received the message
1905 * @param int $useridfrom the user id who send the message. -10 or -20 for no-reply or support user
1906 * @return external_description
1907 */
1908 public static function mark_all_messages_as_read($useridto, $useridfrom) {
a2c7227a
SL
1909 global $USER, $CFG;
1910
1911 // Check if messaging is enabled.
1912 if (empty($CFG->messaging)) {
1913 throw new moodle_exception('disabled', 'message');
1914 }
8c55bd6c
RW
1915
1916 $params = self::validate_parameters(
1917 self::mark_all_messages_as_read_parameters(),
1918 array(
1919 'useridto' => $useridto,
1920 'useridfrom' => $useridfrom,
1921 )
1922 );
1923
1924 $context = context_system::instance();
1925 self::validate_context($context);
1926
1927 $useridto = $params['useridto'];
1928 $useridfrom = $params['useridfrom'];
1929
1930 if (!empty($useridto)) {
1931 if (core_user::is_real_user($useridto)) {
1932 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
1933 } else {
1934 throw new moodle_exception('invaliduser');
1935 }
1936 }
1937
1938 if (!empty($useridfrom)) {
1939 // We use get_user here because the from user can be the noreply or support user.
1940 $userfrom = core_user::get_user($useridfrom, '*', MUST_EXIST);
1941 }
1942
1943 // Check if the current user is the sender/receiver or just a privileged user.
1944 if ($useridto != $USER->id and $useridfrom != $USER->id and
7b55aaa1 1945 // The deleteanymessage cap seems more reasonable here than readallmessages.
8c55bd6c
RW
1946 !has_capability('moodle/site:deleteanymessage', $context)) {
1947 throw new moodle_exception('accessdenied', 'admin');
1948 }
1949
79f6c36c 1950 \core_message\api::mark_all_read_for_user($useridto, $useridfrom, MESSAGE_TYPE_MESSAGE);
8c55bd6c
RW
1951
1952 return true;
1953 }
1954
1955 /**
1956 * Mark all notifications as read return description.
1957 *
1958 * @return external_single_structure
1959 * @since 3.2
1960 */
1961 public static function mark_all_messages_as_read_returns() {
1962 return new external_value(PARAM_BOOL, 'True if the messages were marked read, false otherwise');
1963 }
1964
dec0cd99
MN
1965 /**
1966 * Returns description of method parameters.
1967 *
1968 * @return external_function_parameters
1969 * @since 3.2
1970 */
1971 public static function delete_conversation_parameters() {
1972 return new external_function_parameters(
1973 array(
1974 'userid' => new external_value(PARAM_INT, 'The user id of who we want to delete the conversation for'),
1975 'otheruserid' => new external_value(PARAM_INT, 'The user id of the other user in the conversation'),
1976 )
1977 );
1978 }
1979
1980 /**
1981 * Deletes a conversation.
1982 *
1983 * @param int $userid The user id of who we want to delete the conversation for
1984 * @param int $otheruserid The user id of the other user in the conversation
1985 * @return array
1986 * @throws moodle_exception
1987 * @since 3.2
1988 */
1989 public static function delete_conversation($userid, $otheruserid) {
1990 global $CFG;
1991
1992 // Check if private messaging between users is allowed.
1993 if (empty($CFG->messaging)) {
1994 throw new moodle_exception('disabled', 'message');
1995 }
1996
1997 // Warnings array, it can be empty at the end but is mandatory.
1998 $warnings = array();
1999
2000 // Validate params.
2001 $params = array(
2002 'userid' => $userid,
2003 'otheruserid' => $otheruserid,
2004 );
2005 $params = self::validate_parameters(self::delete_conversation_parameters(), $params);
2006
2007 // Validate context.
2008 $context = context_system::instance();
2009 self::validate_context($context);
2010
2011 $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
2012 core_user::require_active_user($user);
2013
2014 if (\core_message\api::can_delete_conversation($user->id)) {
2015 $status = \core_message\api::delete_conversation($user->id, $otheruserid);
2016 } else {
2017 throw new moodle_exception('You do not have permission to delete messages');
2018 }
2019
2020 $results = array(
2021 'status' => $status,
2022 'warnings' => $warnings
2023 );
2024
2025 return $results;
2026 }
2027
2028 /**
2029 * Returns description of method result value.
2030 *
2031 * @return external_description
2032 * @since 3.2
2033 */
2034 public static function delete_conversation_returns() {
2035 return new external_single_structure(
2036 array(
2037 'status' => new external_value(PARAM_BOOL, 'True if the conversation was deleted, false otherwise'),
2038 'warnings' => new external_warnings()
2039 )
2040 );
2041 }
2042
419b1128
JL
2043 /**
2044 * Returns description of method parameters
2045 *
2046 * @return external_function_parameters
2047 * @since 3.1
2048 */
2049 public static function delete_message_parameters() {
2050 return new external_function_parameters(
2051 array(
2052 'messageid' => new external_value(PARAM_INT, 'The message id'),
2053 'userid' => new external_value(PARAM_INT, 'The user id of who we want to delete the message for'),
2054 'read' => new external_value(PARAM_BOOL, 'If is a message read', VALUE_DEFAULT, true)
2055 )
2056 );
2057 }
2058
2059 /**
2060 * Deletes a message
2061 *
2062 * @param int $messageid the message id
2063 * @param int $userid the user id of who we want to delete the message for
2064 * @param bool $read if is a message read (default to true)
2065 * @return external_description
2066 * @throws moodle_exception
2067 * @since 3.1
2068 */
2069 public static function delete_message($messageid, $userid, $read = true) {
2070 global $CFG, $DB;
419b1128
JL
2071
2072 // Check if private messaging between users is allowed.
2073 if (empty($CFG->messaging)) {
2074 throw new moodle_exception('disabled', 'message');
2075 }
2076
2077 // Warnings array, it can be empty at the end but is mandatory.
2078 $warnings = array();
2079
2080 // Validate params.
2081 $params = array(
2082 'messageid' => $messageid,
2083 'userid' => $userid,
2084 'read' => $read
2085 );
2086 $params = self::validate_parameters(self::delete_message_parameters(), $params);
2087
2088 // Validate context.
2089 $context = context_system::instance();
2090 self::validate_context($context);
2091
2092 $messagestable = $params['read'] ? 'message_read' : 'message';
2093 $message = $DB->get_record($messagestable, array('id' => $params['messageid']), '*', MUST_EXIST);
2094
2095 $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
2096 core_user::require_active_user($user);
2097
2098 $status = false;
2099 if (message_can_delete_message($message, $user->id)) {
2100 $status = message_delete_message($message, $user->id);;
2101 } else {
2102 throw new moodle_exception('You do not have permission to delete this message');
2103 }
2104
2105 $results = array(
2106 'status' => $status,
2107 'warnings' => $warnings
2108 );
2109 return $results;
2110 }
2111
2112 /**
2113 * Returns description of method result value
2114 *
2115 * @return external_description
2116 * @since 3.1
2117 */
2118 public static function delete_message_returns() {
2119 return new external_single_structure(
2120 array(
2121 'status' => new external_value(PARAM_BOOL, 'True if the message was deleted, false otherwise'),
2122 'warnings' => new external_warnings()
2123 )
2124 );
2125 }
2126
a0eabdd3
RW
2127 /**
2128 * Returns description of method parameters
2129 *
2130 * @return external_function_parameters
2131 * @since 3.2
2132 */
2133 public static function message_processor_config_form_parameters() {
2134 return new external_function_parameters(
2135 array(
2136 'userid' => new external_value(PARAM_INT, 'id of the user, 0 for current user', VALUE_REQUIRED),
2137 'name' => new external_value(PARAM_TEXT, 'The name of the message processor'),
2138 'formvalues' => new external_multiple_structure(
2139 new external_single_structure(
2140 array(
2141 'name' => new external_value(PARAM_TEXT, 'name of the form element', VALUE_REQUIRED),
2142 'value' => new external_value(PARAM_RAW, 'value of the form element', VALUE_REQUIRED),
2143 )
2144 ),
2145 'Config form values',
2146 VALUE_REQUIRED
2147 ),
2148 )
2149 );
2150 }
2151
2152 /**
2153 * Processes a message processor config form.
2154 *
2155 * @param int $userid the user id
2156 * @param string $name the name of the processor
2157 * @param array $formvalues the form values
2158 * @return external_description
2159 * @throws moodle_exception
2160 * @since 3.2
2161 */
2162 public static function message_processor_config_form($userid, $name, $formvalues) {
a2c7227a
SL
2163 global $USER, $CFG;
2164
2165 // Check if messaging is enabled.
2166 if (empty($CFG->messaging)) {
2167 throw new moodle_exception('disabled', 'message');
2168 }
8c125526 2169
a0eabdd3
RW
2170 $params = self::validate_parameters(
2171 self::message_processor_config_form_parameters(),
2172 array(
2173 'userid' => $userid,
2174 'name' => $name,
2175 'formvalues' => $formvalues,
2176 )
2177 );
2178
2179 if (empty($params['userid'])) {
2180 $params['userid'] = $USER->id;
2181 }
2182
2183 $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
2184 core_user::require_active_user($user);
2185
2186 $processor = get_message_processor($name);
2187 $preferences = [];
2188 $form = new stdClass();
2189
2190 foreach ($formvalues as $formvalue) {
cdff0944
RW
2191 // Curly braces to ensure interpretation is consistent between
2192 // php 5 and php 7.
2193 $form->{$formvalue['name']} = $formvalue['value'];
a0eabdd3
RW
2194 }
2195
2196 $processor->process_form($form, $preferences);
2197
2198 if (!empty($preferences)) {
2199 set_user_preferences($preferences, $userid);
2200 }
2201 }
2202
2203 /**
2204 * Returns description of method result value
2205 *
2206 * @return external_description
2207 * @since 3.2
2208 */
2209 public static function message_processor_config_form_returns() {
2210 return null;
2211 }
8c125526
RW
2212
2213 /**
2214 * Returns description of method parameters
2215 *
2216 * @return external_function_parameters
2217 * @since 3.2
2218 */
2219 public static function get_message_processor_parameters() {
2220 return new external_function_parameters(
2221 array(
2222 'userid' => new external_value(PARAM_INT, 'id of the user, 0 for current user'),
2223 'name' => new external_value(PARAM_TEXT, 'The name of the message processor', VALUE_REQUIRED),
2224 )
2225 );
2226 }
2227
2228 /**
2229 * Get a message processor.
2230 *
7b55aaa1
MN
2231 * @param int $userid
2232 * @param string $name the name of the processor
8c125526
RW
2233 * @return external_description
2234 * @throws moodle_exception
2235 * @since 3.2
2236 */
2237 public static function get_message_processor($userid = 0, $name) {
a2c7227a
SL
2238 global $USER, $PAGE, $CFG;
2239
2240 // Check if messaging is enabled.
2241 if (empty($CFG->messaging)) {
2242 throw new moodle_exception('disabled', 'message');
2243 }
8c125526
RW
2244
2245 $params = self::validate_parameters(
2246 self::get_message_processor_parameters(),
2247 array(
2248 'userid' => $userid,
2249 'name' => $name,
2250 )
2251 );
2252
2253 if (empty($params['userid'])) {
2254 $params['userid'] = $USER->id;
2255 }
2256
2257 $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
2258 core_user::require_active_user($user);
2259 self::validate_context(context_user::instance($params['userid']));
2260
2261 $processor = get_message_processor($name);
2262
2263 $processoroutput = new \core_message\output\processor($processor, $user);
2264 $renderer = $PAGE->get_renderer('core_message');
2265
2266 return $processoroutput->export_for_template($renderer);
2267 }
2268
2269 /**
2270 * Returns description of method result value
2271 *
2272 * @return external_description
2273 * @since 3.2
2274 */
2275 public static function get_message_processor_returns() {
2276 return new external_function_parameters(
2277 array(
2278 'systemconfigured' => new external_value(PARAM_BOOL, 'Site configuration status'),
2279 'userconfigured' => new external_value(PARAM_BOOL, 'The user configuration status'),
2280 )
2281 );
2282 }
e86f0cb4
JL
2283
2284 /**
2285 * Returns description of method parameters
2286 *
2287 * @return external_function_parameters
2288 * @since 3.2
2289 */
2290 public static function get_user_notification_preferences_parameters() {
2291 return new external_function_parameters(
2292 array(
2293 'userid' => new external_value(PARAM_INT, 'id of the user, 0 for current user', VALUE_DEFAULT, 0)
2294 )
2295 );
2296 }
2297
2298 /**
2299 * Get the notification preferences for a given user.
2300 *
2301 * @param int $userid id of the user, 0 for current user
2302 * @return external_description
2303 * @throws moodle_exception
2304 * @since 3.2
2305 */
2306 public static function get_user_notification_preferences($userid = 0) {
a2c7227a
SL
2307 global $USER, $PAGE, $CFG;
2308
2309 // Check if messaging is enabled.
2310 if (empty($CFG->messaging)) {
2311 throw new moodle_exception('disabled', 'message');
2312 }
e86f0cb4
JL
2313
2314 $params = self::validate_parameters(
2315 self::get_user_notification_preferences_parameters(),
2316 array(
2317 'userid' => $userid,
2318 )
2319 );
2320
2321 if (empty($params['userid'])) {
2322 $user = $USER;
2323 } else {
2324 $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
2325 core_user::require_active_user($user);
2326 }
2327
2328 $systemcontext = context_system::instance();
2329 self::validate_context($systemcontext);
2330
2331 // Check access control.
2332 if ($user->id == $USER->id) {
2333 // Editing own message profile.
2334 require_capability('moodle/user:editownmessageprofile', $systemcontext);
2335 } else {
2336 // Teachers, parents, etc.
2337 $personalcontext = context_user::instance($user->id);
2338 require_capability('moodle/user:editmessageprofile', $personalcontext);
2339 }
2340
2341 $processors = get_message_processors();
2342 $providers = message_get_providers_for_user($user->id);
1686d93a 2343 $preferences = \core_message\api::get_all_message_preferences($processors, $providers, $user);
e86f0cb4
JL
2344 $notificationlist = new \core_message\output\preferences\notification_list($processors, $providers, $preferences, $user);
2345
2346 $renderer = $PAGE->get_renderer('core_message');
2347
2348 $result = array(
2349 'warnings' => array(),
2350 'preferences' => $notificationlist->export_for_template($renderer)
2351 );
2352 return $result;
2353 }
2354
2355 /**
2356 * Returns description of method result value
2357 *
2358 * @return external_description
2359 * @since 3.2
2360 */
2361 public static function get_user_notification_preferences_returns() {
2362 return new external_function_parameters(
2363 array(
2364 'preferences' => new external_single_structure(
2365 array(
2366 'userid' => new external_value(PARAM_INT, 'User id'),
2367 'disableall' => new external_value(PARAM_INT, 'Whether all the preferences are disabled'),
2368 'processors' => new external_multiple_structure(
2369 new external_single_structure(
2370 array(
2371 'displayname' => new external_value(PARAM_TEXT, 'Display name'),
e86f0cb4
JL
2372 'name' => new external_value(PARAM_PLUGIN, 'Processor name'),
2373 'hassettings' => new external_value(PARAM_BOOL, 'Whether has settings'),
2374 'contextid' => new external_value(PARAM_INT, 'Context id'),
2375 'userconfigured' => new external_value(PARAM_INT, 'Whether is configured by the user'),
2376 )
2377 ),
2378 'Config form values'
2379 ),
2380 'components' => new external_multiple_structure(
2381 new external_single_structure(
2382 array(
2383 'displayname' => new external_value(PARAM_TEXT, 'Display name'),
2384 'notifications' => new external_multiple_structure(
2385 new external_single_structure(
2386 array(
2387 'displayname' => new external_value(PARAM_TEXT, 'Display name'),
2388 'preferencekey' => new external_value(PARAM_ALPHANUMEXT, 'Preference key'),
2389 'processors' => new external_multiple_structure(
2390 new external_single_structure(
2391 array(
2392 'displayname' => new external_value(PARAM_TEXT, 'Display name'),
e86f0cb4
JL
2393 'name' => new external_value(PARAM_PLUGIN, 'Processor name'),
2394 'locked' => new external_value(PARAM_BOOL, 'Is locked by admin?'),
2395 'userconfigured' => new external_value(PARAM_INT, 'Is configured?'),
2396 'loggedin' => new external_single_structure(
2397 array(
2398 'name' => new external_value(PARAM_NOTAGS, 'Name'),
2399 'displayname' => new external_value(PARAM_TEXT, 'Display name'),
2400 'checked' => new external_value(PARAM_BOOL, 'Is checked?'),
2401 )
2402 ),
2403 'loggedoff' => new external_single_structure(
2404 array(
2405 'name' => new external_value(PARAM_NOTAGS, 'Name'),
2406 'displayname' => new external_value(PARAM_TEXT, 'Display name'),
2407 'checked' => new external_value(PARAM_BOOL, 'Is checked?'),
2408 )
2409 ),
2410 )
2411 ),
2412 'Processors values for this notification'
2413 ),
2414 )
2415 ),
2416 'List of notificaitons for the component'
2417 ),
2418 )
2419 ),
2420 'Available components'
2421 ),
2422 )
2423 ),
2424 'warnings' => new external_warnings(),
2425 )
2426 );
2427 }
a623b6b8 2428}