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 - not that you can send anything it will be automatically cleaned to PARAM_TEXT and used againt MOODLE_FORMAT'),
  54                             '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),
  55                         )
  56                     )
  57                 )
  58             )
  59         );
  60     }
  61
  62     /**
  63      * Send private messages from the current USER to other users
  64      *
  65      * @param array $messages An array of message to send.
  66      * @return array
  67      * @since Moodle 2.2
  68      */
  69     public static function send_instant_messages($messages = array()) {
  70         global $CFG, $USER, $DB;
  71         require_once($CFG->dirroot . "/message/lib.php");
  72
  73         //check if messaging is enabled
  74         if (!$CFG->messaging) {
  75             throw new moodle_exception('disabled', 'message');
  76         }
  77
  78         // Ensure the current user is allowed to run this function
  79         $context = get_context_instance(CONTEXT_SYSTEM);
  80         self::validate_context($context);
  81         require_capability('moodle/site:sendmessage', $context);
  82
  83         $params = self::validate_parameters(self::send_instant_messages_parameters(), array('messages' => $messages));
  84
  85         //retrieve all tousers of the messages
  86         $receivers = array();
  87         foreach($params['messages'] as $message) {
  88             $receivers[] = $message['touserid'];
  89         }
  90         list($sqluserids, $sqlparams) = $DB->get_in_or_equal($receivers, SQL_PARAMS_NAMED, 'userid_');
  91         $tousers = $DB->get_records_select("user", "id " . $sqluserids . " AND deleted = 0", $sqlparams);
  92         $blocklist   = array();
  93         $contactlist = array();
  94         $sqlparams['contactid'] = $USER->id;
  95         $rs = $DB->get_recordset_sql("SELECT *
  96                                         FROM {message_contacts}
  97                                        WHERE userid $sqluserids
  98                                              AND contactid = :contactid", $sqlparams);
  99         foreach ($rs as $record) {
 100             if ($record->blocked) {
 101                 // $record->userid is blocking current user
 102                 $blocklist[$record->userid] = true;
 103             } else {
 104                 // $record->userid have current user as contact
 105                 $contactlist[$record->userid] = true;
 106             }
 107         }
 108         $rs->close();
 109
 110         $canreadallmessages = has_capability('moodle/site:readallmessages', $context);
 111
 112         $resultmessages = array();
 113         foreach ($params['messages'] as $message) {
 114             $text = clean_param($message['text'], PARAM_TEXT);
 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']], $text, FORMAT_MOODLE);
 147             }
 148
 149             //build the resultmsg
 150             if (isset($message['clientmsgid'])) {
 151                 $resultmsg['clientmsgid'] = $message['clientmsgid'];
 152             }
 153             if ($success) {
 154                 $resultmsg['msgid'] = $success;
 155             } else {
 156                 $resultmsg['msgid'] = -1;
 157                 $resultmsg['errormessage'] = $errormessage;
 158             }
 159
 160             $resultmessages[] = $resultmsg;
 161         }
 162
 163         return $resultmessages;
 164     }
 165
 166     /**
 167      * Returns description of method result value
 168      *
 169      * @return external_description
 170      * @since Moodle 2.2
 171      */
 172     public static function send_instant_messages_returns() {
 173         return new external_multiple_structure(
 174             new external_single_structure(
 175                 array(
 176                     'msgid' => new external_value(PARAM_INT, 'test this to know if it succeeds:  id of the created message if it succeeded, -1 when failed'),
 177                     'clientmsgid' => new external_value(PARAM_ALPHANUMEXT, 'your own id for the message', VALUE_OPTIONAL),
 178                     'errormessage' => new external_value(PARAM_TEXT, 'error message - if it failed', VALUE_OPTIONAL)
 179                 )
 180             )
 181         );
 182     }
 183
 184 }
 185
 186 /**
 187  * Deprecated message external functions
 188  *
 189  * @package    core_message
 190  * @copyright  2011 Jerome Mouneyrac
 191  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 192  * @since Moodle 2.1
 193  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
 194  * @todo MDL-31194 This will be deleted in Moodle 2.5.
 195  * @see core_notes_external
 196  */
 197 class moodle_message_external extends external_api {
 198
 199     /**
 200      * Returns description of method parameters
 201      *
 202      * @return external_function_parameters
 203      * @since Moodle 2.1
 204      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 205      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 206      * @see core_message_external::send_instant_messages_parameters()
 207      */
 208     public static function send_instantmessages_parameters() {
 209         return core_message_external::send_instant_messages_parameters();
 210     }
 211
 212     /**
 213      * Send private messages from the current USER to other users
 214      *
 215      * @param array $messages An array of message to send.
 216      * @return array
 217      * @since Moodle 2.1
 218      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 219      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 220      * @see core_message_external::send_instant_messages()
 221      */
 222     public static function send_instantmessages($messages = array()) {
 223         return core_message_external::send_instant_messages($messages);
 224     }
 225
 226     /**
 227      * Returns description of method result value
 228      *
 229      * @return external_description
 230      * @since Moodle 2.1
 231      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 232      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 233      * @see core_message_external::send_instant_messages_returns()
 234      */
 235     public static function send_instantmessages_returns() {
 236         return core_message_external::send_instant_messages_returns();
 237     }
 238
 239 }