232 lines
8.6 KiB
PHP
232 lines
8.6 KiB
PHP
|
<?php
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Every CalDAV backend must at least implement this interface.
|
||
|
|
*
|
||
|
|
* @package Sabre
|
||
|
|
* @subpackage CalDAV
|
||
|
|
* @copyright Copyright (C) 2007-2012 Rooftop Solutions. All rights reserved.
|
||
|
|
* @author Evert Pot (http://www.rooftopsolutions.nl/)
|
||
|
|
* @license http://code.google.com/p/sabredav/wiki/License Modified BSD License
|
||
|
|
*/
|
||
|
|
interface Sabre_CalDAV_Backend_BackendInterface {
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns a list of calendars for a principal.
|
||
|
|
*
|
||
|
|
* Every project is an array with the following keys:
|
||
|
|
* * id, a unique id that will be used by other functions to modify the
|
||
|
|
* calendar. This can be the same as the uri or a database key.
|
||
|
|
* * uri, which the basename of the uri with which the calendar is
|
||
|
|
* accessed.
|
||
|
|
* * principaluri. The owner of the calendar. Almost always the same as
|
||
|
|
* principalUri passed to this method.
|
||
|
|
*
|
||
|
|
* Furthermore it can contain webdav properties in clark notation. A very
|
||
|
|
* common one is '{DAV:}displayname'.
|
||
|
|
*
|
||
|
|
* @param string $principalUri
|
||
|
|
* @return array
|
||
|
|
*/
|
||
|
|
public function getCalendarsForUser($principalUri);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Creates a new calendar for a principal.
|
||
|
|
*
|
||
|
|
* If the creation was a success, an id must be returned that can be used to reference
|
||
|
|
* this calendar in other methods, such as updateCalendar.
|
||
|
|
*
|
||
|
|
* @param string $principalUri
|
||
|
|
* @param string $calendarUri
|
||
|
|
* @param array $properties
|
||
|
|
* @return void
|
||
|
|
*/
|
||
|
|
public function createCalendar($principalUri,$calendarUri,array $properties);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Updates properties for a calendar.
|
||
|
|
*
|
||
|
|
* The mutations array uses the propertyName in clark-notation as key,
|
||
|
|
* and the array value for the property value. In the case a property
|
||
|
|
* should be deleted, the property value will be null.
|
||
|
|
*
|
||
|
|
* This method must be atomic. If one property cannot be changed, the
|
||
|
|
* entire operation must fail.
|
||
|
|
*
|
||
|
|
* If the operation was successful, true can be returned.
|
||
|
|
* If the operation failed, false can be returned.
|
||
|
|
*
|
||
|
|
* Deletion of a non-existent property is always successful.
|
||
|
|
*
|
||
|
|
* Lastly, it is optional to return detailed information about any
|
||
|
|
* failures. In this case an array should be returned with the following
|
||
|
|
* structure:
|
||
|
|
*
|
||
|
|
* array(
|
||
|
|
* 403 => array(
|
||
|
|
* '{DAV:}displayname' => null,
|
||
|
|
* ),
|
||
|
|
* 424 => array(
|
||
|
|
* '{DAV:}owner' => null,
|
||
|
|
* )
|
||
|
|
* )
|
||
|
|
*
|
||
|
|
* In this example it was forbidden to update {DAV:}displayname.
|
||
|
|
* (403 Forbidden), which in turn also caused {DAV:}owner to fail
|
||
|
|
* (424 Failed Dependency) because the request needs to be atomic.
|
||
|
|
*
|
||
|
|
* @param mixed $calendarId
|
||
|
|
* @param array $mutations
|
||
|
|
* @return bool|array
|
||
|
|
*/
|
||
|
|
public function updateCalendar($calendarId, array $mutations);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Delete a calendar and all it's objects
|
||
|
|
*
|
||
|
|
* @param mixed $calendarId
|
||
|
|
* @return void
|
||
|
|
*/
|
||
|
|
public function deleteCalendar($calendarId);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns all calendar objects within a calendar.
|
||
|
|
*
|
||
|
|
* Every item contains an array with the following keys:
|
||
|
|
* * id - unique identifier which will be used for subsequent updates
|
||
|
|
* * calendardata - The iCalendar-compatible calendar data
|
||
|
|
* * uri - a unique key which will be used to construct the uri. This can be any arbitrary string.
|
||
|
|
* * lastmodified - a timestamp of the last modification time
|
||
|
|
* * etag - An arbitrary string, surrounded by double-quotes. (e.g.:
|
||
|
|
* ' "abcdef"')
|
||
|
|
* * calendarid - The calendarid as it was passed to this function.
|
||
|
|
* * size - The size of the calendar objects, in bytes.
|
||
|
|
*
|
||
|
|
* Note that the etag is optional, but it's highly encouraged to return for
|
||
|
|
* speed reasons.
|
||
|
|
*
|
||
|
|
* The calendardata is also optional. If it's not returned
|
||
|
|
* 'getCalendarObject' will be called later, which *is* expected to return
|
||
|
|
* calendardata.
|
||
|
|
*
|
||
|
|
* If neither etag or size are specified, the calendardata will be
|
||
|
|
* used/fetched to determine these numbers. If both are specified the
|
||
|
|
* amount of times this is needed is reduced by a great degree.
|
||
|
|
*
|
||
|
|
* @param mixed $calendarId
|
||
|
|
* @return array
|
||
|
|
*/
|
||
|
|
public function getCalendarObjects($calendarId);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns information from a single calendar object, based on it's object
|
||
|
|
* uri.
|
||
|
|
*
|
||
|
|
* The returned array must have the same keys as getCalendarObjects. The
|
||
|
|
* 'calendardata' object is required here though, while it's not required
|
||
|
|
* for getCalendarObjects.
|
||
|
|
*
|
||
|
|
* @param mixed $calendarId
|
||
|
|
* @param string $objectUri
|
||
|
|
* @return array
|
||
|
|
*/
|
||
|
|
public function getCalendarObject($calendarId,$objectUri);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Creates a new calendar object.
|
||
|
|
*
|
||
|
|
* It is possible return an etag from this function, which will be used in
|
||
|
|
* the response to this PUT request. Note that the ETag must be surrounded
|
||
|
|
* by double-quotes.
|
||
|
|
*
|
||
|
|
* However, you should only really return this ETag if you don't mangle the
|
||
|
|
* calendar-data. If the result of a subsequent GET to this object is not
|
||
|
|
* the exact same as this request body, you should omit the ETag.
|
||
|
|
*
|
||
|
|
* @param mixed $calendarId
|
||
|
|
* @param string $objectUri
|
||
|
|
* @param string $calendarData
|
||
|
|
* @return string|null
|
||
|
|
*/
|
||
|
|
public function createCalendarObject($calendarId,$objectUri,$calendarData);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Updates an existing calendarobject, based on it's uri.
|
||
|
|
*
|
||
|
|
* It is possible return an etag from this function, which will be used in
|
||
|
|
* the response to this PUT request. Note that the ETag must be surrounded
|
||
|
|
* by double-quotes.
|
||
|
|
*
|
||
|
|
* However, you should only really return this ETag if you don't mangle the
|
||
|
|
* calendar-data. If the result of a subsequent GET to this object is not
|
||
|
|
* the exact same as this request body, you should omit the ETag.
|
||
|
|
*
|
||
|
|
* @param mixed $calendarId
|
||
|
|
* @param string $objectUri
|
||
|
|
* @param string $calendarData
|
||
|
|
* @return string|null
|
||
|
|
*/
|
||
|
|
public function updateCalendarObject($calendarId,$objectUri,$calendarData);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Deletes an existing calendar object.
|
||
|
|
*
|
||
|
|
* @param mixed $calendarId
|
||
|
|
* @param string $objectUri
|
||
|
|
* @return void
|
||
|
|
*/
|
||
|
|
public function deleteCalendarObject($calendarId,$objectUri);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Performs a calendar-query on the contents of this calendar.
|
||
|
|
*
|
||
|
|
* The calendar-query is defined in RFC4791 : CalDAV. Using the
|
||
|
|
* calendar-query it is possible for a client to request a specific set of
|
||
|
|
* object, based on contents of iCalendar properties, date-ranges and
|
||
|
|
* iCalendar component types (VTODO, VEVENT).
|
||
|
|
*
|
||
|
|
* This method should just return a list of (relative) urls that match this
|
||
|
|
* query.
|
||
|
|
*
|
||
|
|
* The list of filters are specified as an array. The exact array is
|
||
|
|
* documented by Sabre_CalDAV_CalendarQueryParser.
|
||
|
|
*
|
||
|
|
* Note that it is extremely likely that getCalendarObject for every path
|
||
|
|
* returned from this method will be called almost immediately after. You
|
||
|
|
* may want to anticipate this to speed up these requests.
|
||
|
|
*
|
||
|
|
* This method provides a default implementation, which parses *all* the
|
||
|
|
* iCalendar objects in the specified calendar.
|
||
|
|
*
|
||
|
|
* This default may well be good enough for personal use, and calendars
|
||
|
|
* that aren't very large. But if you anticipate high usage, big calendars
|
||
|
|
* or high loads, you are strongly adviced to optimize certain paths.
|
||
|
|
*
|
||
|
|
* The best way to do so is override this method and to optimize
|
||
|
|
* specifically for 'common filters'.
|
||
|
|
*
|
||
|
|
* Requests that are extremely common are:
|
||
|
|
* * requests for just VEVENTS
|
||
|
|
* * requests for just VTODO
|
||
|
|
* * requests with a time-range-filter on either VEVENT or VTODO.
|
||
|
|
*
|
||
|
|
* ..and combinations of these requests. It may not be worth it to try to
|
||
|
|
* handle every possible situation and just rely on the (relatively
|
||
|
|
* easy to use) CalendarQueryValidator to handle the rest.
|
||
|
|
*
|
||
|
|
* Note that especially time-range-filters may be difficult to parse. A
|
||
|
|
* time-range filter specified on a VEVENT must for instance also handle
|
||
|
|
* recurrence rules correctly.
|
||
|
|
* A good example of how to interprete all these filters can also simply
|
||
|
|
* be found in Sabre_CalDAV_CalendarQueryFilter. This class is as correct
|
||
|
|
* as possible, so it gives you a good idea on what type of stuff you need
|
||
|
|
* to think of.
|
||
|
|
*
|
||
|
|
* @param mixed $calendarId
|
||
|
|
* @param array $filters
|
||
|
|
* @return array
|
||
|
|
*/
|
||
|
|
public function calendarQuery($calendarId, array $filters);
|
||
|
|
|
||
|
|
}
|