MDL-54701 message: added isread to data_for_messagearea_conversations
[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
MN
423 /**
424 * Get messagearea conversations parameters.
425 *
426 * @return external_function_parameters
427 */
428 public static function data_for_messagearea_conversations_parameters() {
429 return new external_function_parameters(
430 array(
431 'userid' => new external_value(PARAM_INT, 'The id of the user who we are viewing conversations for'),
432 'limitfrom' => new external_value(PARAM_INT, 'Limit from', VALUE_DEFAULT, 0),
433 'limitnum' => new external_value(PARAM_INT, 'Limit number', VALUE_DEFAULT, 0)
434 )
435 );
436 }
437
438 /**
439 * Get messagearea conversations.
440 *
441 * @param int $userid The id of the user who we are viewing conversations for
442 * @param int $limitfrom
443 * @param int $limitnum
444 * @return external_function_parameters
445 */
446 public static function data_for_messagearea_conversations($userid, $limitfrom = 0, $limitnum = 0) {
447 global $CFG, $PAGE;
448
449 // Check if messaging is enabled.
450 if (!$CFG->messaging) {
451 throw new moodle_exception('disabled', 'message');
452 }
453
454 $params = array(
455 'userid' => $userid,
456 'limitfrom' => $limitfrom,
457 'limitnum' => $limitnum
458 );
459 self::validate_parameters(self::data_for_messagearea_conversations_parameters(), $params);
460
461 self::validate_context(context_user::instance($userid));
462
463 $contacts = \core_message\api::get_conversations($userid, 0, $limitfrom, $limitnum);
464
465 $renderer = $PAGE->get_renderer('core_message');
466 return $contacts->export_for_template($renderer);
467 }
468
469 /**
470 * Get messagearea conversations returns.
471 *
472 * @return external_function_parameters
473 */
474 public static function data_for_messagearea_conversations_returns() {
475 return new external_function_parameters(
476 array(
477 'userid' => new external_value(PARAM_INT, 'The id of the user who we are viewing conversations for'),
478 'conversationsselected' => new external_value(PARAM_BOOL, 'Determines if conversations were selected,
479 otherwise contacts were'),
480 'contacts' => new external_multiple_structure(
481 new external_single_structure(
482 array(
483 'userid' => new external_value(PARAM_INT, 'The user\'s id'),
484 'fullname' => new external_value(PARAM_NOTAGS, 'The user\'s name'),
485 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL'),
486 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL'),
487 'lastmessage' => new external_value(PARAM_NOTAGS, 'The user\'s last message', VALUE_OPTIONAL),
eda6bc19
RW
488 'isonline' => new external_value(PARAM_BOOL, 'The user\'s online status', VALUE_OPTIONAL),
489 'isread' => new external_value(PARAM_BOOL, 'If the user has read the message', VALUE_OPTIONAL),
9aa012b5
MN
490 )
491 )
492 )
493 )
494 );
495 }
496
497 /**
498 * Get messagearea contacts parameters.
499 *
500 * @return external_function_parameters
501 */
502 public static function data_for_messagearea_contacts_parameters() {
503 return self::data_for_messagearea_conversations_parameters();
504 }
505
506 /**
507 * Get messagearea contacts parameters.
508 *
509 * @param int $userid The id of the user who we are viewing conversations for
510 * @param int $limitfrom
511 * @param int $limitnum
512 * @return external_function_parameters
513 */
514 public static function data_for_messagearea_contacts($userid, $limitfrom = 0, $limitnum = 0) {
515 global $CFG, $PAGE;
516
517 // Check if messaging is enabled.
518 if (!$CFG->messaging) {
519 throw new moodle_exception('disabled', 'message');
520 }
521
522 $params = array(
523 'userid' => $userid,
524 'limitfrom' => $limitfrom,
525 'limitnum' => $limitnum
526 );
527 self::validate_parameters(self::data_for_messagearea_contacts_parameters(), $params);
528
529 self::validate_context(context_user::instance($userid));
530
531 $contacts = \core_message\api::get_contacts($userid, $limitfrom, $limitnum);
532
533 $renderer = $PAGE->get_renderer('core_message');
534 return $contacts->export_for_template($renderer);
535 }
536
537 /**
538 * Get messagearea contacts returns.
539 *
540 * @return external_function_parameters
541 */
542 public static function data_for_messagearea_contacts_returns() {
543 return self::data_for_messagearea_conversations_returns();
544 }
545
3cd13828
MN
546 /**
547 * Get messagearea messages parameters.
548 *
549 * @return external_function_parameters
550 */
551 public static function data_for_messagearea_messages_parameters() {
552 return new external_function_parameters(
553 array(
554 'currentuserid' => new external_value(PARAM_INT, 'The current user\'s id'),
555 'otheruserid' => new external_value(PARAM_INT, 'The other user\'s id'),
556 'limitfrom' => new external_value(PARAM_INT, 'Limit from', VALUE_DEFAULT, 0),
557 'limitnum' => new external_value(PARAM_INT, 'Limit number', VALUE_DEFAULT, 0)
558 )
559 );
560 }
561
562 /**
563 * Get messagearea messages.
564 *
565 * @param int $currentuserid The current user's id
566 * @param int $otheruserid The other user's id
567 * @param int $limitfrom
568 * @param int $limitnum
569 * @return external_description
570 */
571 public static function data_for_messagearea_messages($currentuserid, $otheruserid, $limitfrom = 0, $limitnum = 0) {
572 global $CFG, $PAGE;
573
574 // Check if messaging is enabled.
575 if (!$CFG->messaging) {
576 throw new moodle_exception('disabled', 'message');
577 }
578
579 $params = array(
580 'currentuserid' => $currentuserid,
581 'otheruserid' => $otheruserid,
582 'limitfrom' => $limitfrom,
583 'limitnum' => $limitnum
584 );
585 self::validate_parameters(self::data_for_messagearea_messages_parameters(), $params);
586
587 self::validate_context(context_user::instance($currentuserid));
588
589 $messages = \core_message\api::get_messages($currentuserid, $otheruserid, $limitfrom, $limitnum);
590
591 $renderer = $PAGE->get_renderer('core_message');
592 return $messages->export_for_template($renderer);
593 }
594
595 /**
596 * Get messagearea messages returns.
597 *
598 * @return external_description
599 */
600 public static function data_for_messagearea_messages_returns() {
601 return new external_function_parameters(
602 array(
603 'iscurrentuser' => new external_value(PARAM_BOOL, 'Is the currently logged in user the user we are viewing the messages on behalf of?'),
604 'currentuserid' => new external_value(PARAM_INT, 'The current user\'s id'),
605 'otheruserid' => new external_value(PARAM_INT, 'The other user\'s id'),
606 'otheruserfullname' => new external_value(PARAM_NOTAGS, 'The other user\'s fullname'),
607 'messages' => new external_multiple_structure(
608 new external_single_structure(
609 array(
3090f52f 610 'id' => new external_value(PARAM_INT, 'The id of the message'),
3cd13828 611 'text' => new external_value(PARAM_RAW, 'The text of the message'),
3090f52f 612 'displayblocktime' => new external_value(PARAM_BOOL, 'Should we display the block time?'),
3cd13828
MN
613 'blocktime' => new external_value(PARAM_NOTAGS, 'The time to display above the message'),
614 'position' => new external_value(PARAM_ALPHA, 'The position of the text'),
615 'timesent' => new external_value(PARAM_NOTAGS, 'The time the message was sent'),
3090f52f 616 'isread' => new external_value(PARAM_INT, 'Determines if the message was read or not'),
3cd13828
MN
617 )
618 )
619 )
620 )
621 );
622 }
623
c060cd49
MN
624 /**
625 * Get the most recent message in a conversation parameters.
626 *
627 * @return external_function_parameters
628 */
629 public static function data_for_messagearea_get_most_recent_message_parameters() {
630 return new external_function_parameters(
631 array(
632 'currentuserid' => new external_value(PARAM_INT, 'The current user\'s id'),
633 'otheruserid' => new external_value(PARAM_INT, 'The other user\'s id'),
634 )
635 );
636 }
637
638 /**
639 * Get the most recent message in a conversation.
640 *
641 * @param int $currentuserid The current user's id
642 * @param int $otheruserid The other user's id
643 * @return external_single_structure
644 */
645 public static function data_for_messagearea_get_most_recent_message($currentuserid, $otheruserid) {
646 global $CFG, $PAGE;
647
648 // Check if messaging is enabled.
649 if (!$CFG->messaging) {
650 throw new moodle_exception('disabled', 'message');
651 }
652
653 $params = array(
654 'currentuserid' => $currentuserid,
655 'otheruserid' => $otheruserid
656 );
657 self::validate_parameters(self::data_for_messagearea_get_most_recent_message_parameters(), $params);
658
659 self::validate_context(context_user::instance($currentuserid));
660
661 $message = \core_message\api::get_most_recent_message($currentuserid, $otheruserid);
662
663 $renderer = $PAGE->get_renderer('core_message');
664 return $message->export_for_template($renderer);
665 }
666
667 /**
668 * Get messagearea get most recent message returns.
669 *
670 * @return external_single_structure
671 */
672 public static function data_for_messagearea_get_most_recent_message_returns() {
673 return new external_single_structure(
674 array(
3090f52f 675 'id' => new external_value(PARAM_INT, 'The id of the message'),
c060cd49 676 'text' => new external_value(PARAM_RAW, 'The text of the message'),
3090f52f 677 'displayblocktime' => new external_value(PARAM_BOOL, 'Should we display the block time?'),
c060cd49
MN
678 'blocktime' => new external_value(PARAM_NOTAGS, 'The time to display above the message'),
679 'position' => new external_value(PARAM_ALPHA, 'The position of the text'),
680 'timesent' => new external_value(PARAM_NOTAGS, 'The time the message was sent'),
3090f52f 681 'isread' => new external_value(PARAM_INT, 'Determines if the message was read or not'),
c060cd49
MN
682 )
683 );
684 }
685
c6e97f54
MN
686 /**
687 * The get profile parameters.
688 *
689 * @return external_function_parameters
690 */
691 public static function data_for_messagearea_get_profile_parameters() {
692 return new external_function_parameters(
693 array(
694 'currentuserid' => new external_value(PARAM_INT, 'The current user\'s id'),
695 'otheruserid' => new external_value(PARAM_INT, 'The id of the user whose profile we want to view'),
696 )
697 );
698 }
699
700 /**
701 * Get the profile information for a contact.
702 *
703 * @param int $currentuserid The current user's id
704 * @param int $otheruserid The id of the user whose profile we are viewing
705 * @return external_single_structure
706 */
707 public static function data_for_messagearea_get_profile($currentuserid, $otheruserid) {
708 global $CFG, $PAGE;
709
710 // Check if messaging is enabled.
711 if (!$CFG->messaging) {
712 throw new moodle_exception('disabled', 'message');
713 }
714
715 $params = array(
716 'currentuserid' => $currentuserid,
717 'otheruserid' => $otheruserid
718 );
719 self::validate_parameters(self::data_for_messagearea_get_profile_parameters(), $params);
720
721 self::validate_context(context_user::instance($otheruserid));
722
723 $profile = \core_message\api::get_profile($currentuserid, $otheruserid);
724
725 $renderer = $PAGE->get_renderer('core_message');
726 return $profile->export_for_template($renderer);
727 }
728
729 /**
730 * Get profile returns.
731 *
732 * @return external_single_structure
733 */
734 public static function data_for_messagearea_get_profile_returns() {
735 return new external_single_structure(
736 array(
737 'iscurrentuser' => new external_value(PARAM_BOOL, 'Is the currently logged in user the user we are viewing the profile on behalf of?'),
738 'currentuserid' => new external_value(PARAM_INT, 'The current user\'s id'),
739 'otheruserid' => new external_value(PARAM_INT, 'The id of the user whose profile we are viewing'),
740 'email' => new external_value(core_user::get_property_type('email'), 'An email address'),
741 'country' => new external_value(core_user::get_property_type('country'), 'Home country code of the user'),
742 'city' => new external_value(core_user::get_property_type('city'), 'Home city of the user'),
743 'fullname' => new external_value(PARAM_NOTAGS, 'The user\'s name'),
744 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL'),
745 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL'),
746 'isblocked' => new external_value(PARAM_BOOL, 'Is the user blocked?'),
747 'iscontact' => new external_value(PARAM_BOOL, 'Is the user a contact?')
748 )
749 );
750 }
751
d6731600
FM
752 /**
753 * Get contacts parameters description.
754 *
755 * @return external_function_parameters
5bcfd504 756 * @since Moodle 2.5
d6731600
FM
757 */
758 public static function get_contacts_parameters() {
759 return new external_function_parameters(array());
760 }
761
762 /**
763 * Get contacts.
764 *
765 * @param array $userids array of user IDs.
766 * @return external_description
5bcfd504 767 * @since Moodle 2.5
d6731600
FM
768 */
769 public static function get_contacts() {
d85bedf7 770 global $CFG, $PAGE;
436bbf89
DM
771
772 // Check if messaging is enabled.
773 if (!$CFG->messaging) {
774 throw new moodle_exception('disabled', 'message');
775 }
776
d6731600
FM
777 require_once($CFG->dirroot . '/user/lib.php');
778
779 list($online, $offline, $strangers) = message_get_contacts();
780 $allcontacts = array('online' => $online, 'offline' => $offline, 'strangers' => $strangers);
781 foreach ($allcontacts as $mode => $contacts) {
782 foreach ($contacts as $key => $contact) {
783 $newcontact = array(
784 'id' => $contact->id,
785 'fullname' => fullname($contact),
786 'unread' => $contact->messagecount
787 );
788
d85bedf7
JL
789 $userpicture = new user_picture($contact);
790 $userpicture->size = 1; // Size f1.
791 $newcontact['profileimageurl'] = $userpicture->get_url($PAGE)->out(false);
792 $userpicture->size = 0; // Size f2.
793 $newcontact['profileimageurlsmall'] = $userpicture->get_url($PAGE)->out(false);
d6731600
FM
794
795 $allcontacts[$mode][$key] = $newcontact;
796 }
797 }
798 return $allcontacts;
799 }
800
801 /**
802 * Get contacts return description.
803 *
804 * @return external_description
5bcfd504 805 * @since Moodle 2.5
d6731600
FM
806 */
807 public static function get_contacts_returns() {
808 return new external_single_structure(
809 array(
810 'online' => new external_multiple_structure(
811 new external_single_structure(
812 array(
813 'id' => new external_value(PARAM_INT, 'User ID'),
814 'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
815 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL),
816 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL', VALUE_OPTIONAL),
817 'unread' => new external_value(PARAM_INT, 'Unread message count')
818 )
819 ),
820 'List of online contacts'
821 ),
822 'offline' => new external_multiple_structure(
823 new external_single_structure(
824 array(
825 'id' => new external_value(PARAM_INT, 'User ID'),
826 'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
827 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL),
828 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL', VALUE_OPTIONAL),
829 'unread' => new external_value(PARAM_INT, 'Unread message count')
830 )
831 ),
832 'List of offline contacts'
833 ),
834 'strangers' => new external_multiple_structure(
835 new external_single_structure(
836 array(
837 'id' => new external_value(PARAM_INT, 'User ID'),
838 'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
839 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL),
840 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL', VALUE_OPTIONAL),
841 'unread' => new external_value(PARAM_INT, 'Unread message count')
842 )
843 ),
844 'List of users that are not in the user\'s contact list but have sent a message'
845 )
846 )
847 );
848 }
849
850 /**
851 * Search contacts parameters description.
852 *
853 * @return external_function_parameters
5bcfd504 854 * @since Moodle 2.5
d6731600
FM
855 */
856 public static function search_contacts_parameters() {
857 return new external_function_parameters(
858 array(
859 'searchtext' => new external_value(PARAM_CLEAN, 'String the user\'s fullname has to match to be found'),
860 'onlymycourses' => new external_value(PARAM_BOOL, 'Limit search to the user\'s courses',
861 VALUE_DEFAULT, false)
862 )
863 );
864 }
865
866 /**
867 * Search contacts.
868 *
869 * @param string $searchtext query string.
870 * @param bool $onlymycourses limit the search to the user's courses only.
871 * @return external_description
5bcfd504 872 * @since Moodle 2.5
d6731600
FM
873 */
874 public static function search_contacts($searchtext, $onlymycourses = false) {
d85bedf7 875 global $CFG, $USER, $PAGE;
11d83ab3 876 require_once($CFG->dirroot . '/user/lib.php');
436bbf89
DM
877
878 // Check if messaging is enabled.
879 if (!$CFG->messaging) {
880 throw new moodle_exception('disabled', 'message');
881 }
882
d6731600
FM
883 require_once($CFG->libdir . '/enrollib.php');
884
885 $params = array('searchtext' => $searchtext, 'onlymycourses' => $onlymycourses);
886 $params = self::validate_parameters(self::search_contacts_parameters(), $params);
887
888 // Extra validation, we do not allow empty queries.
889 if ($params['searchtext'] === '') {
890 throw new moodle_exception('querystringcannotbeempty');
891 }
892
893 $courseids = array();
894 if ($params['onlymycourses']) {
895 $mycourses = enrol_get_my_courses(array('id'));
896 foreach ($mycourses as $mycourse) {
897 $courseids[] = $mycourse->id;
898 }
899 } else {
900 $courseids[] = SITEID;
901 }
902
903 // Retrieving the users matching the query.
904 $users = message_search_users($courseids, $params['searchtext']);
905 $results = array();
906 foreach ($users as $user) {
907 $results[$user->id] = $user;
908 }
909
910 // Reorganising information.
911 foreach ($results as &$user) {
912 $newuser = array(
913 'id' => $user->id,
914 'fullname' => fullname($user)
915 );
916
917 // Avoid undefined property notice as phone not specified.
918 $user->phone1 = null;
919 $user->phone2 = null;
920
d85bedf7
JL
921 $userpicture = new user_picture($user);
922 $userpicture->size = 1; // Size f1.
923 $newuser['profileimageurl'] = $userpicture->get_url($PAGE)->out(false);
924 $userpicture->size = 0; // Size f2.
925 $newuser['profileimageurlsmall'] = $userpicture->get_url($PAGE)->out(false);
d6731600
FM
926
927 $user = $newuser;
928 }
929
930 return $results;
931 }
932
933 /**
934 * Search contacts return description.
935 *
936 * @return external_description
5bcfd504 937 * @since Moodle 2.5
d6731600
FM
938 */
939 public static function search_contacts_returns() {
940 return new external_multiple_structure(
941 new external_single_structure(
942 array(
943 'id' => new external_value(PARAM_INT, 'User ID'),
944 'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
945 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL),
946 'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL', VALUE_OPTIONAL)
947 )
948 ),
949 'List of contacts'
950 );
951 }
aff9da17
JL
952
953 /**
954 * Get messages parameters description.
955 *
956 * @return external_function_parameters
193edf7f 957 * @since 2.8
aff9da17
JL
958 */
959 public static function get_messages_parameters() {
960 return new external_function_parameters(
961 array(
6ff4464b 962 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
127ef540
SH
963 'useridfrom' => new external_value(
964 PARAM_INT, 'the user id who send the message, 0 for any user. -10 or -20 for no-reply or support user',
965 VALUE_DEFAULT, 0),
966 'type' => new external_value(
967 PARAM_ALPHA, 'type of message to return, expected values are: notifications, conversations and both',
968 VALUE_DEFAULT, 'both'),
6ff4464b 969 'read' => new external_value(PARAM_BOOL, 'true for getting read messages, false for unread', VALUE_DEFAULT, true),
127ef540
SH
970 'newestfirst' => new external_value(
971 PARAM_BOOL, 'true for ordering by newest first, false for oldest first',
972 VALUE_DEFAULT, true),
aff9da17 973 'limitfrom' => new external_value(PARAM_INT, 'limit from', VALUE_DEFAULT, 0),
127ef540
SH
974 'limitnum' => new external_value(PARAM_INT, 'limit number', VALUE_DEFAULT, 0)
975 )
aff9da17
JL
976 );
977 }
978
979 /**
980 * Get messages function implementation.
127ef540
SH
981 *
982 * @since 2.8
983 * @throws invalid_parameter_exception
984 * @throws moodle_exception
6ff4464b
JL
985 * @param int $useridto the user id who received the message
986 * @param int $useridfrom the user id who send the message. -10 or -20 for no-reply or support user
193edf7f 987 * @param string $type type of message to return, expected values: notifications, conversations and both
aff9da17 988 * @param bool $read true for retreiving read messages, false for unread
6ff4464b 989 * @param bool $newestfirst true for ordering by newest first, false for oldest first
aff9da17
JL
990 * @param int $limitfrom limit from
991 * @param int $limitnum limit num
992 * @return external_description
aff9da17 993 */
193edf7f 994 public static function get_messages($useridto, $useridfrom = 0, $type = 'both', $read = true,
aff9da17 995 $newestfirst = true, $limitfrom = 0, $limitnum = 0) {
127ef540 996 global $CFG, $USER;
aff9da17
JL
997
998 $warnings = array();
999
1000 $params = array(
1001 'useridto' => $useridto,
6ff4464b 1002 'useridfrom' => $useridfrom,
aff9da17
JL
1003 'type' => $type,
1004 'read' => $read,
aff9da17
JL
1005 'newestfirst' => $newestfirst,
1006 'limitfrom' => $limitfrom,
1007 'limitnum' => $limitnum
1008 );
1009
1010 $params = self::validate_parameters(self::get_messages_parameters(), $params);
1011
1012 $context = context_system::instance();
1013 self::validate_context($context);
1014
1015 $useridto = $params['useridto'];
6ff4464b 1016 $useridfrom = $params['useridfrom'];
aff9da17
JL
1017 $type = $params['type'];
1018 $read = $params['read'];
aff9da17
JL
1019 $newestfirst = $params['newestfirst'];
1020 $limitfrom = $params['limitfrom'];
1021 $limitnum = $params['limitnum'];
1022
1023 $allowedvalues = array('notifications', 'conversations', 'both');
1024 if (!in_array($type, $allowedvalues)) {
1025 throw new invalid_parameter_exception('Invalid value for type parameter (value: ' . $type . '),' .
1026 'allowed values are: ' . implode(',', $allowedvalues));
1027 }
1028
1029 // Check if private messaging between users is allowed.
1030 if (empty($CFG->messaging)) {
1031 // If we are retreiving only conversations, and messaging is disabled, throw an exception.
aff9da17
JL
1032 if ($type == "conversations") {
1033 throw new moodle_exception('disabled', 'message');
1034 }
1035 if ($type == "both") {
1036 $warning = array();
1037 $warning['item'] = 'message';
1038 $warning['itemid'] = $USER->id;
1039 $warning['warningcode'] = '1';
1040 $warning['message'] = 'Private messages (conversations) are not enabled in this site.
1041 Only notifications will be returned';
1042 $warnings[] = $warning;
1043 }
1044 }
1045
1046 if (!empty($useridto)) {
6ff4464b
JL
1047 if (core_user::is_real_user($useridto)) {
1048 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
1049 } else {
1050 throw new moodle_exception('invaliduser');
1051 }
aff9da17
JL
1052 }
1053
1054 if (!empty($useridfrom)) {
1055 // We use get_user here because the from user can be the noreply or support user.
1056 $userfrom = core_user::get_user($useridfrom, '*', MUST_EXIST);
1057 }
1058
1059 // Check if the current user is the sender/receiver or just a privileged user.
1060 if ($useridto != $USER->id and $useridfrom != $USER->id and
1061 !has_capability('moodle/site:readallmessages', $context)) {
1062 throw new moodle_exception('accessdenied', 'admin');
1063 }
1064
127ef540 1065 // Which type of messages to retrieve.
193edf7f 1066 $notifications = -1;
aff9da17 1067 if ($type != 'both') {
193edf7f 1068 $notifications = ($type == 'notifications') ? 1 : 0;
aff9da17
JL
1069 }
1070
aff9da17 1071 $orderdirection = $newestfirst ? 'DESC' : 'ASC';
193edf7f 1072 $sort = "mr.timecreated $orderdirection";
aff9da17 1073
193edf7f 1074 if ($messages = message_get_messages($useridto, $useridfrom, $notifications, $read, $sort, $limitfrom, $limitnum)) {
aff9da17
JL
1075 $canviewfullname = has_capability('moodle/site:viewfullnames', $context);
1076
1077 // In some cases, we don't need to get the to/from user objects from the sql query.
1078 $userfromfullname = '';
1079 $usertofullname = '';
1080
1081 // In this case, the useridto field is not empty, so we can get the user destinatary fullname from there.
1082 if (!empty($useridto)) {
1083 $usertofullname = fullname($userto, $canviewfullname);
1084 // The user from may or may not be filled.
1085 if (!empty($useridfrom)) {
1086 $userfromfullname = fullname($userfrom, $canviewfullname);
1087 }
1088 } else {
1089 // If the useridto field is empty, the useridfrom must be filled.
1090 $userfromfullname = fullname($userfrom, $canviewfullname);
1091 }
aff9da17
JL
1092 foreach ($messages as $mid => $message) {
1093
ea21d637
JL
1094 // Do not return deleted messages.
1095 if (($useridto == $USER->id and $message->timeusertodeleted) or
1096 ($useridfrom == $USER->id and $message->timeuserfromdeleted)) {
1097
1098 unset($messages[$mid]);
1099 continue;
1100 }
1101
aff9da17
JL
1102 // We need to get the user from the query.
1103 if (empty($userfromfullname)) {
6ff4464b
JL
1104 // Check for non-reply and support users.
1105 if (core_user::is_real_user($message->useridfrom)) {
127ef540 1106 $user = new stdClass();
6ff4464b
JL
1107 $user = username_load_fields_from_object($user, $message, 'userfrom');
1108 $message->userfromfullname = fullname($user, $canviewfullname);
1109 } else {
1110 $user = core_user::get_user($message->useridfrom);
1111 $message->userfromfullname = fullname($user, $canviewfullname);
1112 }
aff9da17
JL
1113 } else {
1114 $message->userfromfullname = $userfromfullname;
1115 }
1116
1117 // We need to get the user from the query.
1118 if (empty($usertofullname)) {
127ef540 1119 $user = new stdClass();
aff9da17
JL
1120 $user = username_load_fields_from_object($user, $message, 'userto');
1121 $message->usertofullname = fullname($user, $canviewfullname);
1122 } else {
1123 $message->usertofullname = $usertofullname;
1124 }
1125
193edf7f 1126 // This field is only available in the message_read table.
aff9da17
JL
1127 if (!isset($message->timeread)) {
1128 $message->timeread = 0;
1129 }
1130
aff9da17 1131 $message->text = message_format_message_text($message);
aff9da17
JL
1132 $messages[$mid] = (array) $message;
1133 }
1134 }
1135
1136 $results = array(
1137 'messages' => $messages,
1138 'warnings' => $warnings
1139 );
1140
1141 return $results;
1142 }
1143
1144 /**
1145 * Get messages return description.
1146 *
6ff4464b 1147 * @return external_single_structure
193edf7f 1148 * @since 2.8
aff9da17
JL
1149 */
1150 public static function get_messages_returns() {
1151 return new external_single_structure(
1152 array(
1153 'messages' => new external_multiple_structure(
1154 new external_single_structure(
1155 array(
193edf7f 1156 'id' => new external_value(PARAM_INT, 'Message id'),
aff9da17
JL
1157 'useridfrom' => new external_value(PARAM_INT, 'User from id'),
1158 'useridto' => new external_value(PARAM_INT, 'User to id'),
1159 'subject' => new external_value(PARAM_TEXT, 'The message subject'),
1160 'text' => new external_value(PARAM_RAW, 'The message text formated'),
1161 'fullmessage' => new external_value(PARAM_RAW, 'The message'),
193edf7f 1162 'fullmessageformat' => new external_format_value('fullmessage'),
aff9da17
JL
1163 'fullmessagehtml' => new external_value(PARAM_RAW, 'The message in html'),
1164 'smallmessage' => new external_value(PARAM_RAW, 'The shorten message'),
1165 'notification' => new external_value(PARAM_INT, 'Is a notification?'),
1166 'contexturl' => new external_value(PARAM_RAW, 'Context URL'),
1167 'contexturlname' => new external_value(PARAM_TEXT, 'Context URL link name'),
1168 'timecreated' => new external_value(PARAM_INT, 'Time created'),
1169 'timeread' => new external_value(PARAM_INT, 'Time read'),
1170 'usertofullname' => new external_value(PARAM_TEXT, 'User to full name'),
1171 'userfromfullname' => new external_value(PARAM_TEXT, 'User from full name')
1172 ), 'message'
1173 )
1174 ),
1175 'warnings' => new external_warnings()
1176 )
1177 );
3274d5ca
RW
1178 }
1179
1180 /**
1181 * Get notifications parameters description.
1182 *
1183 * @return external_function_parameters
1184 * @since 3.2
1185 */
1186 public static function get_notifications_parameters() {
1187 return new external_function_parameters(
1188 array(
1189 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
1190 'useridfrom' => new external_value(
1191 PARAM_INT, 'the user id who send the message, 0 for any user. -10 or -20 for no-reply or support user',
1192 VALUE_DEFAULT, 0),
1193 'status' => new external_value(
1194 PARAM_ALPHA, 'filter the results to just "read" or "unread" notifications',
1195 VALUE_DEFAULT, ''),
c5dd16a1
RW
1196 'embedpreference' => new external_value(
1197 PARAM_BOOL, 'true for returning user\'s preference for the notification',
1198 VALUE_DEFAULT, false),
3274d5ca
RW
1199 'embeduserto' => new external_value(
1200 PARAM_BOOL, 'true for returning user details for the recipient in each notification',
1201 VALUE_DEFAULT, false),
1202 'embeduserfrom' => new external_value(
1203 PARAM_BOOL, 'true for returning user details for the sender in each notification',
1204 VALUE_DEFAULT, false),
1205 'newestfirst' => new external_value(
1206 PARAM_BOOL, 'true for ordering by newest first, false for oldest first',
1207 VALUE_DEFAULT, true),
1208 'markasread' => new external_value(
1209 PARAM_BOOL, 'mark notifications as read when they are returned by this function',
1210 VALUE_DEFAULT, false),
1211 'limit' => new external_value(PARAM_INT, 'the number of results to return', VALUE_DEFAULT, 0),
1212 'offset' => new external_value(PARAM_INT, 'offset the result set by a given amount', VALUE_DEFAULT, 0)
1213 )
1214 );
1215 }
1216
1217 /**
1218 * Get notifications function.
1219 *
1220 * @since 3.2
1221 * @throws invalid_parameter_exception
1222 * @throws moodle_exception
c5dd16a1
RW
1223 * @param int $useridto the user id who received the message
1224 * @param int $useridfrom the user id who send the message. -10 or -20 for no-reply or support user
1225 * @param string $status filter the results to only read or unread notifications
1226 * @param bool $embedpreference true to embed the recipient user details in the record for each notification
1227 * @param bool $embeduserto true to embed the recipient user details in the record for each notification
1228 * @param bool $embeduserfrom true to embed the send user details in the record for each notification
1229 * @param bool $newestfirst true for ordering by newest first, false for oldest first
1230 * @param bool $markasread mark notifications as read when they are returned by this function
1231 * @param int $limit the number of results to return
1232 * @param int $offset offset the result set by a given amount
3274d5ca
RW
1233 * @return external_description
1234 */
c5dd16a1
RW
1235 public static function get_notifications($useridto, $useridfrom, $status, $embedpreference,
1236 $embeduserto, $embeduserfrom, $newestfirst, $markasread, $limit, $offset) {
3274d5ca
RW
1237 global $CFG, $USER, $OUTPUT;
1238
1239 $params = self::validate_parameters(
1240 self::get_notifications_parameters(),
1241 array(
1242 'useridto' => $useridto,
1243 'useridfrom' => $useridfrom,
1244 'status' => $status,
c5dd16a1 1245 'embedpreference' => $embedpreference,
3274d5ca
RW
1246 'embeduserto' => $embeduserto,
1247 'embeduserfrom' => $embeduserfrom,
1248 'newestfirst' => $newestfirst,
1249 'markasread' => $markasread,
1250 'limit' => $limit,
1251 'offset' => $offset,
1252 )
1253 );
1254
1255 $context = context_system::instance();
1256 self::validate_context($context);
1257
1258 $useridto = $params['useridto'];
1259 $useridfrom = $params['useridfrom'];
1260 $status = $params['status'];
c5dd16a1 1261 $embedpreference = $params['embedpreference'];
3274d5ca
RW
1262 $embeduserto = $params['embeduserto'];
1263 $embeduserfrom = $params['embeduserfrom'];
1264 $newestfirst = $params['newestfirst'];
1265 $markasread = $params['markasread'];
1266 $limit = $params['limit'];
1267 $offset = $params['offset'];
c5dd16a1 1268 $issuperuser = has_capability('moodle/site:readallmessages', $context);
3274d5ca
RW
1269
1270 if (!empty($useridto)) {
1271 if (core_user::is_real_user($useridto)) {
1272 if ($embeduserto) {
1273 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
1274 }
1275 } else {
1276 throw new moodle_exception('invaliduser');
1277 }
1278 }
1279
1280 if (!empty($useridfrom) && $embeduserfrom) {
1281 // We use get_user here because the from user can be the noreply or support user.
1282 $userfrom = core_user::get_user($useridfrom, '*', MUST_EXIST);
1283 }
1284
1285 // Check if the current user is the sender/receiver or just a privileged user.
c5dd16a1 1286 if ($useridto != $USER->id and $useridfrom != $USER->id and !$issuperuser) {
3274d5ca
RW
1287 throw new moodle_exception('accessdenied', 'admin');
1288 }
1289
1290 $sort = $newestfirst ? 'DESC' : 'ASC';
1291 $notifications = message_get_notifications($useridto, $useridfrom, $status, $embeduserto, $embeduserfrom, $sort, $limit, $offset);
1292
1293 if ($notifications) {
1294 // In some cases, we don't need to get the to/from user objects from the sql query.
1295 $userfromfullname = '';
1296 $usertofullname = '';
1297
1298 // In this case, the useridto field is not empty, so we can get the user destinatary fullname from there.
1299 if (!empty($useridto) && $embeduserto) {
1300 $usertofullname = fullname($userto);
1301 // The user from may or may not be filled.
1302 if (!empty($useridfrom) && $embeduserfrom) {
1303 $userfromfullname = fullname($userfrom);
1304 }
1305 } else if (!empty($useridfrom) && $embeduserfrom) {
1306 // If the useridto field is empty, the useridfrom must be filled.
1307 $userfromfullname = fullname($userfrom);
1308 }
1309
1310 foreach ($notifications as $notification) {
1311
1312 if (($useridto == $USER->id and $notification->timeusertodeleted) or
1313 ($useridfrom == $USER->id and $notification->timeuserfromdeleted)) {
1314
1315 $notification->deleted = true;
1316 } else {
1317 $notification->deleted = false;
1318 }
1319
1320 // We need to get the user from the query.
1321 if ($embeduserfrom) {
1322 if (empty($userfromfullname)) {
1323 // Check for non-reply and support users.
1324 if (core_user::is_real_user($notification->useridfrom)) {
1325 $user = new stdClass();
1326 $user = username_load_fields_from_object($user, $notification, 'userfrom');
1327 $profileurl = new moodle_url('/user/profile.php', array('id' => $notification->useridfrom));
1328 $notification->userfromfullname = fullname($user);
1329 $notification->userfromprofileurl = $profileurl->out();
1330 } else {
1331 $notification->userfromfullname = get_string('coresystem');
1332 }
1333 } else {
1334 $notification->userfromfullname = $userfromfullname;
1335 }
1336 }
1337
1338 // We need to get the user from the query.
1339 if ($embeduserto) {
1340 if (empty($usertofullname)) {
1341 $user = new stdClass();
1342 $user = username_load_fields_from_object($user, $notification, 'userto');
1343 $notification->usertofullname = fullname($user);
1344 } else {
1345 $notification->usertofullname = $usertofullname;
1346 }
1347 }
1348
1349 $notification->timecreatedpretty = get_string('ago', 'message', format_time(time() - $notification->timecreated));
1350 $notification->text = message_format_message_text($notification);
1351 $notification->read = $notification->timeread ? true : false;
1352
1353 if (!empty($notification->component) && substr($notification->component, 0, 4) == 'mod_') {
1354 $iconurl = $OUTPUT->pix_url('icon', $notification->component);
1355 } else {
1356 $iconurl = $OUTPUT->pix_url('i/marker', 'core');
1357 }
1358
1359 $notification->iconurl = $iconurl->out();
1360
c5dd16a1
RW
1361 // We only return the logged in user's preferences, so if it isn't the sender or receiver
1362 // of this notification then skip embedding the preferences.
1363 if ($embedpreference && !empty($notification->component) && !empty($notification->eventtype) && !$issuperuser) {
1364 $key = 'message_provider_' . $notification->component . '_' . $notification->eventtype;
1365 $notification->preference = array(
1366 'key' => $key,
1367 'loggedin' => get_user_preferences($key . '_loggedin', $USER->id),
1368 'loggedoff' => get_user_preferences($key . '_loggedoff', $USER->id),
1369 );
1370 }
1371
3274d5ca
RW
1372 if ($markasread && !$notification->read) {
1373 // Have to clone here because this function mutates the given data. Naughty, naughty...
1374 message_mark_message_read(clone $notification, time());
1375 }
1376 }
1377 }
1378
1379 return array(
1380 'notifications' => $notifications,
1381 'unreadcount' => message_count_unread_notifications($useridto, $useridfrom),
1382 );
1383 }
1384
1385 /**
1386 * Get notifications return description.
1387 *
1388 * @return external_single_structure
1389 * @since 3.2
1390 */
1391 public static function get_notifications_returns() {
1392 return new external_single_structure(
1393 array(
1394 'notifications' => new external_multiple_structure(
1395 new external_single_structure(
1396 array(
1397 'id' => new external_value(PARAM_INT, 'Notification id (this is not guaranteed to be unique within this result set)'),
1398 'useridfrom' => new external_value(PARAM_INT, 'User from id'),
1399 'useridto' => new external_value(PARAM_INT, 'User to id'),
1400 'subject' => new external_value(PARAM_TEXT, 'The notification subject'),
1401 'text' => new external_value(PARAM_RAW, 'The message text formated'),
1402 'fullmessage' => new external_value(PARAM_RAW, 'The message'),
1403 'fullmessageformat' => new external_format_value('fullmessage'),
1404 'fullmessagehtml' => new external_value(PARAM_RAW, 'The message in html'),
1405 'smallmessage' => new external_value(PARAM_RAW, 'The shorten message'),
1406 'contexturl' => new external_value(PARAM_RAW, 'Context URL'),
1407 'contexturlname' => new external_value(PARAM_TEXT, 'Context URL link name'),
1408 'timecreated' => new external_value(PARAM_INT, 'Time created'),
1409 'timecreatedpretty' => new external_value(PARAM_TEXT, 'Time created in a pretty format'),
1410 'timeread' => new external_value(PARAM_INT, 'Time read'),
1411 'usertofullname' => new external_value(PARAM_TEXT, 'User to full name', VALUE_OPTIONAL),
1412 'userfromfullname' => new external_value(PARAM_TEXT, 'User from full name', VALUE_OPTIONAL),
1413 'userfromprofileurl' => new external_value(PARAM_URL, 'User from profile url', VALUE_OPTIONAL),
1414 'read' => new external_value(PARAM_BOOL, 'notification read status'),
1415 'deleted' => new external_value(PARAM_BOOL, 'notification deletion status'),
1416 'iconurl' => new external_value(PARAM_URL, 'URL for notification icon'),
1417 'component' => new external_value(PARAM_TEXT, 'The component that generated the notification', VALUE_OPTIONAL),
1418 'eventtype' => new external_value(PARAM_TEXT, 'The type of notification', VALUE_OPTIONAL),
c5dd16a1
RW
1419 'preference' => new external_single_structure(
1420 array (
1421 'key' => new external_value(PARAM_TEXT, 'The preference key'),
1422 'loggedin' => new external_value(PARAM_TEXT, 'The logged in preference setting'),
1423 'loggedoff' => new external_value(PARAM_TEXT, 'The logged off preference setting'),
1424 ),
1425 'The preference configuration',
1426 VALUE_OPTIONAL
1427 ),
3274d5ca
RW
1428 ), 'message'
1429 )
1430 ),
1431 'unreadcount' => new external_value(PARAM_INT, 'the user whose blocked users we want to retrieve'),
1432 )
1433 );
1434 }
1435
1436 /**
1437 * Mark all notifications as read parameters description.
1438 *
1439 * @return external_function_parameters
1440 * @since 3.2
1441 */
1442 public static function mark_all_notifications_as_read_parameters() {
1443 return new external_function_parameters(
1444 array(
1445 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
1446 'useridfrom' => new external_value(
1447 PARAM_INT, 'the user id who send the message, 0 for any user. -10 or -20 for no-reply or support user',
1448 VALUE_DEFAULT, 0),
1449 )
1450 );
1451 }
1452
1453 /**
1454 * Mark all notifications as read function.
1455 *
1456 * @since 3.2
1457 * @throws invalid_parameter_exception
1458 * @throws moodle_exception
1459 * @param int $useridto the user id who received the message
1460 * @param int $useridfrom the user id who send the message. -10 or -20 for no-reply or support user
1461 * @return external_description
1462 */
1463 public static function mark_all_notifications_as_read($useridto, $useridfrom) {
1464 global $CFG, $USER;
1465
1466 $params = self::validate_parameters(
1467 self::mark_all_notifications_as_read_parameters(),
1468 array(
1469 'useridto' => $useridto,
1470 'useridfrom' => $useridfrom,
1471 )
1472 );
1473
1474 $context = context_system::instance();
1475 self::validate_context($context);
1476
1477 $useridto = $params['useridto'];
1478 $useridfrom = $params['useridfrom'];
1479
1480 if (!empty($useridto)) {
1481 if (core_user::is_real_user($useridto)) {
1482 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
1483 } else {
1484 throw new moodle_exception('invaliduser');
1485 }
1486 }
1487
1488 if (!empty($useridfrom)) {
1489 // We use get_user here because the from user can be the noreply or support user.
1490 $userfrom = core_user::get_user($useridfrom, '*', MUST_EXIST);
1491 }
1492
1493 // Check if the current user is the sender/receiver or just a privileged user.
1494 if ($useridto != $USER->id and $useridfrom != $USER->id and
1495 // deleteanymessage seems more reasonable here than readallmessages.
1496 !has_capability('moodle/site:deleteanymessage', $context)) {
1497 throw new moodle_exception('accessdenied', 'admin');
1498 }
1499
1500 message_mark_all_read_for_user($useridto, $useridfrom, 'notification');
1501
1502 return true;
1503 }
1504
1505 /**
1506 * Mark all notifications as read return description.
1507 *
1508 * @return external_single_structure
1509 * @since 3.2
1510 */
1511 public static function mark_all_notifications_as_read_returns() {
1512 return new external_value(PARAM_BOOL, 'True if the messages were marked read, false otherwise');
1513 }
1514
1515 /**
1516 * Get unread notification count parameters description.
1517 *
1518 * @return external_function_parameters
1519 * @since 3.2
1520 */
1521 public static function get_unread_notification_count_parameters() {
1522 return new external_function_parameters(
1523 array(
1524 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
1525 'useridfrom' => new external_value(
1526 PARAM_INT, 'the user id who send the message, 0 for any user. -10 or -20 for no-reply or support user',
1527 VALUE_DEFAULT, 0),
1528 )
1529 );
1530 }
1531
1532 /**
1533 * Get unread notification count function.
1534 *
1535 * @since 3.2
1536 * @throws invalid_parameter_exception
1537 * @throws moodle_exception
1538 * @param int $useridto the user id who received the message
1539 * @param int $useridfrom the user id who send the message. -10 or -20 for no-reply or support user
1540 * @return external_description
1541 */
1542 public static function get_unread_notification_count($useridto, $useridfrom) {
1543 global $CFG, $USER;
1544
1545 $params = self::validate_parameters(
1546 self::get_unread_notification_count_parameters(),
1547 array(
1548 'useridto' => $useridto,
1549 'useridfrom' => $useridfrom,
1550 )
1551 );
1552
1553 $context = context_system::instance();
1554 self::validate_context($context);
1555
1556 $useridto = $params['useridto'];
1557 $useridfrom = $params['useridfrom'];
1558
1559 if (!empty($useridto)) {
1560 if (core_user::is_real_user($useridto)) {
1561 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
1562 } else {
1563 throw new moodle_exception('invaliduser');
1564 }
1565 }
1566
1567 if (!empty($useridfrom)) {
1568 // We use get_user here because the from user can be the noreply or support user.
1569 $userfrom = core_user::get_user($useridfrom, '*', MUST_EXIST);
1570 }
1571
1572 // Check if the current user is the sender/receiver or just a privileged user.
1573 if ($useridto != $USER->id and $useridfrom != $USER->id and
1574 !has_capability('moodle/site:readallmessages', $context)) {
1575 throw new moodle_exception('accessdenied', 'admin');
1576 }
1577
1578 return message_count_unread_notifications($useridto, $useridfrom);
1579 }
1580
1581 /**
1582 * Get unread notification count return description.
1583 *
1584 * @return external_single_structure
1585 * @since 3.2
1586 */
1587 public static function get_unread_notification_count_returns() {
1588 return new external_value(PARAM_INT, 'the user whose blocked users we want to retrieve');
aff9da17
JL
1589 }
1590
60ab2e1b
JL
1591 /**
1592 * Get blocked users parameters description.
1593 *
1594 * @return external_function_parameters
1595 * @since 2.9
1596 */
1597 public static function get_blocked_users_parameters() {
1598 return new external_function_parameters(
1599 array(
1600 'userid' => new external_value(PARAM_INT,
1601 'the user whose blocked users we want to retrieve',
1602 VALUE_REQUIRED),
1603 )
1604 );
1605 }
1606
1607 /**
1608 * Retrieve a list of users blocked
1609 *
1610 * @param int $userid the user whose blocked users we want to retrieve
1611 * @return external_description
1612 * @since 2.9
1613 */
1614 public static function get_blocked_users($userid) {
d85bedf7 1615 global $CFG, $USER, $PAGE;
60ab2e1b
JL
1616
1617 // Warnings array, it can be empty at the end but is mandatory.
1618 $warnings = array();
1619
1620 // Validate params.
1621 $params = array(
1622 'userid' => $userid
1623 );
1624 $params = self::validate_parameters(self::get_blocked_users_parameters(), $params);
1625 $userid = $params['userid'];
1626
1627 // Validate context.
1628 $context = context_system::instance();
1629 self::validate_context($context);
1630
1631 // Check if private messaging between users is allowed.
1632 if (empty($CFG->messaging)) {
1633 throw new moodle_exception('disabled', 'message');
1634 }
1635
4485f7c5
JL
1636 $user = core_user::get_user($userid, '*', MUST_EXIST);
1637 core_user::require_active_user($user);
60ab2e1b
JL
1638
1639 // Check if we have permissions for retrieve the information.
1640 if ($userid != $USER->id and !has_capability('moodle/site:readallmessages', $context)) {
1641 throw new moodle_exception('accessdenied', 'admin');
1642 }
1643
1644 // Now, we can get safely all the blocked users.
1645 $users = message_get_blocked_users($user);
1646
1647 $blockedusers = array();
1648 foreach ($users as $user) {
1649 $newuser = array(
1650 'id' => $user->id,
1651 'fullname' => fullname($user),
1652 );
0b074e88 1653
d85bedf7
JL
1654 $userpicture = new user_picture($user);
1655 $userpicture->size = 1; // Size f1.
1656 $newuser['profileimageurl'] = $userpicture->get_url($PAGE)->out(false);
60ab2e1b
JL
1657
1658 $blockedusers[] = $newuser;
1659 }
1660
1661 $results = array(
1662 'users' => $blockedusers,
1663 'warnings' => $warnings
1664 );
1665 return $results;
1666 }
1667
1668 /**
1669 * Get blocked users return description.
1670 *
1671 * @return external_single_structure
1672 * @since 2.9
1673 */
1674 public static function get_blocked_users_returns() {
1675 return new external_single_structure(
1676 array(
1677 'users' => new external_multiple_structure(
1678 new external_single_structure(
1679 array(
1680 'id' => new external_value(PARAM_INT, 'User ID'),
1681 'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
1682 'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL)
1683 )
1684 ),
1685 'List of blocked users'
1686 ),
1687 'warnings' => new external_warnings()
1688 )
1689 );
1690 }
1691
31c474da
JL
1692 /**
1693 * Returns description of method parameters
1694 *
1695 * @return external_function_parameters
1696 * @since 2.9
1697 */
1698 public static function mark_message_read_parameters() {
1699 return new external_function_parameters(
1700 array(
1701 'messageid' => new external_value(PARAM_INT, 'id of the message (in the message table)'),
1702 'timeread' => new external_value(PARAM_INT, 'timestamp for when the message should be marked read')
1703 )
1704 );
1705 }
1706
1707 /**
1708 * Mark a single message as read, trigger message_viewed event
1709 *
1710 * @param int $messageid id of the message (in the message table)
1711 * @param int $timeread timestamp for when the message should be marked read
1712 * @return external_description
1713 * @throws invalid_parameter_exception
1714 * @throws moodle_exception
1715 * @since 2.9
1716 */
1717 public static function mark_message_read($messageid, $timeread) {
1718 global $CFG, $DB, $USER;
31c474da
JL
1719
1720 // Check if private messaging between users is allowed.
1721 if (empty($CFG->messaging)) {
1722 throw new moodle_exception('disabled', 'message');
1723 }
1724
1725 // Warnings array, it can be empty at the end but is mandatory.
1726 $warnings = array();
1727
1728 // Validate params.
1729 $params = array(
1730 'messageid' => $messageid,
1731 'timeread' => $timeread
1732 );
1733 $params = self::validate_parameters(self::mark_message_read_parameters(), $params);
1734
1735 // Validate context.
1736 $context = context_system::instance();
1737 self::validate_context($context);
1738
1739 $message = $DB->get_record('message', array('id' => $params['messageid']), '*', MUST_EXIST);
1740
1741 if ($message->useridto != $USER->id) {
1742 throw new invalid_parameter_exception('Invalid messageid, you don\'t have permissions to mark this message as read');
1743 }
1744
1745 $messageid = message_mark_message_read($message, $params['timeread']);
1746
1747 $results = array(
1748 'messageid' => $messageid,
1749 'warnings' => $warnings
1750 );
1751 return $results;
1752 }
1753
1754 /**
1755 * Returns description of method result value
1756 *
1757 * @return external_description
1758 * @since 2.9
1759 */
1760 public static function mark_message_read_returns() {
1761 return new external_single_structure(
1762 array(
1763 'messageid' => new external_value(PARAM_INT, 'the id of the message in the message_read table'),
1764 'warnings' => new external_warnings()
1765 )
1766 );
1767 }
1768
dec0cd99
MN
1769 /**
1770 * Returns description of method parameters.
1771 *
1772 * @return external_function_parameters
1773 * @since 3.2
1774 */
1775 public static function delete_conversation_parameters() {
1776 return new external_function_parameters(
1777 array(
1778 'userid' => new external_value(PARAM_INT, 'The user id of who we want to delete the conversation for'),
1779 'otheruserid' => new external_value(PARAM_INT, 'The user id of the other user in the conversation'),
1780 )
1781 );
1782 }
1783
1784 /**
1785 * Deletes a conversation.
1786 *
1787 * @param int $userid The user id of who we want to delete the conversation for
1788 * @param int $otheruserid The user id of the other user in the conversation
1789 * @return array
1790 * @throws moodle_exception
1791 * @since 3.2
1792 */
1793 public static function delete_conversation($userid, $otheruserid) {
1794 global $CFG;
1795
1796 // Check if private messaging between users is allowed.
1797 if (empty($CFG->messaging)) {
1798 throw new moodle_exception('disabled', 'message');
1799 }
1800
1801 // Warnings array, it can be empty at the end but is mandatory.
1802 $warnings = array();
1803
1804 // Validate params.
1805 $params = array(
1806 'userid' => $userid,
1807 'otheruserid' => $otheruserid,
1808 );
1809 $params = self::validate_parameters(self::delete_conversation_parameters(), $params);
1810
1811 // Validate context.
1812 $context = context_system::instance();
1813 self::validate_context($context);
1814
1815 $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
1816 core_user::require_active_user($user);
1817
1818 if (\core_message\api::can_delete_conversation($user->id)) {
1819 $status = \core_message\api::delete_conversation($user->id, $otheruserid);
1820 } else {
1821 throw new moodle_exception('You do not have permission to delete messages');
1822 }
1823
1824 $results = array(
1825 'status' => $status,
1826 'warnings' => $warnings
1827 );
1828
1829 return $results;
1830 }
1831
1832 /**
1833 * Returns description of method result value.
1834 *
1835 * @return external_description
1836 * @since 3.2
1837 */
1838 public static function delete_conversation_returns() {
1839 return new external_single_structure(
1840 array(
1841 'status' => new external_value(PARAM_BOOL, 'True if the conversation was deleted, false otherwise'),
1842 'warnings' => new external_warnings()
1843 )
1844 );
1845 }
1846
419b1128
JL
1847 /**
1848 * Returns description of method parameters
1849 *
1850 * @return external_function_parameters
1851 * @since 3.1
1852 */
1853 public static function delete_message_parameters() {
1854 return new external_function_parameters(
1855 array(
1856 'messageid' => new external_value(PARAM_INT, 'The message id'),
1857 'userid' => new external_value(PARAM_INT, 'The user id of who we want to delete the message for'),
1858 'read' => new external_value(PARAM_BOOL, 'If is a message read', VALUE_DEFAULT, true)
1859 )
1860 );
1861 }
1862
1863 /**
1864 * Deletes a message
1865 *
1866 * @param int $messageid the message id
1867 * @param int $userid the user id of who we want to delete the message for
1868 * @param bool $read if is a message read (default to true)
1869 * @return external_description
1870 * @throws moodle_exception
1871 * @since 3.1
1872 */
1873 public static function delete_message($messageid, $userid, $read = true) {
1874 global $CFG, $DB;
419b1128
JL
1875
1876 // Check if private messaging between users is allowed.
1877 if (empty($CFG->messaging)) {
1878 throw new moodle_exception('disabled', 'message');
1879 }
1880
1881 // Warnings array, it can be empty at the end but is mandatory.
1882 $warnings = array();
1883
1884 // Validate params.
1885 $params = array(
1886 'messageid' => $messageid,
1887 'userid' => $userid,
1888 'read' => $read
1889 );
1890 $params = self::validate_parameters(self::delete_message_parameters(), $params);
1891
1892 // Validate context.
1893 $context = context_system::instance();
1894 self::validate_context($context);
1895
1896 $messagestable = $params['read'] ? 'message_read' : 'message';
1897 $message = $DB->get_record($messagestable, array('id' => $params['messageid']), '*', MUST_EXIST);
1898
1899 $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
1900 core_user::require_active_user($user);
1901
1902 $status = false;
1903 if (message_can_delete_message($message, $user->id)) {
1904 $status = message_delete_message($message, $user->id);;
1905 } else {
1906 throw new moodle_exception('You do not have permission to delete this message');
1907 }
1908
1909 $results = array(
1910 'status' => $status,
1911 'warnings' => $warnings
1912 );
1913 return $results;
1914 }
1915
1916 /**
1917 * Returns description of method result value
1918 *
1919 * @return external_description
1920 * @since 3.1
1921 */
1922 public static function delete_message_returns() {
1923 return new external_single_structure(
1924 array(
1925 'status' => new external_value(PARAM_BOOL, 'True if the message was deleted, false otherwise'),
1926 'warnings' => new external_warnings()
1927 )
1928 );
1929 }
1930
a0eabdd3
RW
1931 /**
1932 * Returns description of method parameters
1933 *
1934 * @return external_function_parameters
1935 * @since 3.2
1936 */
1937 public static function message_processor_config_form_parameters() {
1938 return new external_function_parameters(
1939 array(
1940 'userid' => new external_value(PARAM_INT, 'id of the user, 0 for current user', VALUE_REQUIRED),
1941 'name' => new external_value(PARAM_TEXT, 'The name of the message processor'),
1942 'formvalues' => new external_multiple_structure(
1943 new external_single_structure(
1944 array(
1945 'name' => new external_value(PARAM_TEXT, 'name of the form element', VALUE_REQUIRED),
1946 'value' => new external_value(PARAM_RAW, 'value of the form element', VALUE_REQUIRED),
1947 )
1948 ),
1949 'Config form values',
1950 VALUE_REQUIRED
1951 ),
1952 )
1953 );
1954 }
1955
1956 /**
1957 * Processes a message processor config form.
1958 *
1959 * @param int $userid the user id
1960 * @param string $name the name of the processor
1961 * @param array $formvalues the form values
1962 * @return external_description
1963 * @throws moodle_exception
1964 * @since 3.2
1965 */
1966 public static function message_processor_config_form($userid, $name, $formvalues) {
1967 $params = self::validate_parameters(
1968 self::message_processor_config_form_parameters(),
1969 array(
1970 'userid' => $userid,
1971 'name' => $name,
1972 'formvalues' => $formvalues,
1973 )
1974 );
1975
1976 if (empty($params['userid'])) {
1977 $params['userid'] = $USER->id;
1978 }
1979
1980 $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
1981 core_user::require_active_user($user);
1982
1983 $processor = get_message_processor($name);
1984 $preferences = [];
1985 $form = new stdClass();
1986
1987 foreach ($formvalues as $formvalue) {
1988 $form->$formvalue['name'] = $formvalue['value'];
1989 }
1990
1991 $processor->process_form($form, $preferences);
1992
1993 if (!empty($preferences)) {
1994 set_user_preferences($preferences, $userid);
1995 }
1996 }
1997
1998 /**
1999 * Returns description of method result value
2000 *
2001 * @return external_description
2002 * @since 3.2
2003 */
2004 public static function message_processor_config_form_returns() {
2005 return null;
2006 }
a623b6b8 2007}