1<?php
2
3namespace Sabre\CalDAV\Backend;
4
5/**
6 * Every CalDAV backend must at least implement this interface.
7 *
8 * @copyright Copyright (C) 2007-2015 fruux GmbH (https://fruux.com/).
9 * @author Evert Pot (http://evertpot.com/)
10 * @license http://sabre.io/license/ Modified BSD License
11 */
12interface BackendInterface {
13
14    /**
15     * Returns a list of calendars for a principal.
16     *
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 is the basename of the uri with which the calendar is
21     *    accessed.
22     *  * principaluri. The owner of the calendar. Almost always the same as
23     *    principalUri passed to this method.
24     *
25     * Furthermore it can contain webdav properties in clark notation. A very
26     * common one is '{DAV:}displayname'.
27     *
28     * Many clients also require:
29     * {urn:ietf:params:xml:ns:caldav}supported-calendar-component-set
30     * For this property, you can just return an instance of
31     * Sabre\CalDAV\Property\SupportedCalendarComponentSet.
32     *
33     * If you return {http://sabredav.org/ns}read-only and set the value to 1,
34     * ACL will automatically be put in read-only mode.
35     *
36     * @param string $principalUri
37     * @return array
38     */
39    function getCalendarsForUser($principalUri);
40
41    /**
42     * Creates a new calendar for a principal.
43     *
44     * If the creation was a success, an id must be returned that can be used to
45     * reference this calendar in other methods, such as updateCalendar.
46     *
47     * @param string $principalUri
48     * @param string $calendarUri
49     * @param array $properties
50     * @return void
51     */
52    function createCalendar($principalUri, $calendarUri, array $properties);
53
54    /**
55     * Updates properties for a calendar.
56     *
57     * The list of mutations is stored in a Sabre\DAV\PropPatch object.
58     * To do the actual updates, you must tell this object which properties
59     * you're going to process with the handle() method.
60     *
61     * Calling the handle method is like telling the PropPatch object "I
62     * promise I can handle updating this property".
63     *
64     * Read the PropPatch documentation for more info and examples.
65     *
66     * @param string $path
67     * @param \Sabre\DAV\PropPatch $propPatch
68     * @return void
69     */
70    function updateCalendar($calendarId, \Sabre\DAV\PropPatch $propPatch);
71
72    /**
73     * Delete a calendar and all its objects
74     *
75     * @param mixed $calendarId
76     * @return void
77     */
78    function deleteCalendar($calendarId);
79
80    /**
81     * Returns all calendar objects within a calendar.
82     *
83     * Every item contains an array with the following keys:
84     *   * calendardata - The iCalendar-compatible calendar data
85     *   * uri - a unique key which will be used to construct the uri. This can
86     *     be any arbitrary string, but making sure it ends with '.ics' is a
87     *     good idea. This is only the basename, or filename, not the full
88     *     path.
89     *   * lastmodified - a timestamp of the last modification time
90     *   * etag - An arbitrary string, surrounded by double-quotes. (e.g.:
91     *   '"abcdef"')
92     *   * size - The size of the calendar objects, in bytes.
93     *   * component - optional, a string containing the type of object, such
94     *     as 'vevent' or 'vtodo'. If specified, this will be used to populate
95     *     the Content-Type header.
96     *
97     * Note that the etag is optional, but it's highly encouraged to return for
98     * speed reasons.
99     *
100     * The calendardata is also optional. If it's not returned
101     * 'getCalendarObject' will be called later, which *is* expected to return
102     * calendardata.
103     *
104     * If neither etag or size are specified, the calendardata will be
105     * used/fetched to determine these numbers. If both are specified the
106     * amount of times this is needed is reduced by a great degree.
107     *
108     * @param mixed $calendarId
109     * @return array
110     */
111    function getCalendarObjects($calendarId);
112
113    /**
114     * Returns information from a single calendar object, based on it's object
115     * uri.
116     *
117     * The object uri is only the basename, or filename and not a full path.
118     *
119     * The returned array must have the same keys as getCalendarObjects. The
120     * 'calendardata' object is required here though, while it's not required
121     * for getCalendarObjects.
122     *
123     * This method must return null if the object did not exist.
124     *
125     * @param mixed $calendarId
126     * @param string $objectUri
127     * @return array|null
128     */
129    function getCalendarObject($calendarId, $objectUri);
130
131    /**
132     * Returns a list of calendar objects.
133     *
134     * This method should work identical to getCalendarObject, but instead
135     * return all the calendar objects in the list as an array.
136     *
137     * If the backend supports this, it may allow for some speed-ups.
138     *
139     * @param mixed $calendarId
140     * @param array $uris
141     * @return array
142     */
143    function getMultipleCalendarObjects($calendarId, array $uris);
144
145    /**
146     * Creates a new calendar object.
147     *
148     * The object uri is only the basename, or filename and not a full path.
149     *
150     * It is possible to return an etag from this function, which will be used
151     * in the response to this PUT request. Note that the ETag must be
152     * surrounded by double-quotes.
153     *
154     * However, you should only really return this ETag if you don't mangle the
155     * calendar-data. If the result of a subsequent GET to this object is not
156     * the exact same as this request body, you should omit the ETag.
157     *
158     * @param mixed $calendarId
159     * @param string $objectUri
160     * @param string $calendarData
161     * @return string|null
162     */
163    function createCalendarObject($calendarId, $objectUri, $calendarData);
164
165    /**
166     * Updates an existing calendarobject, based on it's uri.
167     *
168     * The object uri is only the basename, or filename and not a full path.
169     *
170     * It is possible return an etag from this function, which will be used in
171     * the response to this PUT request. Note that the ETag must be surrounded
172     * by double-quotes.
173     *
174     * However, you should only really return this ETag if you don't mangle the
175     * calendar-data. If the result of a subsequent GET to this object is not
176     * the exact same as this request body, you should omit the ETag.
177     *
178     * @param mixed $calendarId
179     * @param string $objectUri
180     * @param string $calendarData
181     * @return string|null
182     */
183    function updateCalendarObject($calendarId, $objectUri, $calendarData);
184
185    /**
186     * Deletes an existing calendar object.
187     *
188     * The object uri is only the basename, or filename and not a full path.
189     *
190     * @param mixed $calendarId
191     * @param string $objectUri
192     * @return void
193     */
194    function deleteCalendarObject($calendarId, $objectUri);
195
196    /**
197     * Performs a calendar-query on the contents of this calendar.
198     *
199     * The calendar-query is defined in RFC4791 : CalDAV. Using the
200     * calendar-query it is possible for a client to request a specific set of
201     * object, based on contents of iCalendar properties, date-ranges and
202     * iCalendar component types (VTODO, VEVENT).
203     *
204     * This method should just return a list of (relative) urls that match this
205     * query.
206     *
207     * The list of filters are specified as an array. The exact array is
208     * documented by Sabre\CalDAV\CalendarQueryParser.
209     *
210     * Note that it is extremely likely that getCalendarObject for every path
211     * returned from this method will be called almost immediately after. You
212     * may want to anticipate this to speed up these requests.
213     *
214     * This method provides a default implementation, which parses *all* the
215     * iCalendar objects in the specified calendar.
216     *
217     * This default may well be good enough for personal use, and calendars
218     * that aren't very large. But if you anticipate high usage, big calendars
219     * or high loads, you are strongly adviced to optimize certain paths.
220     *
221     * The best way to do so is override this method and to optimize
222     * specifically for 'common filters'.
223     *
224     * Requests that are extremely common are:
225     *   * requests for just VEVENTS
226     *   * requests for just VTODO
227     *   * requests with a time-range-filter on either VEVENT or VTODO.
228     *
229     * ..and combinations of these requests. It may not be worth it to try to
230     * handle every possible situation and just rely on the (relatively
231     * easy to use) CalendarQueryValidator to handle the rest.
232     *
233     * Note that especially time-range-filters may be difficult to parse. A
234     * time-range filter specified on a VEVENT must for instance also handle
235     * recurrence rules correctly.
236     * A good example of how to interprete all these filters can also simply
237     * be found in Sabre\CalDAV\CalendarQueryFilter. This class is as correct
238     * as possible, so it gives you a good idea on what type of stuff you need
239     * to think of.
240     *
241     * @param mixed $calendarId
242     * @param array $filters
243     * @return array
244     */
245    function calendarQuery($calendarId, array $filters);
246
247    /**
248     * Searches through all of a users calendars and calendar objects to find
249     * an object with a specific UID.
250     *
251     * This method should return the path to this object, relative to the
252     * calendar home, so this path usually only contains two parts:
253     *
254     * calendarpath/objectpath.ics
255     *
256     * If the uid is not found, return null.
257     *
258     * This method should only consider * objects that the principal owns, so
259     * any calendars owned by other principals that also appear in this
260     * collection should be ignored.
261     *
262     * @param string $principalUri
263     * @param string $uid
264     * @return string|null
265     */
266    function getCalendarObjectByUID($principalUri, $uid);
267
268}
269