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 * Chat external API 19 * 20 * @package mod_chat 21 * @category external 22 * @copyright 2015 Juan Leyva <juan@moodle.com> 23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 24 * @since Moodle 3.0 25 */ 26 27defined('MOODLE_INTERNAL') || die; 28 29require_once($CFG->libdir . '/externallib.php'); 30require_once($CFG->dirroot . '/mod/chat/lib.php'); 31 32use mod_chat\external\chat_message_exporter; 33 34/** 35 * Chat external functions 36 * 37 * @package mod_chat 38 * @category external 39 * @copyright 2015 Juan Leyva <juan@moodle.com> 40 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 41 * @since Moodle 3.0 42 */ 43class mod_chat_external extends external_api { 44 45 /** 46 * Returns description of method parameters 47 * 48 * @return external_function_parameters 49 * @since Moodle 3.0 50 */ 51 public static function login_user_parameters() { 52 return new external_function_parameters( 53 array( 54 'chatid' => new external_value(PARAM_INT, 'chat instance id'), 55 'groupid' => new external_value(PARAM_INT, 'group id, 0 means that the function will determine the user group', 56 VALUE_DEFAULT, 0), 57 ) 58 ); 59 } 60 61 /** 62 * Log the current user into a chat room in the given chat. 63 * 64 * @param int $chatid the chat instance id 65 * @param int $groupid the user group id 66 * @return array of warnings and the chat unique session id 67 * @since Moodle 3.0 68 * @throws moodle_exception 69 */ 70 public static function login_user($chatid, $groupid = 0) { 71 global $DB; 72 73 $params = self::validate_parameters(self::login_user_parameters(), 74 array( 75 'chatid' => $chatid, 76 'groupid' => $groupid 77 )); 78 $warnings = array(); 79 80 // Request and permission validation. 81 $chat = $DB->get_record('chat', array('id' => $params['chatid']), '*', MUST_EXIST); 82 list($course, $cm) = get_course_and_cm_from_instance($chat, 'chat'); 83 84 $context = context_module::instance($cm->id); 85 self::validate_context($context); 86 87 require_capability('mod/chat:chat', $context); 88 89 if (!empty($params['groupid'])) { 90 $groupid = $params['groupid']; 91 // Determine is the group is visible to user. 92 if (!groups_group_visible($groupid, $course, $cm)) { 93 throw new moodle_exception('notingroup'); 94 } 95 } else { 96 // Check to see if groups are being used here. 97 if ($groupmode = groups_get_activity_groupmode($cm)) { 98 $groupid = groups_get_activity_group($cm); 99 // Determine is the group is visible to user (this is particullary for the group 0). 100 if (!groups_group_visible($groupid, $course, $cm)) { 101 throw new moodle_exception('notingroup'); 102 } 103 } else { 104 $groupid = 0; 105 } 106 } 107 108 // Get the unique chat session id. 109 // Since we are going to use the chat via Web Service requests we set the ajax version (since it's the most similar). 110 if (!$chatsid = chat_login_user($chat->id, 'ajax', $groupid, $course)) { 111 throw new moodle_exception('cantlogin', 'chat'); 112 } 113 114 $result = array(); 115 $result['chatsid'] = $chatsid; 116 $result['warnings'] = $warnings; 117 return $result; 118 } 119 120 /** 121 * Returns description of method result value 122 * 123 * @return external_description 124 * @since Moodle 3.0 125 */ 126 public static function login_user_returns() { 127 return new external_single_structure( 128 array( 129 'chatsid' => new external_value(PARAM_ALPHANUM, 'unique chat session id'), 130 'warnings' => new external_warnings() 131 ) 132 ); 133 } 134 135 /** 136 * Returns description of method parameters 137 * 138 * @return external_function_parameters 139 * @since Moodle 3.0 140 */ 141 public static function get_chat_users_parameters() { 142 return new external_function_parameters( 143 array( 144 'chatsid' => new external_value(PARAM_ALPHANUM, 'chat session id (obtained via mod_chat_login_user)') 145 ) 146 ); 147 } 148 149 /** 150 * Get the list of users in the given chat session. 151 * 152 * @param int $chatsid the chat session id 153 * @return array of warnings and the user lists 154 * @since Moodle 3.0 155 * @throws moodle_exception 156 */ 157 public static function get_chat_users($chatsid) { 158 global $DB, $PAGE; 159 160 $params = self::validate_parameters(self::get_chat_users_parameters(), 161 array( 162 'chatsid' => $chatsid 163 )); 164 $warnings = array(); 165 166 // Request and permission validation. 167 if (!$chatuser = $DB->get_record('chat_users', array('sid' => $params['chatsid']))) { 168 throw new moodle_exception('notlogged', 'chat'); 169 } 170 $chat = $DB->get_record('chat', array('id' => $chatuser->chatid), '*', MUST_EXIST); 171 list($course, $cm) = get_course_and_cm_from_instance($chat, 'chat'); 172 173 $context = context_module::instance($cm->id); 174 self::validate_context($context); 175 176 require_capability('mod/chat:chat', $context); 177 178 // First, delete old users from the chats. 179 chat_delete_old_users(); 180 181 $users = chat_get_users($chatuser->chatid, $chatuser->groupid, $cm->groupingid); 182 $returnedusers = array(); 183 184 foreach ($users as $user) { 185 186 $userpicture = new user_picture($user); 187 $userpicture->size = 1; // Size f1. 188 $profileimageurl = $userpicture->get_url($PAGE)->out(false); 189 190 $returnedusers[] = array( 191 'id' => $user->id, 192 'fullname' => fullname($user), 193 'profileimageurl' => $profileimageurl 194 ); 195 } 196 197 $result = array(); 198 $result['users'] = $returnedusers; 199 $result['warnings'] = $warnings; 200 return $result; 201 } 202 203 /** 204 * Returns description of method result value 205 * 206 * @return external_description 207 * @since Moodle 3.0 208 */ 209 public static function get_chat_users_returns() { 210 return new external_single_structure( 211 array( 212 'users' => new external_multiple_structure( 213 new external_single_structure( 214 array( 215 'id' => new external_value(PARAM_INT, 'user id'), 216 'fullname' => new external_value(PARAM_NOTAGS, 'user full name'), 217 'profileimageurl' => new external_value(PARAM_URL, 'user picture URL'), 218 ) 219 ), 220 'list of users' 221 ), 222 'warnings' => new external_warnings() 223 ) 224 ); 225 } 226 227 /** 228 * Returns description of method parameters 229 * 230 * @return external_function_parameters 231 * @since Moodle 3.0 232 */ 233 public static function send_chat_message_parameters() { 234 return new external_function_parameters( 235 array( 236 'chatsid' => new external_value(PARAM_ALPHANUM, 'chat session id (obtained via mod_chat_login_user)'), 237 'messagetext' => new external_value(PARAM_RAW, 'the message text'), 238 'beepid' => new external_value(PARAM_RAW, 'the beep id', VALUE_DEFAULT, ''), 239 240 ) 241 ); 242 } 243 244 /** 245 * Send a message on the given chat session. 246 * 247 * @param int $chatsid the chat session id 248 * @param string $messagetext the message text 249 * @param string $beepid the beep message id 250 * @return array of warnings and the new message id (0 if the message was empty) 251 * @since Moodle 3.0 252 * @throws moodle_exception 253 */ 254 public static function send_chat_message($chatsid, $messagetext, $beepid = '') { 255 global $DB; 256 257 $params = self::validate_parameters(self::send_chat_message_parameters(), 258 array( 259 'chatsid' => $chatsid, 260 'messagetext' => $messagetext, 261 'beepid' => $beepid 262 )); 263 $warnings = array(); 264 265 // Request and permission validation. 266 if (!$chatuser = $DB->get_record('chat_users', array('sid' => $params['chatsid']))) { 267 throw new moodle_exception('notlogged', 'chat'); 268 } 269 $chat = $DB->get_record('chat', array('id' => $chatuser->chatid), '*', MUST_EXIST); 270 list($course, $cm) = get_course_and_cm_from_instance($chat, 'chat'); 271 272 $context = context_module::instance($cm->id); 273 self::validate_context($context); 274 275 require_capability('mod/chat:chat', $context); 276 277 $chatmessage = clean_text($params['messagetext'], FORMAT_MOODLE); 278 279 if (!empty($params['beepid'])) { 280 $chatmessage = 'beep ' . $params['beepid']; 281 } 282 283 if (!empty($chatmessage)) { 284 // Send the message. 285 $messageid = chat_send_chatmessage($chatuser, $chatmessage, 0, $cm); 286 // Update ping time. 287 $chatuser->lastmessageping = time() - 2; 288 $DB->update_record('chat_users', $chatuser); 289 } else { 290 $messageid = 0; 291 } 292 293 $result = array(); 294 $result['messageid'] = $messageid; 295 $result['warnings'] = $warnings; 296 return $result; 297 } 298 299 /** 300 * Returns description of method result value 301 * 302 * @return external_description 303 * @since Moodle 3.0 304 */ 305 public static function send_chat_message_returns() { 306 return new external_single_structure( 307 array( 308 'messageid' => new external_value(PARAM_INT, 'message sent id'), 309 'warnings' => new external_warnings() 310 ) 311 ); 312 } 313 314 /** 315 * Returns description of method parameters 316 * 317 * @return external_function_parameters 318 * @since Moodle 3.0 319 */ 320 public static function get_chat_latest_messages_parameters() { 321 return new external_function_parameters( 322 array( 323 'chatsid' => new external_value(PARAM_ALPHANUM, 'chat session id (obtained via mod_chat_login_user)'), 324 'chatlasttime' => new external_value(PARAM_INT, 'last time messages were retrieved (epoch time)', VALUE_DEFAULT, 0) 325 ) 326 ); 327 } 328 329 /** 330 * Get the latest messages from the given chat session. 331 * 332 * @param int $chatsid the chat session id 333 * @param int $chatlasttime last time messages were retrieved (epoch time) 334 * @return array of warnings and the new message id (0 if the message was empty) 335 * @since Moodle 3.0 336 * @throws moodle_exception 337 */ 338 public static function get_chat_latest_messages($chatsid, $chatlasttime = 0) { 339 global $DB, $CFG; 340 341 $params = self::validate_parameters(self::get_chat_latest_messages_parameters(), 342 array( 343 'chatsid' => $chatsid, 344 'chatlasttime' => $chatlasttime 345 )); 346 $warnings = array(); 347 348 // Request and permission validation. 349 if (!$chatuser = $DB->get_record('chat_users', array('sid' => $params['chatsid']))) { 350 throw new moodle_exception('notlogged', 'chat'); 351 } 352 $chat = $DB->get_record('chat', array('id' => $chatuser->chatid), '*', MUST_EXIST); 353 list($course, $cm) = get_course_and_cm_from_instance($chat, 'chat'); 354 355 $context = context_module::instance($cm->id); 356 self::validate_context($context); 357 358 require_capability('mod/chat:chat', $context); 359 360 $chatlasttime = $params['chatlasttime']; 361 if ((time() - $chatlasttime) > $CFG->chat_old_ping) { 362 chat_delete_old_users(); 363 } 364 365 // Set default chat last time (to not retrieve all the conversations). 366 if ($chatlasttime == 0) { 367 $chatlasttime = time() - $CFG->chat_old_ping; 368 } 369 370 if ($latestmessage = chat_get_latest_message($chatuser->chatid, $chatuser->groupid)) { 371 $chatnewlasttime = $latestmessage->timestamp; 372 } else { 373 $chatnewlasttime = 0; 374 } 375 376 $messages = chat_get_latest_messages($chatuser, $chatlasttime); 377 $returnedmessages = array(); 378 379 foreach ($messages as $message) { 380 381 // FORMAT_MOODLE is mandatory in the chat plugin. 382 list($messageformatted, $format) = external_format_text($message->message, FORMAT_MOODLE, $context->id, 'mod_chat', 383 '', 0); 384 385 $returnedmessages[] = array( 386 'id' => $message->id, 387 'userid' => $message->userid, 388 'system' => (bool) $message->issystem, 389 'message' => $messageformatted, 390 'timestamp' => $message->timestamp, 391 ); 392 } 393 394 // Update our status since we are active in the chat. 395 $DB->set_field('chat_users', 'lastping', time(), array('id' => $chatuser->id)); 396 397 $result = array(); 398 $result['messages'] = $returnedmessages; 399 $result['chatnewlasttime'] = $chatnewlasttime; 400 $result['warnings'] = $warnings; 401 return $result; 402 } 403 404 /** 405 * Returns description of method result value 406 * 407 * @return external_description 408 * @since Moodle 3.0 409 */ 410 public static function get_chat_latest_messages_returns() { 411 return new external_single_structure( 412 array( 413 'messages' => new external_multiple_structure( 414 new external_single_structure( 415 array( 416 'id' => new external_value(PARAM_INT, 'message id'), 417 'userid' => new external_value(PARAM_INT, 'user id'), 418 'system' => new external_value(PARAM_BOOL, 'true if is a system message (like user joined)'), 419 'message' => new external_value(PARAM_RAW, 'message text'), 420 'timestamp' => new external_value(PARAM_INT, 'timestamp for the message'), 421 ) 422 ), 423 'list of users' 424 ), 425 'chatnewlasttime' => new external_value(PARAM_INT, 'new last time'), 426 'warnings' => new external_warnings() 427 ) 428 ); 429 } 430 431 /** 432 * Returns description of method parameters 433 * 434 * @return external_function_parameters 435 * @since Moodle 3.0 436 */ 437 public static function view_chat_parameters() { 438 return new external_function_parameters( 439 array( 440 'chatid' => new external_value(PARAM_INT, 'chat instance id') 441 ) 442 ); 443 } 444 445 /** 446 * Trigger the course module viewed event and update the module completion status. 447 * 448 * @param int $chatid the chat instance id 449 * @return array of warnings and status result 450 * @since Moodle 3.0 451 * @throws moodle_exception 452 */ 453 public static function view_chat($chatid) { 454 global $DB, $CFG; 455 456 $params = self::validate_parameters(self::view_chat_parameters(), 457 array( 458 'chatid' => $chatid 459 )); 460 $warnings = array(); 461 462 // Request and permission validation. 463 $chat = $DB->get_record('chat', array('id' => $params['chatid']), '*', MUST_EXIST); 464 list($course, $cm) = get_course_and_cm_from_instance($chat, 'chat'); 465 466 $context = context_module::instance($cm->id); 467 self::validate_context($context); 468 469 require_capability('mod/chat:chat', $context); 470 471 // Call the url/lib API. 472 chat_view($chat, $course, $cm, $context); 473 474 $result = array(); 475 $result['status'] = true; 476 $result['warnings'] = $warnings; 477 return $result; 478 } 479 480 /** 481 * Returns description of method result value 482 * 483 * @return external_description 484 * @since Moodle 3.0 485 */ 486 public static function view_chat_returns() { 487 return new external_single_structure( 488 array( 489 'status' => new external_value(PARAM_BOOL, 'status: true if success'), 490 'warnings' => new external_warnings() 491 ) 492 ); 493 } 494 495 496 /** 497 * Describes the parameters for get_chats_by_courses. 498 * 499 * @return external_function_parameters 500 * @since Moodle 3.0 501 */ 502 public static function get_chats_by_courses_parameters() { 503 return new external_function_parameters ( 504 array( 505 'courseids' => new external_multiple_structure( 506 new external_value(PARAM_INT, 'course id'), 'Array of course ids', VALUE_DEFAULT, array() 507 ), 508 ) 509 ); 510 } 511 512 /** 513 * Returns a list of chats in a provided list of courses, 514 * if no list is provided all chats that the user can view will be returned. 515 * 516 * @param array $courseids the course ids 517 * @return array of chats details 518 * @since Moodle 3.0 519 */ 520 public static function get_chats_by_courses($courseids = array()) { 521 global $CFG; 522 523 $returnedchats = array(); 524 $warnings = array(); 525 526 $params = self::validate_parameters(self::get_chats_by_courses_parameters(), array('courseids' => $courseids)); 527 528 $courses = array(); 529 if (empty($params['courseids'])) { 530 $courses = enrol_get_my_courses(); 531 $params['courseids'] = array_keys($courses); 532 } 533 534 // Ensure there are courseids to loop through. 535 if (!empty($params['courseids'])) { 536 537 list($courses, $warnings) = external_util::validate_courses($params['courseids'], $courses); 538 539 // Get the chats in this course, this function checks users visibility permissions. 540 // We can avoid then additional validate_context calls. 541 $chats = get_all_instances_in_courses("chat", $courses); 542 foreach ($chats as $chat) { 543 $chatcontext = context_module::instance($chat->coursemodule); 544 // Entry to return. 545 $chatdetails = array(); 546 // First, we return information that any user can see in the web interface. 547 $chatdetails['id'] = $chat->id; 548 $chatdetails['coursemodule'] = $chat->coursemodule; 549 $chatdetails['course'] = $chat->course; 550 $chatdetails['name'] = external_format_string($chat->name, $chatcontext->id); 551 // Format intro. 552 $options = array('noclean' => true); 553 list($chatdetails['intro'], $chatdetails['introformat']) = 554 external_format_text($chat->intro, $chat->introformat, $chatcontext->id, 'mod_chat', 'intro', null, $options); 555 $chatdetails['introfiles'] = external_util::get_area_files($chatcontext->id, 'mod_chat', 'intro', false, false); 556 557 if (has_capability('mod/chat:chat', $chatcontext)) { 558 $chatdetails['chatmethod'] = $CFG->chat_method; 559 $chatdetails['keepdays'] = $chat->keepdays; 560 $chatdetails['studentlogs'] = $chat->studentlogs; 561 $chatdetails['chattime'] = $chat->chattime; 562 $chatdetails['schedule'] = $chat->schedule; 563 } 564 565 if (has_capability('moodle/course:manageactivities', $chatcontext)) { 566 $chatdetails['timemodified'] = $chat->timemodified; 567 $chatdetails['section'] = $chat->section; 568 $chatdetails['visible'] = $chat->visible; 569 $chatdetails['groupmode'] = $chat->groupmode; 570 $chatdetails['groupingid'] = $chat->groupingid; 571 } 572 $returnedchats[] = $chatdetails; 573 } 574 } 575 $result = array(); 576 $result['chats'] = $returnedchats; 577 $result['warnings'] = $warnings; 578 return $result; 579 } 580 581 /** 582 * Describes the get_chats_by_courses return value. 583 * 584 * @return external_single_structure 585 * @since Moodle 3.0 586 */ 587 public static function get_chats_by_courses_returns() { 588 return new external_single_structure( 589 array( 590 'chats' => new external_multiple_structure( 591 new external_single_structure( 592 array( 593 'id' => new external_value(PARAM_INT, 'Chat id'), 594 'coursemodule' => new external_value(PARAM_INT, 'Course module id'), 595 'course' => new external_value(PARAM_INT, 'Course id'), 596 'name' => new external_value(PARAM_RAW, 'Chat name'), 597 'intro' => new external_value(PARAM_RAW, 'The Chat intro'), 598 'introformat' => new external_format_value('intro'), 599 'introfiles' => new external_files('Files in the introduction text', VALUE_OPTIONAL), 600 'chatmethod' => new external_value(PARAM_PLUGIN, 'chat method (sockets, ajax, header_js)', 601 VALUE_OPTIONAL), 602 'keepdays' => new external_value(PARAM_INT, 'keep days', VALUE_OPTIONAL), 603 'studentlogs' => new external_value(PARAM_INT, 'student logs visible to everyone', VALUE_OPTIONAL), 604 'chattime' => new external_value(PARAM_INT, 'chat time', VALUE_OPTIONAL), 605 'schedule' => new external_value(PARAM_INT, 'schedule type', VALUE_OPTIONAL), 606 'timemodified' => new external_value(PARAM_INT, 'time of last modification', VALUE_OPTIONAL), 607 'section' => new external_value(PARAM_INT, 'course section id', VALUE_OPTIONAL), 608 'visible' => new external_value(PARAM_BOOL, 'visible', VALUE_OPTIONAL), 609 'groupmode' => new external_value(PARAM_INT, 'group mode', VALUE_OPTIONAL), 610 'groupingid' => new external_value(PARAM_INT, 'group id', VALUE_OPTIONAL), 611 ), 'Chats' 612 ) 613 ), 614 'warnings' => new external_warnings(), 615 ) 616 ); 617 } 618 619 /** 620 * Returns description of method parameters 621 * 622 * @return external_function_parameters 623 * @since Moodle 3.4 624 */ 625 public static function get_sessions_parameters() { 626 return new external_function_parameters( 627 array( 628 'chatid' => new external_value(PARAM_INT, 'Chat instance id.'), 629 'groupid' => new external_value(PARAM_INT, 'Get messages from users in this group. 630 0 means that the function will determine the user group', VALUE_DEFAULT, 0), 631 'showall' => new external_value(PARAM_BOOL, 'Whether to show completed sessions or not.', VALUE_DEFAULT, false), 632 ) 633 ); 634 } 635 636 /** 637 * Retrieves chat sessions for a given chat. 638 * 639 * @param int $chatid the chat instance id 640 * @param int $groupid filter messages by this group. 0 to determine the group. 641 * @param bool $showall whether to include incomplete sessions or not 642 * @return array of warnings and the sessions 643 * @since Moodle 3.4 644 * @throws moodle_exception 645 */ 646 public static function get_sessions($chatid, $groupid = 0, $showall = false) { 647 global $DB; 648 649 $params = self::validate_parameters(self::get_sessions_parameters(), 650 array( 651 'chatid' => $chatid, 652 'groupid' => $groupid, 653 'showall' => $showall, 654 )); 655 $sessions = $warnings = array(); 656 657 // Request and permission validation. 658 $chat = $DB->get_record('chat', array('id' => $params['chatid']), '*', MUST_EXIST); 659 list($course, $cm) = get_course_and_cm_from_instance($chat, 'chat'); 660 661 $context = context_module::instance($cm->id); 662 self::validate_context($context); 663 664 if (empty($chat->studentlogs) && !has_capability('mod/chat:readlog', $context)) { 665 throw new moodle_exception('nopermissiontoseethechatlog', 'chat'); 666 } 667 668 if (!empty($params['groupid'])) { 669 $groupid = $params['groupid']; 670 // Determine is the group is visible to user. 671 if (!groups_group_visible($groupid, $course, $cm)) { 672 throw new moodle_exception('notingroup'); 673 } 674 } else { 675 // Check to see if groups are being used here. 676 if ($groupmode = groups_get_activity_groupmode($cm)) { 677 $groupid = groups_get_activity_group($cm); 678 // Determine is the group is visible to user (this is particullary for the group 0). 679 if (!groups_group_visible($groupid, $course, $cm)) { 680 throw new moodle_exception('notingroup'); 681 } 682 } else { 683 $groupid = 0; 684 } 685 } 686 687 $messages = chat_get_session_messages($chat->id, $groupid, 0, 0, 'timestamp DESC'); 688 if ($messages) { 689 $chatsessions = chat_get_sessions($messages, $params['showall']); 690 // Format sessions for external. 691 foreach ($chatsessions as $session) { 692 $sessionusers = array(); 693 foreach ($session->sessionusers as $sessionuser => $usermessagecount) { 694 $sessionusers[] = array( 695 'userid' => $sessionuser, 696 'messagecount' => $usermessagecount 697 ); 698 } 699 $session->sessionusers = $sessionusers; 700 $sessions[] = $session; 701 } 702 } 703 704 $result = array(); 705 $result['sessions'] = $sessions; 706 $result['warnings'] = $warnings; 707 return $result; 708 } 709 710 /** 711 * Returns description of method result value 712 * 713 * @return external_description 714 * @since Moodle 3.4 715 */ 716 public static function get_sessions_returns() { 717 return new external_single_structure( 718 array( 719 'sessions' => new external_multiple_structure( 720 new external_single_structure( 721 array( 722 'sessionstart' => new external_value(PARAM_INT, 'Session start time.'), 723 'sessionend' => new external_value(PARAM_INT, 'Session end time.'), 724 'sessionusers' => new external_multiple_structure( 725 new external_single_structure( 726 array( 727 'userid' => new external_value(PARAM_INT, 'User id.'), 728 'messagecount' => new external_value(PARAM_INT, 'Number of messages in the session.'), 729 ) 730 ), 'Session users.' 731 ), 732 'iscomplete' => new external_value(PARAM_BOOL, 'Whether the session is completed or not.'), 733 ) 734 ), 735 'list of users' 736 ), 737 'warnings' => new external_warnings() 738 ) 739 ); 740 } 741 742 /** 743 * Returns description of method parameters 744 * 745 * @return external_function_parameters 746 * @since Moodle 3.4 747 */ 748 public static function get_session_messages_parameters() { 749 return new external_function_parameters( 750 array( 751 'chatid' => new external_value(PARAM_INT, 'Chat instance id.'), 752 'sessionstart' => new external_value(PARAM_INT, 'The session start time (timestamp).'), 753 'sessionend' => new external_value(PARAM_INT, 'The session end time (timestamp).'), 754 'groupid' => new external_value(PARAM_INT, 'Get messages from users in this group. 755 0 means that the function will determine the user group', VALUE_DEFAULT, 0), 756 ) 757 ); 758 } 759 760 /** 761 * Retrieves messages of the given chat session. 762 * 763 * @param int $chatid the chat instance id 764 * @param int $sessionstart the session start time (timestamp) 765 * @param int $sessionend the session end time (timestamp) 766 * @param int $groupid filter messages by this group. 0 to determine the group. 767 * @return array of warnings and the messages 768 * @since Moodle 3.4 769 * @throws moodle_exception 770 */ 771 public static function get_session_messages($chatid, $sessionstart, $sessionend, $groupid = 0) { 772 global $DB, $PAGE; 773 774 $params = self::validate_parameters(self::get_session_messages_parameters(), 775 array( 776 'chatid' => $chatid, 777 'sessionstart' => $sessionstart, 778 'sessionend' => $sessionend, 779 'groupid' => $groupid, 780 )); 781 $messages = $warnings = array(); 782 783 // Request and permission validation. 784 $chat = $DB->get_record('chat', array('id' => $params['chatid']), '*', MUST_EXIST); 785 list($course, $cm) = get_course_and_cm_from_instance($chat, 'chat'); 786 787 $context = context_module::instance($cm->id); 788 self::validate_context($context); 789 790 if (empty($chat->studentlogs) && !has_capability('mod/chat:readlog', $context)) { 791 throw new moodle_exception('nopermissiontoseethechatlog', 'chat'); 792 } 793 794 if (!empty($params['groupid'])) { 795 $groupid = $params['groupid']; 796 // Determine is the group is visible to user. 797 if (!groups_group_visible($groupid, $course, $cm)) { 798 throw new moodle_exception('notingroup'); 799 } 800 } else { 801 // Check to see if groups are being used here. 802 if ($groupmode = groups_get_activity_groupmode($cm)) { 803 $groupid = groups_get_activity_group($cm); 804 // Determine is the group is visible to user (this is particullary for the group 0). 805 if (!groups_group_visible($groupid, $course, $cm)) { 806 throw new moodle_exception('notingroup'); 807 } 808 } else { 809 $groupid = 0; 810 } 811 } 812 813 $messages = chat_get_session_messages($chat->id, $groupid, $params['sessionstart'], $params['sessionend'], 814 'timestamp ASC'); 815 if ($messages) { 816 foreach ($messages as $message) { 817 $exporter = new chat_message_exporter($message, array('context' => $context)); 818 $returneditems[] = $exporter->export($PAGE->get_renderer('core')); 819 } 820 } 821 822 $result = array( 823 'messages' => $messages, 824 'warnings' => $warnings, 825 ); 826 return $result; 827 } 828 829 /** 830 * Returns description of method result value 831 * 832 * @return external_description 833 * @since Moodle 3.4 834 */ 835 public static function get_session_messages_returns() { 836 return new external_single_structure( 837 array( 838 'messages' => new external_multiple_structure( 839 chat_message_exporter::get_read_structure() 840 ), 841 'warnings' => new external_warnings() 842 ) 843 ); 844 } 845} 846