diff options
Diffstat (limited to 'lib/public/Calendar')
32 files changed, 780 insertions, 345 deletions
diff --git a/lib/public/Calendar/BackendTemporarilyUnavailableException.php b/lib/public/Calendar/BackendTemporarilyUnavailableException.php index 5485c9e9e4e..c2bbb1417ee 100644 --- a/lib/public/Calendar/BackendTemporarilyUnavailableException.php +++ b/lib/public/Calendar/BackendTemporarilyUnavailableException.php @@ -1,25 +1,8 @@ <?php + /** - * @copyright 2018, Georg Ehrke <oc.list@georgehrke.com> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Georg Ehrke <oc.list@georgehrke.com> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Calendar; diff --git a/lib/public/Calendar/CalendarEventStatus.php b/lib/public/Calendar/CalendarEventStatus.php new file mode 100644 index 00000000000..fd735150578 --- /dev/null +++ b/lib/public/Calendar/CalendarEventStatus.php @@ -0,0 +1,17 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Calendar; + +use OCP\AppFramework\Attribute\Listenable; + +#[Listenable(since: '32.0.0')] +enum CalendarEventStatus: string { + case TENTATIVE = 'TENTATIVE'; + case CONFIRMED = 'CONFIRMED'; + case CANCELLED = 'CANCELLED'; +}; diff --git a/lib/public/Calendar/CalendarExportOptions.php b/lib/public/Calendar/CalendarExportOptions.php new file mode 100644 index 00000000000..bf21dd85ae4 --- /dev/null +++ b/lib/public/Calendar/CalendarExportOptions.php @@ -0,0 +1,68 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Calendar; + +/** + * Calendar Export Options + * + * @since 32.0.0 + */ +final class CalendarExportOptions { + + /** @var 'ical'|'jcal'|'xcal' */ + private string $format = 'ical'; + private ?string $rangeStart = null; + private ?int $rangeCount = null; + + /** + * Gets the export format + * + * @return 'ical'|'jcal'|'xcal' (defaults to ical) + */ + public function getFormat(): string { + return $this->format; + } + + /** + * Sets the export format + * + * @param 'ical'|'jcal'|'xcal' $format + */ + public function setFormat(string $format): void { + $this->format = $format; + } + + /** + * Gets the start of the range to export + */ + public function getRangeStart(): ?string { + return $this->rangeStart; + } + + /** + * Sets the start of the range to export + */ + public function setRangeStart(?string $rangeStart): void { + $this->rangeStart = $rangeStart; + } + + /** + * Gets the number of objects to export + */ + public function getRangeCount(): ?int { + return $this->rangeCount; + } + + /** + * Sets the number of objects to export + */ + public function setRangeCount(?int $rangeCount): void { + $this->rangeCount = $rangeCount; + } +} diff --git a/lib/public/Calendar/Events/AbstractCalendarObjectEvent.php b/lib/public/Calendar/Events/AbstractCalendarObjectEvent.php new file mode 100644 index 00000000000..111ed096f78 --- /dev/null +++ b/lib/public/Calendar/Events/AbstractCalendarObjectEvent.php @@ -0,0 +1,79 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Calendar\Events; + +use OCP\EventDispatcher\Event; +use OCP\EventDispatcher\IWebhookCompatibleEvent; + +/** + * @since 32.0.0 + */ +abstract class AbstractCalendarObjectEvent extends Event implements IWebhookCompatibleEvent { + + /** + * @param int $calendarId + * @param array $calendarData + * @param array $shares + * @param array $objectData + * @since 32.0.0 + */ + public function __construct( + private int $calendarId, + private array $calendarData, + private array $shares, + private array $objectData, + ) { + parent::__construct(); + } + + /** + * @return int + * @since 32.0.0 + */ + public function getCalendarId(): int { + return $this->calendarId; + } + + /** + * @return array + * @since 32.0.0 + */ + public function getCalendarData(): array { + return $this->calendarData; + } + + /** + * @return array + * @since 32.0.0 + */ + public function getShares(): array { + return $this->shares; + } + + /** + * @return array + * @since 32.0.0 + */ + public function getObjectData(): array { + return $this->objectData; + } + + /** + * @return array + * @since 32.0.0 + */ + public function getWebhookSerializable(): array { + return [ + 'calendarId' => $this->getCalendarId(), + 'calendarData' => $this->getCalendarData(), + 'shares' => $this->getShares(), + 'objectData' => $this->getObjectData(), + ]; + } +} diff --git a/lib/public/Calendar/Events/CalendarObjectCreatedEvent.php b/lib/public/Calendar/Events/CalendarObjectCreatedEvent.php new file mode 100644 index 00000000000..a4d0f40ec55 --- /dev/null +++ b/lib/public/Calendar/Events/CalendarObjectCreatedEvent.php @@ -0,0 +1,15 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Calendar\Events; + +/** + * @since 32.0.0 + */ +class CalendarObjectCreatedEvent extends AbstractCalendarObjectEvent { +} diff --git a/lib/public/Calendar/Events/CalendarObjectDeletedEvent.php b/lib/public/Calendar/Events/CalendarObjectDeletedEvent.php new file mode 100644 index 00000000000..5466213584e --- /dev/null +++ b/lib/public/Calendar/Events/CalendarObjectDeletedEvent.php @@ -0,0 +1,15 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Calendar\Events; + +/** + * @since 32.0.0 + */ +class CalendarObjectDeletedEvent extends AbstractCalendarObjectEvent { +} diff --git a/lib/public/Calendar/Events/CalendarObjectMovedEvent.php b/lib/public/Calendar/Events/CalendarObjectMovedEvent.php new file mode 100644 index 00000000000..1c7df0e1ed5 --- /dev/null +++ b/lib/public/Calendar/Events/CalendarObjectMovedEvent.php @@ -0,0 +1,104 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Calendar\Events; + +use OCP\EventDispatcher\Event; +use OCP\EventDispatcher\IWebhookCompatibleEvent; + +/** + * @since 32.0.0 + */ +class CalendarObjectMovedEvent extends Event implements IWebhookCompatibleEvent { + /** + * @since 32.0.0 + */ + public function __construct( + private int $sourceCalendarId, + private array $sourceCalendarData, + private int $targetCalendarId, + private array $targetCalendarData, + private array $sourceShares, + private array $targetShares, + private array $objectData, + ) { + parent::__construct(); + } + + /** + * @return int + * @since 32.0.0 + */ + public function getSourceCalendarId(): int { + return $this->sourceCalendarId; + } + + /** + * @return array + * @since 32.0.0 + */ + public function getSourceCalendarData(): array { + return $this->sourceCalendarData; + } + + /** + * @return int + * @since 32.0.0 + */ + public function getTargetCalendarId(): int { + return $this->targetCalendarId; + } + + /** + * @return array + * @since 32.0.0 + */ + public function getTargetCalendarData(): array { + return $this->targetCalendarData; + } + + /** + * @return array + * @since 32.0.0 + */ + public function getSourceShares(): array { + return $this->sourceShares; + } + + /** + * @return array + * @since 32.0.0 + */ + public function getTargetShares(): array { + return $this->targetShares; + } + + /** + * @return array + * @since 32.0.0 + */ + public function getObjectData(): array { + return $this->objectData; + } + + /** + * @return array + * @since 32.0.0 + */ + public function getWebhookSerializable(): array { + return [ + 'sourceCalendarId' => $this->getSourceCalendarId(), + 'sourceCalendarData' => $this->getSourceCalendarData(), + 'targetCalendarId' => $this->getTargetCalendarId(), + 'targetCalendarData' => $this->getTargetCalendarData(), + 'sourceShares' => $this->getSourceShares(), + 'targetShares' => $this->getTargetShares(), + 'objectData' => $this->getObjectData(), + ]; + } +} diff --git a/lib/public/Calendar/Events/CalendarObjectMovedToTrashEvent.php b/lib/public/Calendar/Events/CalendarObjectMovedToTrashEvent.php new file mode 100644 index 00000000000..ffbd7b0375a --- /dev/null +++ b/lib/public/Calendar/Events/CalendarObjectMovedToTrashEvent.php @@ -0,0 +1,15 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Calendar\Events; + +/** + * @since 32.0.0 + */ +class CalendarObjectMovedToTrashEvent extends AbstractCalendarObjectEvent { +} diff --git a/lib/public/Calendar/Events/CalendarObjectRestoredEvent.php b/lib/public/Calendar/Events/CalendarObjectRestoredEvent.php new file mode 100644 index 00000000000..7890e3ca5b3 --- /dev/null +++ b/lib/public/Calendar/Events/CalendarObjectRestoredEvent.php @@ -0,0 +1,15 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Calendar\Events; + +/** + * @since 32.0.0 + */ +class CalendarObjectRestoredEvent extends AbstractCalendarObjectEvent { +} diff --git a/lib/public/Calendar/Events/CalendarObjectUpdatedEvent.php b/lib/public/Calendar/Events/CalendarObjectUpdatedEvent.php new file mode 100644 index 00000000000..c06b2b8198f --- /dev/null +++ b/lib/public/Calendar/Events/CalendarObjectUpdatedEvent.php @@ -0,0 +1,15 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Calendar\Events; + +/** + * @since 32.0.0 + */ +class CalendarObjectUpdatedEvent extends AbstractCalendarObjectEvent { +} diff --git a/lib/public/Calendar/Exceptions/CalendarException.php b/lib/public/Calendar/Exceptions/CalendarException.php index 834dd1a234a..27fea75bf14 100644 --- a/lib/public/Calendar/Exceptions/CalendarException.php +++ b/lib/public/Calendar/Exceptions/CalendarException.php @@ -1,27 +1,10 @@ <?php declare(strict_types=1); - /** - * @copyright 2021 Anna Larch <anna.larch@gmx.net> - * - * @author Anna Larch <anna.larch@gmx.net> - * - * This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE - * License as published by the Free Software Foundation; either - * version 3 of the License, or any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU AFFERO GENERAL PUBLIC LICENSE for more details. - * - * You should have received a copy of the GNU Affero General Public - * License along with this library. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ - namespace OCP\Calendar\Exceptions; use Exception; diff --git a/lib/public/Calendar/IAvailabilityResult.php b/lib/public/Calendar/IAvailabilityResult.php new file mode 100644 index 00000000000..d437a5da047 --- /dev/null +++ b/lib/public/Calendar/IAvailabilityResult.php @@ -0,0 +1,32 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Calendar; + +/** + * DTO for the availability check results. + * Holds information about whether an attendee is available or not during the request time slot. + * + * @since 31.0.0 + */ +interface IAvailabilityResult { + /** + * Get the attendee's email address. + * + * @since 31.0.0 + */ + public function getAttendeeEmail(): string; + + /** + * Whether the attendee is available during the requested time slot. + * + * @since 31.0.0 + */ + public function isAvailable(): bool; +} diff --git a/lib/public/Calendar/ICalendar.php b/lib/public/Calendar/ICalendar.php index c6037690f65..50152d1240b 100644 --- a/lib/public/Calendar/ICalendar.php +++ b/lib/public/Calendar/ICalendar.php @@ -3,33 +3,23 @@ declare(strict_types=1); /** - * @copyright 2017, Georg Ehrke <oc.list@georgehrke.com> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Georg Ehrke <oc.list@georgehrke.com> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Calendar; +use DateTimeInterface; + /** * Interface ICalendar * * @since 13.0.0 + * + * @psalm-type CalendarSearchOptions = array{ + * timerange?: array{start?: DateTimeInterface, end?: DateTimeInterface}, + * uid?: string, + * types?: string[], + * } */ interface ICalendar { /** @@ -59,25 +49,76 @@ interface ICalendar { public function getDisplayColor(): ?string; /** - * @param string $pattern which should match within the $searchProperties - * @param array $searchProperties defines the properties within the query pattern should match - * @param array $options - optional parameters: - * ['timerange' => ['start' => new DateTime(...), 'end' => new DateTime(...)]] - * @param int|null $limit - limit number of search results - * @param int|null $offset - offset for paging of search results - * @return array an array of events/journals/todos which are arrays of key-value-pairs + * Search the current calendar for matching events. + * + * This method searches for events in the calendar that match a given pattern within specified properties. + * The search is case-insensitive. It supports optional parameters such as a time range, limit, and offset. + * The results are sorted by start date, with the closest events appearing first. + * + * @param string $pattern A string to search for within the events. The search is done case-insensitive. + * @param array $searchProperties Defines the properties within which the pattern should match. + * @param array $options Optional parameters for the search: + * - 'timerange' element that can have 'start' (DateTimeInterface), 'end' (DateTimeInterface), or both. + * - 'uid' element to look for events with a given uid. + * - 'types' element to only return events for a given type (e.g. VEVENT or VTODO) + * @psalm-param CalendarSearchOptions $options + * @param int|null $limit Limit the number of search results. + * @param int|null $offset For paging of search results. + * @return array An array of events/journals/todos which are arrays of key-value-pairs. The events are sorted by start date (closest first, furthest last). + * + * Implementation Details: + * + * An event can consist of many sub-events, typically the case for events with recurrence rules. On a database level, + * there's only one event stored (with a matching first occurrence and last occurrence timestamp). Expanding an event + * into sub-events is done on the backend level. Using limit, offset, and timerange comes with some drawbacks. + * When asking the database for events, the result is ordered by the primary key to guarantee a stable order. + * After expanding the events into sub-events, they are sorted by the date (closest to furthest). + * + * Usage Examples: + * + * 1) Find 7 events within the next two weeks: + * + * $dateTime = (new DateTimeImmutable())->setTimestamp($this->timeFactory->getTime()); + * $inTwoWeeks = $dateTime->add(new DateInterval('P14D')); + * + * $calendar->search( + * '', + * [], + * ['timerange' => ['start' => $dateTime, 'end' => $inTwoWeeks]], + * 7 + * ); + * + * Note: When combining timerange and limit, it's possible that the expected outcome is not in the order you would expect. + * + * Example: Create 7 events for tomorrow, starting from 11:00, 30 minutes each. Then create an 8th event for tomorrow at 10:00. + * The above code will list the event at 11:00 first, missing the event at 10:00. The reason is the ordering by the primary key + * and expanding on the backend level. This is a technical limitation. The easiest workaround is to fetch more events + * than you actually need, with the downside of needing more resources. + * + * Related: + * - https://github.com/nextcloud/server/pull/45222 + * - https://github.com/nextcloud/server/issues/53002 + * + * 2) Find all events where the location property contains the string 'Berlin': + * + * $calendar->search( + * 'Berlin', + * ['LOCATION'] + * ); + * * @since 13.0.0 */ public function search(string $pattern, array $searchProperties = [], array $options = [], ?int $limit = null, ?int $offset = null): array; /** - * @return int build up using \OCP\Constants + * @return int build up using {@see \OCP\Constants} * @since 13.0.0 */ public function getPermissions(): int; /** - * Whether the calendar is deleted + * Indicates whether the calendar is in the trash bin + * * @since 26.0.0 */ public function isDeleted(): bool; diff --git a/lib/public/Calendar/ICalendarEventBuilder.php b/lib/public/Calendar/ICalendarEventBuilder.php new file mode 100644 index 00000000000..c99dc60cc8c --- /dev/null +++ b/lib/public/Calendar/ICalendarEventBuilder.php @@ -0,0 +1,117 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\Calendar; + +use DateTimeInterface; +use InvalidArgumentException; +use OCP\Calendar\Exceptions\CalendarException; + +/** + * The calendar event builder can be used to conveniently build a calendar event and then serialize + * it to a ICS string. The ICS string can be submitted to calendar instances implementing the + * {@see \OCP\Calendar\ICreateFromString} interface. + * + * Also note this class can not be injected directly with dependency injection. + * Instead, inject {@see \OCP\Calendar\IManager} and use + * {@see \OCP\Calendar\IManager::createEventBuilder()} afterwards. + * + * All setters return self to allow chaining method calls. + * + * @since 31.0.0 + */ +interface ICalendarEventBuilder { + /** + * Set the start date, time and time zone. + * This property is required! + * + * @since 31.0.0 + */ + public function setStartDate(DateTimeInterface $start): self; + + /** + * Set the end date, time and time zone. + * This property is required! + * + * @since 31.0.0 + */ + public function setEndDate(DateTimeInterface $end): self; + + /** + * Set the event summary or title. + * This property is required! + * + * @since 31.0.0 + */ + public function setSummary(string $summary): self; + + /** + * Set the event description. + * + * @since 31.0.0 + */ + public function setDescription(string $description): self; + + /** + * Set the event location. It can either be a physical address or a URL. + * + * @since 31.0.0 + */ + public function setLocation(string $location): self; + + /** + * Set the event status. + * + * @since 32.0.0 + */ + public function setStatus(CalendarEventStatus $status): static; + + /** + * Set the event organizer. + * This property is required if attendees are added! + * + * The "mailto:" prefix is optional and will be added automatically if it is missing. + * + * @since 31.0.0 + */ + public function setOrganizer(string $email, ?string $commonName = null): self; + + /** + * Add a new attendee to the event. + * Adding at least one attendee requires also setting the organizer! + * + * The "mailto:" prefix is optional and will be added automatically if it is missing. + * + * @since 31.0.0 + */ + public function addAttendee(string $email, ?string $commonName = null): self; + + /** + * Serialize the built event to an ICS string if all required properties set. + * + * @since 31.0.0 + * + * @return string The serialized ICS string + * + * @throws InvalidArgumentException If required properties were not set + */ + public function toIcs(): string; + + /** + * Create the event in the given calendar. + * + * @since 31.0.0 + * + * @return string The filename of the created event + * + * @throws InvalidArgumentException If required properties were not set + * @throws CalendarException If writing the event to the calendar fails + */ + public function createInCalendar(ICreateFromString $calendar): string; +} diff --git a/lib/public/Calendar/ICalendarExport.php b/lib/public/Calendar/ICalendarExport.php new file mode 100644 index 00000000000..d884c104a4a --- /dev/null +++ b/lib/public/Calendar/ICalendarExport.php @@ -0,0 +1,31 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Calendar; + +use Generator; + +/** + * ICalendar Interface Extension to export data + * + * @since 32.0.0 + */ +interface ICalendarExport { + + /** + * Export objects + * + * @since 32.0.0 + * + * @param CalendarExportOptions|null $options + * + * @return Generator<\Sabre\VObject\Component\VCalendar> + */ + public function export(?CalendarExportOptions $options): Generator; + +} diff --git a/lib/public/Calendar/ICalendarIsEnabled.php b/lib/public/Calendar/ICalendarIsEnabled.php new file mode 100644 index 00000000000..6bcb487e3dc --- /dev/null +++ b/lib/public/Calendar/ICalendarIsEnabled.php @@ -0,0 +1,24 @@ +<?php + +declare(strict_types=1); +/** + * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Calendar; + +/** + * ICalendar Interface Extension + * + * @since 32.0.0 + */ +interface ICalendarIsEnabled { + + /** + * Indicates whether the calendar is enabled + * + * @since 32.0.0 + */ + public function isEnabled(): bool; + +} diff --git a/lib/public/Calendar/ICalendarIsShared.php b/lib/public/Calendar/ICalendarIsShared.php new file mode 100644 index 00000000000..6f63c6eefd0 --- /dev/null +++ b/lib/public/Calendar/ICalendarIsShared.php @@ -0,0 +1,25 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Calendar; + +/** + * ICalendar Interface Extension + * + * @since 31.0.0 + */ +interface ICalendarIsShared { + + /** + * Indicates whether the calendar is shared with the current user + * + * @since 31.0.0 + */ + public function isShared(): bool; + +} diff --git a/lib/public/Calendar/ICalendarIsWritable.php b/lib/public/Calendar/ICalendarIsWritable.php new file mode 100644 index 00000000000..5bf08a25cdc --- /dev/null +++ b/lib/public/Calendar/ICalendarIsWritable.php @@ -0,0 +1,25 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ +namespace OCP\Calendar; + +/** + * ICalendar Interface Extension + * + * @since 31.0.0 + */ +interface ICalendarIsWritable { + + /** + * Indicates whether the calendar can be modified + * + * @since 31.0.0 + */ + public function isWritable(): bool; + +} diff --git a/lib/public/Calendar/ICalendarProvider.php b/lib/public/Calendar/ICalendarProvider.php index 99b199c1518..95090b1c377 100644 --- a/lib/public/Calendar/ICalendarProvider.php +++ b/lib/public/Calendar/ICalendarProvider.php @@ -3,27 +3,8 @@ declare(strict_types=1); /** - * @copyright 2021 Anna Larch <anna.larch@gmx.net> - * - * @author Anna Larch <anna.larch@gmx.net> - * - * @license GNU AGPL version 3 or any later version - * - * - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Calendar; diff --git a/lib/public/Calendar/ICalendarQuery.php b/lib/public/Calendar/ICalendarQuery.php index 9151f2b3d47..c927fc42efa 100644 --- a/lib/public/Calendar/ICalendarQuery.php +++ b/lib/public/Calendar/ICalendarQuery.php @@ -3,25 +3,8 @@ declare(strict_types=1); /** - * @copyright 2021 Anna Larch <anna.larch@gmx.net> - * - * @author Anna Larch <anna.larch@gmx.net> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Calendar; diff --git a/lib/public/Calendar/ICreateFromString.php b/lib/public/Calendar/ICreateFromString.php index 9e60f20db4c..2bb0f2ffa20 100644 --- a/lib/public/Calendar/ICreateFromString.php +++ b/lib/public/Calendar/ICreateFromString.php @@ -2,25 +2,8 @@ declare(strict_types=1); /** - * @copyright 2021 Anna Larch <anna.larch@gmx.net> - * - * @author Anna Larch <anna.larch@gmx.net> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Calendar; @@ -34,9 +17,31 @@ use OCP\Calendar\Exceptions\CalendarException; */ interface ICreateFromString extends ICalendar { /** - * @since 23.0.0 + * Create an event in this calendar from an ICS string. + * + * @param string $name the file name - needs to contain the .ics ending + * @param string $calendarData a string containing a valid VEVENT ics * * @throws CalendarException + * + * @since 23.0.0 + * */ public function createFromString(string $name, string $calendarData): void; + + /** + * Create an event in this calendar from an ICS string using a minimal CalDAV server. + * Usually, the createFromString() method should be preferred. + * + * However, in some cases it is useful to not set up a full CalDAV server. + * Missing features include no iMIP plugin, no invitation emails amongst others. + * + * @param string $name the file name - needs to contain the .ics ending + * @param string $calendarData a string containing a valid VEVENT ics + * + * @throws CalendarException + * + * @since 32.0.0 + */ + public function createFromStringMinimal(string $name, string $calendarData): void; } diff --git a/lib/public/Calendar/IHandleImipMessage.php b/lib/public/Calendar/IHandleImipMessage.php index e3848d6a859..27190f93f24 100644 --- a/lib/public/Calendar/IHandleImipMessage.php +++ b/lib/public/Calendar/IHandleImipMessage.php @@ -2,25 +2,8 @@ declare(strict_types=1); /** - * @copyright 2022 Anna Larch <anna.larch@gmx.net> - * - * @author Anna Larch <anna.larch@gmx.net> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Calendar; @@ -41,7 +24,7 @@ interface IHandleImipMessage extends ICalendar { * * @since 26.0.0 * - * @throws CalendarException on validation failure or calendar write error + * @throws CalendarException on validation failure or calendar write error */ public function handleIMipMessage(string $name, string $calendarData): void; } diff --git a/lib/public/Calendar/IManager.php b/lib/public/Calendar/IManager.php index bd23e67bebc..124dc65f5f6 100644 --- a/lib/public/Calendar/IManager.php +++ b/lib/public/Calendar/IManager.php @@ -3,30 +3,14 @@ declare(strict_types=1); /** - * @copyright 2017, Georg Ehrke <oc.list@georgehrke.com> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Georg Ehrke <oc.list@georgehrke.com> - * @author Anna Larch <anna.larch@gmx.net> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Calendar; +use DateTimeInterface; +use OCP\IUser; + /** * This class provides access to the Nextcloud CalDAV backend. * Use this class exclusively if you want to access calendars. @@ -65,7 +49,7 @@ interface IManager { * @param string $pattern which should match within the $searchProperties * @param array $searchProperties defines the properties within the query pattern should match * @param array $options - optional parameters: - * ['timerange' => ['start' => new DateTime(...), 'end' => new DateTime(...)]] + * ['timerange' => ['start' => new DateTime(...), 'end' => new DateTime(...)]] * @param integer|null $limit - limit number of search results * @param integer|null $offset - offset for paging of search results * @return array an array of events/journals/todos which are arrays of arrays of key-value-pairs @@ -157,6 +141,13 @@ interface IManager { public function newQuery(string $principalUri) : ICalendarQuery; /** + * Handle a iMip REQUEST message + * + * @since 31.0.0 + */ + public function handleIMipRequest(string $principalUri, string $sender, string $recipient, string $calendarData): bool; + + /** * Handle a iMip REPLY message * * @since 25.0.0 @@ -169,4 +160,28 @@ interface IManager { * @since 25.0.0 */ public function handleIMipCancel(string $principalUri, string $sender, ?string $replyTo, string $recipient, string $calendarData): bool; + + /** + * Create a new event builder instance. Please have a look at its documentation and the + * \OCP\Calendar\ICreateFromString interface on how to use it. + * + * @since 31.0.0 + */ + public function createEventBuilder(): ICalendarEventBuilder; + + /** + * Check the availability of the given organizer and attendees in the given time range. + * + * @since 31.0.0 + * + * @param IUser $organizer The organizing user from whose perspective to do the availability check. + * @param string[] $attendees Email addresses of attendees to check for (with or without a "mailto:" prefix). Only users on this instance can be checked. The rest will be silently ignored. + * @return IAvailabilityResult[] Availabilities of the organizer and all attendees which are also users on this instance. As such, the array might not contain an entry for each given attendee. + */ + public function checkAvailability( + DateTimeInterface $start, + DateTimeInterface $end, + IUser $organizer, + array $attendees, + ): array; } diff --git a/lib/public/Calendar/IMetadataProvider.php b/lib/public/Calendar/IMetadataProvider.php index 31f888e45d7..acacf7efdaf 100644 --- a/lib/public/Calendar/IMetadataProvider.php +++ b/lib/public/Calendar/IMetadataProvider.php @@ -1,24 +1,8 @@ <?php + /** - * @copyright 2019, Georg Ehrke <oc.list@georgehrke.com> - * - * @author Georg Ehrke <oc.list@georgehrke.com> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Calendar; diff --git a/lib/public/Calendar/Resource/IBackend.php b/lib/public/Calendar/Resource/IBackend.php index 95ff958be86..23d37c102f2 100644 --- a/lib/public/Calendar/Resource/IBackend.php +++ b/lib/public/Calendar/Resource/IBackend.php @@ -1,25 +1,8 @@ <?php + /** - * @copyright 2018, Georg Ehrke <oc.list@georgehrke.com> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Georg Ehrke <oc.list@georgehrke.com> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Calendar\Resource; diff --git a/lib/public/Calendar/Resource/IManager.php b/lib/public/Calendar/Resource/IManager.php index 00f94bcc548..d3a6b2449e3 100644 --- a/lib/public/Calendar/Resource/IManager.php +++ b/lib/public/Calendar/Resource/IManager.php @@ -3,31 +3,13 @@ declare(strict_types=1); /** - * @copyright 2018, Georg Ehrke <oc.list@georgehrke.com> - * - * @author Georg Ehrke <oc.list@georgehrke.com> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Calendar\Resource; /** * @since 14.0.0 - * @deprecated 24.0.0 */ interface IManager { /** @@ -72,4 +54,11 @@ interface IManager { * @deprecated 24.0.0 */ public function clear(); + + /** + * Update all resources from all backends right now. + * + * @since 30.0.0 + */ + public function update(): void; } diff --git a/lib/public/Calendar/Resource/IResource.php b/lib/public/Calendar/Resource/IResource.php index d419b9f2abc..15abe4e2d0f 100644 --- a/lib/public/Calendar/Resource/IResource.php +++ b/lib/public/Calendar/Resource/IResource.php @@ -1,24 +1,8 @@ <?php + /** - * @copyright 2018, Georg Ehrke <oc.list@georgehrke.com> - * - * @author Georg Ehrke <oc.list@georgehrke.com> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Calendar\Resource; diff --git a/lib/public/Calendar/Resource/IResourceMetadata.php b/lib/public/Calendar/Resource/IResourceMetadata.php index f97f684e8af..29f628d6f7f 100644 --- a/lib/public/Calendar/Resource/IResourceMetadata.php +++ b/lib/public/Calendar/Resource/IResourceMetadata.php @@ -1,24 +1,8 @@ <?php + /** - * @copyright 2019, Georg Ehrke <oc.list@georgehrke.com> - * - * @author Georg Ehrke <oc.list@georgehrke.com> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Calendar\Resource; diff --git a/lib/public/Calendar/Room/IBackend.php b/lib/public/Calendar/Room/IBackend.php index 211780ef57c..c99f5fbdb72 100644 --- a/lib/public/Calendar/Room/IBackend.php +++ b/lib/public/Calendar/Room/IBackend.php @@ -1,25 +1,8 @@ <?php + /** - * @copyright 2018, Georg Ehrke <oc.list@georgehrke.com> - * - * @author Christoph Wurst <christoph@winzerhof-wurst.at> - * @author Georg Ehrke <oc.list@georgehrke.com> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Calendar\Room; diff --git a/lib/public/Calendar/Room/IManager.php b/lib/public/Calendar/Room/IManager.php index 3095ddc118a..b1136ede3fe 100644 --- a/lib/public/Calendar/Room/IManager.php +++ b/lib/public/Calendar/Room/IManager.php @@ -3,31 +3,13 @@ declare(strict_types=1); /** - * @copyright 2018, Georg Ehrke <oc.list@georgehrke.com> - * - * @author Georg Ehrke <oc.list@georgehrke.com> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Calendar\Room; /** * @since 14.0.0 - * @deprecated 24.0.0 */ interface IManager { /** @@ -72,4 +54,11 @@ interface IManager { * @deprecated 24.0.0 */ public function clear(); + + /** + * Update all rooms from all backends right now. + * + * @since 30.0.0 + */ + public function update(): void; } diff --git a/lib/public/Calendar/Room/IRoom.php b/lib/public/Calendar/Room/IRoom.php index e29f658899e..526e65b8f5f 100644 --- a/lib/public/Calendar/Room/IRoom.php +++ b/lib/public/Calendar/Room/IRoom.php @@ -1,24 +1,8 @@ <?php + /** - * @copyright 2018, Georg Ehrke <oc.list@georgehrke.com> - * - * @author Georg Ehrke <oc.list@georgehrke.com> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2018 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Calendar\Room; diff --git a/lib/public/Calendar/Room/IRoomMetadata.php b/lib/public/Calendar/Room/IRoomMetadata.php index d28bd9a6e94..15d4b501e12 100644 --- a/lib/public/Calendar/Room/IRoomMetadata.php +++ b/lib/public/Calendar/Room/IRoomMetadata.php @@ -1,24 +1,8 @@ <?php + /** - * @copyright 2019, Georg Ehrke <oc.list@georgehrke.com> - * - * @author Georg Ehrke <oc.list@georgehrke.com> - * - * @license GNU AGPL version 3 or any later version - * - * This program is free software: you can redistribute it and/or modify - * it under the terms of the GNU Affero General Public License as - * published by the Free Software Foundation, either version 3 of the - * License, or (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Affero General Public License for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see <http://www.gnu.org/licenses/>. - * + * SPDX-FileCopyrightText: 2019 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later */ namespace OCP\Calendar\Room; |