1/*
2 * Copyright (c) 2009 Volker Krause <vkrause@kde.org>
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
16 */
17
18#ifndef AKONADI_RESOURCESYNCHRONIZATIONJOB_H
19#define AKONADI_RESOURCESYNCHRONIZATIONJOB_H
20
21#include "akonadi_export.h"
22
23#include <kjob.h>
24
25namespace Akonadi {
26
27class AgentInstance;
28class ResourceSynchronizationJobPrivate;
29
30/**
31 * @short Job that synchronizes a resource.
32 *
33 * This job will trigger a resource to synchronize the backend it is
34 * responsible for (e.g. a local file or a groupware server) with the
35 * Akonadi storage.
36 *
37 * If you only want to trigger the synchronization without being
38 * interested in the result, using Akonadi::AgentInstance::synchronize() is enough.
39 * If you want to wait until it's finished, use this class.
40 *
41 * Example:
42 *
43 * @code
44 * using namespace Akonadi;
45 *
46 * const AgentInstance resource = AgentManager::self()->instance( "myresourceidentifier" );
47 *
48 * ResourceSynchronizationJob *job = new ResourceSynchronizationJob( resource );
49 * connect( job, SIGNAL(result(KJob*)), SLOT(synchronizationFinished(KJob*)) );
50 * job->start();
51 *
52 * @endcode
53 *
54 * @note This is a KJob, not an Akonadi::Job, so it won't auto-start!
55 *
56 * @author Volker Krause <vkrause@kde.org>
57 * @since 4.4
58 */
59class AKONADI_EXPORT ResourceSynchronizationJob : public KJob
60{
61 Q_OBJECT
62
63public:
64 /**
65 * Creates a new synchronization job for the given resource.
66 *
67 * @param instance The resource instance to synchronize.
68 */
69 explicit ResourceSynchronizationJob(const AgentInstance &instance, QObject *parent = 0);
70
71 /**
72 * Destroys the synchronization job.
73 */
74 ~ResourceSynchronizationJob();
75
76 /**
77 * Returns whether a full synchronization will be done, or just the collection tree (without items).
78 * The default is @c false, i.e. a full sync will be requested.
79 *
80 * @since 4.8
81 */
82 bool collectionTreeOnly() const;
83
84 /**
85 * Sets the collectionTreeOnly property.
86 *
87 * @param collectionTreeOnly If set, only the collection tree will be synchronized.
88 * @since 4.8
89 */
90 void setCollectionTreeOnly(bool collectionTreeOnly);
91
92 /**
93 * Returns the resource that has been synchronized.
94 */
95 AgentInstance resource() const;
96
97 /* reimpl */
98 void start();
99
100private:
101 //@cond PRIVATE
102 ResourceSynchronizationJobPrivate *const d;
103 friend class ResourceSynchronizationJobPrivate;
104
105 Q_PRIVATE_SLOT(d, void slotSynchronized())
106 Q_PRIVATE_SLOT(d, void slotTimeout())
107 //@endcond
108};
109
110}
111
112#endif
113