1 | /* |
2 | Copyright (c) 2007, 2009 Volker Krause <vkrause@kde.org> |
3 | |
4 | This library is free software; you can redistribute it and/or modify it |
5 | under the terms of the GNU Library General Public License as published by |
6 | the Free Software Foundation; either version 2 of the License, or (at your |
7 | option) any later version. |
8 | |
9 | This library is distributed in the hope that it will be useful, but WITHOUT |
10 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
11 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public |
12 | License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to the |
16 | Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA |
17 | 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef AKONADI_COLLECTIONSYNC_P_H |
21 | #define AKONADI_COLLECTIONSYNC_P_H |
22 | |
23 | #include <akonadi/collection.h> |
24 | #include <akonadi/transactionsequence.h> |
25 | |
26 | namespace Akonadi { |
27 | |
28 | /** |
29 | @internal |
30 | |
31 | Syncs remote and local collections. |
32 | |
33 | Basic terminology: |
34 | - "local": The current state in the Akonadi server |
35 | - "remote": The state in the backend, which is also the state the Akonadi |
36 | server is supposed to have afterwards. |
37 | |
38 | There are three options to influence the way syncing is done: |
39 | - Streaming vs. complete delivery: If streaming is enabled remote collections |
40 | do not need to be delivered in a single batch but can be delivered in multiple |
41 | chunks. This improves performance but requires an explicit notification |
42 | when delivery has been completed. |
43 | - Incremental vs. non-incremental: In the incremental case only remote changes |
44 | since the last sync have to be delivered, in the non-incremental mode the full |
45 | remote state has to be provided. The first is obviously the preferred way, |
46 | but requires support by the backend. |
47 | - Hierarchical vs. global RIDs: The first requires RIDs to be unique per parent |
48 | collection, the second one requires globally unique RIDs (per resource). Those |
49 | have different advantages and disadvantages, esp. regarding moving. Which one |
50 | to chose mostly depends on what the backend provides in this regard. |
51 | |
52 | */ |
53 | class CollectionSync : public Job |
54 | { |
55 | Q_OBJECT |
56 | |
57 | public: |
58 | /** |
59 | Creates a new collection synchronzier. |
60 | @param resourceId The identifier of the resource we are syncing. |
61 | @param parent The parent object. |
62 | */ |
63 | explicit CollectionSync(const QString &resourceId, QObject *parent = 0); |
64 | |
65 | /** |
66 | Destroys this job. |
67 | */ |
68 | ~CollectionSync(); |
69 | |
70 | /** |
71 | Sets the result of a full remote collection listing. |
72 | @param remoteCollections A list of collections. |
73 | Important: All of these need a unique remote identifier and parent remote |
74 | identifier. |
75 | */ |
76 | void setRemoteCollections(const Collection::List &remoteCollections); |
77 | |
78 | /** |
79 | Sets the result of an incremental remote collection listing. |
80 | @param changedCollections A list of remotely added or changed collections. |
81 | @param removedCollections A list of remotely deleted collections. |
82 | */ |
83 | void setRemoteCollections(const Collection::List &changedCollections, |
84 | const Collection::List &removedCollections); |
85 | |
86 | /** |
87 | Enables streaming, that is not all collections are delivered at once. |
88 | Use setRemoteCollections() multiple times when streaming is enabled and call |
89 | retrievalDone() when all collections have been retrieved. |
90 | Must be called before the first call to setRemoteCollections(). |
91 | @param streaming enables streaming if set as @c true |
92 | */ |
93 | void setStreamingEnabled(bool streaming); |
94 | |
95 | /** |
96 | Indicate that all collections have been retrieved in streaming mode. |
97 | */ |
98 | void retrievalDone(); |
99 | |
100 | /** |
101 | Indicate whether the resource supplies collections with hierarchical or |
102 | global remote identifiers. @c false by default. |
103 | Must be called before the first call to setRemoteCollections(). |
104 | @param hierarchical @c true if collection remote IDs are relative to their parents' remote IDs |
105 | */ |
106 | void setHierarchicalRemoteIds(bool hierarchical); |
107 | |
108 | /** |
109 | Do a rollback operation if needed. In read only cases this is a noop. |
110 | */ |
111 | void rollback(); |
112 | |
113 | /** |
114 | * Allows to specify parts of the collection that should not be changed if locally available. |
115 | * |
116 | * This is useful for resources to provide default values during the collection sync, while |
117 | * preserving more up-to date values if available. |
118 | * |
119 | * Use CONTENTMIMETYPES as identifier to not overwrite the content mimetypes. |
120 | * |
121 | * @since 4.14 |
122 | */ |
123 | void setKeepLocalChanges(const QSet<QByteArray> &parts); |
124 | |
125 | protected: |
126 | void doStart(); |
127 | |
128 | private: |
129 | class Private; |
130 | Private *const d; |
131 | |
132 | Q_PRIVATE_SLOT(d, void localCollectionsReceived(const Akonadi::Collection::List &localCols)) |
133 | Q_PRIVATE_SLOT(d, void localCollectionFetchResult(KJob *job)) |
134 | Q_PRIVATE_SLOT(d, void updateLocalCollectionResult(KJob *job)) |
135 | Q_PRIVATE_SLOT(d, void createLocalCollectionResult(KJob *job)) |
136 | Q_PRIVATE_SLOT(d, void deleteLocalCollectionsResult(KJob *job)) |
137 | Q_PRIVATE_SLOT(d, void transactionSequenceResult(KJob *job)) |
138 | }; |
139 | |
140 | } |
141 | |
142 | #endif |
143 | |