MDL-54708 message: notification popover respects message preferences
[moodle.git] / message / externallib.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
18 /**
19  * External message API
20  *
21  * @package    core_message
22  * @category   external
23  * @copyright  2011 Jerome Mouneyrac
24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25  */
27 require_once("$CFG->libdir/externallib.php");
28 require_once($CFG->dirroot . "/message/lib.php");
30 /**
31  * Message external functions
32  *
33  * @package    core_message
34  * @category   external
35  * @copyright  2011 Jerome Mouneyrac
36  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
37  * @since Moodle 2.2
38  */
39 class core_message_external extends external_api {
41     /**
42      * Returns description of method parameters
43      *
44      * @return external_function_parameters
45      * @since Moodle 2.2
46      */
47     public static function send_instant_messages_parameters() {
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'),
54                             'text' => new external_value(PARAM_RAW, 'the text of the message'),
55                             'textformat' => new external_format_value('text', VALUE_DEFAULT),
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     }
64     /**
65      * Send private messages from the current USER to other users
66      *
67      * @param array $messages An array of message to send.
68      * @return array
69      * @since Moodle 2.2
70      */
71     public static function send_instant_messages($messages = array()) {
72         global $CFG, $USER, $DB;
74         // Check if messaging is enabled.
75         if (!$CFG->messaging) {
76             throw new moodle_exception('disabled', 'message');
77         }
79         // Ensure the current user is allowed to run this function
80         $context = context_system::instance();
81         self::validate_context($context);
82         require_capability('moodle/site:sendmessage', $context);
84         $params = self::validate_parameters(self::send_instant_messages_parameters(), array('messages' => $messages));
86         //retrieve all tousers of the messages
87         $receivers = array();
88         foreach($params['messages'] as $message) {
89             $receivers[] = $message['touserid'];
90         }
91         list($sqluserids, $sqlparams) = $DB->get_in_or_equal($receivers, SQL_PARAMS_NAMED, 'userid_');
92         $tousers = $DB->get_records_select("user", "id " . $sqluserids . " AND deleted = 0", $sqlparams);
93         $blocklist   = array();
94         $contactlist = array();
95         $sqlparams['contactid'] = $USER->id;
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();
111         $canreadallmessages = has_capability('moodle/site:readallmessages', $context);
113         $resultmessages = array();
114         foreach ($params['messages'] as $message) {
115             $resultmsg = array(); //the infos about the success of the operation
117             //we are going to do some checking
118             //code should match /messages/index.php checks
119             $success = true;
121             //check the user exists
122             if (empty($tousers[$message['touserid']])) {
123                 $success = false;
124                 $errormessage = get_string('touserdoesntexist', 'message', $message['touserid']);
125             }
127             //check that the touser is not blocking the current user
128             if ($success and !empty($blocklist[$message['touserid']]) and !$canreadallmessages) {
129                 $success = false;
130                 $errormessage = get_string('userisblockingyou', 'message');
131             }
133             // Check if the user is a contact
134             //TODO MDL-31118 performance improvement - edit the function so we can pass an array instead userid
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)) {
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;
140                 $errormessage = get_string('userisblockingyounoncontact', 'message',
141                         fullname(core_user::get_user($message['touserid'])));
142             }
144             //now we can send the message (at least try)
145             if ($success) {
146                 //TODO MDL-31118 performance improvement - edit the function so we can pass an array instead one touser object
147                 $success = message_post_message($USER, $tousers[$message['touserid']],
148                         $message['text'], external_validate_format($message['textformat']));
149             }
151             //build the resultmsg
152             if (isset($message['clientmsgid'])) {
153                 $resultmsg['clientmsgid'] = $message['clientmsgid'];
154             }
155             if ($success) {
156                 $resultmsg['msgid'] = $success;
157             } else {
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 .
161                 $resultmsg['msgid'] = -1;
162                 $resultmsg['errormessage'] = $errormessage;
163             }
165             $resultmessages[] = $resultmsg;
166         }
168         return $resultmessages;
169     }
171     /**
172      * Returns description of method result value
173      *
174      * @return external_description
175      * @since Moodle 2.2
176      */
177     public static function send_instant_messages_returns() {
178         return new external_multiple_structure(
179             new external_single_structure(
180                 array(
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'),
182                     'clientmsgid' => new external_value(PARAM_ALPHANUMEXT, 'your own id for the message', VALUE_OPTIONAL),
183                     'errormessage' => new external_value(PARAM_TEXT, 'error message - if it failed', VALUE_OPTIONAL)
184                 )
185             )
186         );
187     }
189     /**
190      * Create contacts parameters description.
191      *
192      * @return external_function_parameters
193      * @since Moodle 2.5
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'
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)
204             )
205         );
206     }
208     /**
209      * Create contacts.
210      *
211      * @param array $userids array of user IDs.
212      * @param int $userid The id of the user we are creating the contacts for
213      * @return external_description
214      * @since Moodle 2.5
215      */
216     public static function create_contacts($userids, $userid = 0) {
217         global $CFG;
219         // Check if messaging is enabled.
220         if (!$CFG->messaging) {
221             throw new moodle_exception('disabled', 'message');
222         }
224         $params = array('userids' => $userids, 'userid' => $userid);
225         $params = self::validate_parameters(self::create_contacts_parameters(), $params);
227         $warnings = array();
228         foreach ($params['userids'] as $id) {
229             if (!message_add_contact($id, 0, $userid)) {
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     }
241     /**
242      * Create contacts return description.
243      *
244      * @return external_description
245      * @since Moodle 2.5
246      */
247     public static function create_contacts_returns() {
248         return new external_warnings();
249     }
251     /**
252      * Delete contacts parameters description.
253      *
254      * @return external_function_parameters
255      * @since Moodle 2.5
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'
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)
266             )
267         );
268     }
270     /**
271      * Delete contacts.
272      *
273      * @param array $userids array of user IDs.
274      * @param int $userid The id of the user we are deleting the contacts for
275      * @return null
276      * @since Moodle 2.5
277      */
278     public static function delete_contacts($userids, $userid = 0) {
279         global $CFG;
281         // Check if messaging is enabled.
282         if (!$CFG->messaging) {
283             throw new moodle_exception('disabled', 'message');
284         }
286         $params = array('userids' => $userids, 'userid' => $userid);
287         $params = self::validate_parameters(self::delete_contacts_parameters(), $params);
289         foreach ($params['userids'] as $id) {
290             message_remove_contact($id, $userid);
291         }
293         return null;
294     }
296     /**
297      * Delete contacts return description.
298      *
299      * @return external_description
300      * @since Moodle 2.5
301      */
302     public static function delete_contacts_returns() {
303         return null;
304     }
306     /**
307      * Block contacts parameters description.
308      *
309      * @return external_function_parameters
310      * @since Moodle 2.5
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'
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)
321             )
322         );
323     }
325     /**
326      * Block contacts.
327      *
328      * @param array $userids array of user IDs.
329      * @param int $userid The id of the user we are blocking the contacts for
330      * @return external_description
331      * @since Moodle 2.5
332      */
333     public static function block_contacts($userids, $userid = 0) {
334         global $CFG;
336         // Check if messaging is enabled.
337         if (!$CFG->messaging) {
338             throw new moodle_exception('disabled', 'message');
339         }
341         $params = array('userids' => $userids, 'userid' => $userid);
342         $params = self::validate_parameters(self::block_contacts_parameters(), $params);
344         $warnings = array();
345         foreach ($params['userids'] as $id) {
346             if (!message_block_contact($id, $userid)) {
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     }
358     /**
359      * Block contacts return description.
360      *
361      * @return external_description
362      * @since Moodle 2.5
363      */
364     public static function block_contacts_returns() {
365         return new external_warnings();
366     }
368     /**
369      * Unblock contacts parameters description.
370      *
371      * @return external_function_parameters
372      * @since Moodle 2.5
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'
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)
383             )
384         );
385     }
387     /**
388      * Unblock contacts.
389      *
390      * @param array $userids array of user IDs.
391      * @param int $userid The id of the user we are unblocking the contacts for
392      * @return null
393      * @since Moodle 2.5
394      */
395     public static function unblock_contacts($userids, $userid = 0) {
396         global $CFG;
398         // Check if messaging is enabled.
399         if (!$CFG->messaging) {
400             throw new moodle_exception('disabled', 'message');
401         }
403         $params = array('userids' => $userids, 'userid' => $userid);
404         $params = self::validate_parameters(self::unblock_contacts_parameters(), $params);
406         foreach ($params['userids'] as $id) {
407             message_unblock_contact($id, $userid);
408         }
410         return null;
411     }
413     /**
414      * Unblock contacts return description.
415      *
416      * @return external_description
417      * @since Moodle 2.5
418      */
419     public static function unblock_contacts_returns() {
420         return null;
421     }
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     }
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;
449         // Check if messaging is enabled.
450         if (!$CFG->messaging) {
451             throw new moodle_exception('disabled', 'message');
452         }
454         $params = array(
455             'userid' => $userid,
456             'limitfrom' => $limitfrom,
457             'limitnum' => $limitnum
458         );
459         self::validate_parameters(self::data_for_messagearea_conversations_parameters(), $params);
461         self::validate_context(context_user::instance($userid));
463         $contacts = \core_message\api::get_conversations($userid, 0, $limitfrom, $limitnum);
465         $renderer = $PAGE->get_renderer('core_message');
466         return $contacts->export_for_template($renderer);
467     }
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),
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),
490                         )
491                     )
492                 )
493             )
494         );
495     }
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     }
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;
517         // Check if messaging is enabled.
518         if (!$CFG->messaging) {
519             throw new moodle_exception('disabled', 'message');
520         }
522         $params = array(
523             'userid' => $userid,
524             'limitfrom' => $limitfrom,
525             'limitnum' => $limitnum
526         );
527         self::validate_parameters(self::data_for_messagearea_contacts_parameters(), $params);
529         self::validate_context(context_user::instance($userid));
531         $contacts = \core_message\api::get_contacts($userid, $limitfrom, $limitnum);
533         $renderer = $PAGE->get_renderer('core_message');
534         return $contacts->export_for_template($renderer);
535     }
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     }
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     }
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;
574         // Check if messaging is enabled.
575         if (!$CFG->messaging) {
576             throw new moodle_exception('disabled', 'message');
577         }
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);
587         self::validate_context(context_user::instance($currentuserid));
589         $messages = \core_message\api::get_messages($currentuserid, $otheruserid, $limitfrom, $limitnum);
591         $renderer = $PAGE->get_renderer('core_message');
592         return $messages->export_for_template($renderer);
593     }
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(
610                             'id' => new external_value(PARAM_INT, 'The id of the message'),
611                             'text' => new external_value(PARAM_RAW, 'The text of the message'),
612                             'displayblocktime' => new external_value(PARAM_BOOL, 'Should we display the block time?'),
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'),
616                             'isread' => new external_value(PARAM_INT, 'Determines if the message was read or not'),
617                         )
618                     )
619                 )
620             )
621         );
622     }
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     }
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;
648         // Check if messaging is enabled.
649         if (!$CFG->messaging) {
650             throw new moodle_exception('disabled', 'message');
651         }
653         $params = array(
654             'currentuserid' => $currentuserid,
655             'otheruserid' => $otheruserid
656         );
657         self::validate_parameters(self::data_for_messagearea_get_most_recent_message_parameters(), $params);
659         self::validate_context(context_user::instance($currentuserid));
661         $message = \core_message\api::get_most_recent_message($currentuserid, $otheruserid);
663         $renderer = $PAGE->get_renderer('core_message');
664         return $message->export_for_template($renderer);
665     }
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(
675                 'id' => new external_value(PARAM_INT, 'The id of the message'),
676                 'text' => new external_value(PARAM_RAW, 'The text of the message'),
677                 'displayblocktime' => new external_value(PARAM_BOOL, 'Should we display the block time?'),
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'),
681                 'isread' => new external_value(PARAM_INT, 'Determines if the message was read or not'),
682             )
683         );
684     }
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     }
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;
710         // Check if messaging is enabled.
711         if (!$CFG->messaging) {
712             throw new moodle_exception('disabled', 'message');
713         }
715         $params = array(
716             'currentuserid' => $currentuserid,
717             'otheruserid' => $otheruserid
718         );
719         self::validate_parameters(self::data_for_messagearea_get_profile_parameters(), $params);
721         self::validate_context(context_user::instance($otheruserid));
723         $profile = \core_message\api::get_profile($currentuserid, $otheruserid);
725         $renderer = $PAGE->get_renderer('core_message');
726         return $profile->export_for_template($renderer);
727     }
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     }
752     /**
753      * Get contacts parameters description.
754      *
755      * @return external_function_parameters
756      * @since Moodle 2.5
757      */
758     public static function get_contacts_parameters() {
759         return new external_function_parameters(array());
760     }
762     /**
763      * Get contacts.
764      *
765      * @param array $userids array of user IDs.
766      * @return external_description
767      * @since Moodle 2.5
768      */
769     public static function get_contacts() {
770         global $CFG, $PAGE;
772         // Check if messaging is enabled.
773         if (!$CFG->messaging) {
774             throw new moodle_exception('disabled', 'message');
775         }
777         require_once($CFG->dirroot . '/user/lib.php');
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                 );
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);
795                 $allcontacts[$mode][$key] = $newcontact;
796             }
797         }
798         return $allcontacts;
799     }
801     /**
802      * Get contacts return description.
803      *
804      * @return external_description
805      * @since Moodle 2.5
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     }
850     /**
851      * Search contacts parameters description.
852      *
853      * @return external_function_parameters
854      * @since Moodle 2.5
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     }
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
872      * @since Moodle 2.5
873      */
874     public static function search_contacts($searchtext, $onlymycourses = false) {
875         global $CFG, $USER, $PAGE;
876         require_once($CFG->dirroot . '/user/lib.php');
878         // Check if messaging is enabled.
879         if (!$CFG->messaging) {
880             throw new moodle_exception('disabled', 'message');
881         }
883         require_once($CFG->libdir . '/enrollib.php');
885         $params = array('searchtext' => $searchtext, 'onlymycourses' => $onlymycourses);
886         $params = self::validate_parameters(self::search_contacts_parameters(), $params);
888         // Extra validation, we do not allow empty queries.
889         if ($params['searchtext'] === '') {
890             throw new moodle_exception('querystringcannotbeempty');
891         }
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         }
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         }
910         // Reorganising information.
911         foreach ($results as &$user) {
912             $newuser = array(
913                 'id' => $user->id,
914                 'fullname' => fullname($user)
915             );
917             // Avoid undefined property notice as phone not specified.
918             $user->phone1 = null;
919             $user->phone2 = null;
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);
927             $user = $newuser;
928         }
930         return $results;
931     }
933     /**
934      * Search contacts return description.
935      *
936      * @return external_description
937      * @since Moodle 2.5
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     }
953     /**
954      * Get messages parameters description.
955      *
956      * @return external_function_parameters
957      * @since 2.8
958      */
959     public static function get_messages_parameters() {
960         return new external_function_parameters(
961             array(
962                 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
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'),
969                 'read' => new external_value(PARAM_BOOL, 'true for getting read messages, false for unread', VALUE_DEFAULT, true),
970                 'newestfirst' => new external_value(
971                     PARAM_BOOL, 'true for ordering by newest first, false for oldest first',
972                     VALUE_DEFAULT, true),
973                 'limitfrom' => new external_value(PARAM_INT, 'limit from', VALUE_DEFAULT, 0),
974                 'limitnum' => new external_value(PARAM_INT, 'limit number', VALUE_DEFAULT, 0)
975             )
976         );
977     }
979     /**
980      * Get messages function implementation.
981      *
982      * @since  2.8
983      * @throws invalid_parameter_exception
984      * @throws moodle_exception
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
987      * @param  string   $type           type of message to return, expected values: notifications, conversations and both
988      * @param  bool     $read           true for retreiving read messages, false for unread
989      * @param  bool     $newestfirst    true for ordering by newest first, false for oldest first
990      * @param  int      $limitfrom      limit from
991      * @param  int      $limitnum       limit num
992      * @return external_description
993      */
994     public static function get_messages($useridto, $useridfrom = 0, $type = 'both', $read = true,
995                                         $newestfirst = true, $limitfrom = 0, $limitnum = 0) {
996         global $CFG, $USER;
998         $warnings = array();
1000         $params = array(
1001             'useridto' => $useridto,
1002             'useridfrom' => $useridfrom,
1003             'type' => $type,
1004             'read' => $read,
1005             'newestfirst' => $newestfirst,
1006             'limitfrom' => $limitfrom,
1007             'limitnum' => $limitnum
1008         );
1010         $params = self::validate_parameters(self::get_messages_parameters(), $params);
1012         $context = context_system::instance();
1013         self::validate_context($context);
1015         $useridto = $params['useridto'];
1016         $useridfrom = $params['useridfrom'];
1017         $type = $params['type'];
1018         $read = $params['read'];
1019         $newestfirst = $params['newestfirst'];
1020         $limitfrom = $params['limitfrom'];
1021         $limitnum = $params['limitnum'];
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         }
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.
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         }
1046         if (!empty($useridto)) {
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             }
1052         }
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         }
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         }
1065         // Which type of messages to retrieve.
1066         $notifications = -1;
1067         if ($type != 'both') {
1068             $notifications = ($type == 'notifications') ? 1 : 0;
1069         }
1071         $orderdirection = $newestfirst ? 'DESC' : 'ASC';
1072         $sort = "mr.timecreated $orderdirection";
1074         if ($messages = message_get_messages($useridto, $useridfrom, $notifications, $read, $sort, $limitfrom, $limitnum)) {
1075             $canviewfullname = has_capability('moodle/site:viewfullnames', $context);
1077             // In some cases, we don't need to get the to/from user objects from the sql query.
1078             $userfromfullname = '';
1079             $usertofullname = '';
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             }
1092             foreach ($messages as $mid => $message) {
1094                 // Do not return deleted messages.
1095                 if (($useridto == $USER->id and $message->timeusertodeleted) or
1096                         ($useridfrom == $USER->id and $message->timeuserfromdeleted)) {
1098                     unset($messages[$mid]);
1099                     continue;
1100                 }
1102                 // We need to get the user from the query.
1103                 if (empty($userfromfullname)) {
1104                     // Check for non-reply and support users.
1105                     if (core_user::is_real_user($message->useridfrom)) {
1106                         $user = new stdClass();
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                     }
1113                 } else {
1114                     $message->userfromfullname = $userfromfullname;
1115                 }
1117                 // We need to get the user from the query.
1118                 if (empty($usertofullname)) {
1119                     $user = new stdClass();
1120                     $user = username_load_fields_from_object($user, $message, 'userto');
1121                     $message->usertofullname = fullname($user, $canviewfullname);
1122                 } else {
1123                     $message->usertofullname = $usertofullname;
1124                 }
1126                 // This field is only available in the message_read table.
1127                 if (!isset($message->timeread)) {
1128                     $message->timeread = 0;
1129                 }
1131                 $message->text = message_format_message_text($message);
1132                 $messages[$mid] = (array) $message;
1133             }
1134         }
1136         $results = array(
1137             'messages' => $messages,
1138             'warnings' => $warnings
1139         );
1141         return $results;
1142     }
1144     /**
1145      * Get messages return description.
1146      *
1147      * @return external_single_structure
1148      * @since 2.8
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(
1156                             'id' => new external_value(PARAM_INT, 'Message id'),
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'),
1162                             'fullmessageformat' => new external_format_value('fullmessage'),
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         );
1178     }
1180     /**
1181      * Get popup notifications parameters description.
1182      *
1183      * @return external_function_parameters
1184      * @since 3.2
1185      */
1186     public static function get_popup_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                 'status' => new external_value(
1191                     PARAM_ALPHA, 'filter the results to just "read" or "unread" notifications',
1192                     VALUE_DEFAULT, ''),
1193                 'embedpreference' => new external_value(
1194                     PARAM_BOOL, 'true for returning user\'s preference for the notification',
1195                     VALUE_DEFAULT, false),
1196                 'embeduserto' => new external_value(
1197                     PARAM_BOOL, 'true for returning user details for the recipient in each notification',
1198                     VALUE_DEFAULT, false),
1199                 'embeduserfrom' => new external_value(
1200                     PARAM_BOOL, 'true for returning user details for the sender in each notification',
1201                     VALUE_DEFAULT, false),
1202                 'newestfirst' => new external_value(
1203                     PARAM_BOOL, 'true for ordering by newest first, false for oldest first',
1204                     VALUE_DEFAULT, true),
1205                 'markasread' => new external_value(
1206                     PARAM_BOOL, 'mark notifications as read when they are returned by this function',
1207                     VALUE_DEFAULT, false),
1208                 'limit' => new external_value(PARAM_INT, 'the number of results to return', VALUE_DEFAULT, 0),
1209                 'offset' => new external_value(PARAM_INT, 'offset the result set by a given amount', VALUE_DEFAULT, 0)
1210             )
1211         );
1212     }
1214     /**
1215      * Get notifications function.
1216      *
1217      * @since  3.2
1218      * @throws invalid_parameter_exception
1219      * @throws moodle_exception
1220      * @param  int      $useridto           the user id who received the message
1221      * @param  string   $status             filter the results to only read or unread notifications
1222      * @param  bool     $embedpreference    true to embed the recipient user details in the record for each notification
1223      * @param  bool     $embeduserto        true to embed the recipient user details in the record for each notification
1224      * @param  bool     $embeduserfrom      true to embed the send user details in the record for each notification
1225      * @param  bool     $newestfirst        true for ordering by newest first, false for oldest first
1226      * @param  bool     $markasread         mark notifications as read when they are returned by this function
1227      * @param  int      $limit              the number of results to return
1228      * @param  int      $offset             offset the result set by a given amount
1229      * @return external_description
1230      */
1231     public static function get_popup_notifications($useridto, $status, $embedpreference,
1232         $embeduserto, $embeduserfrom, $newestfirst, $markasread, $limit, $offset) {
1233         global $CFG, $USER, $OUTPUT;
1235         $params = self::validate_parameters(
1236             self::get_popup_notifications_parameters(),
1237             array(
1238                 'useridto' => $useridto,
1239                 'status' => $status,
1240                 'embedpreference' => $embedpreference,
1241                 'embeduserto' => $embeduserto,
1242                 'embeduserfrom' => $embeduserfrom,
1243                 'newestfirst' => $newestfirst,
1244                 'markasread' => $markasread,
1245                 'limit' => $limit,
1246                 'offset' => $offset,
1247             )
1248         );
1250         $context = context_system::instance();
1251         self::validate_context($context);
1253         $useridto = $params['useridto'];
1254         $status = $params['status'];
1255         $embedpreference = $params['embedpreference'];
1256         $embeduserto = $params['embeduserto'];
1257         $embeduserfrom = $params['embeduserfrom'];
1258         $newestfirst = $params['newestfirst'];
1259         $markasread = $params['markasread'];
1260         $limit = $params['limit'];
1261         $offset = $params['offset'];
1262         $issuperuser = has_capability('moodle/site:readallmessages', $context);
1264         if (!empty($useridto)) {
1265             if (core_user::is_real_user($useridto)) {
1266                 if ($embeduserto) {
1267                     $userto = core_user::get_user($useridto, '*', MUST_EXIST);
1268                 }
1269             } else {
1270                 throw new moodle_exception('invaliduser');
1271             }
1272         }
1274         // Check if the current user is the sender/receiver or just a privileged user.
1275         if ($useridto != $USER->id and !$issuperuser) {
1276             throw new moodle_exception('accessdenied', 'admin');
1277         }
1279         $sort = $newestfirst ? 'DESC' : 'ASC';
1280         $notifications = message_get_popup_notifications($useridto, $status, $embeduserto, $embeduserfrom, $sort, $limit, $offset);
1282         if ($notifications) {
1283             // In some cases, we don't need to get the to user objects from the sql query.
1284             $usertofullname = '';
1286             // In this case, the useridto field is not empty, so we can get the user destinatary fullname from there.
1287             if (!empty($useridto) && $embeduserto) {
1288                 $usertofullname = fullname($userto);
1289             }
1291             foreach ($notifications as $notification) {
1293                 if ($useridto == $USER->id and $notification->timeusertodeleted) {
1294                     $notification->deleted = true;
1295                 } else {
1296                     $notification->deleted = false;
1297                 }
1299                 // We need to get the user from the query.
1300                 if ($embeduserfrom) {
1301                     // Check for non-reply and support users.
1302                     if (core_user::is_real_user($notification->useridfrom)) {
1303                         $user = new stdClass();
1304                         $user = username_load_fields_from_object($user, $notification, 'userfrom');
1305                         $profileurl = new moodle_url('/user/profile.php', array('id' => $notification->useridfrom));
1306                         $notification->userfromfullname = fullname($user);
1307                         $notification->userfromprofileurl = $profileurl->out();
1308                     } else {
1309                         $notification->userfromfullname = get_string('coresystem');
1310                     }
1311                 }
1313                 // We need to get the user from the query.
1314                 if ($embeduserto) {
1315                     if (empty($usertofullname)) {
1316                         $user = new stdClass();
1317                         $user = username_load_fields_from_object($user, $notification, 'userto');
1318                         $notification->usertofullname = fullname($user);
1319                     } else {
1320                         $notification->usertofullname = $usertofullname;
1321                     }
1322                 }
1324                 $notification->timecreatedpretty = get_string('ago', 'message', format_time(time() - $notification->timecreated));
1325                 $notification->text = message_format_message_text($notification);
1326                 $notification->read = $notification->timeread ? true : false;
1328                 if (!empty($notification->component) && substr($notification->component, 0, 4) == 'mod_') {
1329                     $iconurl = $OUTPUT->pix_url('icon', $notification->component);
1330                 } else {
1331                     $iconurl = $OUTPUT->pix_url('i/marker', 'core');
1332                 }
1334                 $notification->iconurl = $iconurl->out();
1336                 // We only return the logged in user's preferences, so if it isn't the sender or receiver
1337                 // of this notification then skip embedding the preferences.
1338                 if ($embedpreference && !empty($notification->component) && !empty($notification->eventtype) && !$issuperuser) {
1339                     $key = 'message_provider_' . $notification->component . '_' . $notification->eventtype;
1340                     $notification->preference = array(
1341                         'key' => $key,
1342                         'loggedin' => get_user_preferences($key . '_loggedin', $USER->id),
1343                         'loggedoff' => get_user_preferences($key . '_loggedoff', $USER->id),
1344                     );
1345                 }
1347                 if ($markasread && !$notification->read) {
1348                     // Have to clone here because this function mutates the given data. Naughty, naughty...
1349                     message_mark_message_read(clone $notification, time());
1350                 }
1351             }
1352         }
1354         return array(
1355             'notifications' => $notifications,
1356             'unreadcount' => message_count_unread_popup_notifications($useridto),
1357         );
1358     }
1360     /**
1361      * Get notifications return description.
1362      *
1363      * @return external_single_structure
1364      * @since 3.2
1365      */
1366     public static function get_popup_notifications_returns() {
1367         return new external_single_structure(
1368             array(
1369                 'notifications' => new external_multiple_structure(
1370                     new external_single_structure(
1371                         array(
1372                             'id' => new external_value(PARAM_INT, 'Notification id (this is not guaranteed to be unique within this result set)'),
1373                             'useridfrom' => new external_value(PARAM_INT, 'User from id'),
1374                             'useridto' => new external_value(PARAM_INT, 'User to id'),
1375                             'subject' => new external_value(PARAM_TEXT, 'The notification subject'),
1376                             'text' => new external_value(PARAM_RAW, 'The message text formated'),
1377                             'fullmessage' => new external_value(PARAM_RAW, 'The message'),
1378                             'fullmessageformat' => new external_format_value('fullmessage'),
1379                             'fullmessagehtml' => new external_value(PARAM_RAW, 'The message in html'),
1380                             'smallmessage' => new external_value(PARAM_RAW, 'The shorten message'),
1381                             'contexturl' => new external_value(PARAM_RAW, 'Context URL'),
1382                             'contexturlname' => new external_value(PARAM_TEXT, 'Context URL link name'),
1383                             'timecreated' => new external_value(PARAM_INT, 'Time created'),
1384                             'timecreatedpretty' => new external_value(PARAM_TEXT, 'Time created in a pretty format'),
1385                             'timeread' => new external_value(PARAM_INT, 'Time read'),
1386                             'usertofullname' => new external_value(PARAM_TEXT, 'User to full name', VALUE_OPTIONAL),
1387                             'userfromfullname' => new external_value(PARAM_TEXT, 'User from full name', VALUE_OPTIONAL),
1388                             'userfromprofileurl' => new external_value(PARAM_URL, 'User from profile url', VALUE_OPTIONAL),
1389                             'read' => new external_value(PARAM_BOOL, 'notification read status'),
1390                             'deleted' => new external_value(PARAM_BOOL, 'notification deletion status'),
1391                             'iconurl' => new external_value(PARAM_URL, 'URL for notification icon'),
1392                             'component' => new external_value(PARAM_TEXT, 'The component that generated the notification', VALUE_OPTIONAL),
1393                             'eventtype' => new external_value(PARAM_TEXT, 'The type of notification', VALUE_OPTIONAL),
1394                             'preference' => new external_single_structure(
1395                                 array (
1396                                     'key' => new external_value(PARAM_TEXT, 'The preference key'),
1397                                     'loggedin' => new external_value(PARAM_TEXT, 'The logged in preference setting'),
1398                                     'loggedoff' => new external_value(PARAM_TEXT, 'The logged off preference setting'),
1399                                 ),
1400                                 'The preference configuration',
1401                                  VALUE_OPTIONAL
1402                             ),
1403                         ), 'message'
1404                     )
1405                 ),
1406                 'unreadcount' => new external_value(PARAM_INT, 'the user whose blocked users we want to retrieve'),
1407             )
1408         );
1409     }
1411     /**
1412      * Mark all notifications as read parameters description.
1413      *
1414      * @return external_function_parameters
1415      * @since 3.2
1416      */
1417     public static function mark_all_notifications_as_read_parameters() {
1418         return new external_function_parameters(
1419             array(
1420                 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
1421                 'useridfrom' => new external_value(
1422                     PARAM_INT, 'the user id who send the message, 0 for any user. -10 or -20 for no-reply or support user',
1423                     VALUE_DEFAULT, 0),
1424             )
1425         );
1426     }
1428     /**
1429      * Mark all notifications as read function.
1430      *
1431      * @since  3.2
1432      * @throws invalid_parameter_exception
1433      * @throws moodle_exception
1434      * @param  int      $useridto       the user id who received the message
1435      * @param  int      $useridfrom     the user id who send the message. -10 or -20 for no-reply or support user
1436      * @return external_description
1437      */
1438     public static function mark_all_notifications_as_read($useridto, $useridfrom) {
1439         global $CFG, $USER;
1441         $params = self::validate_parameters(
1442             self::mark_all_notifications_as_read_parameters(),
1443             array(
1444                 'useridto' => $useridto,
1445                 'useridfrom' => $useridfrom,
1446             )
1447         );
1449         $context = context_system::instance();
1450         self::validate_context($context);
1452         $useridto = $params['useridto'];
1453         $useridfrom = $params['useridfrom'];
1455         if (!empty($useridto)) {
1456             if (core_user::is_real_user($useridto)) {
1457                 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
1458             } else {
1459                 throw new moodle_exception('invaliduser');
1460             }
1461         }
1463         if (!empty($useridfrom)) {
1464             // We use get_user here because the from user can be the noreply or support user.
1465             $userfrom = core_user::get_user($useridfrom, '*', MUST_EXIST);
1466         }
1468         // Check if the current user is the sender/receiver or just a privileged user.
1469         if ($useridto != $USER->id and $useridfrom != $USER->id and
1470             // deleteanymessage seems more reasonable here than readallmessages.
1471              !has_capability('moodle/site:deleteanymessage', $context)) {
1472             throw new moodle_exception('accessdenied', 'admin');
1473         }
1475         message_mark_all_read_for_user($useridto, $useridfrom, 'notification');
1477         return true;
1478     }
1480     /**
1481      * Mark all notifications as read return description.
1482      *
1483      * @return external_single_structure
1484      * @since 3.2
1485      */
1486     public static function mark_all_notifications_as_read_returns() {
1487         return new external_value(PARAM_BOOL, 'True if the messages were marked read, false otherwise');
1488     }
1490     /**
1491      * Get unread notification count parameters description.
1492      *
1493      * @return external_function_parameters
1494      * @since 3.2
1495      */
1496     public static function get_unread_popup_notification_count_parameters() {
1497         return new external_function_parameters(
1498             array(
1499                 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
1500             )
1501         );
1502     }
1504     /**
1505      * Get unread notification count function.
1506      *
1507      * @since  3.2
1508      * @throws invalid_parameter_exception
1509      * @throws moodle_exception
1510      * @param  int      $useridto       the user id who received the message
1511      * @return external_description
1512      */
1513     public static function get_unread_popup_notification_count($useridto) {
1514         global $CFG, $USER;
1516         $params = self::validate_parameters(
1517             self::get_unread_popup_notification_count_parameters(),
1518             array('useridto' => $useridto)
1519         );
1521         $context = context_system::instance();
1522         self::validate_context($context);
1524         $useridto = $params['useridto'];
1526         if (!empty($useridto)) {
1527             if (core_user::is_real_user($useridto)) {
1528                 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
1529             } else {
1530                 throw new moodle_exception('invaliduser');
1531             }
1532         }
1534         // Check if the current user is the sender/receiver or just a privileged user.
1535         if ($useridto != $USER->id and !has_capability('moodle/site:readallmessages', $context)) {
1536             throw new moodle_exception('accessdenied', 'admin');
1537         }
1539         return message_count_unread_popup_notifications($useridto);
1540     }
1542     /**
1543      * Get unread popup notification count return description.
1544      *
1545      * @return external_single_structure
1546      * @since 3.2
1547      */
1548     public static function get_unread_popup_notification_count_returns() {
1549         return new external_value(PARAM_INT, 'the user whose blocked users we want to retrieve');
1550     }
1552     /**
1553      * Get blocked users parameters description.
1554      *
1555      * @return external_function_parameters
1556      * @since 2.9
1557      */
1558     public static function get_blocked_users_parameters() {
1559         return new external_function_parameters(
1560             array(
1561                 'userid' => new external_value(PARAM_INT,
1562                                 'the user whose blocked users we want to retrieve',
1563                                 VALUE_REQUIRED),
1564             )
1565         );
1566     }
1568     /**
1569      * Retrieve a list of users blocked
1570      *
1571      * @param  int $userid the user whose blocked users we want to retrieve
1572      * @return external_description
1573      * @since 2.9
1574      */
1575     public static function get_blocked_users($userid) {
1576         global $CFG, $USER, $PAGE;
1578         // Warnings array, it can be empty at the end but is mandatory.
1579         $warnings = array();
1581         // Validate params.
1582         $params = array(
1583             'userid' => $userid
1584         );
1585         $params = self::validate_parameters(self::get_blocked_users_parameters(), $params);
1586         $userid = $params['userid'];
1588         // Validate context.
1589         $context = context_system::instance();
1590         self::validate_context($context);
1592         // Check if private messaging between users is allowed.
1593         if (empty($CFG->messaging)) {
1594             throw new moodle_exception('disabled', 'message');
1595         }
1597         $user = core_user::get_user($userid, '*', MUST_EXIST);
1598         core_user::require_active_user($user);
1600         // Check if we have permissions for retrieve the information.
1601         if ($userid != $USER->id and !has_capability('moodle/site:readallmessages', $context)) {
1602             throw new moodle_exception('accessdenied', 'admin');
1603         }
1605         // Now, we can get safely all the blocked users.
1606         $users = message_get_blocked_users($user);
1608         $blockedusers = array();
1609         foreach ($users as $user) {
1610             $newuser = array(
1611                 'id' => $user->id,
1612                 'fullname' => fullname($user),
1613             );
1615             $userpicture = new user_picture($user);
1616             $userpicture->size = 1; // Size f1.
1617             $newuser['profileimageurl'] = $userpicture->get_url($PAGE)->out(false);
1619             $blockedusers[] = $newuser;
1620         }
1622         $results = array(
1623             'users' => $blockedusers,
1624             'warnings' => $warnings
1625         );
1626         return $results;
1627     }
1629     /**
1630      * Get blocked users return description.
1631      *
1632      * @return external_single_structure
1633      * @since 2.9
1634      */
1635     public static function get_blocked_users_returns() {
1636         return new external_single_structure(
1637             array(
1638                 'users' => new external_multiple_structure(
1639                     new external_single_structure(
1640                         array(
1641                             'id' => new external_value(PARAM_INT, 'User ID'),
1642                             'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
1643                             'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL)
1644                         )
1645                     ),
1646                     'List of blocked users'
1647                 ),
1648                 'warnings' => new external_warnings()
1649             )
1650         );
1651     }
1653     /**
1654      * Returns description of method parameters
1655      *
1656      * @return external_function_parameters
1657      * @since 2.9
1658      */
1659     public static function mark_message_read_parameters() {
1660         return new external_function_parameters(
1661             array(
1662                 'messageid' => new external_value(PARAM_INT, 'id of the message (in the message table)'),
1663                 'timeread' => new external_value(PARAM_INT, 'timestamp for when the message should be marked read')
1664             )
1665         );
1666     }
1668     /**
1669      * Mark a single message as read, trigger message_viewed event
1670      *
1671      * @param  int $messageid id of the message (in the message table)
1672      * @param  int $timeread timestamp for when the message should be marked read
1673      * @return external_description
1674      * @throws invalid_parameter_exception
1675      * @throws moodle_exception
1676      * @since 2.9
1677      */
1678     public static function mark_message_read($messageid, $timeread) {
1679         global $CFG, $DB, $USER;
1681         // Check if private messaging between users is allowed.
1682         if (empty($CFG->messaging)) {
1683             throw new moodle_exception('disabled', 'message');
1684         }
1686         // Warnings array, it can be empty at the end but is mandatory.
1687         $warnings = array();
1689         // Validate params.
1690         $params = array(
1691             'messageid' => $messageid,
1692             'timeread' => $timeread
1693         );
1694         $params = self::validate_parameters(self::mark_message_read_parameters(), $params);
1696         // Validate context.
1697         $context = context_system::instance();
1698         self::validate_context($context);
1700         $message = $DB->get_record('message', array('id' => $params['messageid']), '*', MUST_EXIST);
1702         if ($message->useridto != $USER->id) {
1703             throw new invalid_parameter_exception('Invalid messageid, you don\'t have permissions to mark this message as read');
1704         }
1706         $messageid = message_mark_message_read($message, $params['timeread']);
1708         $results = array(
1709             'messageid' => $messageid,
1710             'warnings' => $warnings
1711         );
1712         return $results;
1713     }
1715     /**
1716      * Returns description of method result value
1717      *
1718      * @return external_description
1719      * @since 2.9
1720      */
1721     public static function mark_message_read_returns() {
1722         return new external_single_structure(
1723             array(
1724                 'messageid' => new external_value(PARAM_INT, 'the id of the message in the message_read table'),
1725                 'warnings' => new external_warnings()
1726             )
1727         );
1728     }
1730     /**
1731      * Returns description of method parameters.
1732      *
1733      * @return external_function_parameters
1734      * @since 3.2
1735      */
1736     public static function delete_conversation_parameters() {
1737         return new external_function_parameters(
1738             array(
1739                 'userid' => new external_value(PARAM_INT, 'The user id of who we want to delete the conversation for'),
1740                 'otheruserid' => new external_value(PARAM_INT, 'The user id of the other user in the conversation'),
1741             )
1742         );
1743     }
1745     /**
1746      * Deletes a conversation.
1747      *
1748      * @param int $userid The user id of who we want to delete the conversation for
1749      * @param int $otheruserid The user id of the other user in the conversation
1750      * @return array
1751      * @throws moodle_exception
1752      * @since 3.2
1753      */
1754     public static function delete_conversation($userid, $otheruserid) {
1755         global $CFG;
1757         // Check if private messaging between users is allowed.
1758         if (empty($CFG->messaging)) {
1759             throw new moodle_exception('disabled', 'message');
1760         }
1762         // Warnings array, it can be empty at the end but is mandatory.
1763         $warnings = array();
1765         // Validate params.
1766         $params = array(
1767             'userid' => $userid,
1768             'otheruserid' => $otheruserid,
1769         );
1770         $params = self::validate_parameters(self::delete_conversation_parameters(), $params);
1772         // Validate context.
1773         $context = context_system::instance();
1774         self::validate_context($context);
1776         $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
1777         core_user::require_active_user($user);
1779         if (\core_message\api::can_delete_conversation($user->id)) {
1780             $status = \core_message\api::delete_conversation($user->id, $otheruserid);
1781         } else {
1782             throw new moodle_exception('You do not have permission to delete messages');
1783         }
1785         $results = array(
1786             'status' => $status,
1787             'warnings' => $warnings
1788         );
1790         return $results;
1791     }
1793     /**
1794      * Returns description of method result value.
1795      *
1796      * @return external_description
1797      * @since 3.2
1798      */
1799     public static function delete_conversation_returns() {
1800         return new external_single_structure(
1801             array(
1802                 'status' => new external_value(PARAM_BOOL, 'True if the conversation was deleted, false otherwise'),
1803                 'warnings' => new external_warnings()
1804             )
1805         );
1806     }
1808     /**
1809      * Returns description of method parameters
1810      *
1811      * @return external_function_parameters
1812      * @since 3.1
1813      */
1814     public static function delete_message_parameters() {
1815         return new external_function_parameters(
1816             array(
1817                 'messageid' => new external_value(PARAM_INT, 'The message id'),
1818                 'userid' => new external_value(PARAM_INT, 'The user id of who we want to delete the message for'),
1819                 'read' => new external_value(PARAM_BOOL, 'If is a message read', VALUE_DEFAULT, true)
1820             )
1821         );
1822     }
1824     /**
1825      * Deletes a message
1826      *
1827      * @param  int $messageid the message id
1828      * @param  int $userid the user id of who we want to delete the message for
1829      * @param  bool $read if is a message read (default to true)
1830      * @return external_description
1831      * @throws moodle_exception
1832      * @since 3.1
1833      */
1834     public static function delete_message($messageid, $userid, $read = true) {
1835         global $CFG, $DB;
1837         // Check if private messaging between users is allowed.
1838         if (empty($CFG->messaging)) {
1839             throw new moodle_exception('disabled', 'message');
1840         }
1842         // Warnings array, it can be empty at the end but is mandatory.
1843         $warnings = array();
1845         // Validate params.
1846         $params = array(
1847             'messageid' => $messageid,
1848             'userid' => $userid,
1849             'read' => $read
1850         );
1851         $params = self::validate_parameters(self::delete_message_parameters(), $params);
1853         // Validate context.
1854         $context = context_system::instance();
1855         self::validate_context($context);
1857         $messagestable = $params['read'] ? 'message_read' : 'message';
1858         $message = $DB->get_record($messagestable, array('id' => $params['messageid']), '*', MUST_EXIST);
1860         $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
1861         core_user::require_active_user($user);
1863         $status = false;
1864         if (message_can_delete_message($message, $user->id)) {
1865             $status = message_delete_message($message, $user->id);;
1866         } else {
1867             throw new moodle_exception('You do not have permission to delete this message');
1868         }
1870         $results = array(
1871             'status' => $status,
1872             'warnings' => $warnings
1873         );
1874         return $results;
1875     }
1877     /**
1878      * Returns description of method result value
1879      *
1880      * @return external_description
1881      * @since 3.1
1882      */
1883     public static function delete_message_returns() {
1884         return new external_single_structure(
1885             array(
1886                 'status' => new external_value(PARAM_BOOL, 'True if the message was deleted, false otherwise'),
1887                 'warnings' => new external_warnings()
1888             )
1889         );
1890     }
1892     /**
1893      * Returns description of method parameters
1894      *
1895      * @return external_function_parameters
1896      * @since 3.2
1897      */
1898     public static function message_processor_config_form_parameters() {
1899         return new external_function_parameters(
1900             array(
1901                 'userid' => new external_value(PARAM_INT, 'id of the user, 0 for current user', VALUE_REQUIRED),
1902                 'name' => new external_value(PARAM_TEXT, 'The name of the message processor'),
1903                 'formvalues' => new external_multiple_structure(
1904                     new external_single_structure(
1905                         array(
1906                             'name' => new external_value(PARAM_TEXT, 'name of the form element', VALUE_REQUIRED),
1907                             'value' => new external_value(PARAM_RAW, 'value of the form element', VALUE_REQUIRED),
1908                         )
1909                     ),
1910                     'Config form values',
1911                     VALUE_REQUIRED
1912                 ),
1913             )
1914         );
1915     }
1917     /**
1918      * Processes a message processor config form.
1919      *
1920      * @param  int $userid the user id
1921      * @param  string $name the name of the processor
1922      * @param  array $formvalues the form values
1923      * @return external_description
1924      * @throws moodle_exception
1925      * @since 3.2
1926      */
1927     public static function message_processor_config_form($userid, $name, $formvalues) {
1928         $params = self::validate_parameters(
1929             self::message_processor_config_form_parameters(),
1930             array(
1931                 'userid' => $userid,
1932                 'name' => $name,
1933                 'formvalues' => $formvalues,
1934             )
1935         );
1937         if (empty($params['userid'])) {
1938             $params['userid'] = $USER->id;
1939         }
1941         $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
1942         core_user::require_active_user($user);
1944         $processor = get_message_processor($name);
1945         $preferences = [];
1946         $form = new stdClass();
1948         foreach ($formvalues as $formvalue) {
1949             $form->$formvalue['name'] = $formvalue['value'];
1950         }
1952         $processor->process_form($form, $preferences);
1954         if (!empty($preferences)) {
1955             set_user_preferences($preferences, $userid);
1956         }
1957     }
1959     /**
1960      * Returns description of method result value
1961      *
1962      * @return external_description
1963      * @since 3.2
1964      */
1965     public static function message_processor_config_form_returns() {
1966         return null;
1967     }