See Release Notes
Long Term Support Release
Differences Between: [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]
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 namespace mod_bigbluebuttonbn; 18 19 use cache; 20 use cache_store; 21 use context_course; 22 use core_tag_tag; 23 use Exception; 24 use Firebase\JWT\Key; 25 use mod_bigbluebuttonbn\local\config; 26 use mod_bigbluebuttonbn\local\exceptions\bigbluebutton_exception; 27 use mod_bigbluebuttonbn\local\exceptions\meeting_join_exception; 28 use mod_bigbluebuttonbn\local\helpers\roles; 29 use mod_bigbluebuttonbn\local\proxy\bigbluebutton_proxy; 30 use stdClass; 31 32 /** 33 * Class to describe a BBB Meeting. 34 * 35 * @package mod_bigbluebuttonbn 36 * @copyright 2021 Andrew Lyons <andrew@nicols.co.uk> 37 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 38 */ 39 class meeting { 40 41 /** @var instance The bbb instance */ 42 protected $instance; 43 44 /** @var stdClass Info about the meeting */ 45 protected $meetinginfo = null; 46 47 /** 48 * Constructor for the meeting object. 49 * 50 * @param instance $instance 51 */ 52 public function __construct(instance $instance) { 53 $this->instance = $instance; 54 } 55 56 /** 57 * Helper to join a meeting. 58 * 59 * 60 * It will create the meeting if not already created. 61 * 62 * @param instance $instance 63 * @param int $origin 64 * @return string 65 * @throws meeting_join_exception this is sent if we cannot join (meeting full, user needs to wait...) 66 */ 67 public static function join_meeting(instance $instance, $origin = logger::ORIGIN_BASE): string { 68 // See if the session is in progress. 69 $meeting = new meeting($instance); 70 // As the meeting doesn't exist, try to create it. 71 if (empty($meeting->get_meeting_info(true)->createtime)) { 72 $meeting->create_meeting(); 73 } 74 return $meeting->join($origin); 75 } 76 77 /** 78 * Get currently stored meeting info 79 * 80 * @return stdClass 81 */ 82 public function get_meeting_info() { 83 if (!$this->meetinginfo) { 84 $this->meetinginfo = $this->do_get_meeting_info(); 85 } 86 return $this->meetinginfo; 87 } 88 89 /** 90 * Return meeting information for the specified instance. 91 * 92 * @param instance $instance 93 * @param bool $updatecache Whether to update the cache when fetching the information 94 * @return stdClass 95 */ 96 public static function get_meeting_info_for_instance(instance $instance, bool $updatecache = false): stdClass { 97 $meeting = new self($instance); 98 return $meeting->do_get_meeting_info($updatecache); 99 } 100 101 /** 102 * Helper function returns a sha1 encoded string that is unique and will be used as a seed for meetingid. 103 * 104 * @return string 105 */ 106 public static function get_unique_meetingid_seed() { 107 global $DB; 108 do { 109 $encodedseed = sha1(plugin::random_password(12)); 110 $meetingid = (string) $DB->get_field('bigbluebuttonbn', 'meetingid', ['meetingid' => $encodedseed]); 111 } while ($meetingid == $encodedseed); 112 return $encodedseed; 113 } 114 115 /** 116 * Is meeting running ? 117 * 118 * @return bool 119 */ 120 public function is_running() { 121 return $this->get_meeting_info()->statusrunning ?? false; 122 } 123 124 /** 125 * Force update the meeting in cache. 126 */ 127 public function update_cache() { 128 $this->meetinginfo = $this->do_get_meeting_info(true); 129 } 130 131 /** 132 * Get meeting attendees 133 * 134 * @return array[] 135 */ 136 public function get_attendees(): array { 137 return $this->get_meeting_info()->attendees ?? []; 138 } 139 140 /** 141 * Can the meeting be joined ? 142 * 143 * @return bool 144 */ 145 public function can_join() { 146 return $this->get_meeting_info()->canjoin; 147 } 148 149 /** 150 * Total number of moderators and viewers. 151 * 152 * @return int 153 */ 154 public function get_participant_count() { 155 return $this->get_meeting_info()->totalusercount; 156 } 157 158 /** 159 * Creates a bigbluebutton meeting, send the message to BBB and returns the response in an array. 160 * 161 * @return array 162 */ 163 public function create_meeting() { 164 $data = $this->create_meeting_data(); 165 $metadata = $this->create_meeting_metadata(); 166 $presentation = $this->instance->get_presentation_for_bigbluebutton_upload(); // The URL must contain nonce. 167 $presentationname = $presentation['name'] ?? null; 168 $presentationurl = $presentation['url'] ?? null; 169 $response = bigbluebutton_proxy::create_meeting($data, $metadata, $presentationname, $presentationurl); 170 // New recording management: Insert a recordingID that corresponds to the meeting created. 171 if ($this->instance->is_recorded()) { 172 $recording = new recording(0, (object) [ 173 'courseid' => $this->instance->get_course_id(), 174 'bigbluebuttonbnid' => $this->instance->get_instance_id(), 175 'recordingid' => $response['internalMeetingID'], 176 'groupid' => $this->instance->get_group_id()] 177 ); 178 $recording->create(); 179 } 180 return $response; 181 } 182 183 /** 184 * Send an end meeting message to BBB server 185 */ 186 public function end_meeting() { 187 bigbluebutton_proxy::end_meeting($this->instance->get_meeting_id(), $this->instance->get_moderator_password()); 188 } 189 190 /** 191 * Get meeting join URL 192 * 193 * @return string 194 */ 195 public function get_join_url(): string { 196 return bigbluebutton_proxy::get_join_url( 197 $this->instance->get_meeting_id(), 198 $this->instance->get_user_fullname(), 199 $this->instance->get_current_user_password(), 200 $this->instance->get_logout_url()->out(false), 201 $this->instance->get_current_user_role(), 202 null, 203 $this->instance->get_user_id(), 204 $this->get_meeting_info()->createtime 205 ); 206 } 207 208 /** 209 * Get meeting join URL for guest 210 * 211 * @param string $fullname 212 * @return string 213 */ 214 public function get_guest_join_url(string $fullname): string { 215 return bigbluebutton_proxy::get_join_url( 216 $this->instance->get_meeting_id(), 217 $fullname, 218 $this->instance->get_current_user_password(), 219 $this->instance->get_guest_access_url()->out(false), 220 $this->instance->get_current_user_role(), 221 null, 222 0, 223 $this->get_meeting_info()->createtime 224 ); 225 } 226 227 228 /** 229 * Return meeting information for this meeting. 230 * 231 * @param bool $updatecache Whether to update the cache when fetching the information 232 * @return stdClass 233 */ 234 protected function do_get_meeting_info(bool $updatecache = false): stdClass { 235 $instance = $this->instance; 236 $meetinginfo = (object) [ 237 'instanceid' => $instance->get_instance_id(), 238 'bigbluebuttonbnid' => $instance->get_instance_id(), 239 'groupid' => $instance->get_group_id(), 240 'meetingid' => $instance->get_meeting_id(), 241 'cmid' => $instance->get_cm_id(), 242 'ismoderator' => $instance->is_moderator(), 243 'joinurl' => $instance->get_join_url()->out(), 244 'userlimit' => $instance->get_user_limit(), 245 'presentations' => [], 246 ]; 247 if ($instance->get_instance_var('openingtime')) { 248 $meetinginfo->openingtime = intval($instance->get_instance_var('openingtime')); 249 } 250 if ($instance->get_instance_var('closingtime')) { 251 $meetinginfo->closingtime = intval($instance->get_instance_var('closingtime')); 252 } 253 $activitystatus = bigbluebutton_proxy::view_get_activity_status($instance); 254 // This might raise an exception if info cannot be retrieved. 255 // But this might be totally fine as the meeting is maybe not yet created on BBB side. 256 $totalusercount = 0; 257 // This is the default value for any meeting that has not been created. 258 $meetinginfo->statusrunning = false; 259 $meetinginfo->createtime = null; 260 261 $info = self::retrieve_cached_meeting_info($this->instance->get_meeting_id(), $updatecache); 262 if (!empty($info)) { 263 $meetinginfo->statusrunning = $info['running'] === 'true'; 264 $meetinginfo->createtime = $info['createTime'] ?? null; 265 $totalusercount = isset($info['participantCount']) ? $info['participantCount'] : 0; 266 } 267 268 $meetinginfo->statusclosed = $activitystatus === 'ended'; 269 $meetinginfo->statusopen = !$meetinginfo->statusrunning && $activitystatus === 'open'; 270 $meetinginfo->totalusercount = $totalusercount; 271 272 $canjoin = !$instance->user_must_wait_to_join() || $meetinginfo->statusrunning; 273 // Limit has not been reached. 274 $canjoin = $canjoin && (!$instance->has_user_limit_been_reached($totalusercount)); 275 // User should only join during scheduled session start and end time, if defined. 276 $canjoin = $canjoin && ($instance->is_currently_open()); 277 // Double check that the user has the capabilities to join. 278 $canjoin = $canjoin && $instance->can_join(); 279 $meetinginfo->canjoin = $canjoin; 280 281 // If user is administrator, moderator or if is viewer and no waiting is required, join allowed. 282 if ($meetinginfo->statusrunning) { 283 $meetinginfo->startedat = floor(intval($info['startTime']) / 1000); // Milliseconds. 284 $meetinginfo->moderatorcount = $info['moderatorCount']; 285 $meetinginfo->moderatorplural = $info['moderatorCount'] > 1; 286 $meetinginfo->participantcount = $totalusercount - $meetinginfo->moderatorcount; 287 $meetinginfo->participantplural = $meetinginfo->participantcount > 1; 288 } 289 $meetinginfo->statusmessage = $this->get_status_message($meetinginfo, $instance); 290 291 $presentation = $instance->get_presentation(); // This is for internal use. 292 if (!empty($presentation)) { 293 $meetinginfo->presentations[] = $presentation; 294 } 295 $meetinginfo->attendees = []; 296 if (!empty($info['attendees'])) { 297 // Ensure each returned attendee is cast to an array, rather than a simpleXML object. 298 foreach ($info['attendees'] as $attendee) { 299 $meetinginfo->attendees[] = (array) $attendee; 300 } 301 } 302 $meetinginfo->guestaccessenabled = $instance->is_guest_allowed(); 303 if ($meetinginfo->guestaccessenabled && $instance->is_moderator()) { 304 $meetinginfo->guestjoinurl = $instance->get_guest_access_url()->out(); 305 $meetinginfo->guestpassword = $instance->get_guest_access_password(); 306 } 307 308 $meetinginfo->features = $instance->get_enabled_features(); 309 return $meetinginfo; 310 } 311 312 /** 313 * Deduce status message from the current meeting info and the instance 314 * 315 * Returns the human-readable message depending on if the user must wait to join, the meeting has not 316 * yet started ... 317 * @param object $meetinginfo 318 * @param instance $instance 319 * @return string 320 */ 321 protected function get_status_message(object $meetinginfo, instance $instance): string { 322 if ($instance->has_user_limit_been_reached($meetinginfo->totalusercount)) { 323 return get_string('view_message_conference_user_limit_reached', 'bigbluebuttonbn'); 324 } 325 if ($meetinginfo->statusrunning) { 326 return get_string('view_message_conference_in_progress', 'bigbluebuttonbn'); 327 } 328 if ($instance->user_must_wait_to_join() && !$instance->user_can_force_join()) { 329 return get_string('view_message_conference_wait_for_moderator', 'bigbluebuttonbn'); 330 } 331 if ($instance->before_start_time()) { 332 return get_string('view_message_conference_not_started', 'bigbluebuttonbn'); 333 } 334 if ($instance->has_ended()) { 335 return get_string('view_message_conference_has_ended', 'bigbluebuttonbn'); 336 } 337 return get_string('view_message_conference_room_ready', 'bigbluebuttonbn'); 338 } 339 340 /** 341 * Gets a meeting info object cached or fetched from the live session. 342 * 343 * @param string $meetingid 344 * @param bool $updatecache 345 * 346 * @return array 347 */ 348 protected static function retrieve_cached_meeting_info($meetingid, $updatecache = false) { 349 $cachettl = (int) config::get('waitformoderator_cache_ttl'); 350 $cache = cache::make_from_params(cache_store::MODE_APPLICATION, 'mod_bigbluebuttonbn', 'meetings_cache'); 351 $result = $cache->get($meetingid); 352 $now = time(); 353 if (!$updatecache && !empty($result) && $now < ($result['creation_time'] + $cachettl)) { 354 // Use the value in the cache. 355 return (array) json_decode($result['meeting_info']); 356 } 357 // We set the cache to an empty value so then if get_meeting_info raises an exception we still have the 358 // info about the last creation_time, so we don't ask the server again for a bit. 359 $defaultcacheinfo = ['creation_time' => time(), 'meeting_info' => '[]']; 360 // Pings again and refreshes the cache. 361 try { 362 $meetinginfo = bigbluebutton_proxy::get_meeting_info($meetingid); 363 $cache->set($meetingid, ['creation_time' => time(), 'meeting_info' => json_encode($meetinginfo)]); 364 } catch (bigbluebutton_exception $e) { 365 // The meeting is not created on BBB side, so we set the value in the cache so we don't poll again 366 // and return an empty array. 367 $cache->set($meetingid, $defaultcacheinfo); 368 return []; 369 } 370 return $meetinginfo; 371 } 372 373 /** 374 * Conversion between form settings and lockSettings as set in BBB API. 375 */ 376 const LOCK_SETTINGS_MEETING_DATA = [ 377 'disablecam' => 'lockSettingsDisableCam', 378 'disablemic' => 'lockSettingsDisableMic', 379 'disableprivatechat' => 'lockSettingsDisablePrivateChat', 380 'disablepublicchat' => 'lockSettingsDisablePublicChat', 381 'disablenote' => 'lockSettingsDisableNote', 382 'hideuserlist' => 'lockSettingsHideUserList' 383 ]; 384 /** 385 * Helper to prepare data used for create meeting. 386 * @todo moderatorPW and attendeePW will be removed from create after release of BBB v2.6. 387 * 388 * @return array 389 */ 390 protected function create_meeting_data() { 391 $data = ['meetingID' => $this->instance->get_meeting_id(), 392 'name' => \mod_bigbluebuttonbn\plugin::html2text($this->instance->get_meeting_name(), 64), 393 'attendeePW' => $this->instance->get_viewer_password(), 394 'moderatorPW' => $this->instance->get_moderator_password(), 395 'logoutURL' => $this->instance->get_logout_url()->out(false), 396 ]; 397 $data['record'] = $this->instance->should_record() ? 'true' : 'false'; 398 // Check if auto_start_record is enable. 399 if ($data['record'] == 'true' && $this->instance->should_record_from_start()) { 400 $data['autoStartRecording'] = 'true'; 401 } 402 // Check if hide_record_button is enable. 403 if (!$this->instance->should_show_recording_button()) { 404 $data['allowStartStopRecording'] = 'false'; 405 } 406 $data['welcome'] = trim($this->instance->get_welcome_message()); 407 $voicebridge = intval($this->instance->get_voice_bridge()); 408 if ($voicebridge > 0 && $voicebridge < 79999) { 409 $data['voiceBridge'] = $voicebridge; 410 } 411 $maxparticipants = intval($this->instance->get_user_limit()); 412 if ($maxparticipants > 0) { 413 $data['maxParticipants'] = $maxparticipants; 414 } 415 if ($this->instance->get_mute_on_start()) { 416 $data['muteOnStart'] = 'true'; 417 } 418 // Here a bit of a change compared to the API default behaviour: we should not allow guest to join 419 // a meeting managed by Moodle by default. 420 if ($this->instance->is_guest_allowed()) { 421 $data['guestPolicy'] = $this->instance->is_moderator_approval_required() ? 'ASK_MODERATOR' : 'ALWAYS_ACCEPT'; 422 } 423 // Locks settings. 424 foreach (self::LOCK_SETTINGS_MEETING_DATA as $instancevarname => $lockname) { 425 $instancevar = $this->instance->get_instance_var($instancevarname); 426 if (!is_null($instancevar)) { 427 $data[$lockname] = $instancevar ? 'true' : 'false'; 428 if ($instancevar) { 429 $data['lockSettingsLockOnJoin'] = 'true'; // This will be locked whenever one settings is locked. 430 } 431 } 432 } 433 return $data; 434 } 435 436 /** 437 * Helper for preparing metadata used while creating the meeting. 438 * 439 * @return array 440 */ 441 protected function create_meeting_metadata() { 442 global $USER; 443 // Create standard metadata. 444 $origindata = $this->instance->get_origin_data(); 445 $metadata = [ 446 'bbb-origin' => $origindata->origin, 447 'bbb-origin-version' => $origindata->originVersion, 448 'bbb-origin-server-name' => $origindata->originServerName, 449 'bbb-origin-server-common-name' => $origindata->originServerCommonName, 450 'bbb-origin-tag' => $origindata->originTag, 451 'bbb-context' => $this->instance->get_course()->fullname, 452 'bbb-context-id' => $this->instance->get_course_id(), 453 'bbb-context-name' => trim(html_to_text($this->instance->get_course()->fullname, 0)), 454 'bbb-context-label' => trim(html_to_text($this->instance->get_course()->shortname, 0)), 455 'bbb-recording-name' => plugin::html2text($this->instance->get_meeting_name(), 64), 456 'bbb-recording-description' => plugin::html2text($this->instance->get_meeting_description(), 457 64), 458 'bbb-recording-tags' => 459 implode(',', core_tag_tag::get_item_tags_array('core', 460 'course_modules', $this->instance->get_cm_id())), // Same as $id. 461 'bbb-meeting-size-hint' => 462 count_enrolled_users(context_course::instance($this->instance->get_course_id()), 463 '', $this->instance->get_group_id()), 464 ]; 465 // Special metadata for recording processing. 466 if ((boolean) config::get('recordingstatus_enabled')) { 467 $metadata["bn-recording-status"] = json_encode( 468 [ 469 'email' => ['"' . fullname($USER) . '" <' . $USER->email . '>'], 470 'context' => $this->instance->get_view_url(), 471 ] 472 ); 473 } 474 if ((boolean) config::get('recordingready_enabled')) { 475 $metadata['bn-recording-ready-url'] = $this->instance->get_record_ready_url()->out(false); 476 } 477 if ((boolean) config::get('meetingevents_enabled')) { 478 $metadata['analytics-callback-url'] = $this->instance->get_meeting_event_notification_url()->out(false); 479 } 480 return $metadata; 481 } 482 483 /** 484 * Helper for responding when storing live meeting events is requested. 485 * 486 * The callback with a POST request includes: 487 * - Authentication: Bearer <A JWT token containing {"exp":<TIMESTAMP>} encoded with HS512> 488 * - Content Type: application/json 489 * - Body: <A JSON Object> 490 * 491 * @param instance $instance 492 * @param object $data 493 * @return string 494 */ 495 public static function meeting_events(instance $instance, object $data): string { 496 $bigbluebuttonbn = $instance->get_instance_data(); 497 // Validate that the bigbluebuttonbn activity corresponds to the meeting_id received. 498 $meetingidelements = explode('[', $data->{'meeting_id'}); 499 $meetingidelements = explode('-', $meetingidelements[0]); 500 if (!isset($bigbluebuttonbn) || $bigbluebuttonbn->meetingid != $meetingidelements[0]) { 501 return 'HTTP/1.0 410 Gone. The activity may have been deleted'; 502 } 503 504 // We make sure events are processed only once. 505 $overrides = ['meetingid' => $data->{'meeting_id'}]; 506 $meta['internalmeetingid'] = $data->{'internal_meeting_id'}; 507 $meta['callback'] = 'meeting_events'; 508 $meta['meetingid'] = $data->{'meeting_id'}; 509 510 $eventcount = logger::log_event_callback($instance, $overrides, $meta); 511 if ($eventcount === 1) { 512 // Process the events. 513 self::process_meeting_events($instance, $data); 514 return 'HTTP/1.0 200 Accepted. Enqueued.'; 515 } else { 516 return 'HTTP/1.0 202 Accepted. Already processed.'; 517 } 518 } 519 520 /** 521 * Helper function enqueues list of meeting events to be stored and processed as for completion. 522 * 523 * @param instance $instance 524 * @param stdClass $jsonobj 525 */ 526 protected static function process_meeting_events(instance $instance, stdClass $jsonobj) { 527 $meetingid = $jsonobj->{'meeting_id'}; 528 $recordid = $jsonobj->{'internal_meeting_id'}; 529 $attendees = $jsonobj->{'data'}->{'attendees'}; 530 foreach ($attendees as $attendee) { 531 $userid = $attendee->{'ext_user_id'}; 532 $overrides['meetingid'] = $meetingid; 533 $overrides['userid'] = $userid; 534 $meta['recordid'] = $recordid; 535 $meta['data'] = $attendee; 536 537 // Stores the log. 538 logger::log_event_summary($instance, $overrides, $meta); 539 540 // Enqueue a task for processing the completion. 541 bigbluebutton_proxy::enqueue_completion_event($instance->get_instance_data(), $userid); 542 } 543 } 544 545 /** 546 * Prepare join meeting action 547 * 548 * @param int $origin 549 * @return void 550 */ 551 protected function prepare_meeting_join_action(int $origin) { 552 $this->do_get_meeting_info(true); 553 if ($this->is_running()) { 554 if ($this->instance->has_user_limit_been_reached($this->get_participant_count())) { 555 throw new meeting_join_exception('userlimitreached'); 556 } 557 } else if ($this->instance->user_must_wait_to_join()) { 558 // If user is not administrator nor moderator (user is student) and waiting is required. 559 throw new meeting_join_exception('waitformoderator'); 560 } 561 562 // Moodle event logger: Create an event for meeting joined. 563 logger::log_meeting_joined_event($this->instance, $origin); 564 565 // Before executing the redirect, increment the number of participants. 566 roles::participant_joined($this->instance->get_meeting_id(), $this->instance->is_moderator()); 567 } 568 /** 569 * Join a meeting. 570 * 571 * @param int $origin The spec 572 * @return string The URL to redirect to 573 * @throws meeting_join_exception 574 */ 575 public function join(int $origin): string { 576 $this->prepare_meeting_join_action($origin); 577 return $this->get_join_url(); 578 } 579 580 /** 581 * Join a meeting as a guest. 582 * 583 * @param int $origin The spec 584 * @param string $userfullname Fullname for the guest user 585 * @return string The URL to redirect to 586 * @throws meeting_join_exception 587 */ 588 public function guest_join(int $origin, string $userfullname): string { 589 $this->prepare_meeting_join_action($origin); 590 return $this->get_join_url(); 591 } 592 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body