1<?php
2
3namespace Sabre\DAV\Sync;
4
5use Sabre\DAV;
6
7/**
8 * If a class extends ISyncCollection, it supports WebDAV-sync.
9 *
10 * You are responsible for maintaining a changelist for this collection. This
11 * means that if any child nodes in this collection was created, modified or
12 * deleted in any way, you should maintain an updated changelist.
13 *
14 * @copyright Copyright (C) 2007-2015 fruux GmbH (https://fruux.com/).
15 * @author Evert Pot (http://evertpot.com/)
16 * @license http://sabre.io/license/ Modified BSD License
17 */
18interface ISyncCollection extends DAV\ICollection {
19
20    /**
21     * This method returns the current sync-token for this collection.
22     * This can be any string.
23     *
24     * If null is returned from this function, the plugin assumes there's no
25     * sync information available.
26     *
27     * @return string|null
28     */
29    function getSyncToken();
30
31    /**
32     * The getChanges method returns all the changes that have happened, since
33     * the specified syncToken and the current collection.
34     *
35     * This function should return an array, such as the following:
36     *
37     * [
38     *   'syncToken' => 'The current synctoken',
39     *   'added'   => [
40     *      'new.txt',
41     *   ],
42     *   'modified'   => [
43     *      'modified.txt',
44     *   ],
45     *   'deleted' => array(
46     *      'foo.php.bak',
47     *      'old.txt'
48     *   )
49     * ];
50     *
51     * The syncToken property should reflect the *current* syncToken of the
52     * collection, as reported getSyncToken(). This is needed here too, to
53     * ensure the operation is atomic.
54     *
55     * If the syncToken is specified as null, this is an initial sync, and all
56     * members should be reported.
57     *
58     * The modified property is an array of nodenames that have changed since
59     * the last token.
60     *
61     * The deleted property is an array with nodenames, that have been deleted
62     * from collection.
63     *
64     * The second argument is basically the 'depth' of the report. If it's 1,
65     * you only have to report changes that happened only directly in immediate
66     * descendants. If it's 2, it should also include changes from the nodes
67     * below the child collections. (grandchildren)
68     *
69     * The third (optional) argument allows a client to specify how many
70     * results should be returned at most. If the limit is not specified, it
71     * should be treated as infinite.
72     *
73     * If the limit (infinite or not) is higher than you're willing to return,
74     * you should throw a Sabre\DAV\Exception\TooMuchMatches() exception.
75     *
76     * If the syncToken is expired (due to data cleanup) or unknown, you must
77     * return null.
78     *
79     * The limit is 'suggestive'. You are free to ignore it.
80     *
81     * @param string $syncToken
82     * @param int $syncLevel
83     * @param int $limit
84     * @return array
85     */
86    function getChanges($syncToken, $syncLevel, $limit = null);
87
88}
89