Commit | Line | Data |
---|---|---|
a623b6b8 JM |
1 | <?php |
2 | ||
3 | // This file is part of Moodle - http://moodle.org/ | |
4 | // | |
5 | // Moodle is free software: you can redistribute it and/or modify | |
6 | // it under the terms of the GNU General Public License as published by | |
7 | // the Free Software Foundation, either version 3 of the License, or | |
8 | // (at your option) any later version. | |
9 | // | |
10 | // Moodle is distributed in the hope that it will be useful, | |
11 | // but WITHOUT ANY WARRANTY; without even the implied warranty of | |
12 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
13 | // GNU General Public License for more details. | |
14 | // | |
15 | // You should have received a copy of the GNU General Public License | |
16 | // along with Moodle. If not, see <http://www.gnu.org/licenses/>. | |
17 | ||
18 | /** | |
19 | * External message API | |
20 | * | |
21 | * @package moodlecore | |
22 | * @subpackage message | |
23 | * @copyright 2011 Moodle Pty Ltd (http://moodle.com) | |
24 | * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later | |
25 | */ | |
26 | require_once("$CFG->libdir/externallib.php"); | |
27 | ||
28 | class moodle_message_external extends external_api { | |
29 | ||
30 | /** | |
31 | * Returns description of method parameters | |
32 | * @return external_function_parameters | |
33 | */ | |
34 | public static function send_messages_parameters() { | |
35 | return new external_function_parameters( | |
36 | array( | |
37 | 'messages' => new external_multiple_structure( | |
38 | new external_single_structure( | |
39 | array( | |
40 | 'touserid' => new external_value(PARAM_INT, 'id of the user to send the private message'), | |
41 | 'text' => new external_value(PARAM_RAW, 'the text of the message - not that you can send anything it will be automatically cleaned to PARAM_TEXT and used againt MOODLE_FORMAT'), | |
42 | '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), | |
43 | ) | |
44 | ) | |
45 | ) | |
46 | ) | |
47 | ); | |
48 | } | |
49 | ||
50 | /** | |
51 | * Send private messages from the current USER to other users | |
52 | * | |
53 | * @param $messages An array of message to send. | |
54 | * @return boolean | |
55 | */ | |
56 | public static function send_messages($messages = array()) { | |
57 | global $CFG, $USER, $DB; | |
58 | require_once($CFG->dirroot . "/message/lib.php"); | |
59 | ||
60 | //check if messaging is enabled | |
61 | if (!$CFG->messaging) { | |
62 | throw new moodle_exception('disabled', 'message'); | |
63 | } | |
64 | ||
65 | // Ensure the current user is allowed to run this function | |
66 | $context = get_context_instance(CONTEXT_SYSTEM); | |
67 | self::validate_context($context); | |
68 | require_capability('moodle/site:sendmessage', $context); | |
69 | ||
70 | $params = self::validate_parameters(self::send_messages_parameters(), array('messages' => $messages)); | |
71 | ||
72 | //retrieve all tousers of the messages | |
73 | $touserids = array(); | |
74 | foreach($params['messages'] as $message) { | |
75 | $touserids[] = $message['touserid']; | |
76 | } | |
77 | list($sqluserids, $sqlparams) = $DB->get_in_or_equal($touserids, SQL_PARAMS_NAMED, 'userid_'); | |
78 | $tousers = $DB->get_records_select("user", "id " . $sqluserids . " AND deleted = 0", $sqlparams); | |
79 | ||
80 | //retrieve the tousers who are blocking the $USER | |
81 | $sqlparams['contactid'] = $USER->id; | |
82 | $sqlparams['blocked'] = 1; | |
83 | //Note: return userid field should be unique for the below request, | |
84 | //so we'll use this field as key of $blockingcontacts | |
85 | $blockingcontacts = $DB->get_records_select("message_contacts", | |
86 | "userid " . $sqluserids . " AND contactid = :contactid AND blocked = :blocked", | |
87 | $sqlparams, '', "userid"); | |
88 | ||
89 | $canreadallmessages = has_capability('moodle/site:readallmessages', $context); | |
90 | ||
91 | $resultmessages = array(); | |
92 | foreach ($params['messages'] as $message) { | |
93 | $text = clean_param($message['text'], PARAM_TEXT); | |
94 | $resultmsg = array(); //the infos about the success of the operation | |
95 | ||
96 | //we are going to do some checking | |
97 | //code should match /messages/index.php checks | |
98 | $success = true; | |
99 | ||
100 | //check the user exists | |
101 | if (empty($tousers[$message['touserid']])) { | |
102 | $success = false; | |
103 | $errormessage = get_string('touserdoesntexist', 'message', $message['touserid']); | |
104 | } | |
105 | ||
106 | //check that the touser is not blocking the current user | |
107 | if ($success and isset($blockingcontacts[$message['touserid']]) and !$canreadallmessages) { | |
108 | $success = false; | |
109 | $errormessage = get_string('userisblockingyou', 'message'); | |
110 | } | |
111 | ||
112 | //check that user preference | |
113 | //TODO: performance improvement - edit the function so we can pass an array instead userid | |
114 | if ($success and empty($contact)) { | |
115 | $userpreferences = get_user_preferences(NULL, NULL, $message['touserid']); | |
116 | if (!empty($userpreferences['message_blocknoncontacts'])) { | |
117 | $success = false; | |
118 | $errormessage = get_string('userisblockingyounoncontact', 'message'); | |
119 | } | |
120 | } | |
121 | ||
122 | //now we can send the message (at least try) | |
123 | if ($success) { | |
124 | //TODO: performance improvement - edit the function so we can pass an array instead one touser object | |
125 | $success = message_post_message($USER, $tousers[$message['touserid']], $text, FORMAT_MOODLE); | |
126 | } | |
127 | ||
128 | //build the resultmsg | |
129 | if (isset($message['clientmsgid'])) { | |
130 | $resultmsg['clientmsgid'] = $message['clientmsgid']; | |
131 | } | |
132 | if ($success) { | |
133 | $resultmsg['msgid'] = $success; | |
134 | } else { | |
135 | $resultmsg['msgid'] = -1; | |
136 | $resultmsg['errormessage'] = $errormessage; | |
137 | } | |
138 | ||
139 | $resultmessages[] = $resultmsg; | |
140 | } | |
141 | ||
142 | return $resultmessages; | |
143 | } | |
144 | ||
145 | /** | |
146 | * Returns description of method result value | |
147 | * @return external_description | |
148 | */ | |
149 | public static function send_messages_returns() { | |
150 | return new external_multiple_structure( | |
151 | new external_single_structure( | |
152 | array( | |
153 | 'clientmsgid' => new external_value(PARAM_ALPHANUMEXT, 'your own id for the message', VALUE_OPTIONAL), | |
154 | 'msgid' => new external_value(PARAM_INT, 'test this to know if it success: id of the created message when successed, -1 when failed'), | |
155 | 'errormessage' => new external_value(PARAM_TEXT, 'error message - if failed', VALUE_OPTIONAL) | |
156 | ) | |
157 | ) | |
158 | ); | |
159 | } | |
160 | ||
161 | } |