[Summary view]

Differences Between: [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  
  18  /**
  19   * External notes API
  20   *
  21   * @package    core_notes
  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  defined('MOODLE_INTERNAL') || die();
  28  
  29  require_once("$CFG->libdir/externallib.php");
  30  require_once($CFG->dirroot . "/notes/lib.php");
  31  
  32  /**
  33   * Notes external functions
  34   *
  35   * @package    core_notes
  36   * @category   external
  37   * @copyright  2011 Jerome Mouneyrac
  38   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  39   * @since Moodle 2.2
  40   */
  41  class core_notes_external extends external_api {
  42  
  43      /**
  44       * Returns description of method parameters
  45       *
  46       * @return external_function_parameters
  47       * @since Moodle 2.2
  48       */
  49      public static function create_notes_parameters() {
  50          return new external_function_parameters(
  51              array(
  52                  'notes' => new external_multiple_structure(
  53                      new external_single_structure(
  54                          array(
  55                              'userid' => new external_value(PARAM_INT, 'id of the user the note is about'),
  56                              'publishstate' => new external_value(PARAM_ALPHA, '\'personal\', \'course\' or \'site\''),
  57                              'courseid' => new external_value(PARAM_INT, 'course id of the note (in Moodle a note can only be created into a course, even for site and personal notes)'),
  58                              'text' => new external_value(PARAM_RAW, 'the text of the message - text or HTML'),
  59                              'format' => new external_format_value('text', VALUE_DEFAULT),
  60                              'clientnoteid' => new external_value(PARAM_ALPHANUMEXT, 'your own client id for the note. If this id is provided, the fail message id will be returned to you', VALUE_OPTIONAL),
  61                          )
  62                      )
  63                  )
  64              )
  65          );
  66      }
  67  
  68      /**
  69       * Create notes about some users
  70       * Note: code should be matching the /notes/edit.php checks
  71       * and the /user/addnote.php checks. (they are similar cheks)
  72       *
  73       * @param array $notes  An array of notes to create.
  74       * @return array (success infos and fail infos)
  75       * @since Moodle 2.2
  76       */
  77      public static function create_notes($notes = array()) {
  78          global $CFG, $DB;
  79  
  80          $params = self::validate_parameters(self::create_notes_parameters(), array('notes' => $notes));
  81  
  82          // Check if note system is enabled.
  83          if (!$CFG->enablenotes) {
  84              throw new moodle_exception('notesdisabled', 'notes');
  85          }
  86  
  87          // Retrieve all courses.
  88          $courseids = array();
  89          foreach ($params['notes'] as $note) {
  90              $courseids[] = $note['courseid'];
  91          }
  92          $courses = $DB->get_records_list("course", "id", $courseids);
  93  
  94          // Retrieve all users of the notes.
  95          $userids = array();
  96          foreach ($params['notes'] as $note) {
  97              $userids[] = $note['userid'];
  98          }
  99          list($sqluserids, $sqlparams) = $DB->get_in_or_equal($userids, SQL_PARAMS_NAMED, 'userid_');
 100          $users = $DB->get_records_select("user", "id " . $sqluserids . " AND deleted = 0", $sqlparams);
 101  
 102          $resultnotes = array();
 103          foreach ($params['notes'] as $note) {
 104  
 105              $success = true;
 106              $resultnote = array(); // The infos about the success of the operation.
 107  
 108              // Check the course exists.
 109              if (empty($courses[$note['courseid']])) {
 110                  $success = false;
 111                  $errormessage = get_string('invalidcourseid', 'error');
 112              } else {
 113                  // Ensure the current user is allowed to run this function.
 114                  $context = context_course::instance($note['courseid']);
 115                  self::validate_context($context);
 116                  require_capability('moodle/notes:manage', $context);
 117              }
 118  
 119              // Check the user exists.
 120              if (empty($users[$note['userid']])) {
 121                  $success = false;
 122                  $errormessage = get_string('invaliduserid', 'notes', $note['userid']);
 123              }
 124  
 125              // Build the resultnote.
 126              if (isset($note['clientnoteid'])) {
 127                  $resultnote['clientnoteid'] = $note['clientnoteid'];
 128              }
 129  
 130              if ($success) {
 131                  // Now we can create the note.
 132                  $dbnote = new stdClass;
 133                  $dbnote->courseid = $note['courseid'];
 134                  $dbnote->userid = $note['userid'];
 135                  // Need to support 'html' and 'text' format values for backward compatibility.
 136                  switch (strtolower($note['format'])) {
 137                      case 'html':
 138                          $textformat = FORMAT_HTML;
 139                          break;
 140                      case 'text':
 141                          $textformat = FORMAT_PLAIN;
 142                      default:
 143                          $textformat = external_validate_format($note['format']);
 144                          break;
 145                  }
 146                  $dbnote->content = $note['text'];
 147                  $dbnote->format = $textformat;
 148  
 149                  // Get the state ('personal', 'course', 'site').
 150                  switch ($note['publishstate']) {
 151                      case 'personal':
 152                          $dbnote->publishstate = NOTES_STATE_DRAFT;
 153                          break;
 154                      case 'course':
 155                          $dbnote->publishstate = NOTES_STATE_PUBLIC;
 156                          break;
 157                      case 'site':
 158                          $dbnote->publishstate = NOTES_STATE_SITE;
 159                          $dbnote->courseid = SITEID;
 160                          break;
 161                      default:
 162                          break;
 163                  }
 164  
 165                  // TODO MDL-31119 performance improvement - if possible create a bulk functions for saving multiple notes at once
 166                  if (note_save($dbnote)) { // Note_save attribut an id in case of success.
 167                      $success = $dbnote->id;
 168                  }
 169  
 170                  $resultnote['noteid'] = $success;
 171              } else {
 172                  // WARNINGS: for backward compatibility we return this errormessage.
 173                  //          We should have thrown exceptions as these errors prevent results to be returned.
 174                  // See http://docs.moodle.org/dev/Errors_handling_in_web_services#When_to_send_a_warning_on_the_server_side .
 175                  $resultnote['noteid'] = -1;
 176                  $resultnote['errormessage'] = $errormessage;
 177              }
 178  
 179              $resultnotes[] = $resultnote;
 180          }
 181  
 182          return $resultnotes;
 183      }
 184  
 185      /**
 186       * Returns description of method result value
 187       *
 188       * @return external_description
 189       * @since Moodle 2.2
 190       */
 191      public static function create_notes_returns() {
 192          return new external_multiple_structure(
 193              new external_single_structure(
 194                  array(
 195                      'clientnoteid' => new external_value(PARAM_ALPHANUMEXT, 'your own id for the note', VALUE_OPTIONAL),
 196                      'noteid' => new external_value(PARAM_INT, 'ID of the created note when successful, -1 when failed'),
 197                      'errormessage' => new external_value(PARAM_TEXT, 'error message - if failed', VALUE_OPTIONAL)
 198                  )
 199              )
 200          );
 201      }
 202  
 203      /**
 204       * Returns description of delete_notes parameters
 205       *
 206       * @return external_function_parameters
 207       * @since Moodle 2.5
 208       */
 209      public static function delete_notes_parameters() {
 210          return new external_function_parameters(
 211              array(
 212                  "notes"=> new external_multiple_structure(
 213                      new external_value(PARAM_INT, 'ID of the note to be deleted'), 'Array of Note Ids to be deleted.'
 214                  )
 215              )
 216          );
 217      }
 218  
 219      /**
 220       * Delete notes about users.
 221       * Note: code should be matching the /notes/delete.php checks.
 222       *
 223       * @param array $notes An array of ids for the notes to delete.
 224       * @return null
 225       * @since Moodle 2.5
 226       */
 227      public static function delete_notes($notes = array()) {
 228          global $CFG;
 229  
 230          $params = self::validate_parameters(self::delete_notes_parameters(), array('notes' => $notes));
 231  
 232          // Check if note system is enabled.
 233          if (!$CFG->enablenotes) {
 234              throw new moodle_exception('notesdisabled', 'notes');
 235          }
 236          $warnings = array();
 237          foreach ($params['notes'] as $noteid) {
 238              $note = note_load($noteid);
 239              if (isset($note->id)) {
 240                  // Ensure the current user is allowed to run this function.
 241                  $context = context_course::instance($note->courseid);
 242                  self::validate_context($context);
 243                  require_capability('moodle/notes:manage', $context);
 244                  note_delete($note);
 245              } else {
 246                  $warnings[] = array('item'=>'note', 'itemid'=>$noteid, 'warningcode'=>'badid', 'message'=>'Note does not exist');
 247              }
 248          }
 249          return $warnings;
 250      }
 251  
 252      /**
 253       * Returns description of delete_notes result value.
 254       *
 255       * @return external_description
 256       * @since Moodle 2.5
 257       */
 258      public static function delete_notes_returns() {
 259          return  new external_warnings('item is always \'note\'',
 260                              'When errorcode is savedfailed the note could not be modified.' .
 261                              'When errorcode is badparam, an incorrect parameter was provided.' .
 262                              'When errorcode is badid, the note does not exist',
 263                              'errorcode can be badparam (incorrect parameter), savedfailed (could not be modified), or badid (note does not exist)');
 264  
 265      }
 266  
 267      /**
 268       * Returns description of get_notes parameters.
 269       *
 270       * @return external_function_parameters
 271       * @since Moodle 2.5
 272       */
 273      public static function get_notes_parameters() {
 274          return new external_function_parameters(
 275              array(
 276                  "notes"=> new external_multiple_structure(
 277                      new external_value(PARAM_INT, 'ID of the note to be retrieved'), 'Array of Note Ids to be retrieved.'
 278                  )
 279              )
 280          );
 281      }
 282  
 283      /**
 284       * Get notes about users.
 285       *
 286       * @param array $notes An array of ids for the notes to retrieve.
 287       * @return null
 288       * @since Moodle 2.5
 289       */
 290      public static function get_notes($notes) {
 291          global $CFG;
 292  
 293          $params = self::validate_parameters(self::get_notes_parameters(), array('notes' => $notes));
 294          // Check if note system is enabled.
 295          if (!$CFG->enablenotes) {
 296              throw new moodle_exception('notesdisabled', 'notes');
 297          }
 298          $resultnotes = array();
 299          foreach ($params['notes'] as $noteid) {
 300              $resultnote = array();
 301  
 302              $note = note_load($noteid);
 303              if (isset($note->id)) {
 304                  // Ensure the current user is allowed to run this function.
 305                  $context = context_course::instance($note->courseid);
 306                  self::validate_context($context);
 307                  require_capability('moodle/notes:view', $context);
 308                  list($gotnote['text'], $gotnote['format']) = external_format_text($note->content,
 309                                                                                    $note->format,
 310                                                                                    $context->id,
 311                                                                                    'notes',
 312                                                                                    '',
 313                                                                                    '');
 314                  $gotnote['noteid'] = $note->id;
 315                  $gotnote['userid'] = $note->userid;
 316                  $gotnote['publishstate'] = $note->publishstate;
 317                  $gotnote['courseid'] = $note->courseid;
 318                  $resultnotes["notes"][] = $gotnote;
 319              } else {
 320                  $resultnotes["warnings"][] = array('item' => 'note',
 321                                                     'itemid' => $noteid,
 322                                                     'warningcode' => 'badid',
 323                                                     'message' => 'Note does not exist');
 324              }
 325          }
 326          return $resultnotes;
 327      }
 328  
 329      /**
 330       * Returns description of get_notes result value.
 331       *
 332       * @return external_description
 333       * @since Moodle 2.5
 334       */
 335      public static function get_notes_returns() {
 336          return new external_single_structure(
 337              array(
 338                  'notes' => new external_multiple_structure(
 339                      new external_single_structure(
 340                          array(
 341                              'noteid' => new external_value(PARAM_INT, 'id of the note', VALUE_OPTIONAL),
 342                              'userid' => new external_value(PARAM_INT, 'id of the user the note is about', VALUE_OPTIONAL),
 343                              'publishstate' => new external_value(PARAM_ALPHA, '\'personal\', \'course\' or \'site\'', VALUE_OPTIONAL),
 344                              'courseid' => new external_value(PARAM_INT, 'course id of the note', VALUE_OPTIONAL),
 345                              'text' => new external_value(PARAM_RAW, 'the text of the message - text or HTML', VALUE_OPTIONAL),
 346                              'format' => new external_format_value('text', VALUE_OPTIONAL),
 347                          ), 'note'
 348                      )
 349                   ),
 350                   'warnings' => new external_warnings('item is always \'note\'',
 351                          'When errorcode is savedfailed the note could not be modified.' .
 352                          'When errorcode is badparam, an incorrect parameter was provided.' .
 353                          'When errorcode is badid, the note does not exist',
 354                          'errorcode can be badparam (incorrect parameter), savedfailed (could not be modified), or badid (note does not exist)')
 355              )
 356          );
 357      }
 358  
 359      /**
 360       * Returns description of update_notes parameters.
 361       *
 362       * @return external_function_parameters
 363       * @since Moodle 2.5
 364       */
 365      public static function update_notes_parameters() {
 366          return new external_function_parameters(
 367              array(
 368                  'notes' => new external_multiple_structure(
 369                      new external_single_structure(
 370                          array(
 371                              'id' => new external_value(PARAM_INT, 'id of the note'),
 372                              'publishstate' => new external_value(PARAM_ALPHA, '\'personal\', \'course\' or \'site\''),
 373                              'text' => new external_value(PARAM_RAW, 'the text of the message - text or HTML'),
 374                              'format' => new external_format_value('text', VALUE_DEFAULT),
 375                          )
 376                      ), "Array of Notes", VALUE_DEFAULT, array()
 377                  )
 378              )
 379          );
 380      }
 381  
 382      /**
 383       * Update notes about users.
 384       *
 385       * @param array $notes An array of ids for the notes to update.
 386       * @return array fail infos.
 387       * @since Moodle 2.2
 388       */
 389      public static function update_notes($notes = array()) {
 390          global $CFG, $DB;
 391  
 392          $params = self::validate_parameters(self::update_notes_parameters(), array('notes' => $notes));
 393  
 394          // Check if note system is enabled.
 395          if (!$CFG->enablenotes) {
 396              throw new moodle_exception('notesdisabled', 'notes');
 397          }
 398  
 399          $warnings = array();
 400          foreach ($params['notes'] as $note) {
 401              $notedetails = note_load($note['id']);
 402              if (isset($notedetails->id)) {
 403                  // Ensure the current user is allowed to run this function.
 404                  $context = context_course::instance($notedetails->courseid);
 405                  self::validate_context($context);
 406                  require_capability('moodle/notes:manage', $context);
 407  
 408                  $dbnote = new stdClass;
 409                  $dbnote->id = $note['id'];
 410                  $dbnote->content = $note['text'];
 411                  $dbnote->format = external_validate_format($note['format']);
 412                  // Get the state ('personal', 'course', 'site').
 413                  switch ($note['publishstate']) {
 414                      case 'personal':
 415                          $dbnote->publishstate = NOTES_STATE_DRAFT;
 416                          break;
 417                      case 'course':
 418                          $dbnote->publishstate = NOTES_STATE_PUBLIC;
 419                          break;
 420                      case 'site':
 421                          $dbnote->publishstate = NOTES_STATE_SITE;
 422                          $dbnote->courseid = SITEID;
 423                          break;
 424                      default:
 425                          $warnings[] = array('item' => 'note',
 426                                              'itemid' => $note["id"],
 427                                              'warningcode' => 'badparam',
 428                                              'message' => 'Provided publishstate incorrect');
 429                          break;
 430                  }
 431                  if (!note_save($dbnote)) {
 432                      $warnings[] = array('item' => 'note',
 433                                          'itemid' => $note["id"],
 434                                          'warningcode' => 'savedfailed',
 435                                          'message' => 'Note could not be modified');
 436                  }
 437              } else {
 438                  $warnings[] = array('item' => 'note',
 439                                      'itemid' => $note["id"],
 440                                      'warningcode' => 'badid',
 441                                      'message' => 'Note does not exist');
 442              }
 443          }
 444          return $warnings;
 445      }
 446  
 447      /**
 448       * Returns description of update_notes result value.
 449       *
 450       * @return external_description
 451       * @since Moodle 2.5
 452       */
 453      public static function update_notes_returns() {
 454          return new external_warnings('item is always \'note\'',
 455                              'When errorcode is savedfailed the note could not be modified.' .
 456                              'When errorcode is badparam, an incorrect parameter was provided.' .
 457                              'When errorcode is badid, the note does not exist',
 458                              'errorcode can be badparam (incorrect parameter), savedfailed (could not be modified), or badid (note does not exist)');
 459      }
 460  
 461      /**
 462       * Returns description of method parameters
 463       *
 464       * @return external_function_parameters
 465       * @since Moodle 2.9
 466       */
 467      public static function get_course_notes_parameters() {
 468          return new external_function_parameters(
 469              array(
 470                  'courseid' => new external_value(PARAM_INT, 'course id, 0 for SITE'),
 471                  'userid'   => new external_value(PARAM_INT, 'user id', VALUE_DEFAULT, 0),
 472              )
 473          );
 474      }
 475  
 476      /**
 477       * Create a notes list
 478       *
 479       * @param int $courseid ID of the Course
 480       * @param stdClass $context context object
 481       * @param int $userid ID of the User
 482       * @param int $state
 483       * @param int $author
 484       * @return array of notes
 485       * @since Moodle 2.9
 486       */
 487      protected static function create_note_list($courseid, $context, $userid, $state, $author = 0) {
 488          $results = array();
 489          $notes = note_list($courseid, $userid, $state, $author);
 490          foreach ($notes as $key => $note) {
 491              $note = (array)$note;
 492              list($note['content'], $note['format']) = external_format_text($note['content'],
 493                                                                             $note['format'],
 494                                                                             $context->id,
 495                                                                             '',
 496                                                                             '',
 497                                                                             0);
 498              $results[$key] = $note;
 499          }
 500          return $results;
 501      }
 502  
 503      /**
 504       * Get a list of course notes
 505       *
 506       * @param int $courseid ID of the Course
 507       * @param int $userid ID of the User
 508       * @return array of site, course and personal notes and warnings
 509       * @since Moodle 2.9
 510       * @throws moodle_exception
 511       */
 512      public static function get_course_notes($courseid, $userid = 0) {
 513          global $CFG, $USER;
 514  
 515          if (empty($CFG->enablenotes)) {
 516              throw new moodle_exception('notesdisabled', 'notes');
 517          }
 518  
 519          $warnings = array();
 520          $arrayparams = array(
 521              'courseid' => $courseid,
 522              'userid'   => $userid,
 523          );
 524          $params = self::validate_parameters(self::get_course_notes_parameters(), $arrayparams);
 525  
 526          if (empty($params['courseid'])) {
 527              $params['courseid'] = SITEID;
 528          }
 529          $user = null;
 530          if (!empty($params['userid'])) {
 531              $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
 532              core_user::require_active_user($user);
 533          }
 534  
 535          $course = get_course($params['courseid']);
 536  
 537          $systemcontext = context_system::instance();
 538          $canmanagesystemnotes = has_capability('moodle/notes:manage', $systemcontext);
 539  
 540          if ($course->id == SITEID) {
 541              $context = $systemcontext;
 542              $canmanagecoursenotes = $canmanagesystemnotes;
 543          } else {
 544              $context = context_course::instance($course->id);
 545              $canmanagecoursenotes = has_capability('moodle/notes:manage', $context);
 546          }
 547          self::validate_context($context);
 548  
 549          $sitenotes = array();
 550          $coursenotes = array();
 551          $personalnotes = array();
 552  
 553          if ($course->id != SITEID) {
 554  
 555              require_capability('moodle/notes:view', $context);
 556              $sitenotes = self::create_note_list(0, $systemcontext, $params['userid'], NOTES_STATE_SITE);
 557              $coursenotes = self::create_note_list($course->id, $context, $params['userid'], NOTES_STATE_PUBLIC);
 558              $personalnotes = self::create_note_list($course->id, $context, $params['userid'], NOTES_STATE_DRAFT,
 559                                                          $USER->id);
 560          } else {
 561              if (has_capability('moodle/notes:view', $context)) {
 562                  $sitenotes = self::create_note_list(0, $context, $params['userid'], NOTES_STATE_SITE);
 563              }
 564              // It returns notes only for a specific user!
 565              if (!empty($user)) {
 566                  $usercourses = enrol_get_users_courses($user->id, true);
 567                  foreach ($usercourses as $c) {
 568                      // All notes at course level, only if we have capability on every course.
 569                      if (has_capability('moodle/notes:view', context_course::instance($c->id))) {
 570                          $coursenotes += self::create_note_list($c->id, $context, $params['userid'], NOTES_STATE_PUBLIC);
 571                      }
 572                  }
 573              }
 574          }
 575  
 576          $results = array(
 577              'sitenotes'     => $sitenotes,
 578              'coursenotes'   => $coursenotes,
 579              'personalnotes' => $personalnotes,
 580              'canmanagesystemnotes' => $canmanagesystemnotes,
 581              'canmanagecoursenotes' => $canmanagecoursenotes,
 582              'warnings'      => $warnings
 583          );
 584          return $results;
 585  
 586      }
 587  
 588      /**
 589       * Returns array of note structure
 590       *
 591       * @return external_description
 592       * @since Moodle 2.9
 593       */
 594      protected static function get_note_structure() {
 595          return array(
 596                       'id'           => new external_value(PARAM_INT, 'id of this note'),
 597                       'courseid'     => new external_value(PARAM_INT, 'id of the course'),
 598                       'userid'       => new external_value(PARAM_INT, 'user id'),
 599                       'content'      => new external_value(PARAM_RAW, 'the content text formated'),
 600                       'format'       => new external_format_value('content'),
 601                       'created'      => new external_value(PARAM_INT, 'time created (timestamp)'),
 602                       'lastmodified' => new external_value(PARAM_INT, 'time of last modification (timestamp)'),
 603                       'usermodified' => new external_value(PARAM_INT, 'user id of the creator of this note'),
 604                       'publishstate' => new external_value(PARAM_ALPHA, "state of the note (i.e. draft, public, site) ")
 605          );
 606      }
 607  
 608      /**
 609       * Returns description of method result value
 610       *
 611       * @return external_description
 612       * @since Moodle 2.9
 613       */
 614      public static function get_course_notes_returns() {
 615          return new external_single_structure(
 616              array(
 617                  'sitenotes' => new external_multiple_structure(
 618                      new external_single_structure(self::get_note_structure() , ''), 'site notes', VALUE_OPTIONAL
 619                  ),
 620                  'coursenotes' => new external_multiple_structure(
 621                      new external_single_structure(self::get_note_structure() , ''), 'couse notes', VALUE_OPTIONAL
 622                  ),
 623                  'personalnotes' => new external_multiple_structure(
 624                      new external_single_structure(self::get_note_structure() , ''), 'personal notes', VALUE_OPTIONAL
 625                  ),
 626                  'canmanagesystemnotes' => new external_value(PARAM_BOOL, 'Whether the user can manage notes at system level.',
 627                      VALUE_OPTIONAL),
 628                  'canmanagecoursenotes' => new external_value(PARAM_BOOL, 'Whether the user can manage notes at the given course.',
 629                      VALUE_OPTIONAL),
 630                  'warnings' => new external_warnings()
 631              ), 'notes'
 632          );
 633      }
 634  
 635      /**
 636       * Returns description of method parameters
 637       *
 638       * @return external_function_parameters
 639       * @since Moodle 2.9
 640       */
 641      public static function view_notes_parameters() {
 642          return new external_function_parameters(
 643              array(
 644                  'courseid' => new external_value(PARAM_INT, 'course id, 0 for notes at system level'),
 645                  'userid' => new external_value(PARAM_INT, 'user id, 0 means view all the user notes', VALUE_DEFAULT, 0)
 646              )
 647          );
 648      }
 649  
 650      /**
 651       * Simulates the web interface view of notes/index.php: trigger events
 652       *
 653       * @param int $courseid id of the course
 654       * @param int $userid id of the user
 655       * @return array of warnings and status result
 656       * @since Moodle 2.9
 657       * @throws moodle_exception
 658       */
 659      public static function view_notes($courseid, $userid = 0) {
 660          global $CFG;
 661          require_once($CFG->dirroot . "/notes/lib.php");
 662  
 663          if (empty($CFG->enablenotes)) {
 664              throw new moodle_exception('notesdisabled', 'notes');
 665          }
 666  
 667          $warnings = array();
 668          $arrayparams = array(
 669              'courseid' => $courseid,
 670              'userid' => $userid
 671          );
 672          $params = self::validate_parameters(self::view_notes_parameters(), $arrayparams);
 673  
 674          if (empty($params['courseid'])) {
 675              $params['courseid'] = SITEID;
 676          }
 677  
 678          $course = get_course($params['courseid']);
 679  
 680          if ($course->id == SITEID) {
 681              $context = context_system::instance();
 682          } else {
 683              $context = context_course::instance($course->id);
 684          }
 685  
 686          // First of all, validate the context before do further permission checks.
 687          self::validate_context($context);
 688          require_capability('moodle/notes:view', $context);
 689  
 690          if (!empty($params['userid'])) {
 691              $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
 692              core_user::require_active_user($user);
 693  
 694              if ($course->id != SITEID and !can_access_course($course, $user, '', true)) {
 695                  throw new moodle_exception('notenrolledprofile');
 696              }
 697          }
 698  
 699          note_view($context, $params['userid']);
 700  
 701          $result = array();
 702          $result['status'] = true;
 703          $result['warnings'] = $warnings;
 704          return $result;
 705  
 706      }
 707  
 708      /**
 709       * Returns description of method result value
 710       *
 711       * @return external_description
 712       * @since Moodle 2.9
 713       */
 714      public static function view_notes_returns() {
 715          return new external_single_structure(
 716              array(
 717                  'status' => new external_value(PARAM_BOOL, 'status: true if success'),
 718                  'warnings' => new external_warnings()
 719              )
 720          );
 721      }
 722  
 723  }