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 Moodle 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 Moodle 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 Moodle 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 Moodle 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 Moodle 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 Moodle 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 Moodle 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 Moodle 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 Moodle 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 Moodle 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 Moodle 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 Moodle 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 Moodle 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 Moodle 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 Moodle 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 Moodle 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 Moodle 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 Moodle 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      * Get messages parameters description.
 574      *
 575      * @return external_function_parameters
 576      * @since 2.8
 577      */
 578     public static function get_messages_parameters() {
 579         return new external_function_parameters(
 580             array(
 581                 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
 582                 'useridfrom' => new external_value(
 583                     PARAM_INT, 'the user id who send the message, 0 for any user. -10 or -20 for no-reply or support user',
 584                     VALUE_DEFAULT, 0),
 585                 'type' => new external_value(
 586                     PARAM_ALPHA, 'type of message to return, expected values are: notifications, conversations and both',
 587                     VALUE_DEFAULT, 'both'),
 588                 'read' => new external_value(PARAM_BOOL, 'true for getting read messages, false for unread', VALUE_DEFAULT, true),
 589                 'newestfirst' => new external_value(
 590                     PARAM_BOOL, 'true for ordering by newest first, false for oldest first',
 591                     VALUE_DEFAULT, true),
 592                 'limitfrom' => new external_value(PARAM_INT, 'limit from', VALUE_DEFAULT, 0),
 593                 'limitnum' => new external_value(PARAM_INT, 'limit number', VALUE_DEFAULT, 0)
 594             )
 595         );
 596     }
 597
 598     /**
 599      * Get messages function implementation.
 600      *
 601      * @since  2.8
 602      * @throws invalid_parameter_exception
 603      * @throws moodle_exception
 604      * @param  int      $useridto       the user id who received the message
 605      * @param  int      $useridfrom     the user id who send the message. -10 or -20 for no-reply or support user
 606      * @param  string   $type           type of message to return, expected values: notifications, conversations and both
 607      * @param  bool     $read           true for retreiving read messages, false for unread
 608      * @param  bool     $newestfirst    true for ordering by newest first, false for oldest first
 609      * @param  int      $limitfrom      limit from
 610      * @param  int      $limitnum       limit num
 611      * @return external_description
 612      */
 613     public static function get_messages($useridto, $useridfrom = 0, $type = 'both', $read = true,
 614                                         $newestfirst = true, $limitfrom = 0, $limitnum = 0) {
 615         global $CFG, $USER;
 616         require_once($CFG->dirroot . "/message/lib.php");
 617
 618         $warnings = array();
 619
 620         $params = array(
 621             'useridto' => $useridto,
 622             'useridfrom' => $useridfrom,
 623             'type' => $type,
 624             'read' => $read,
 625             'newestfirst' => $newestfirst,
 626             'limitfrom' => $limitfrom,
 627             'limitnum' => $limitnum
 628         );
 629
 630         $params = self::validate_parameters(self::get_messages_parameters(), $params);
 631
 632         $context = context_system::instance();
 633         self::validate_context($context);
 634
 635         $useridto = $params['useridto'];
 636         $useridfrom = $params['useridfrom'];
 637         $type = $params['type'];
 638         $read = $params['read'];
 639         $newestfirst = $params['newestfirst'];
 640         $limitfrom = $params['limitfrom'];
 641         $limitnum = $params['limitnum'];
 642
 643         $allowedvalues = array('notifications', 'conversations', 'both');
 644         if (!in_array($type, $allowedvalues)) {
 645             throw new invalid_parameter_exception('Invalid value for type parameter (value: ' . $type . '),' .
 646                 'allowed values are: ' . implode(',', $allowedvalues));
 647         }
 648
 649         // Check if private messaging between users is allowed.
 650         if (empty($CFG->messaging)) {
 651             // If we are retreiving only conversations, and messaging is disabled, throw an exception.
 652             if ($type == "conversations") {
 653                 throw new moodle_exception('disabled', 'message');
 654             }
 655             if ($type == "both") {
 656                 $warning = array();
 657                 $warning['item'] = 'message';
 658                 $warning['itemid'] = $USER->id;
 659                 $warning['warningcode'] = '1';
 660                 $warning['message'] = 'Private messages (conversations) are not enabled in this site.
 661                     Only notifications will be returned';
 662                 $warnings[] = $warning;
 663             }
 664         }
 665
 666         if (!empty($useridto)) {
 667             if (core_user::is_real_user($useridto)) {
 668                 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
 669             } else {
 670                 throw new moodle_exception('invaliduser');
 671             }
 672         }
 673
 674         if (!empty($useridfrom)) {
 675             // We use get_user here because the from user can be the noreply or support user.
 676             $userfrom = core_user::get_user($useridfrom, '*', MUST_EXIST);
 677         }
 678
 679         // Check if the current user is the sender/receiver or just a privileged user.
 680         if ($useridto != $USER->id and $useridfrom != $USER->id and
 681              !has_capability('moodle/site:readallmessages', $context)) {
 682             throw new moodle_exception('accessdenied', 'admin');
 683         }
 684
 685         // Which type of messages to retrieve.
 686         $notifications = -1;
 687         if ($type != 'both') {
 688             $notifications = ($type == 'notifications') ? 1 : 0;
 689         }
 690
 691         $orderdirection = $newestfirst ? 'DESC' : 'ASC';
 692         $sort = "mr.timecreated $orderdirection";
 693
 694         if ($messages = message_get_messages($useridto, $useridfrom, $notifications, $read, $sort, $limitfrom, $limitnum)) {
 695             $canviewfullname = has_capability('moodle/site:viewfullnames', $context);
 696
 697             // In some cases, we don't need to get the to/from user objects from the sql query.
 698             $userfromfullname = '';
 699             $usertofullname = '';
 700
 701             // In this case, the useridto field is not empty, so we can get the user destinatary fullname from there.
 702             if (!empty($useridto)) {
 703                 $usertofullname = fullname($userto, $canviewfullname);
 704                 // The user from may or may not be filled.
 705                 if (!empty($useridfrom)) {
 706                     $userfromfullname = fullname($userfrom, $canviewfullname);
 707                 }
 708             } else {
 709                 // If the useridto field is empty, the useridfrom must be filled.
 710                 $userfromfullname = fullname($userfrom, $canviewfullname);
 711             }
 712             foreach ($messages as $mid => $message) {
 713
 714                 // We need to get the user from the query.
 715                 if (empty($userfromfullname)) {
 716                     // Check for non-reply and support users.
 717                     if (core_user::is_real_user($message->useridfrom)) {
 718                         $user = new stdClass();
 719                         $user = username_load_fields_from_object($user, $message, 'userfrom');
 720                         $message->userfromfullname = fullname($user, $canviewfullname);
 721                     } else {
 722                         $user = core_user::get_user($message->useridfrom);
 723                         $message->userfromfullname = fullname($user, $canviewfullname);
 724                     }
 725                 } else {
 726                     $message->userfromfullname = $userfromfullname;
 727                 }
 728
 729                 // We need to get the user from the query.
 730                 if (empty($usertofullname)) {
 731                     $user = new stdClass();
 732                     $user = username_load_fields_from_object($user, $message, 'userto');
 733                     $message->usertofullname = fullname($user, $canviewfullname);
 734                 } else {
 735                     $message->usertofullname = $usertofullname;
 736                 }
 737
 738                 // This field is only available in the message_read table.
 739                 if (!isset($message->timeread)) {
 740                     $message->timeread = 0;
 741                 }
 742
 743                 $message->text = message_format_message_text($message);
 744                 $messages[$mid] = (array) $message;
 745             }
 746         }
 747
 748         $results = array(
 749             'messages' => $messages,
 750             'warnings' => $warnings
 751         );
 752
 753         return $results;
 754     }
 755
 756     /**
 757      * Get messages return description.
 758      *
 759      * @return external_single_structure
 760      * @since 2.8
 761      */
 762     public static function get_messages_returns() {
 763         return new external_single_structure(
 764             array(
 765                 'messages' => new external_multiple_structure(
 766                     new external_single_structure(
 767                         array(
 768                             'id' => new external_value(PARAM_INT, 'Message id'),
 769                             'useridfrom' => new external_value(PARAM_INT, 'User from id'),
 770                             'useridto' => new external_value(PARAM_INT, 'User to id'),
 771                             'subject' => new external_value(PARAM_TEXT, 'The message subject'),
 772                             'text' => new external_value(PARAM_RAW, 'The message text formated'),
 773                             'fullmessage' => new external_value(PARAM_RAW, 'The message'),
 774                             'fullmessageformat' => new external_format_value('fullmessage'),
 775                             'fullmessagehtml' => new external_value(PARAM_RAW, 'The message in html'),
 776                             'smallmessage' => new external_value(PARAM_RAW, 'The shorten message'),
 777                             'notification' => new external_value(PARAM_INT, 'Is a notification?'),
 778                             'contexturl' => new external_value(PARAM_RAW, 'Context URL'),
 779                             'contexturlname' => new external_value(PARAM_TEXT, 'Context URL link name'),
 780                             'timecreated' => new external_value(PARAM_INT, 'Time created'),
 781                             'timeread' => new external_value(PARAM_INT, 'Time read'),
 782                             'usertofullname' => new external_value(PARAM_TEXT, 'User to full name'),
 783                             'userfromfullname' => new external_value(PARAM_TEXT, 'User from full name')
 784                         ), 'message'
 785                     )
 786                 ),
 787                 'warnings' => new external_warnings()
 788             )
 789         );
 790     }
 791
 792 }
 793
 794 /**
 795  * Deprecated message external functions
 796  *
 797  * @package    core_message
 798  * @copyright  2011 Jerome Mouneyrac
 799  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 800  * @since Moodle 2.1
 801  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
 802  * @see core_notes_external
 803  */
 804 class moodle_message_external extends external_api {
 805
 806     /**
 807      * Returns description of method parameters
 808      *
 809      * @return external_function_parameters
 810      * @since Moodle 2.1
 811      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 812      * @see core_message_external::send_instant_messages_parameters()
 813      */
 814     public static function send_instantmessages_parameters() {
 815         return core_message_external::send_instant_messages_parameters();
 816     }
 817
 818     /**
 819      * Send private messages from the current USER to other users
 820      *
 821      * @param array $messages An array of message to send.
 822      * @return array
 823      * @since Moodle 2.1
 824      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 825      * @see core_message_external::send_instant_messages()
 826      */
 827     public static function send_instantmessages($messages = array()) {
 828         return core_message_external::send_instant_messages($messages);
 829     }
 830
 831     /**
 832      * Returns description of method result value
 833      *
 834      * @return external_description
 835      * @since Moodle 2.1
 836      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 837      * @see core_message_external::send_instant_messages_returns()
 838      */
 839     public static function send_instantmessages_returns() {
 840         return core_message_external::send_instant_messages_returns();
 841     }
 842
 843 }