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      * Create contacts parameters description.
 190      *
 191      * @return external_function_parameters
 192      * @since 2.5
 193      */
 194     public static function create_contacts_parameters() {
 195         return new external_function_parameters(
 196             array(
 197                 'userids' => new external_multiple_structure(
 198                     new external_value(PARAM_INT, 'User ID'),
 199                     'List of user IDs'
 200                 )
 201             )
 202         );
 203     }
 204
 205     /**
 206      * Create contacts.
 207      *
 208      * @param array $userids array of user IDs.
 209      * @return external_description
 210      * @since 2.5
 211      */
 212     public static function create_contacts($userids) {
 213         $params = array('userids' => $userids);
 214         $params = self::validate_parameters(self::create_contacts_parameters(), $params);
 215
 216         $warnings = array();
 217         foreach ($params['userids'] as $id) {
 218             if (!message_add_contact($id)) {
 219                 $warnings[] = array(
 220                     'item' => 'user',
 221                     'itemid' => $id,
 222                     'warningcode' => 'contactnotcreated',
 223                     'message' => 'The contact could not be created'
 224                 );
 225             }
 226         }
 227         return $warnings;
 228     }
 229
 230     /**
 231      * Create contacts return description.
 232      *
 233      * @return external_description
 234      * @since 2.5
 235      */
 236     public static function create_contacts_returns() {
 237         return new external_warnings();
 238     }
 239
 240     /**
 241      * Delete contacts parameters description.
 242      *
 243      * @return external_function_parameters
 244      * @since 2.5
 245      */
 246     public static function delete_contacts_parameters() {
 247         return new external_function_parameters(
 248             array(
 249                 'userids' => new external_multiple_structure(
 250                     new external_value(PARAM_INT, 'User ID'),
 251                     'List of user IDs'
 252                 )
 253             )
 254         );
 255     }
 256
 257     /**
 258      * Delete contacts.
 259      *
 260      * @param array $userids array of user IDs.
 261      * @return null
 262      * @since 2.5
 263      */
 264     public static function delete_contacts($userids) {
 265         $params = array('userids' => $userids);
 266         $params = self::validate_parameters(self::delete_contacts_parameters(), $params);
 267
 268         foreach ($params['userids'] as $id) {
 269             message_remove_contact($id);
 270         }
 271
 272         return null;
 273     }
 274
 275     /**
 276      * Delete contacts return description.
 277      *
 278      * @return external_description
 279      * @since 2.5
 280      */
 281     public static function delete_contacts_returns() {
 282         return null;
 283     }
 284
 285     /**
 286      * Block contacts parameters description.
 287      *
 288      * @return external_function_parameters
 289      * @since 2.5
 290      */
 291     public static function block_contacts_parameters() {
 292         return new external_function_parameters(
 293             array(
 294                 'userids' => new external_multiple_structure(
 295                     new external_value(PARAM_INT, 'User ID'),
 296                     'List of user IDs'
 297                 )
 298             )
 299         );
 300     }
 301
 302     /**
 303      * Block contacts.
 304      *
 305      * @param array $userids array of user IDs.
 306      * @return external_description
 307      * @since 2.5
 308      */
 309     public static function block_contacts($userids) {
 310         $params = array('userids' => $userids);
 311         $params = self::validate_parameters(self::block_contacts_parameters(), $params);
 312
 313         $warnings = array();
 314         foreach ($params['userids'] as $id) {
 315             if (!message_block_contact($id)) {
 316                 $warnings[] = array(
 317                     'item' => 'user',
 318                     'itemid' => $id,
 319                     'warningcode' => 'contactnotblocked',
 320                     'message' => 'The contact could not be blocked'
 321                 );
 322             }
 323         }
 324         return $warnings;
 325     }
 326
 327     /**
 328      * Block contacts return description.
 329      *
 330      * @return external_description
 331      * @since 2.5
 332      */
 333     public static function block_contacts_returns() {
 334         return new external_warnings();
 335     }
 336
 337     /**
 338      * Unblock contacts parameters description.
 339      *
 340      * @return external_function_parameters
 341      * @since 2.5
 342      */
 343     public static function unblock_contacts_parameters() {
 344         return new external_function_parameters(
 345             array(
 346                 'userids' => new external_multiple_structure(
 347                     new external_value(PARAM_INT, 'User ID'),
 348                     'List of user IDs'
 349                 )
 350             )
 351         );
 352     }
 353
 354     /**
 355      * Unblock contacts.
 356      *
 357      * @param array $userids array of user IDs.
 358      * @return null
 359      * @since 2.5
 360      */
 361     public static function unblock_contacts($userids) {
 362         $params = array('userids' => $userids);
 363         $params = self::validate_parameters(self::unblock_contacts_parameters(), $params);
 364
 365         foreach ($params['userids'] as $id) {
 366             message_unblock_contact($id);
 367         }
 368
 369         return null;
 370     }
 371
 372     /**
 373      * Unblock contacts return description.
 374      *
 375      * @return external_description
 376      * @since 2.5
 377      */
 378     public static function unblock_contacts_returns() {
 379         return null;
 380     }
 381
 382     /**
 383      * Get contacts parameters description.
 384      *
 385      * @return external_function_parameters
 386      * @since 2.5
 387      */
 388     public static function get_contacts_parameters() {
 389         return new external_function_parameters(array());
 390     }
 391
 392     /**
 393      * Get contacts.
 394      *
 395      * @param array $userids array of user IDs.
 396      * @return external_description
 397      * @since 2.5
 398      */
 399     public static function get_contacts() {
 400         global $CFG;
 401         require_once($CFG->dirroot . '/user/lib.php');
 402
 403         list($online, $offline, $strangers) = message_get_contacts();
 404         $allcontacts = array('online' => $online, 'offline' => $offline, 'strangers' => $strangers);
 405         foreach ($allcontacts as $mode => $contacts) {
 406             foreach ($contacts as $key => $contact) {
 407                 $newcontact = array(
 408                     'id' => $contact->id,
 409                     'fullname' => fullname($contact),
 410                     'unread' => $contact->messagecount
 411                 );
 412
 413                 // Try to get the user picture, but sometimes this method can return null.
 414                 $userdetails = user_get_user_details($contact, null, array('profileimageurl', 'profileimageurlsmall'));
 415                 if (!empty($userdetails)) {
 416                     $newcontact['profileimageurl'] = $userdetails['profileimageurl'];
 417                     $newcontact['profileimageurlsmall'] = $userdetails['profileimageurlsmall'];
 418                 }
 419
 420                 $allcontacts[$mode][$key] = $newcontact;
 421             }
 422         }
 423         return $allcontacts;
 424     }
 425
 426     /**
 427      * Get contacts return description.
 428      *
 429      * @return external_description
 430      * @since 2.5
 431      */
 432     public static function get_contacts_returns() {
 433         return new external_single_structure(
 434             array(
 435                 'online' => new external_multiple_structure(
 436                     new external_single_structure(
 437                         array(
 438                             'id' => new external_value(PARAM_INT, 'User ID'),
 439                             'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
 440                             'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL),
 441                             'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL', VALUE_OPTIONAL),
 442                             'unread' => new external_value(PARAM_INT, 'Unread message count')
 443                         )
 444                     ),
 445                     'List of online contacts'
 446                 ),
 447                 'offline' => new external_multiple_structure(
 448                     new external_single_structure(
 449                         array(
 450                             'id' => new external_value(PARAM_INT, 'User ID'),
 451                             'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
 452                             'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL),
 453                             'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL', VALUE_OPTIONAL),
 454                             'unread' => new external_value(PARAM_INT, 'Unread message count')
 455                         )
 456                     ),
 457                     'List of offline contacts'
 458                 ),
 459                 'strangers' => new external_multiple_structure(
 460                     new external_single_structure(
 461                         array(
 462                             'id' => new external_value(PARAM_INT, 'User ID'),
 463                             'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
 464                             'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL),
 465                             'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL', VALUE_OPTIONAL),
 466                             'unread' => new external_value(PARAM_INT, 'Unread message count')
 467                         )
 468                     ),
 469                     'List of users that are not in the user\'s contact list but have sent a message'
 470                 )
 471             )
 472         );
 473     }
 474
 475     /**
 476      * Search contacts parameters description.
 477      *
 478      * @return external_function_parameters
 479      * @since 2.5
 480      */
 481     public static function search_contacts_parameters() {
 482         return new external_function_parameters(
 483             array(
 484                 'searchtext' => new external_value(PARAM_CLEAN, 'String the user\'s fullname has to match to be found'),
 485                 'onlymycourses' => new external_value(PARAM_BOOL, 'Limit search to the user\'s courses',
 486                     VALUE_DEFAULT, false)
 487             )
 488         );
 489     }
 490
 491     /**
 492      * Search contacts.
 493      *
 494      * @param string $searchtext query string.
 495      * @param bool $onlymycourses limit the search to the user's courses only.
 496      * @return external_description
 497      * @since 2.5
 498      */
 499     public static function search_contacts($searchtext, $onlymycourses = false) {
 500         global $CFG, $USER;
 501         require_once($CFG->libdir . '/enrollib.php');
 502
 503         $params = array('searchtext' => $searchtext, 'onlymycourses' => $onlymycourses);
 504         $params = self::validate_parameters(self::search_contacts_parameters(), $params);
 505
 506         // Extra validation, we do not allow empty queries.
 507         if ($params['searchtext'] === '') {
 508             throw new moodle_exception('querystringcannotbeempty');
 509         }
 510
 511         $courseids = array();
 512         if ($params['onlymycourses']) {
 513             $mycourses = enrol_get_my_courses(array('id'));
 514             foreach ($mycourses as $mycourse) {
 515                 $courseids[] = $mycourse->id;
 516             }
 517         } else {
 518             $courseids[] = SITEID;
 519         }
 520
 521         // Retrieving the users matching the query.
 522         $users = message_search_users($courseids, $params['searchtext']);
 523         $results = array();
 524         foreach ($users as $user) {
 525             $results[$user->id] = $user;
 526         }
 527
 528         // Reorganising information.
 529         foreach ($results as &$user) {
 530             $newuser = array(
 531                 'id' => $user->id,
 532                 'fullname' => fullname($user)
 533             );
 534
 535             // Avoid undefined property notice as phone not specified.
 536             $user->phone1 = null;
 537             $user->phone2 = null;
 538
 539             // Try to get the user picture, but sometimes this method can return null.
 540             $userdetails = user_get_user_details($user, null, array('profileimageurl', 'profileimageurlsmall'));
 541             if (!empty($userdetails)) {
 542                 $newuser['profileimageurl'] = $userdetails['profileimageurl'];
 543                 $newuser['profileimageurlsmall'] = $userdetails['profileimageurlsmall'];
 544             }
 545
 546             $user = $newuser;
 547         }
 548
 549         return $results;
 550     }
 551
 552     /**
 553      * Search contacts return description.
 554      *
 555      * @return external_description
 556      * @since 2.5
 557      */
 558     public static function search_contacts_returns() {
 559         return new external_multiple_structure(
 560             new external_single_structure(
 561                 array(
 562                     'id' => new external_value(PARAM_INT, 'User ID'),
 563                     'fullname' => new external_value(PARAM_NOTAGS, 'User full name'),
 564                     'profileimageurl' => new external_value(PARAM_URL, 'User picture URL', VALUE_OPTIONAL),
 565                     'profileimageurlsmall' => new external_value(PARAM_URL, 'Small user picture URL', VALUE_OPTIONAL)
 566                 )
 567             ),
 568             'List of contacts'
 569         );
 570     }
 571 }
 572
 573 /**
 574  * Deprecated message external functions
 575  *
 576  * @package    core_message
 577  * @copyright  2011 Jerome Mouneyrac
 578  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 579  * @since Moodle 2.1
 580  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
 581  * @see core_notes_external
 582  */
 583 class moodle_message_external extends external_api {
 584
 585     /**
 586      * Returns description of method parameters
 587      *
 588      * @return external_function_parameters
 589      * @since Moodle 2.1
 590      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 591      * @see core_message_external::send_instant_messages_parameters()
 592      */
 593     public static function send_instantmessages_parameters() {
 594         return core_message_external::send_instant_messages_parameters();
 595     }
 596
 597     /**
 598      * Send private messages from the current USER to other users
 599      *
 600      * @param array $messages An array of message to send.
 601      * @return array
 602      * @since Moodle 2.1
 603      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 604      * @see core_message_external::send_instant_messages()
 605      */
 606     public static function send_instantmessages($messages = array()) {
 607         return core_message_external::send_instant_messages($messages);
 608     }
 609
 610     /**
 611      * Returns description of method result value
 612      *
 613      * @return external_description
 614      * @since Moodle 2.1
 615      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 616      * @see core_message_external::send_instant_messages_returns()
 617      */
 618     public static function send_instantmessages_returns() {
 619         return core_message_external::send_instant_messages_returns();
 620     }
 621
 622 }