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/>.
  16
  17
  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  */
  26
  27 require_once("$CFG->libdir/externallib.php");
  28
  29 /**
  30  * Message external functions
  31  *
  32  * @package    core_message
  33  * @category   external
  34  * @copyright  2011 Jerome Mouneyrac
  35  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  36  * @since Moodle 2.2
  37  */
  38 class core_message_external extends external_api {
  39
  40     /**
  41      * Returns description of method parameters
  42      *
  43      * @return external_function_parameters
  44      * @since Moodle 2.2
  45      */
  46     public static function send_instant_messages_parameters() {
  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'),
  53                             'text' => new external_value(PARAM_RAW, 'the text of the message'),
  54                             'textformat' => new external_format_value('text', VALUE_DEFAULT),
  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      *
  66      * @param array $messages An array of message to send.
  67      * @return array
  68      * @since Moodle 2.2
  69      */
  70     public static function send_instant_messages($messages = array()) {
  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
  80         $context = context_system::instance();
  81         self::validate_context($context);
  82         require_capability('moodle/site:sendmessage', $context);
  83
  84         $params = self::validate_parameters(self::send_instant_messages_parameters(), array('messages' => $messages));
  85
  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();
 110
 111         $canreadallmessages = has_capability('moodle/site:readallmessages', $context);
 112
 113         $resultmessages = array();
 114         foreach ($params['messages'] as $message) {
 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
 128             if ($success and !empty($blocklist[$message['touserid']]) and !$canreadallmessages) {
 129                 $success = false;
 130                 $errormessage = get_string('userisblockingyou', 'message');
 131             }
 132
 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             }
 142
 143             //now we can send the message (at least try)
 144             if ($success) {
 145                 //TODO MDL-31118 performance improvement - edit the function so we can pass an array instead one touser object
 146                 $success = message_post_message($USER, $tousers[$message['touserid']],
 147                         $message['text'], external_validate_format($message['textformat']));
 148             }
 149
 150             //build the resultmsg
 151             if (isset($message['clientmsgid'])) {
 152                 $resultmsg['clientmsgid'] = $message['clientmsgid'];
 153             }
 154             if ($success) {
 155                 $resultmsg['msgid'] = $success;
 156             } else {
 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 .
 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
 172      *
 173      * @return external_description
 174      * @since Moodle 2.2
 175      */
 176     public static function send_instant_messages_returns() {
 177         return new external_multiple_structure(
 178             new external_single_structure(
 179                 array(
 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'),
 181                     'clientmsgid' => new external_value(PARAM_ALPHANUMEXT, 'your own id for the message', VALUE_OPTIONAL),
 182                     'errormessage' => new external_value(PARAM_TEXT, 'error message - if it failed', VALUE_OPTIONAL)
 183                 )
 184             )
 185         );
 186     }
 187
 188 }
 189
 190 /**
 191  * Deprecated message external functions
 192  *
 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
 200  */
 201 class moodle_message_external extends external_api {
 202
 203     /**
 204      * Returns description of method parameters
 205      *
 206      * @return external_function_parameters
 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()
 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
 218      *
 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()
 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
 232      *
 233      * @return external_description
 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()
 238      */
 239     public static function send_instantmessages_returns() {
 240         return core_message_external::send_instant_messages_returns();
 241     }
 242
 243 }