1/*
2 Copyright (c) 2008 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_CACHEPOLICY_H
21#define AKONADI_CACHEPOLICY_H
22
23#include "akonadi_export.h"
24
25#include <QtCore/QSharedDataPointer>
26#include <QtCore/QStringList>
27
28namespace Akonadi {
29
30/**
31 * @short Represents the caching policy for a collection.
32 *
33 * There is one cache policy per collection. It can either specify that all
34 * properties of the policy of the parent collection will be inherited (the
35 * default) or specify the following values:
36 *
37 * - The item parts that should be permanently kept locally and are downloaded
38 * during a collection sync (e.g. full mail vs. just the headers).
39 * - A minimum time for which non-permanently cached item parts have to be kept
40 * (0 - infinity).
41 * - Whether or not a collection sync is triggered on demand, i.e. as soon
42 * as it is accessed by a client.
43 * - An optional time interval for regular collection sync (aka interval
44 * mail check).
45 *
46 * Syncing means fetching updates from the Akonadi database. The cache policy
47 * does not affect updates of the Akonadi database from the backend, since
48 * backend updates will normally immediately trigger the resource to update the
49 * Akonadi database.
50 *
51 * The cache policy applies only to reading from the collection. Writing to the
52 * collection is independent of cache policy - all updates are written to the
53 * backend as soon as the resource can schedule this.
54 *
55 * @code
56 *
57 * Akonadi::CachePolicy policy;
58 * policy.setCacheTimeout( 30 );
59 * policy.setIntervalCheckTime( 20 );
60 *
61 * Akonadi::Collection collection = ...
62 * collection.setCachePolicy( policy );
63 *
64 * @endcode
65 *
66 * @todo Do we also need a size limit for the cache as well?
67 * @todo on a POP3 account, is should not be possible to change locally cached parts, find a solution for that
68 *
69 * @author Volker Krause <vkrause@kde.org>
70 */
71class AKONADI_EXPORT CachePolicy
72{
73public:
74 /**
75 * Creates an empty cache policy.
76 */
77 CachePolicy();
78
79 /**
80 * Creates a cache policy from an @p other cache policy.
81 */
82 CachePolicy(const CachePolicy &other);
83
84 /**
85 * Destroys the cache policy.
86 */
87 ~CachePolicy();
88
89 /**
90 * Returns whether it inherits cache policy from the parent collection.
91 */
92 bool inheritFromParent() const;
93
94 /**
95 * Sets whether the cache policy should be inherited from the parent collection.
96 */
97 void setInheritFromParent(bool inherit);
98
99 /**
100 * Returns the parts to permanently cache locally.
101 */
102 QStringList localParts() const;
103
104 /**
105 * Specifies the parts to permanently cache locally.
106 */
107 void setLocalParts(const QStringList &parts);
108
109 /**
110 * Returns the cache timeout for non-permanently cached parts in minutes;
111 * -1 means indefinitely.
112 */
113 int cacheTimeout() const;
114
115 /**
116 * Sets cache timeout for non-permanently cached parts.
117 * @param timeout Timeout in minutes, -1 for indefinitely.
118 */
119 void setCacheTimeout(int timeout);
120
121 /**
122 * Returns the interval check time in minutes, -1 for never.
123 */
124 int intervalCheckTime() const;
125
126 /**
127 * Sets interval check time.
128 * @param time Check time interval in minutes, -1 for never.
129 */
130 void setIntervalCheckTime(int time);
131
132 /**
133 * Returns whether the collection will be synced automatically when necessary,
134 * i.e. as soon as it is accessed by a client.
135 */
136 bool syncOnDemand() const;
137
138 /**
139 * Sets whether the collection shall be synced automatically when necessary,
140 * i.e. as soon as it is accessed by a client.
141 * @param enable If @c true the collection is synced.
142 */
143 void setSyncOnDemand(bool enable);
144
145 /**
146 * @internal.
147 * @param other other cache policy
148 */
149 CachePolicy &operator=(const CachePolicy &other);
150
151 /**
152 * @internal
153 * @param other other cache policy
154 */
155 bool operator==(const CachePolicy &other) const;
156
157private:
158 //@cond PRIVATE
159 class Private;
160 QSharedDataPointer<Private> d;
161 //@endcond
162};
163
164}
165
166/**
167 * Allows a cache policy to be output for debugging purposes.
168 */
169AKONADI_EXPORT QDebug operator<<(QDebug, const Akonadi::CachePolicy &);
170
171#endif
172