1 <?php
2 
3 namespace Sabre\CalDAV\Backend;
4 
5 /**
6  * WebDAV-sync support for CalDAV backends.
7  *
8  * In order for backends to advertise support for WebDAV-sync, this interface
9  * must be implemented.
10  *
11  * Implementing this can result in a significant reduction of bandwidth and CPU
12  * time.
13  *
14  * For this to work, you _must_ return a {http://sabredav.org/ns}sync-token
15  * property from getCalendarsFromUser.
16  *
17  * @copyright Copyright (C) fruux GmbH (https://fruux.com/)
18  * @author Evert Pot (http://evertpot.com/)
19  * @license http://sabre.io/license/ Modified BSD License
20  */
21 interface SyncSupport extends BackendInterface {
22 
23     /**
24      * The getChanges method returns all the changes that have happened, since
25      * the specified syncToken in the specified calendar.
26      *
27      * This function should return an array, such as the following:
28      *
29      * [
30      *   'syncToken' => 'The current synctoken',
31      *   'added'   => [
32      *      'new.txt',
33      *   ],
34      *   'modified'   => [
35      *      'modified.txt',
36      *   ],
37      *   'deleted' => [
38      *      'foo.php.bak',
39      *      'old.txt'
40      *   ]
41      * );
42      *
43      * The returned syncToken property should reflect the *current* syncToken
44      * of the calendar, as reported in the {http://sabredav.org/ns}sync-token
45      * property This is * needed here too, to ensure the operation is atomic.
46      *
47      * If the $syncToken argument is specified as null, this is an initial
48      * sync, and all members should be reported.
49      *
50      * The modified property is an array of nodenames that have changed since
51      * the last token.
52      *
53      * The deleted property is an array with nodenames, that have been deleted
54      * from collection.
55      *
56      * The $syncLevel argument is basically the 'depth' of the report. If it's
57      * 1, you only have to report changes that happened only directly in
58      * immediate descendants. If it's 2, it should also include changes from
59      * the nodes below the child collections. (grandchildren)
60      *
61      * The $limit argument allows a client to specify how many results should
62      * be returned at most. If the limit is not specified, it should be treated
63      * as infinite.
64      *
65      * If the limit (infinite or not) is higher than you're willing to return,
66      * you should throw a Sabre\DAV\Exception\TooMuchMatches() exception.
67      *
68      * If the syncToken is expired (due to data cleanup) or unknown, you must
69      * return null.
70      *
71      * The limit is 'suggestive'. You are free to ignore it.
72      *
73      * @param string $calendarId
74      * @param string $syncToken
75      * @param int $syncLevel
76      * @param int $limit
77      * @return array
78      */
79     function getChangesForCalendar($calendarId, $syncToken, $syncLevel, $limit = null);
80 
81 }
82