Add Public Calendar Provider

Signed-off-by: Anna Larch <anna@nextcloud.com>
Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>

4 files changed, 159 insertions, 0 deletions

diff --git a/lib/public/Calendar/ICalendar.php b/lib/public/Calendar/ICalendar.php
index ebaa7c50f84..551870de20e 100644
--- a/lib/public/Calendar/ICalendar.php
+++ b/lib/public/Calendar/ICalendar.php
@@ -1,4 +1,7 @@
 <?php
+
+declare(strict_types=1);
+
 /**
  * @copyright 2017, Georg Ehrke <oc.list@georgehrke.com>
  *
diff --git a/lib/public/Calendar/ICalendarProvider.php b/lib/public/Calendar/ICalendarProvider.php
new file mode 100644
index 00000000000..d135910b08c
--- /dev/null
+++ b/lib/public/Calendar/ICalendarProvider.php
@@ -0,0 +1,45 @@
+<?php
+
+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/>.
+ *
+ */
+namespace OCP\Calendar;
+
+/**
+ * This interface defines a lazy loading mechanism for
+ * calendars for Public Consumption
+ *
+ * @since 23.0.0
+ */
+interface ICalendarProvider {
+
+	/**
+	 * @param string $principalUri
+	 * @param string[] $calendarUris
+	 * @return ICalendar[]
+	 * @since 23.0.0
+	 */
+	public function getCalendars(string $principalUri, array $calendarUris = []): array;
+}
diff --git a/lib/public/Calendar/ICalendarQuery.php b/lib/public/Calendar/ICalendarQuery.php
new file mode 100644
index 00000000000..142810d3fb9
--- /dev/null
+++ b/lib/public/Calendar/ICalendarQuery.php
@@ -0,0 +1,82 @@
+<?php
+
+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/>.
+ *
+ */
+namespace OCP\Calendar;
+
+use DateTimeImmutable;
+
+/**
+ * Build a flexible, extendable query to the CalDAV backend
+ *
+ * @since 23.0.0
+ */
+interface ICalendarQuery {
+
+	/**
+	 * Limit the results to the calendar uri(s)
+	 *
+	 * @since 23.0.0
+	 */
+	public function addSearchCalendar(string $calendarUri): void;
+
+	/**
+	 * Search the property values
+	 *
+	 * @since 23.0.0
+	 */
+	public function setSearchPattern(string $pattern): void;
+
+	/**
+	 * Define the property name(s) to search for
+	 *
+	 * @since 23.0.0
+	 */
+	public function addSearchProperty(string $value): void;
+
+	/**
+	 * @since 23.0.0
+	 */
+	public function addType(string $value): void;
+
+	/**
+	 * @since 23.0.0
+	 */
+	public function setTimerangeStart(DateTimeImmutable $startTime): void;
+
+	/**
+	 * @since 23.0.0
+	 */
+	public function setTimerangeEnd(DateTimeImmutable $endTime): void;
+
+	/**
+	 * @since 23.0.0
+	 */
+	public function setLimit(int $limit): void;
+
+	/**
+	 * @since 23.0.0
+	 */
+	public function setOffset(int $offset): void;
+}
diff --git a/lib/public/Calendar/IManager.php b/lib/public/Calendar/IManager.php
index df4c993b2b5..eb4113bba99 100644
--- a/lib/public/Calendar/IManager.php
+++ b/lib/public/Calendar/IManager.php
@@ -1,9 +1,13 @@
 <?php
+
+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
  *
@@ -67,6 +71,7 @@ interface IManager {
 	 * @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
 	 * @since 13.0.0
+	 * @deprecated 23.0.0 use \OCP\Calendar\IManager::searchForPrincipal
 	 */
 	public function search($pattern, array $searchProperties = [], array $options = [], $limit = null, $offset = null);
 
@@ -75,6 +80,7 @@ interface IManager {
 	 *
 	 * @return bool true if enabled, false if not
 	 * @since 13.0.0
+	 * @deprecated 23.0.0
 	 */
 	public function isEnabled();
 
@@ -84,6 +90,7 @@ interface IManager {
 	 * @param ICalendar $calendar
 	 * @return void
 	 * @since 13.0.0
+	 * @deprecated 23.0.0 use \OCP\AppFramework\Bootstrap\IRegistrationContext::registerCalendarProvider
 	 */
 	public function registerCalendar(ICalendar $calendar);
 
@@ -93,6 +100,7 @@ interface IManager {
 	 * @param ICalendar $calendar
 	 * @return void
 	 * @since 13.0.0
+	 * @deprecated 23.0.0
 	 */
 	public function unregisterCalendar(ICalendar $calendar);
 
@@ -103,19 +111,40 @@ interface IManager {
 	 * @param \Closure $callable
 	 * @return void
 	 * @since 13.0.0
+	 * @deprecated 23.0.0 use \OCP\AppFramework\Bootstrap\IRegistrationContext::registerCalendarProvider
 	 */
 	public function register(\Closure $callable);
 
 	/**
 	 * @return ICalendar[]
 	 * @since 13.0.0
+	 * @deprecated 23.0.0
 	 */
 	public function getCalendars();
 
 	/**
 	 * removes all registered calendar instances
+	 *
 	 * @return void
 	 * @since 13.0.0
+	 * @deprecated 23.0.0
 	 */
 	public function clear();
+
+	/**
+	 * Query a principals calendar(s)
+	 *
+	 * @param ICalendarQuery $query
+	 * @return array[]
+	 * @since 23.0.0
+	 */
+	public function searchForPrincipal(ICalendarQuery $query): array;
+
+	/**
+	 * Build a new query for searchForPrincipal
+	 *
+	 * @return ICalendarQuery
+	 * @since 23.0.0
+	 */
+	public function newQuery(string $principalUri) : ICalendarQuery;
 }