/**
* Modifies an annotation for a site and returns the modified annotation
* and its ID.
*
* If the current user is not allowed to modify an annotation, an exception
* will be thrown. A user can modify a note if:
* - the user has admin access for the site, OR
* - the user has view access, is not the anonymous user and is the user that
* created the note
*
* @param string $idSite The site ID to add the annotation to.
* @param string $idNote The ID of the note.
* @param string|null $date The date the annotation is attached to. If null, the annotation's
* date is not modified.
* @param string|null $note The text of the annotation. If null, the annotation's text
* is not modified.
* @param string|null $starred Either 0 or 1. Whether the annotation should be starred.
* If null, the annotation is not starred/un-starred.
* @return array Returns an array of two elements. The first element (indexed by
* 'annotation') is the new annotation. The second element (indexed
* by 'idNote' is the new note's ID).
*/
public function save($idSite, $idNote, $date = null, $note = null, $starred = null)
{
$this->checkSingleIdSite($idSite, $extraMessage = "Note: Cannot modify more than one note at a time.");
$this->checkDateIsValid($date, $canBeNull = true);
// get the annotations for the site
$annotations = new AnnotationList($idSite);
// check permissions
$this->checkUserCanModifyOrDelete($idSite, $annotations->get($idSite, $idNote));
// modify the annotation, and save the whole list
$annotations->update($idSite, $idNote, $date, $note, $starred);
$annotations->save($idSite);
return $annotations->get($idSite, $idNote);
}
