1 | /* |
2 | This file is part of the kcal library. |
3 | |
4 | Copyright (c) 2006 David Jarvie <djarvie@kde.org> |
5 | Copyright (c) 2003,2004 Cornelius Schumacher <schumacher@kde.org> |
6 | |
7 | This library is free software; you can redistribute it and/or |
8 | modify it under the terms of the GNU Library General Public |
9 | License as published by the Free Software Foundation; either |
10 | version 2 of the License, or (at your option) any later version. |
11 | |
12 | This library is distributed in the hope that it will be useful, |
13 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
14 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
15 | Library General Public License for more details. |
16 | |
17 | You should have received a copy of the GNU Library General Public License |
18 | along with this library; see the file COPYING.LIB. If not, write to |
19 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
20 | Boston, MA 02110-1301, USA. |
21 | */ |
22 | #ifndef KCAL_RESOURCECACHED_H |
23 | #define KCAL_RESOURCECACHED_H |
24 | |
25 | #include "resourcecalendar.h" |
26 | #include "incidence.h" |
27 | |
28 | #include <kdatetime.h> |
29 | |
30 | #include <QtCore/QString> |
31 | |
32 | class KConfigGroup; |
33 | namespace KRES { class IdMapper; } |
34 | |
35 | namespace KCal { |
36 | |
37 | class CalendarLocal; |
38 | |
39 | /** |
40 | This class provides a calendar resource using a local CalendarLocal object to |
41 | cache the calendar data. |
42 | */ |
43 | class KCAL_DEPRECATED_EXPORT ResourceCached : public ResourceCalendar, |
44 | public KCal::Calendar::CalendarObserver |
45 | { |
46 | Q_OBJECT |
47 | public: |
48 | /** |
49 | Reload policy. Whether and when to automatically reload the resource. |
50 | @see setReloadPolicy(), reloadPolicy() |
51 | */ |
52 | enum { |
53 | ReloadNever, /**< never reload the resource automatically */ |
54 | ReloadOnStartup, /**< reload when the resource is opened */ |
55 | ReloadInterval /**< reload at regular intervals set by setReloadInterval() */ |
56 | }; |
57 | |
58 | /** |
59 | Save policy. Whether and when to automatically save the resource. |
60 | @see setSavePolicy(), savePolicy() |
61 | */ |
62 | enum { |
63 | SaveNever, /**< never save the resource automatically */ |
64 | SaveOnExit, /**< save when the resource is closed */ |
65 | SaveInterval, /**< save at regular intervals set by setSaveInterval() */ |
66 | SaveDelayed, /**< save after every change, after a 15 second delay */ |
67 | SaveAlways /**< save after every change, after a 1 second delay */ |
68 | }; |
69 | |
70 | /** |
71 | Whether to update the cache file when loading a resource, or whether to |
72 | upload the cache file after saving the resource. |
73 | Only applicable to genuinely cached resources. |
74 | */ |
75 | enum CacheAction { |
76 | DefaultCache,/**< use the default action set by setReloadPolicy() or setSavePolicy() */ |
77 | NoSyncCache, /**< perform a cache-only operation, without downloading or uploading */ |
78 | SyncCache /**< update the cache file before loading, or upload cache after saving */ |
79 | }; |
80 | |
81 | ResourceCached(); |
82 | explicit ResourceCached( const KConfigGroup &group ); |
83 | virtual ~ResourceCached(); |
84 | |
85 | void readConfig( const KConfigGroup &group ); |
86 | void writeConfig( KConfigGroup &group ); |
87 | |
88 | /** |
89 | Set reload policy. This controls when the cache is refreshed. |
90 | |
91 | ReloadNever never reload |
92 | ReloadOnStartup reload when resource is started |
93 | ReloadInterval reload regularly after given interval |
94 | */ |
95 | void setReloadPolicy( int policy ); |
96 | /** |
97 | Return reload policy. |
98 | |
99 | @see setReloadPolicy() |
100 | */ |
101 | int reloadPolicy() const; |
102 | |
103 | /** |
104 | Set reload interval in minutes which is used when reload policy is |
105 | ReloadInterval. |
106 | */ |
107 | void setReloadInterval( int minutes ); |
108 | |
109 | /** |
110 | Return reload interval in minutes. |
111 | */ |
112 | int reloadInterval() const; |
113 | |
114 | /** |
115 | Inhibit or allow cache reloads when using load(DefaultCache). If inhibited, |
116 | this overrides the policy set by setReloadPolicy(), preventing any non-explicit |
117 | reloads from being performed. If not inhibited, reloads take place according |
118 | to the policy set by setReloadPolicy(). |
119 | |
120 | @param inhibit true to inhibit reloads, false to allow them |
121 | */ |
122 | bool inhibitDefaultReload( bool inhibit ); |
123 | bool defaultReloadInhibited() const; |
124 | |
125 | /** |
126 | Return whether the resource cache has been reloaded since startup. |
127 | */ |
128 | bool reloaded() const; |
129 | |
130 | /** |
131 | Set save policy. This controls when the cache is refreshed. |
132 | |
133 | SaveNever never save |
134 | SaveOnExit save when resource is exited |
135 | SaveInterval save regularly after given interval |
136 | SaveDelayed save on every change, after small delay |
137 | SaveAlways save on every change |
138 | */ |
139 | void setSavePolicy( int policy ); |
140 | /** |
141 | Return save policy. |
142 | |
143 | @see setsavePolicy() |
144 | */ |
145 | int savePolicy() const; |
146 | |
147 | /** |
148 | Set save interval in minutes which is used when save policy is |
149 | SaveInterval. |
150 | */ |
151 | void setSaveInterval( int minutes ); |
152 | |
153 | /** |
154 | Return save interval in minutes. |
155 | */ |
156 | int saveInterval() const; |
157 | |
158 | /** |
159 | Return time of last load. |
160 | */ |
161 | KDateTime lastLoad() const; |
162 | |
163 | /** |
164 | Return time of last save. |
165 | */ |
166 | KDateTime lastSave() const; |
167 | |
168 | /** |
169 | Load resource data, specifying whether to refresh the cache file first. |
170 | For a non-cached resource, this method has the same effect as load(). |
171 | |
172 | @param action is the type of #CacheAction for this data loading. |
173 | */ |
174 | bool load( CacheAction action ); |
175 | |
176 | /** |
177 | Load resource data. |
178 | */ |
179 | virtual bool load(); |
180 | |
181 | /** |
182 | Save the resource data to cache, and optionally upload the cache file |
183 | afterwards. For a non-cached resource, this method has the same effect |
184 | as save(). |
185 | |
186 | @param action is the type of #CacheAction for this data saving. |
187 | @param incidence if given as 0, doSave(bool) is called to save all |
188 | incidences, else doSave(bool, incidence) is called to save only the |
189 | given one. |
190 | */ |
191 | bool save( CacheAction action, Incidence *incidence = 0 ); |
192 | |
193 | /** |
194 | Save resource data. |
195 | */ |
196 | virtual bool save( Incidence *incidence = 0 ); |
197 | |
198 | /** |
199 | Add event to calendar. |
200 | |
201 | @param event is a pointer to the Event to insert. |
202 | */ |
203 | bool addEvent( Event *event ); |
204 | |
205 | /** |
206 | Deletes an event from this calendar. |
207 | */ |
208 | bool deleteEvent( Event *event ); |
209 | |
210 | /** |
211 | Removes all Events from this calendar. |
212 | */ |
213 | void deleteAllEvents(); |
214 | |
215 | /** |
216 | Retrieves an event on the basis of the unique string ID. |
217 | */ |
218 | Event *event( const QString &UniqueStr ); |
219 | |
220 | /** |
221 | Return filtered list of all events in calendar. |
222 | */ |
223 | Event::List events(); |
224 | |
225 | /** |
226 | Return unfiltered list of all events in calendar. |
227 | */ |
228 | Event::List rawEvents( EventSortField sortField = EventSortUnsorted, |
229 | SortDirection sortDirection = SortDirectionAscending ); |
230 | |
231 | /** |
232 | Builds and then returns a list of all events that match for the |
233 | date specified. useful for dayView, etc. etc. |
234 | |
235 | @param date date for which to get the events |
236 | @param timeSpec the time specification of the date |
237 | @param sortField field used as the sort key for the result list |
238 | @param sortDirection direction of sorting according to @p sortField |
239 | */ |
240 | Event::List rawEventsForDate( const QDate &date, |
241 | const KDateTime::Spec &timeSpec = KDateTime::Spec(), |
242 | EventSortField sortField = EventSortUnsorted, |
243 | SortDirection sortDirection = SortDirectionAscending ); |
244 | |
245 | /** |
246 | Get unfiltered events for date @p dt. |
247 | */ |
248 | Event::List rawEventsForDate( const KDateTime &dt ); |
249 | |
250 | /** |
251 | Get unfiltered events in a range of dates. If inclusive is set to true, |
252 | only events are returned, which are completely included in the range. |
253 | |
254 | @param start date at the begin of the searching range |
255 | @param end date at the end of the searching range |
256 | @param timeSpec timeSpec of the searching range |
257 | @param inclusive if @c true, only match events which are completely within |
258 | the specified range |
259 | */ |
260 | Event::List rawEvents( const QDate &start, const QDate &end, |
261 | const KDateTime::Spec &timeSpec = KDateTime::Spec(), |
262 | bool inclusive = false ); |
263 | |
264 | /** |
265 | Add a todo to the todolist. |
266 | |
267 | @param todo is a pointer to the Todo to insert. |
268 | */ |
269 | bool addTodo( Todo *todo ); |
270 | |
271 | /** |
272 | Remove a todo from the todolist. |
273 | */ |
274 | bool deleteTodo( Todo * ); |
275 | |
276 | /** |
277 | Removes all todos from this calendar. |
278 | */ |
279 | void deleteAllTodos(); |
280 | |
281 | /** |
282 | Searches todolist for an event with this unique string identifier, |
283 | returns a pointer or null. |
284 | */ |
285 | Todo *todo( const QString &uid ); |
286 | |
287 | /** |
288 | Return list of all todos. |
289 | */ |
290 | Todo::List rawTodos( TodoSortField sortField = TodoSortUnsorted, |
291 | SortDirection sortDirection = SortDirectionAscending ); |
292 | |
293 | /** |
294 | Returns list of todos due on the specified date. |
295 | */ |
296 | Todo::List rawTodosForDate( const QDate &date ); |
297 | |
298 | /** |
299 | Add a Journal entry to calendar |
300 | |
301 | @param journal is a pointer to the Journal to insert. |
302 | */ |
303 | virtual KCAL_DEPRECATED bool addJournal( Journal *journal ); |
304 | |
305 | /** |
306 | Remove a Journal from the calendar |
307 | */ |
308 | virtual bool deleteJournal( Journal * ); |
309 | |
310 | /** |
311 | Removes all Journals from this calendar. |
312 | */ |
313 | virtual void deleteAllJournals(); |
314 | |
315 | /** |
316 | Return Journal with given unique id. |
317 | */ |
318 | virtual Journal *journal( const QString &uid ); |
319 | |
320 | /** |
321 | Return list of all journals. |
322 | */ |
323 | Journal::List rawJournals( JournalSortField sortField = JournalSortUnsorted, |
324 | SortDirection sortDirection = SortDirectionAscending ); |
325 | |
326 | /** |
327 | Return list of journals for the given date. |
328 | */ |
329 | Journal::List rawJournalsForDate( const QDate &date ); |
330 | |
331 | /** |
332 | Return all alarms, which occur in the given time interval. |
333 | */ |
334 | Alarm::List alarms( const KDateTime &from, const KDateTime &to ); |
335 | |
336 | /** |
337 | Return all alarms, which occur before given date. |
338 | */ |
339 | Alarm::List alarmsTo( const KDateTime &to ); |
340 | |
341 | /** |
342 | Set the time specification (time zone, etc.). |
343 | |
344 | @param timeSpec the time specification to set |
345 | @see timeSpec() |
346 | */ |
347 | void setTimeSpec( const KDateTime::Spec &timeSpec ); |
348 | |
349 | /** |
350 | Get the viewing time specification (time zone etc.) for the calendar. |
351 | |
352 | @return time specification |
353 | */ |
354 | KDateTime::Spec timeSpec() const; |
355 | |
356 | /** |
357 | Set id of timezone, e.g. "Europe/Berlin" |
358 | |
359 | @param timeZoneId the identifier for the timezone |
360 | @see timeZoneId() |
361 | */ |
362 | void setTimeZoneId( const QString &timeZoneId ); |
363 | |
364 | /** |
365 | Returns the viewing time zone ID for the resource. |
366 | |
367 | @return the string containing the time zone ID, or empty string if the |
368 | viewing time specification is not a time zone. |
369 | */ |
370 | QString timeZoneId() const; |
371 | |
372 | /** |
373 | @copydoc |
374 | ResourceCalendar::shiftTimes() |
375 | */ |
376 | virtual void shiftTimes( const KDateTime::Spec &oldSpec, const KDateTime::Spec &newSpec ); |
377 | |
378 | /** |
379 | Return the owner of the calendar's full name. |
380 | */ |
381 | Person owner() const; |
382 | |
383 | /** |
384 | Set the owner of the calendar. Should be owner's full name. |
385 | @param owner the person who owns this calendar resource |
386 | */ |
387 | void setOwner( const Person &owner ); |
388 | |
389 | void enableChangeNotification(); |
390 | void disableChangeNotification(); |
391 | |
392 | void clearChange( Incidence *incidence ); |
393 | void clearChange( const QString &uid ); |
394 | |
395 | void clearChanges(); |
396 | |
397 | bool hasChanges() const; |
398 | |
399 | Incidence::List allChanges() const; |
400 | |
401 | Incidence::List addedIncidences() const; |
402 | Incidence::List changedIncidences() const; |
403 | Incidence::List deletedIncidences() const; |
404 | |
405 | /** |
406 | Load the resource from the cache. |
407 | @return true if the cache file exists, false if not |
408 | */ |
409 | bool loadFromCache(); |
410 | |
411 | /** |
412 | Save the resource back to the cache. |
413 | */ |
414 | void saveToCache(); |
415 | |
416 | /** |
417 | Clear cache. |
418 | */ |
419 | void clearCache(); |
420 | |
421 | void cleanUpEventCache( const KCal::Event::List &eventList ); |
422 | void cleanUpTodoCache( const KCal::Todo::List &todoList ); |
423 | |
424 | /** |
425 | Returns a reference to the id mapper. |
426 | */ |
427 | KRES::IdMapper &idMapper(); |
428 | |
429 | using QObject::event; // prevent warning about hidden virtual method |
430 | |
431 | protected: |
432 | CalendarLocal *calendar() const; |
433 | |
434 | // From Calendar::CalendarObserver |
435 | void calendarIncidenceAdded( KCal::Incidence *incidence ); |
436 | void calendarIncidenceChanged( KCal::Incidence *incidence ); |
437 | void calendarIncidenceDeleted( KCal::Incidence *incidence ); |
438 | |
439 | /** |
440 | Virtual method from KRES::Resource, called when the last instace of the |
441 | resource is closed |
442 | */ |
443 | virtual void doClose(); |
444 | |
445 | /** |
446 | Opens the resource. Dummy implementation, so child classes don't have to |
447 | reimplement this method. By default, this does not do anything, but can be |
448 | reimplemented in child classes |
449 | */ |
450 | virtual bool doOpen(); |
451 | |
452 | /** |
453 | Do the actual loading of the resource data. Called by load(CacheAction). |
454 | */ |
455 | virtual bool doLoad( bool syncCache ) = 0; |
456 | |
457 | /** |
458 | Set the cache-reloaded status. Non-local resources must set this true once |
459 | the cache has been downloaded successfully. |
460 | |
461 | @param done the new cache-reloaded status |
462 | */ |
463 | void setReloaded( bool done ); |
464 | |
465 | /** |
466 | Do the actual saving of the resource data. Called by save(CacheAction). |
467 | Saves the resource data to the cache and optionally uploads (if a remote |
468 | resource). |
469 | |
470 | @param syncCache if true, the cache will be uploaded to the remote |
471 | resource. If false, only the cache will be updated. |
472 | */ |
473 | virtual bool doSave( bool syncCache ) = 0; |
474 | |
475 | /** |
476 | Do the actual saving of the resource data. Called by save(CacheAction). |
477 | Save one Incidence. The default implementation calls doSave(bool) to |
478 | save everything. |
479 | |
480 | @param syncCache if @c true, the cache will be uploaded to the remote |
481 | resource. If @c false, only the cache will be updated |
482 | @param incidence The incidence to be saved. |
483 | */ |
484 | virtual bool doSave( bool syncCache, Incidence *incidence ); |
485 | |
486 | /** |
487 | Check if reload required according to reload policy. |
488 | */ |
489 | bool checkForReload(); |
490 | |
491 | /** |
492 | Check if save required according to save policy. |
493 | */ |
494 | bool checkForSave(); |
495 | |
496 | void checkForAutomaticSave(); |
497 | |
498 | void addInfoText( QString & ) const; |
499 | |
500 | void setupSaveTimer(); |
501 | void setupReloadTimer(); |
502 | |
503 | /** |
504 | This method is used by loadFromCache() and saveToCache(), reimplement |
505 | it to change the location of the cache. |
506 | */ |
507 | virtual QString cacheFile() const; |
508 | |
509 | /** |
510 | Functions for keeping the changes persistent. |
511 | */ |
512 | virtual QString changesCacheFile( const QString &type ) const; |
513 | void loadChangesCache( QMap<Incidence *, bool> &map, const QString &type ); |
514 | void loadChangesCache(); |
515 | void saveChangesCache( const QMap<Incidence *, bool> &map, const QString &type ); |
516 | void saveChangesCache(); |
517 | |
518 | protected Q_SLOTS: |
519 | void slotReload(); |
520 | void slotSave(); |
521 | |
522 | void setIdMapperIdentifier(); |
523 | |
524 | private: |
525 | //@cond PRIVATE |
526 | Q_DISABLE_COPY( ResourceCached ) |
527 | class Private; |
528 | Private *const d; |
529 | //@endcond |
530 | }; |
531 | |
532 | } |
533 | |
534 | #endif |
535 | |