Merge pull request #6840 from nextcloud/feature/5282/calendar_api

Calendar API for apps

7 files changed, 357 insertions, 0 deletions

diff --git a/lib/composer/composer/autoload_classmap.php b/lib/composer/composer/autoload_classmap.php
index 863199dfb93..93c139b7bbe 100644
--- a/lib/composer/composer/autoload_classmap.php
+++ b/lib/composer/composer/autoload_classmap.php
@@ -66,6 +66,8 @@ return array(
     'OCP\\BackgroundJob' => $baseDir . '/lib/public/BackgroundJob.php',
     'OCP\\BackgroundJob\\IJob' => $baseDir . '/lib/public/BackgroundJob/IJob.php',
     'OCP\\BackgroundJob\\IJobList' => $baseDir . '/lib/public/BackgroundJob/IJobList.php',
+    'OCP\\Calendar\\ICalendar' => $baseDir . '/lib/public/Calendar/ICalendar.php',
+    'OCP\\Calendar\\IManager' => $baseDir . '/lib/public/Calendar/IManager.php',
     'OCP\\Capabilities\\ICapability' => $baseDir . '/lib/public/Capabilities/ICapability.php',
     'OCP\\Capabilities\\IPublicCapability' => $baseDir . '/lib/public/Capabilities/IPublicCapability.php',
     'OCP\\Collaboration\\AutoComplete\\IManager' => $baseDir . '/lib/public/Collaboration/AutoComplete/IManager.php',
@@ -394,6 +396,7 @@ return array(
     'OC\\BackgroundJob\\TimedJob' => $baseDir . '/lib/private/BackgroundJob/TimedJob.php',
     'OC\\Cache\\CappedMemoryCache' => $baseDir . '/lib/private/Cache/CappedMemoryCache.php',
     'OC\\Cache\\File' => $baseDir . '/lib/private/Cache/File.php',
+    'OC\\Calendar\\Manager' => $baseDir . '/lib/private/Calendar/Manager.php',
     'OC\\CapabilitiesManager' => $baseDir . '/lib/private/CapabilitiesManager.php',
     'OC\\Collaboration\\AutoComplete\\Manager' => $baseDir . '/lib/private/Collaboration/AutoComplete/Manager.php',
     'OC\\Collaboration\\Collaborators\\GroupPlugin' => $baseDir . '/lib/private/Collaboration/Collaborators/GroupPlugin.php',
diff --git a/lib/composer/composer/autoload_static.php b/lib/composer/composer/autoload_static.php
index e52ee329e24..c073d43ca14 100644
--- a/lib/composer/composer/autoload_static.php
+++ b/lib/composer/composer/autoload_static.php
@@ -96,6 +96,8 @@ class ComposerStaticInit53792487c5a8370acc0b06b1a864ff4c
         'OCP\\BackgroundJob' => __DIR__ . '/../../..' . '/lib/public/BackgroundJob.php',
         'OCP\\BackgroundJob\\IJob' => __DIR__ . '/../../..' . '/lib/public/BackgroundJob/IJob.php',
         'OCP\\BackgroundJob\\IJobList' => __DIR__ . '/../../..' . '/lib/public/BackgroundJob/IJobList.php',
+        'OCP\\Calendar\\ICalendar' => __DIR__ . '/../../..' . '/lib/public/Calendar/ICalendar.php',
+        'OCP\\Calendar\\IManager' => __DIR__ . '/../../..' . '/lib/public/Calendar/IManager.php',
         'OCP\\Capabilities\\ICapability' => __DIR__ . '/../../..' . '/lib/public/Capabilities/ICapability.php',
         'OCP\\Capabilities\\IPublicCapability' => __DIR__ . '/../../..' . '/lib/public/Capabilities/IPublicCapability.php',
         'OCP\\Collaboration\\AutoComplete\\IManager' => __DIR__ . '/../../..' . '/lib/public/Collaboration/AutoComplete/IManager.php',
@@ -424,6 +426,7 @@ class ComposerStaticInit53792487c5a8370acc0b06b1a864ff4c
         'OC\\BackgroundJob\\TimedJob' => __DIR__ . '/../../..' . '/lib/private/BackgroundJob/TimedJob.php',
         'OC\\Cache\\CappedMemoryCache' => __DIR__ . '/../../..' . '/lib/private/Cache/CappedMemoryCache.php',
         'OC\\Cache\\File' => __DIR__ . '/../../..' . '/lib/private/Cache/File.php',
+        'OC\\Calendar\\Manager' => __DIR__ . '/../../..' . '/lib/private/Calendar/Manager.php',
         'OC\\CapabilitiesManager' => __DIR__ . '/../../..' . '/lib/private/CapabilitiesManager.php',
         'OC\\Collaboration\\AutoComplete\\Manager' => __DIR__ . '/../../..' . '/lib/private/Collaboration/AutoComplete/Manager.php',
         'OC\\Collaboration\\Collaborators\\GroupPlugin' => __DIR__ . '/../../..' . '/lib/private/Collaboration/Collaborators/GroupPlugin.php',
diff --git a/lib/private/Calendar/Manager.php b/lib/private/Calendar/Manager.php
new file mode 100644
index 00000000000..85d501f8ea0
--- /dev/null
+++ b/lib/private/Calendar/Manager.php
@@ -0,0 +1,140 @@
+<?php
+/**
+ * @copyright 2017, 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/>.
+ *
+ */
+
+namespace OC\Calendar;
+
+use OCP\Calendar\ICalendar;
+
+class Manager implements \OCP\Calendar\IManager {
+
+	/**
+	 * @var ICalendar[] holds all registered calendars
+	 */
+	private $calendars=[];
+
+	/**
+	 * @var \Closure[] to call to load/register calendar providers
+	 */
+	private $calendarLoaders=[];
+
+	/**
+	 * This function is used to search and find objects within the user's calendars.
+	 * In case $pattern is empty all events/journals/todos will be returned.
+	 *
+	 * @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 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
+	 * @since 13.0.0
+	 */
+	public function search($pattern, array $searchProperties=[], array $options=[], $limit=null, $offset=null) {
+		$this->loadCalendars();
+		$result = [];
+		foreach($this->calendars as $calendar) {
+			$r = $calendar->search($pattern, $searchProperties, $options, $limit, $offset);
+			foreach($r as $o) {
+				$o['calendar-key'] = $calendar->getKey();
+				$result[] = $o;
+			}
+		}
+
+		return $result;
+	}
+
+	/**
+	 * Check if calendars are available
+	 *
+	 * @return bool true if enabled, false if not
+	 * @since 13.0.0
+	 */
+	public function isEnabled() {
+		return !empty($this->calendars) || !empty($this->calendarLoaders);
+	}
+
+	/**
+	 * Registers a calendar
+	 *
+	 * @param ICalendar $calendar
+	 * @return void
+	 * @since 13.0.0
+	 */
+	public function registerCalendar(ICalendar $calendar) {
+		$this->calendars[$calendar->getKey()] = $calendar;
+	}
+
+	/**
+	 * Unregisters a calendar
+	 *
+	 * @param ICalendar $calendar
+	 * @return void
+	 * @since 13.0.0
+	 */
+	public function unregisterCalendar(ICalendar $calendar) {
+		unset($this->calendars[$calendar->getKey()]);
+	}
+
+	/**
+	 * In order to improve lazy loading a closure can be registered which will be called in case
+	 * calendars are actually requested
+	 *
+	 * @param \Closure $callable
+	 * @return void
+	 * @since 13.0.0
+	 */
+	public function register(\Closure $callable) {
+		$this->calendarLoaders[] = $callable;
+	}
+
+	/**
+	 * @return ICalendar[]
+	 * @since 13.0.0
+	 */
+	public function getCalendars() {
+		$this->loadCalendars();
+
+		return array_values($this->calendars);
+	}
+
+	/**
+	 * removes all registered calendar instances
+	 * @return void
+	 * @since 13.0.0
+	 */
+	public function clear() {
+		$this->calendars = [];
+		$this->calendarLoaders = [];
+	}
+
+	/**
+	 * loads all calendars
+	 */
+	private function loadCalendars() {
+		foreach($this->calendarLoaders as $callable) {
+			$callable($this);
+		}
+		$this->calendarLoaders = [];
+	}
+}
diff --git a/lib/private/Server.php b/lib/private/Server.php
index 1e3ac3de271..faa0ce2f2ac 100644
--- a/lib/private/Server.php
+++ b/lib/private/Server.php
@@ -153,6 +153,9 @@ class Server extends ServerContainer implements IServerContainer {
 			return $c;
 		});
 
+		$this->registerAlias(\OCP\Calendar\IManager::class, \OC\Calendar\Manager::class);
+		$this->registerAlias('CalendarManager', \OC\Calendar\Manager::class);
+
 		$this->registerAlias(\OCP\Contacts\IManager::class, \OC\ContactsManager::class);
 		$this->registerAlias('ContactsManager', \OCP\Contacts\IManager::class);
 
@@ -1099,6 +1102,13 @@ class Server extends ServerContainer implements IServerContainer {
 	}
 
 	/**
+	 * @return \OCP\Calendar\IManager
+	 */
+	public function getCalendarManager() {
+		return $this->query('CalendarManager');
+	}
+
+	/**
 	 * @return \OCP\Contacts\IManager
 	 */
 	public function getContactsManager() {
diff --git a/lib/public/Calendar/ICalendar.php b/lib/public/Calendar/ICalendar.php
new file mode 100644
index 00000000000..359e40f6f1f
--- /dev/null
+++ b/lib/public/Calendar/ICalendar.php
@@ -0,0 +1,71 @@
+<?php
+/**
+ * @copyright 2017, 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/>.
+ *
+ */
+
+namespace OCP\Calendar;
+
+/**
+ * Interface ICalendar
+ *
+ * @package OCP
+ * @since 13.0.0
+ */
+interface ICalendar {
+
+	/**
+	 * @return string defining the technical unique key
+	 * @since 13.0.0
+	 */
+	public function getKey();
+
+	/**
+	 * In comparison to getKey() this function returns a human readable (maybe translated) name
+	 * @return null|string
+	 * @since 13.0.0
+	 */
+	public function getDisplayName();
+
+	/**
+	 * Calendar color
+	 * @return null|string
+	 * @since 13.0.0
+	 */
+	public function getDisplayColor();
+
+	/**
+	 * @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 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 key-value-pairs
+	 * @since 13.0.0
+	 */
+	public function search($pattern, array $searchProperties=[], array $options=[], $limit=null, $offset=null);
+
+	/**
+	 * @return integer build up using \OCP\Constants
+	 * @since 13.0.0
+	 */
+	public function getPermissions();
+}
diff --git a/lib/public/Calendar/IManager.php b/lib/public/Calendar/IManager.php
new file mode 100644
index 00000000000..05ccd96c414
--- /dev/null
+++ b/lib/public/Calendar/IManager.php
@@ -0,0 +1,121 @@
+<?php
+/**
+ * @copyright 2017, 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/>.
+ *
+ */
+
+namespace OCP\Calendar;
+
+/**
+ * This class provides access to the Nextcloud CalDAV backend.
+ * Use this class exclusively if you want to access calendars.
+ *
+ * Events/Journals/Todos in general will be expressed as an array of key-value-pairs.
+ * The keys will match the property names defined in https://tools.ietf.org/html/rfc5545
+ *
+ * [
+ *   'id' => 123,
+ *   'type' => 'VEVENT',
+ *   'calendar-key' => 42,
+ *   'objects' => [
+ *     [
+ *       'SUMMARY' => ['FooBar', []],
+ *       'DTSTART' => ['20171001T123456', ['TZID' => 'EUROPE/BERLIN']],
+ *       'DURATION' => ['P1D', []],
+ * 	     'ATTENDEE' => [
+ *         ['mailto:bla@blub.com', ['CN' => 'Mr. Bla Blub']]
+ *       ],
+ *       'VALARM' => [
+ * 	       [
+ *           'TRIGGER' => ['19980101T050000Z', ['VALUE' => DATE-TIME]]
+ *         ]
+ *       ]
+ *     ],
+ *   ]
+ * ]
+ *
+ * @since 13.0.0
+ */
+interface IManager {
+
+	/**
+	 * This function is used to search and find objects within the user's calendars.
+	 * In case $pattern is empty all events/journals/todos will be returned.
+	 *
+	 * @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 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
+	 * @since 13.0.0
+	 */
+	public function search($pattern, array $searchProperties=[], array $options=[], $limit=null, $offset=null);
+
+	/**
+	 * Check if calendars are available
+	 *
+	 * @return bool true if enabled, false if not
+	 * @since 13.0.0
+	 */
+	public function isEnabled();
+
+	/**
+	 * Registers a calendar
+	 *
+	 * @param ICalendar $calendar
+	 * @return void
+	 * @since 13.0.0
+	 */
+	public function registerCalendar(ICalendar $calendar);
+
+	/**
+	 * Unregisters a calendar
+	 *
+	 * @param ICalendar $calendar
+	 * @return void
+	 * @since 13.0.0
+	 */
+	public function unregisterCalendar(ICalendar $calendar);
+
+	/**
+	 * In order to improve lazy loading a closure can be registered which will be called in case
+	 * calendars are actually requested
+	 *
+	 * @param \Closure $callable
+	 * @return void
+	 * @since 13.0.0
+	 */
+	public function register(\Closure $callable);
+
+	/**
+	 * @return ICalendar[]
+	 * @since 13.0.0
+	 */
+	public function getCalendars();
+
+	/**
+	 * removes all registered calendar instances
+	 * @return void
+	 * @since 13.0.0
+	 */
+	public function clear();
+}
diff --git a/lib/public/IServerContainer.php b/lib/public/IServerContainer.php
index 13abd0ff43b..8c33a765d5e 100644
--- a/lib/public/IServerContainer.php
+++ b/lib/public/IServerContainer.php
@@ -58,6 +58,15 @@ use Symfony\Component\EventDispatcher\EventDispatcherInterface;
 interface IServerContainer extends IContainer {
 
 	/**
+	 * The calendar manager will act as a broker between consumers for calendar information and
+	 * providers which actual deliver the calendar information.
+	 *
+	 * @return \OCP\Calendar\IManager
+	 * @since 13.0.0
+	 */
+	public function getCalendarManager();
+
+	/**
 	 * The contacts manager will act as a broker between consumers for contacts information and
 	 * providers which actual deliver the contact information.
 	 *