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  * External message API
  19  *
  20  * @package    core_message
  21  * @copyright  2011 Moodle Pty Ltd (http://moodle.com)
  22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24 require_once("$CFG->libdir/externallib.php");
  25
  26 /**
  27  * Message functions
  28  *
  29  * @package    core_message
  30  * @copyright  2011 Moodle Pty Ltd (http://moodle.com)
  31  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  32  */
  33 class core_message_external extends external_api {
  34
  35     /**
  36      * Returns description of method parameters
  37      * @return external_function_parameters
  38      */
  39     public static function send_instant_messages_parameters() {
  40         return new external_function_parameters(
  41             array(
  42                 'messages' => new external_multiple_structure(
  43                     new external_single_structure(
  44                         array(
  45                             'touserid' => new external_value(PARAM_INT, 'id of the user to send the private message'),
  46                             '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'),
  47                             '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),
  48                         )
  49                     )
  50                 )
  51             )
  52         );
  53     }
  54
  55     /**
  56      * Send private messages from the current USER to other users
  57      *
  58      * @param array $messages An array of message to send
  59      * @return boolean
  60      */
  61     public static function send_instant_messages($messages = array()) {
  62         global $CFG, $USER, $DB;
  63         require_once($CFG->dirroot . "/message/lib.php");
  64
  65         //check if messaging is enabled
  66         if (!$CFG->messaging) {
  67             throw new moodle_exception('disabled', 'message');
  68         }
  69
  70         // Ensure the current user is allowed to run this function
  71         $context = get_context_instance(CONTEXT_SYSTEM);
  72         self::validate_context($context);
  73         require_capability('moodle/site:sendmessage', $context);
  74
  75         $params = self::validate_parameters(self::send_instant_messages_parameters(), array('messages' => $messages));
  76
  77         //retrieve all tousers of the messages
  78         $receivers = array();
  79         foreach($params['messages'] as $message) {
  80             $receivers[] = $message['touserid'];
  81         }
  82         list($sqluserids, $sqlparams) = $DB->get_in_or_equal($receivers, SQL_PARAMS_NAMED, 'userid_');
  83         $tousers = $DB->get_records_select("user", "id " . $sqluserids . " AND deleted = 0", $sqlparams);
  84         $blocklist   = array();
  85         $contactlist = array();
  86         $sqlparams['contactid'] = $USER->id;
  87         $rs = $DB->get_recordset_sql("SELECT *
  88                                         FROM {message_contacts}
  89                                        WHERE userid $sqluserids
  90                                              AND contactid = :contactid", $sqlparams);
  91         foreach ($rs as $record) {
  92             if ($record->blocked) {
  93                 // $record->userid is blocking current user
  94                 $blocklist[$record->userid] = true;
  95             } else {
  96                 // $record->userid have current user as contact
  97                 $contactlist[$record->userid] = true;
  98             }
  99         }
 100         $rs->close();
 101
 102         $canreadallmessages = has_capability('moodle/site:readallmessages', $context);
 103
 104         $resultmessages = array();
 105         foreach ($params['messages'] as $message) {
 106             $text = clean_param($message['text'], PARAM_TEXT);
 107             $resultmsg = array(); //the infos about the success of the operation
 108
 109             //we are going to do some checking
 110             //code should match /messages/index.php checks
 111             $success = true;
 112
 113             //check the user exists
 114             if (empty($tousers[$message['touserid']])) {
 115                 $success = false;
 116                 $errormessage = get_string('touserdoesntexist', 'message', $message['touserid']);
 117             }
 118
 119             //check that the touser is not blocking the current user
 120             if ($success and !empty($blocklist[$message['touserid']]) and !$canreadallmessages) {
 121                 $success = false;
 122                 $errormessage = get_string('userisblockingyou', 'message');
 123             }
 124
 125             // Check if the user is a contact
 126             //TODO: performance improvement - edit the function so we can pass an array instead userid
 127             $blocknoncontacts = get_user_preferences('message_blocknoncontacts', NULL, $message['touserid']);
 128             // message_blocknoncontacts option is on and current user is not in contact list
 129             if ($success && empty($contactlist[$message['touserid']]) && !empty($blocknoncontacts)) {
 130                 // The user isn't a contact and they have selected to block non contacts so this message won't be sent.
 131                 $success = false;
 132                 $errormessage = get_string('userisblockingyounoncontact', 'message');
 133             }
 134
 135             //now we can send the message (at least try)
 136             if ($success) {
 137                 //TODO: performance improvement - edit the function so we can pass an array instead one touser object
 138                 $success = message_post_message($USER, $tousers[$message['touserid']], $text, FORMAT_MOODLE);
 139             }
 140
 141             //build the resultmsg
 142             if (isset($message['clientmsgid'])) {
 143                 $resultmsg['clientmsgid'] = $message['clientmsgid'];
 144             }
 145             if ($success) {
 146                 $resultmsg['msgid'] = $success;
 147             } else {
 148                 $resultmsg['msgid'] = -1;
 149                 $resultmsg['errormessage'] = $errormessage;
 150             }
 151
 152             $resultmessages[] = $resultmsg;
 153         }
 154
 155         return $resultmessages;
 156     }
 157
 158     /**
 159      * Returns description of method result value
 160      * @return external_description
 161      */
 162     public static function send_instant_messages_returns() {
 163         return new external_multiple_structure(
 164             new external_single_structure(
 165                 array(
 166                     'msgid' => new external_value(PARAM_INT, 'test this to know if it succeeds:  id of the created message if it succeeded, -1 when failed'),
 167                     'clientmsgid' => new external_value(PARAM_ALPHANUMEXT, 'your own id for the message', VALUE_OPTIONAL),
 168                     'errormessage' => new external_value(PARAM_TEXT, 'error message - if it failed', VALUE_OPTIONAL)
 169                 )
 170             )
 171         );
 172     }
 173
 174 }
 175
 176 /**
 177  * Deprecated message functions
 178  *
 179  * @deprecated since Moodle 2.2 please use core_message_external instead
 180  * @copyright 2011 Moodle Pty Ltd (http://moodle.com)
 181  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 182  */
 183 class moodle_message_external extends external_api {
 184
 185     /**
 186      * Returns description of method parameters
 187      *
 188      * @deprecated since Moodle 2.2 please use core_message_external::send_instant_messages_parameters instead
 189      * @return external_function_parameters
 190      */
 191     public static function send_instantmessages_parameters() {
 192         return core_message_external::send_instant_messages_parameters();
 193     }
 194
 195     /**
 196      * Send private messages from the current USER to other users
 197      *
 198      * @deprecated since Moodle 2.2 please use core_message_external::send_instant_messages instead
 199      * @param array $messages  An array of message to send.
 200      * @return boolean
 201      */
 202     public static function send_instantmessages($messages = array()) {
 203         return core_message_external::send_instant_messages($messages);
 204     }
 205
 206     /**
 207      * Returns description of method result value
 208      *
 209      * @deprecated since Moodle 2.2 please use core_message_external::send_instant_messages_returns instead
 210      * @return external_description
 211      */
 212     public static function send_instantmessages_returns() {
 213         return core_message_external::send_instant_messages_returns();
 214     }
 215
 216 }