4 * Every CalDAV backend must at least implement this interface.
8 * @copyright Copyright (C) 2007-2012 Rooftop Solutions. All rights reserved.
9 * @author Evert Pot (http://www.rooftopsolutions.nl/)
10 * @license http://code.google.com/p/sabredav/wiki/License Modified BSD License
12 interface Sabre_CalDAV_Backend_BackendInterface {
15 * Returns a list of calendars for a principal.
17 * Every project is an array with the following keys:
18 * * id, a unique id that will be used by other functions to modify the
19 * calendar. This can be the same as the uri or a database key.
20 * * uri, which the basename of the uri with which the calendar is
22 * * principaluri. The owner of the calendar. Almost always the same as
23 * principalUri passed to this method.
25 * Furthermore it can contain webdav properties in clark notation. A very
26 * common one is '{DAV:}displayname'.
28 * @param string $principalUri
31 public function getCalendarsForUser($principalUri);
34 * Creates a new calendar for a principal.
36 * If the creation was a success, an id must be returned that can be used to reference
37 * this calendar in other methods, such as updateCalendar.
39 * @param string $principalUri
40 * @param string $calendarUri
41 * @param array $properties
44 public function createCalendar($principalUri,$calendarUri,array $properties);
47 * Updates properties for a calendar.
49 * The mutations array uses the propertyName in clark-notation as key,
50 * and the array value for the property value. In the case a property
51 * should be deleted, the property value will be null.
53 * This method must be atomic. If one property cannot be changed, the
54 * entire operation must fail.
56 * If the operation was successful, true can be returned.
57 * If the operation failed, false can be returned.
59 * Deletion of a non-existent property is always successful.
61 * Lastly, it is optional to return detailed information about any
62 * failures. In this case an array should be returned with the following
67 * '{DAV:}displayname' => null,
70 * '{DAV:}owner' => null,
74 * In this example it was forbidden to update {DAV:}displayname.
75 * (403 Forbidden), which in turn also caused {DAV:}owner to fail
76 * (424 Failed Dependency) because the request needs to be atomic.
78 * @param mixed $calendarId
79 * @param array $mutations
82 public function updateCalendar($calendarId, array $mutations);
85 * Delete a calendar and all it's objects
87 * @param mixed $calendarId
90 public function deleteCalendar($calendarId);
93 * Returns all calendar objects within a calendar.
95 * Every item contains an array with the following keys:
96 * * id - unique identifier which will be used for subsequent updates
97 * * calendardata - The iCalendar-compatible calendar data
98 * * uri - a unique key which will be used to construct the uri. This can be any arbitrary string.
99 * * lastmodified - a timestamp of the last modification time
100 * * etag - An arbitrary string, surrounded by double-quotes. (e.g.:
102 * * calendarid - The calendarid as it was passed to this function.
103 * * size - The size of the calendar objects, in bytes.
105 * Note that the etag is optional, but it's highly encouraged to return for
108 * The calendardata is also optional. If it's not returned
109 * 'getCalendarObject' will be called later, which *is* expected to return
112 * If neither etag or size are specified, the calendardata will be
113 * used/fetched to determine these numbers. If both are specified the
114 * amount of times this is needed is reduced by a great degree.
116 * @param mixed $calendarId
119 public function getCalendarObjects($calendarId);
122 * Returns information from a single calendar object, based on it's object
125 * The returned array must have the same keys as getCalendarObjects. The
126 * 'calendardata' object is required here though, while it's not required
127 * for getCalendarObjects.
129 * @param mixed $calendarId
130 * @param string $objectUri
133 public function getCalendarObject($calendarId,$objectUri);
136 * Creates a new calendar object.
138 * It is possible return an etag from this function, which will be used in
139 * the response to this PUT request. Note that the ETag must be surrounded
142 * However, you should only really return this ETag if you don't mangle the
143 * calendar-data. If the result of a subsequent GET to this object is not
144 * the exact same as this request body, you should omit the ETag.
146 * @param mixed $calendarId
147 * @param string $objectUri
148 * @param string $calendarData
149 * @return string|null
151 public function createCalendarObject($calendarId,$objectUri,$calendarData);
154 * Updates an existing calendarobject, based on it's uri.
156 * It is possible return an etag from this function, which will be used in
157 * the response to this PUT request. Note that the ETag must be surrounded
160 * However, you should only really return this ETag if you don't mangle the
161 * calendar-data. If the result of a subsequent GET to this object is not
162 * the exact same as this request body, you should omit the ETag.
164 * @param mixed $calendarId
165 * @param string $objectUri
166 * @param string $calendarData
167 * @return string|null
169 public function updateCalendarObject($calendarId,$objectUri,$calendarData);
172 * Deletes an existing calendar object.
174 * @param mixed $calendarId
175 * @param string $objectUri
178 public function deleteCalendarObject($calendarId,$objectUri);
181 * Performs a calendar-query on the contents of this calendar.
183 * The calendar-query is defined in RFC4791 : CalDAV. Using the
184 * calendar-query it is possible for a client to request a specific set of
185 * object, based on contents of iCalendar properties, date-ranges and
186 * iCalendar component types (VTODO, VEVENT).
188 * This method should just return a list of (relative) urls that match this
191 * The list of filters are specified as an array. The exact array is
192 * documented by Sabre_CalDAV_CalendarQueryParser.
194 * Note that it is extremely likely that getCalendarObject for every path
195 * returned from this method will be called almost immediately after. You
196 * may want to anticipate this to speed up these requests.
198 * This method provides a default implementation, which parses *all* the
199 * iCalendar objects in the specified calendar.
201 * This default may well be good enough for personal use, and calendars
202 * that aren't very large. But if you anticipate high usage, big calendars
203 * or high loads, you are strongly adviced to optimize certain paths.
205 * The best way to do so is override this method and to optimize
206 * specifically for 'common filters'.
208 * Requests that are extremely common are:
209 * * requests for just VEVENTS
210 * * requests for just VTODO
211 * * requests with a time-range-filter on either VEVENT or VTODO.
213 * ..and combinations of these requests. It may not be worth it to try to
214 * handle every possible situation and just rely on the (relatively
215 * easy to use) CalendarQueryValidator to handle the rest.
217 * Note that especially time-range-filters may be difficult to parse. A
218 * time-range filter specified on a VEVENT must for instance also handle
219 * recurrence rules correctly.
220 * A good example of how to interprete all these filters can also simply
221 * be found in Sabre_CalDAV_CalendarQueryFilter. This class is as correct
222 * as possible, so it gives you a good idea on what type of stuff you need
225 * @param mixed $calendarId
226 * @param array $filters
229 public function calendarQuery($calendarId, array $filters);