1<?php
2
3namespace Sabre\CardDAV\Backend;
4
5/**
6 * WebDAV-sync support for CardDAV 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 getAddressBooksForUser.
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 */
21interface SyncSupport extends BackendInterface {
22
23    /**
24     * The getChanges method returns all the changes that have happened, since
25     * the specified syncToken in the specified address book.
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 $addressBookId
74     * @param string $syncToken
75     * @param int $syncLevel
76     * @param int $limit
77     * @return array
78     */
79    function getChangesForAddressBook($addressBookId, $syncToken, $syncLevel, $limit = null);
80
81}
82