Commit | Line | Data |
---|---|---|
a623b6b8 | 1 | <?php |
a623b6b8 JM |
2 | // This file is part of Moodle - http://moodle.org/ |
3 | // | |
4 | // Moodle is free software: you can redistribute it and/or modify | |
5 | // it under the terms of the GNU General Public License as published by | |
6 | // the Free Software Foundation, either version 3 of the License, or | |
7 | // (at your option) any later version. | |
8 | // | |
9 | // Moodle is distributed in the hope that it will be useful, | |
10 | // but WITHOUT ANY WARRANTY; without even the implied warranty of | |
11 | // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
12 | // GNU General Public License for more details. | |
13 | // | |
14 | // You should have received a copy of the GNU General Public License | |
15 | // along with Moodle. If not, see <http://www.gnu.org/licenses/>. | |
16 | ||
4615817d | 17 | |
a623b6b8 JM |
18 | /** |
19 | * External message API | |
20 | * | |
6fbd60ef | 21 | * @package core_message |
4615817d JM |
22 | * @category external |
23 | * @copyright 2011 Jerome Mouneyrac | |
a623b6b8 JM |
24 | * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later |
25 | */ | |
4615817d | 26 | |
a623b6b8 JM |
27 | require_once("$CFG->libdir/externallib.php"); |
28 | ||
5d1017e1 | 29 | /** |
4615817d | 30 | * Message external functions |
6fbd60ef AD |
31 | * |
32 | * @package core_message | |
4615817d JM |
33 | * @category external |
34 | * @copyright 2011 Jerome Mouneyrac | |
75e4f98c | 35 | * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later |
4615817d | 36 | * @since Moodle 2.2 |
5d1017e1 JM |
37 | */ |
38 | class core_message_external extends external_api { | |
a623b6b8 JM |
39 | |
40 | /** | |
41 | * Returns description of method parameters | |
4615817d | 42 | * |
a623b6b8 | 43 | * @return external_function_parameters |
4615817d | 44 | * @since Moodle 2.2 |
a623b6b8 | 45 | */ |
5d1017e1 | 46 | public static function send_instant_messages_parameters() { |
a623b6b8 JM |
47 | return new external_function_parameters( |
48 | array( | |
49 | 'messages' => new external_multiple_structure( | |
50 | new external_single_structure( | |
51 | array( | |
52 | 'touserid' => new external_value(PARAM_INT, 'id of the user to send the private message'), | |
93ce0e82 JM |
53 | 'text' => new external_value(PARAM_RAW, 'the text of the message'), |
54 | 'textformat' => new external_format_value('text', VALUE_DEFAULT), | |
a623b6b8 JM |
55 | '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), |
56 | ) | |
57 | ) | |
58 | ) | |
59 | ) | |
60 | ); | |
61 | } | |
62 | ||
63 | /** | |
64 | * Send private messages from the current USER to other users | |
65 | * | |
4615817d JM |
66 | * @param array $messages An array of message to send. |
67 | * @return array | |
68 | * @since Moodle 2.2 | |
a623b6b8 | 69 | */ |
5d1017e1 | 70 | public static function send_instant_messages($messages = array()) { |
a623b6b8 JM |
71 | global $CFG, $USER, $DB; |
72 | require_once($CFG->dirroot . "/message/lib.php"); | |
73 | ||
74 | //check if messaging is enabled | |
75 | if (!$CFG->messaging) { | |
76 | throw new moodle_exception('disabled', 'message'); | |
77 | } | |
78 | ||
79 | // Ensure the current user is allowed to run this function | |
bf0f06b1 | 80 | $context = context_system::instance(); |
a623b6b8 JM |
81 | self::validate_context($context); |
82 | require_capability('moodle/site:sendmessage', $context); | |
83 | ||
5d1017e1 | 84 | $params = self::validate_parameters(self::send_instant_messages_parameters(), array('messages' => $messages)); |
a623b6b8 JM |
85 | |
86 | //retrieve all tousers of the messages | |
4de00da7 | 87 | $receivers = array(); |
a623b6b8 | 88 | foreach($params['messages'] as $message) { |
4de00da7 | 89 | $receivers[] = $message['touserid']; |
a623b6b8 | 90 | } |
4de00da7 | 91 | list($sqluserids, $sqlparams) = $DB->get_in_or_equal($receivers, SQL_PARAMS_NAMED, 'userid_'); |
a623b6b8 | 92 | $tousers = $DB->get_records_select("user", "id " . $sqluserids . " AND deleted = 0", $sqlparams); |
4de00da7 DC |
93 | $blocklist = array(); |
94 | $contactlist = array(); | |
a623b6b8 | 95 | $sqlparams['contactid'] = $USER->id; |
4de00da7 DC |
96 | $rs = $DB->get_recordset_sql("SELECT * |
97 | FROM {message_contacts} | |
98 | WHERE userid $sqluserids | |
99 | AND contactid = :contactid", $sqlparams); | |
100 | foreach ($rs as $record) { | |
101 | if ($record->blocked) { | |
102 | // $record->userid is blocking current user | |
103 | $blocklist[$record->userid] = true; | |
104 | } else { | |
105 | // $record->userid have current user as contact | |
106 | $contactlist[$record->userid] = true; | |
107 | } | |
108 | } | |
109 | $rs->close(); | |
a623b6b8 JM |
110 | |
111 | $canreadallmessages = has_capability('moodle/site:readallmessages', $context); | |
112 | ||
113 | $resultmessages = array(); | |
114 | foreach ($params['messages'] as $message) { | |
a623b6b8 JM |
115 | $resultmsg = array(); //the infos about the success of the operation |
116 | ||
117 | //we are going to do some checking | |
118 | //code should match /messages/index.php checks | |
119 | $success = true; | |
120 | ||
121 | //check the user exists | |
122 | if (empty($tousers[$message['touserid']])) { | |
123 | $success = false; | |
124 | $errormessage = get_string('touserdoesntexist', 'message', $message['touserid']); | |
125 | } | |
126 | ||
127 | //check that the touser is not blocking the current user | |
4de00da7 | 128 | if ($success and !empty($blocklist[$message['touserid']]) and !$canreadallmessages) { |
a623b6b8 JM |
129 | $success = false; |
130 | $errormessage = get_string('userisblockingyou', 'message'); | |
131 | } | |
132 | ||
78736e5d | 133 | // Check if the user is a contact |
4615817d | 134 | //TODO MDL-31118 performance improvement - edit the function so we can pass an array instead userid |
4de00da7 DC |
135 | $blocknoncontacts = get_user_preferences('message_blocknoncontacts', NULL, $message['touserid']); |
136 | // message_blocknoncontacts option is on and current user is not in contact list | |
137 | if ($success && empty($contactlist[$message['touserid']]) && !empty($blocknoncontacts)) { | |
78736e5d SH |
138 | // The user isn't a contact and they have selected to block non contacts so this message won't be sent. |
139 | $success = false; | |
140 | $errormessage = get_string('userisblockingyounoncontact', 'message'); | |
a623b6b8 JM |
141 | } |
142 | ||
143 | //now we can send the message (at least try) | |
144 | if ($success) { | |
4615817d | 145 | //TODO MDL-31118 performance improvement - edit the function so we can pass an array instead one touser object |
93ce0e82 JM |
146 | $success = message_post_message($USER, $tousers[$message['touserid']], |
147 | $message['text'], external_validate_format($message['textformat'])); | |
a623b6b8 JM |
148 | } |
149 | ||
150 | //build the resultmsg | |
151 | if (isset($message['clientmsgid'])) { | |
78736e5d | 152 | $resultmsg['clientmsgid'] = $message['clientmsgid']; |
a623b6b8 JM |
153 | } |
154 | if ($success) { | |
155 | $resultmsg['msgid'] = $success; | |
156 | } else { | |
93ce0e82 JM |
157 | // WARNINGS: for backward compatibility we return this errormessage. |
158 | // We should have thrown exceptions as these errors prevent results to be returned. | |
159 | // See http://docs.moodle.org/dev/Errors_handling_in_web_services#When_to_send_a_warning_on_the_server_side . | |
a623b6b8 JM |
160 | $resultmsg['msgid'] = -1; |
161 | $resultmsg['errormessage'] = $errormessage; | |
162 | } | |
163 | ||
164 | $resultmessages[] = $resultmsg; | |
165 | } | |
166 | ||
167 | return $resultmessages; | |
168 | } | |
169 | ||
170 | /** | |
171 | * Returns description of method result value | |
4615817d | 172 | * |
a623b6b8 | 173 | * @return external_description |
4615817d | 174 | * @since Moodle 2.2 |
a623b6b8 | 175 | */ |
5d1017e1 | 176 | public static function send_instant_messages_returns() { |
a623b6b8 JM |
177 | return new external_multiple_structure( |
178 | new external_single_structure( | |
179 | array( | |
78736e5d | 180 | 'msgid' => new external_value(PARAM_INT, 'test this to know if it succeeds: id of the created message if it succeeded, -1 when failed'), |
4de00da7 | 181 | 'clientmsgid' => new external_value(PARAM_ALPHANUMEXT, 'your own id for the message', VALUE_OPTIONAL), |
78736e5d | 182 | 'errormessage' => new external_value(PARAM_TEXT, 'error message - if it failed', VALUE_OPTIONAL) |
a623b6b8 JM |
183 | ) |
184 | ) | |
185 | ); | |
186 | } | |
187 | ||
188 | } | |
5d1017e1 JM |
189 | |
190 | /** | |
4615817d | 191 | * Deprecated message external functions |
6fbd60ef | 192 | * |
4615817d JM |
193 | * @package core_message |
194 | * @copyright 2011 Jerome Mouneyrac | |
195 | * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later | |
196 | * @since Moodle 2.1 | |
197 | * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more. | |
198 | * @todo MDL-31194 This will be deleted in Moodle 2.5. | |
199 | * @see core_notes_external | |
5d1017e1 JM |
200 | */ |
201 | class moodle_message_external extends external_api { | |
202 | ||
203 | /** | |
204 | * Returns description of method parameters | |
6fbd60ef | 205 | * |
5d1017e1 | 206 | * @return external_function_parameters |
4615817d JM |
207 | * @since Moodle 2.1 |
208 | * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. | |
209 | * @todo MDL-31194 This will be deleted in Moodle 2.5. | |
210 | * @see core_message_external::send_instant_messages_parameters() | |
5d1017e1 JM |
211 | */ |
212 | public static function send_instantmessages_parameters() { | |
213 | return core_message_external::send_instant_messages_parameters(); | |
214 | } | |
215 | ||
216 | /** | |
217 | * Send private messages from the current USER to other users | |
6fbd60ef | 218 | * |
4615817d JM |
219 | * @param array $messages An array of message to send. |
220 | * @return array | |
221 | * @since Moodle 2.1 | |
222 | * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. | |
223 | * @todo MDL-31194 This will be deleted in Moodle 2.5. | |
224 | * @see core_message_external::send_instant_messages() | |
5d1017e1 JM |
225 | */ |
226 | public static function send_instantmessages($messages = array()) { | |
227 | return core_message_external::send_instant_messages($messages); | |
228 | } | |
229 | ||
230 | /** | |
231 | * Returns description of method result value | |
6fbd60ef | 232 | * |
5d1017e1 | 233 | * @return external_description |
4615817d JM |
234 | * @since Moodle 2.1 |
235 | * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more. | |
236 | * @todo MDL-31194 This will be deleted in Moodle 2.5. | |
237 | * @see core_message_external::send_instant_messages_returns() | |
5d1017e1 JM |
238 | */ |
239 | public static function send_instantmessages_returns() { | |
240 | return core_message_external::send_instant_messages_returns(); | |
241 | } | |
242 | ||
6fbd60ef | 243 | } |