Akonadi

resourcebase.h
1/*
2 This file is part of akonadiresources.
3
4 SPDX-FileCopyrightText: 2006 Till Adam <adam@kde.org>
5 SPDX-FileCopyrightText: 2007 Volker Krause <vkrause@kde.org>
6
7 SPDX-License-Identifier: LGPL-2.0-or-later
8*/
9
10#pragma once
11
12#include "agentbase.h"
13#include "akonadiagentbase_export.h"
14// AkonadiCore
15#include "akonadi/collection.h"
16#include "akonadi/item.h"
17#include "akonadi/itemsync.h"
18
19class KJob;
20class Akonadi__ResourceAdaptor;
21class ResourceState;
22
23namespace Akonadi
24{
25class ResourceBasePrivate;
26
27/**
28 * @short The base class for all Akonadi resources.
29 *
30 * This class should be used as a base class by all resource agents,
31 * because it encapsulates large parts of the protocol between
32 * resource agent, agent manager and the Akonadi storage.
33 *
34 * It provides many convenience methods to make implementing a
35 * new Akonadi resource agent as simple as possible.
36 *
37 * <h4>How to write a resource</h4>
38 *
39 * The following provides an overview of what you need to do to implement
40 * your own Akonadi resource. In the following, the term 'backend' refers
41 * to the entity the resource connects with Akonadi, be it a single file
42 * or a remote server.
43 *
44 * @todo Complete this (online/offline state management)
45 *
46 * <h5>Basic %Resource Framework</h5>
47 *
48 * The following is needed to create a new resource:
49 * - A new class deriving from Akonadi::ResourceBase, implementing at least all
50 * pure-virtual methods, see below for further details.
51 * - call init() in your main() function.
52 * - a .desktop file similar to the following example
53 * \code
54 * [Desktop Entry]
55 * Name=My Akonadi Resource
56 * Type=AkonadiResource
57 * Exec=akonadi_my_resource
58 * Icon=my-icon
59 *
60 * X-Akonadi-MimeTypes=<supported-mimetypes>
61 * X-Akonadi-Capabilities=Resource
62 * X-Akonadi-Identifier=akonadi_my_resource
63 * \endcode
64 *
65 * <h5>Handling PIM Items</h5>
66 *
67 * To follow item changes in the backend, the following steps are necessary:
68 * - Implement retrieveItems() to synchronize all items in the given
69 * collection. If the backend supports incremental retrieval,
70 * implementing support for that is recommended to improve performance.
71 * - Convert the items provided by the backend to Akonadi items.
72 * This typically happens either in retrieveItems() if you retrieved
73 * the collection synchronously (not recommended for network backends) or
74 * in the result slot of the asynchronous retrieval job.
75 * Converting means to create Akonadi::Item objects for every retrieved
76 * item. It's very important that every object has its remote identifier set.
77 * - Call itemsRetrieved() or itemsRetrievedIncremental() respectively
78 * with the item objects created above. The Akonadi storage will then be
79 * updated automatically. Note that it is usually not necessary to manipulate
80 * any item in the Akonadi storage manually.
81 *
82 * To fetch item data on demand, the method retrieveItem() needs to be
83 * reimplemented. Fetch the requested data there and call itemRetrieved()
84 * with the result item.
85 *
86 * To write local changes back to the backend, you need to re-implement
87 * the following three methods:
88 * - itemAdded()
89 * - itemChanged()
90 * - itemRemoved()
91 *
92 * Note that these three functions don't get the full payload of the items by default,
93 * you need to change the item fetch scope of the change recorder to fetch the full
94 * payload. This can be expensive with big payloads, though.<br>
95 * Once you have handled changes in itemAdded() and itemChanged(), call changeCommitted().
96 * Once you have handled changes in itemRemoved(), call changeProcessed();
97 * These methods are called whenever a local item related to this resource is
98 * added, modified or deleted. They are only called if the resource is online, otherwise
99 * all changes are recorded and replayed as soon the resource is online again.
100 *
101 * <h5>Handling Collections</h5>
102 *
103 * To follow collection changes in the backend, the following steps are necessary:
104 * - Implement retrieveCollections() to retrieve collections from the backend.
105 * If the backend supports incremental collections updates, implementing
106 * support for that is recommended to improve performance.
107 * - Convert the collections of the backend to Akonadi collections.
108 * This typically happens either in retrieveCollections() if you retrieved
109 * the collection synchronously (not recommended for network backends) or
110 * in the result slot of the asynchronous retrieval job.
111 * Converting means to create Akonadi::Collection objects for every retrieved
112 * collection. It's very important that every object has its remote identifier
113 * and its parent remote identifier set.
114 * - Call collectionsRetrieved() or collectionsRetrievedIncremental() respectively
115 * with the collection objects created above. The Akonadi storage will then be
116 * updated automatically. Note that it is usually not necessary to manipulate
117 * any collection in the Akonadi storage manually.
118 *
119 *
120 * To write local collection changes back to the backend, you need to re-implement
121 * the following three methods:
122 * - collectionAdded()
123 * - collectionChanged()
124 * - collectionRemoved()
125 * Once you have handled changes in collectionAdded() and collectionChanged(), call changeCommitted().
126 * Once you have handled changes in collectionRemoved(), call changeProcessed();
127 * These methods are called whenever a local collection related to this resource is
128 * added, modified or deleted. They are only called if the resource is online, otherwise
129 * all changes are recorded and replayed as soon the resource is online again.
130 *
131 * @todo Convenience base class for collection-less resources
132 */
133// FIXME_API: API dox need to be updated for Observer approach (kevin)
134class AKONADIAGENTBASE_EXPORT ResourceBase : public AgentBase
135{
136 Q_OBJECT
137
138public:
139 /**
140 * This method is used to set the name of the resource.
141 */
142 void setName(const QString &name);
143
144 /**
145 * Returns the name of the resource.
146 */
147 [[nodiscard]] QString name() const;
148
149 /**
150 * This method sets list of activities.
151 */
152 void setActivities(const QStringList &activities);
153
154 /**
155 * return list of activities.
156 */
157 [[nodiscard]] QStringList activities() const;
158
159 /**
160 * This method enables or not activities support.
161 */
162 void setActivitiesEnabled(bool enable);
163
164 /**
165 * Returns true if activities is enabled.
166 */
167 [[nodiscard]] bool activitiesEnabled() const;
168
169 /**
170 * Enable or disable automatic progress reporting. By default, it is enabled.
171 * When enabled, the resource will automatically emit the signals percent() and status()
172 * while syncing items or collections.
173 *
174 * The automatic progress reporting is done on a per item / per collection basis, so if a
175 * finer granularity is desired, automatic reporting should be disabled and the subclass should
176 * emit the percent() and status() signals itself.
177 *
178 * @param enabled Whether or not automatic emission of the signals is enabled.
179 * @since 4.7
180 */
181 void setAutomaticProgressReporting(bool enabled);
182
183Q_SIGNALS:
184 /**
185 * This signal is emitted whenever the name of the resource has changed.
186 *
187 * @param name The new name of the resource.
188 */
189 void nameChanged(const QString &name);
190
191 /**
192 * Emitted when a full synchronization has been completed.
193 */
194 void synchronized();
195
196 /**
197 * Emitted when a collection attributes synchronization has been completed.
198 *
199 * @param collectionId The identifier of the collection whose attributes got synchronized.
200 * @since 4.6
201 */
202 void attributesSynchronized(qlonglong collectionId);
203
204 /**
205 * Emitted when a collection tree synchronization has been completed.
206 *
207 * @since 4.8
208 */
210
211 /**
212 * Emitted when the item synchronization processed the current batch and is ready for a new one.
213 * Use this to throttle the delivery to not overload Akonadi.
214 *
215 * Throttling can be used during item retrieval (retrieveItems(Akonadi::Collection)) in streaming mode.
216 * To throttle only deliver itemSyncBatchSize() items, and wait for this signal, then again deliver
217 * @param remainingBatchSize items.
218 *
219 * By always only providing the number of items required to process the batch, the items don't pile
220 * up in memory and items are only provided as fast as Akonadi can process them.
221 *
222 * @see batchSize()
223 *
224 * @since 4.14
225 */
226 void retrieveNextItemSyncBatch(int remainingBatchSize);
227
228protected Q_SLOTS:
229 /**
230 * Retrieve the collection tree from the remote server and supply it via
231 * collectionsRetrieved() or collectionsRetrievedIncremental().
232 * @see collectionsRetrieved(), collectionsRetrievedIncremental()
233 */
234 virtual void retrieveCollections() = 0;
235
236 /**
237 * Retrieve all tags from the backend
238 * @see tagsRetrieved()
239 */
240 virtual void retrieveTags();
241
242 /**
243 * Retrieve the attributes of a single collection from the backend. The
244 * collection to retrieve attributes for is provided as @p collection.
245 * Add the attributes parts and call collectionAttributesRetrieved()
246 * when done.
247 *
248 * @param collection The collection whose attributes should be retrieved.
249 * @see collectionAttributesRetrieved()
250 * @since 4.6
251 */
252 virtual void retrieveCollectionAttributes(const Akonadi::Collection &collection);
253
254 /**
255 * Retrieve all (new/changed) items in collection @p collection.
256 * It is recommended to use incremental retrieval if the backend supports that
257 * and provide the result by calling itemsRetrievedIncremental().
258 * If incremental retrieval is not possible, provide the full listing by calling
259 * itemsRetrieved( const Item::List& ).
260 * In any case, ensure that all items have a correctly set remote identifier
261 * to allow synchronizing with items already existing locally.
262 * In case you don't want to use the built-in item syncing code, store the retrieved
263 * items manually and call itemsRetrieved() once you are done.
264 * @param collection The collection whose items to retrieve.
265 * @see itemsRetrieved( const Item::List& ), itemsRetrievedIncremental(), itemsRetrieved(), currentCollection(), batchSize()
266 */
267 virtual void retrieveItems(const Akonadi::Collection &collection) = 0;
268
269 /**
270 * Returns the batch size used during the item sync.
271 *
272 * This can be used to throttle the item delivery.
273 *
274 * @see retrieveNextItemSyncBatch(int), retrieveItems(Akonadi::Collection)
275 * @since 4.14
276 */
277 [[nodiscard]] int itemSyncBatchSize() const;
278
279 /**
280 * Set the batch size used during the item sync.
281 * The default is 10.
282 *
283 * @see retrieveNextItemSyncBatch(int)
284 * @since 4.14
285 */
286 void setItemSyncBatchSize(int batchSize);
287
288 /**
289 * Set to true to schedule an attribute sync before every item sync.
290 * The default is false.
291 *
292 * @since 4.15
293 */
294 void setScheduleAttributeSyncBeforeItemSync(bool);
295
296 /**
297 * Retrieve a single item from the backend. The item to retrieve is provided as @p item.
298 * Add the requested payload parts and call itemRetrieved() when done.
299 * @param item The empty item whose payload should be retrieved. Use this object when delivering
300 * the result instead of creating a new item to ensure conflict detection will work.
301 * @param parts The item parts that should be retrieved.
302 * @return false if there is an immediate error when retrieving the item.
303 * @see itemRetrieved()
304 * @deprecated Use retrieveItems(const Akonadi::Item::List &, const QSet<QByteArray> &) instead.
305 */
306 AKONADIAGENTBASE_DEPRECATED virtual bool retrieveItem(const Akonadi::Item &item, const QSet<QByteArray> &parts);
307
308 /**
309 * Retrieve given @p items from the backend.
310 * Add the requested payload parts and call itemsRetrieved() when done.
311 * It is guaranteed that all @p items in the list belong to the same Collection.
312 *
313 * If the items are retrieved synchronously in this method, in case of an error
314 * emit error(const QString &) and return @c false, which will cancel the current task.
315 * If the items are retrieved asynchronously, in case of an non-immediate error you need
316 * to call cancelTask() or cancelTask(const QString&) in the respective handler methods
317 * explicitly.
318 *
319 * @param items The items whose payload should be retrieved. Use those objects
320 * when delivering the result instead of creating new items to ensure conflict
321 * detection will work.
322 * @param parts The item parts that should be retrieved.
323 * @return false if there is an immediate error when retrieving the items.
324 * @see itemsRetrieved()
325 * @since 5.4
326 *
327 * @todo: Make this method pure virtual once retrieveItem() is gone
328 */
329 virtual bool retrieveItems(const Akonadi::Item::List &items, const QSet<QByteArray> &parts);
330
331 /**
332 * Abort any activity in progress in the backend. By default this method does nothing.
333 *
334 * @since 4.6
335 */
336 virtual void abortActivity();
337
338 /**
339 * Dump resource internals, for debugging.
340 * @since 4.9
341 */
343 {
344 return QString();
345 }
346
347protected:
348 /**
349 * Creates a base resource.
350 *
351 * @param id The instance id of the resource.
352 */
353 ResourceBase(const QString &id);
354
355 /**
356 * Destroys the base resource.
357 */
358 ~ResourceBase() override;
359
360 /**
361 * Call this method from retrieveItem() once the result is available.
362 *
363 * @param item The retrieved item.
364 */
365 void itemRetrieved(const Item &item);
366
367 /**
368 * Call this method from retrieveCollectionAttributes() once the result is available.
369 *
370 * @param collection The collection whose attributes got retrieved.
371 * @since 4.6
372 */
373 void collectionAttributesRetrieved(const Collection &collection);
374
375 /**
376 * Resets the dirty flag of the given item and updates the remote id.
377 *
378 * Call whenever you have successfully written changes back to the server.
379 * This implicitly calls changeProcessed().
380 * @param item The changed item.
381 */
382 void changeCommitted(const Item &item);
383
384 /**
385 * Resets the dirty flag of all given items and updates remote ids.
386 *
387 * Call whenever you have successfully written changes back to the server.
388 * This implicitly calls changeProcessed().
389 * @param items Changed items
390 *
391 * @since 4.11
392 */
393 void changesCommitted(const Item::List &items);
394
395 /**
396 * Resets the dirty flag of the given tag and updates the remote id.
397 *
398 * Call whenever you have successfully written changes back to the server.
399 * This implicitly calls changeProcessed().
400 * @param tag Changed tag.
401 *
402 * @since 4.13
403 */
404 void changeCommitted(const Tag &tag);
405
406 /**
407 * Call whenever you have successfully handled or ignored a collection
408 * change notification.
409 *
410 * This will update the remote identifier of @p collection if necessary,
411 * as well as any other collection attributes.
412 * This implicitly calls changeProcessed().
413 * @param collection The collection which changes have been handled.
414 */
415 void changeCommitted(const Collection &collection);
416
417 /**
418 * Call this to supply the full folder tree retrieved from the remote server.
419 *
420 * @param collections A list of collections.
421 * @see collectionsRetrievedIncremental()
422 */
423 void collectionsRetrieved(const Collection::List &collections);
424
425 void tagsRetrieved(const Tag::List &tags, const QHash<QString, Item::List> &tagMembers);
426
427 /**
428 * Call this to supply incrementally retrieved collections from the remote server.
429 *
430 * @param changedCollections Collections that have been added or changed.
431 * @param removedCollections Collections that have been deleted.
432 * @see collectionsRetrieved()
433 */
434 void collectionsRetrievedIncremental(const Collection::List &changedCollections, const Collection::List &removedCollections);
435
436 /**
437 * Enable collection streaming, that is collections don't have to be delivered at once
438 * as result of a retrieveCollections() call but can be delivered by multiple calls
439 * to collectionsRetrieved() or collectionsRetrievedIncremental(). When all collections
440 * have been retrieved, call collectionsRetrievalDone().
441 * @param enable @c true if collection streaming should be enabled, @c false by default
442 */
443 void setCollectionStreamingEnabled(bool enable);
444
445 /**
446 * Call this method to indicate you finished synchronizing the collection tree.
447 *
448 * This is not needed if you use the built in syncing without collection streaming
449 * and call collectionsRetrieved() or collectionRetrievedIncremental() instead.
450 * If collection streaming is enabled, call this method once all collections have been delivered
451 * using collectionsRetrieved() or collectionsRetrievedIncremental().
452 */
453 void collectionsRetrievalDone();
454
455 /**
456 * Allows to keep locally changed collection parts during the collection sync.
457 *
458 * This is useful for resources to be able to provide default values during the collection
459 * sync, while preserving eventual more up-to date values.
460 *
461 * Valid values are attribute types and "CONTENTMIMETYPE" for the collections content mimetypes.
462 *
463 * By default this is enabled for the EntityDisplayAttribute.
464 *
465 * @param parts A set parts for which local changes should be preserved.
466 * @since 4.14
467 */
468 void setKeepLocalCollectionChanges(const QSet<QByteArray> &parts);
469
470 /**
471 * Call this method to supply the full collection listing from the remote server. Items not present in the list
472 * will be dropped from the Akonadi database.
473 *
474 * If the remote server supports incremental listing, it's strongly
475 * recommended to use itemsRetrievedIncremental() instead.
476 * @param items A list of items.
477 * @see itemsRetrievedIncremental().
478 */
479 void itemsRetrieved(const Item::List &items);
480
481 /**
482 * Call this method when you want to use the itemsRetrieved() method
483 * in streaming mode and indicate the amount of items that will arrive
484 * that way.
485 *
486 * @warning By default this will end the item sync automatically once
487 * sufficient items were delivered. To disable this and only make use
488 * of the progress reporting, use setDisableAutomaticItemDeliveryDone()
489 *
490 * @note The recommended way is therefore:
491 * @code
492 * setDisableAutomaticItemDeliveryDone(true);
493 * setItemStreamingEnabled(true);
494 * setTotalItems(X); // X = sum of all items in all batches
495 * while (...) {
496 * itemsRetrievedIncremental(...);
497 * // or itemsRetrieved(...);
498 * }
499 * itemsRetrievalDone();
500 * @endcode
501 *
502 * @param amount number of items that will arrive in streaming mode
503 * @see setDisableAutomaticItemDeliveryDone(bool)
504 * @see setItemStreamingEnabled(bool)
505 */
506 void setTotalItems(int amount);
507
508 /**
509 * Disables the automatic completion of the item sync,
510 * based on the number of delivered items.
511 *
512 * This ensures that the item sync only finishes once itemsRetrieved()
513 * is called, while still making it possible to use the automatic progress
514 * reporting based on setTotalItems().
515 *
516 * @note This needs to be called once, before the item sync is started.
517 *
518 * @see setTotalItems(int)
519 * @since 4.14
520 */
521 void setDisableAutomaticItemDeliveryDone(bool disable);
522
523 /**
524 * Enable item streaming, which is disabled by default.
525 * Item streaming means that the resource can call setTotalItems(),
526 * and then itemsRetrieved() or itemsRetrievedIncremental() multiple times,
527 * in chunks. When all is done, the resource should call itemsRetrievalDone().
528 * @param enable @c true if items are delivered in chunks rather in one big block.
529 * @see setTotalItems(int)
530 */
531 void setItemStreamingEnabled(bool enable);
532
533 /**
534 * Set transaction mode for item sync'ing.
535 * @param mode item transaction mode
536 * @see Akonadi::ItemSync::TransactionMode
537 * @since 4.6
538 */
539 void setItemTransactionMode(ItemSync::TransactionMode mode);
540
541 /**
542 * Set merge mode for item sync'ing.
543 *
544 * Default merge mode is RIDMerge.
545 *
546 * @note This method must be called before first call to itemRetrieved(),
547 * itemsRetrieved() or itemsRetrievedIncremental().
548 *
549 * @param mode Item merging mode (see ItemCreateJob for details on item merging)
550 * @see Akonadi::ItemSync::MergeMode
551 * @since 4.14.11
552 */
553 void setItemMergingMode(ItemSync::MergeMode mode);
554
555 /**
556 * Call this method to supply incrementally retrieved items from the remote server.
557 *
558 * @param changedItems Items changed in the backend.
559 * @param removedItems Items removed from the backend.
560 */
561 void itemsRetrievedIncremental(const Item::List &changedItems, const Item::List &removedItems);
562
563 /**
564 * Call this method to indicate you finished synchronizing the current collection.
565 *
566 * This is not needed if you use the built in syncing without item streaming
567 * and call itemsRetrieved() or itemsRetrievedIncremental() instead.
568 * If item streaming is enabled, call this method once all items have been delivered
569 * using itemsRetrieved() or itemsRetrievedIncremental().
570 * @see retrieveItems()
571 */
572 void itemsRetrievalDone();
573
574 /**
575 * Call this method to remove all items and collections of the resource from the
576 * server cache.
577 *
578 * The method should not be used anymore
579 *
580 * @see invalidateCache()
581 * @since 4.3
582 */
583 void clearCache();
584
585 /**
586 * Call this method to invalidate all cached content in @p collection.
587 *
588 * The method should be used when the backend indicated that the cached content
589 * is no longer valid.
590 *
591 * @param collection parent of the content to be invalidated in cache
592 * @since 4.8
593 */
594 void invalidateCache(const Collection &collection);
595
596 /**
597 * Returns the collection that is currently synchronized.
598 * @note Calling this method is only allowed during a collection synchronization task, that
599 * is directly or indirectly from retrieveItems().
600 */
601 [[nodiscard]] Collection currentCollection() const;
602
603 /**
604 * Returns the item that is currently retrieved.
605 * @note Calling this method is only allowed during fetching a single item, that
606 * is directly or indirectly from retrieveItem().
607 */
608 AKONADIAGENTBASE_DEPRECATED Item currentItem() const;
609
610 /**
611 * Returns the items that are currently retrieved.
612 * @note Calling this method is only allowed during item fetch, that is
613 * directly or indirectly from retrieveItems(Akonadi::Item::List,QSet<QByteArray>)
614 */
615 [[nodiscard]] Item::List currentItems() const;
616
617 /**
618 * This method is called whenever the resource should start synchronize all data.
619 */
620 void synchronize();
621
622 /**
623 * This method is called whenever the collection with the given @p id
624 * shall be synchronized.
625 */
626 void synchronizeCollection(qint64 id);
627
628 /**
629 * This method is called whenever the collection with the given @p id
630 * shall be synchronized.
631 * @param recursive if true, a recursive synchronization is done
632 */
633 void synchronizeCollection(qint64 id, bool recursive);
634
635 /**
636 * This method is called whenever the collection with the given @p id
637 * shall have its attributes synchronized.
638 *
639 * @param id The id of the collection to synchronize
640 * @since 4.6
641 */
642 void synchronizeCollectionAttributes(qint64 id);
643
644 /**
645 * Synchronizes the collection attributes.
646 *
647 * @param col The id of the collection to synchronize
648 * @since 4.15
649 */
650 void synchronizeCollectionAttributes(const Akonadi::Collection &col);
651
652 /**
653 * Refetches the Collections.
654 */
655 void synchronizeCollectionTree();
656
657 /**
658 * Refetches Tags.
659 */
660 void synchronizeTags();
661
662 /**
663 * Stops the execution of the current task and continues with the next one.
664 */
665 void cancelTask();
666
667 /**
668 * Stops the execution of the current task and continues with the next one.
669 * Additionally an error message is emitted.
670 * @param error additional error message to be emitted
671 */
672 void cancelTask(const QString &error);
673
674 /**
675 * Suspends the execution of the current task and tries again to execute it.
676 *
677 * This can be used to delay the task processing until the resource has reached a safe
678 * state, e.g. login to a server succeeded.
679 *
680 * @note This does not change the order of tasks so if there is no task with higher priority
681 * e.g. a custom task added with #Prepend the deferred task will be processed again.
682 *
683 * @since 4.3
684 */
685 void deferTask();
686
687 /**
688 * Inherited from AgentBase.
689 *
690 * When going offline, the scheduler aborts the current task, so you should
691 * do the same in your resource, if the task implementation is asynchronous.
692 */
693 void doSetOnline(bool online) override;
694
695 /**
696 * Indicate the use of hierarchical remote identifiers.
697 *
698 * This means that it is possible to have two different items with the same
699 * remoteId in different Collections.
700 *
701 * This should be called in the resource constructor as needed.
702 *
703 * @param enable whether to enable use of hierarchical remote identifiers
704 * @since 4.4
705 */
706 void setHierarchicalRemoteIdentifiersEnabled(bool enable);
707
708 friend class ResourceScheduler;
709 friend class ::ResourceState;
710
711 /**
712 * Describes the scheduling priority of a task that has been queued
713 * for execution.
714 *
715 * @see scheduleCustomTask
716 * @since 4.4
717 */
719 Prepend, ///< The task will be executed as soon as the current task has finished.
720 AfterChangeReplay, ///< The task is scheduled after the last ChangeReplay task in the queue
721 Append ///< The task will be executed after all tasks currently in the queue are finished
722 };
723
724 /**
725 * Schedules a custom task in the internal scheduler. It will be queued with
726 * all other tasks such as change replays and retrieval requests and eventually
727 * executed by calling the specified method. With the priority parameter the
728 * time of execution of the Task can be influenced. @see SchedulePriority
729 * @param receiver The object the slot should be called on.
730 * @param method The name of the method (and only the name, not signature, not SLOT(...) macro),
731 * that should be called to execute this task. The method has to be a slot and take a QVariant as
732 * argument.
733 * @param argument A QVariant argument passed to the method specified above. Use this to pass task
734 * parameters.
735 * @param priority Priority of the task. Use this to influence the position in
736 * the execution queue.
737 * @since 4.4
738 */
739 void scheduleCustomTask(QObject *receiver, const char *method, const QVariant &argument, SchedulePriority priority = Append);
740
741 /**
742 * Indicate that the current task is finished. Use this method from the slot called via scheduleCustomTaks().
743 * As with all the other callbacks, make sure to either call taskDone() or cancelTask()/deferTask() on all
744 * exit paths, otherwise the resource will hang.
745 * @since 4.4
746 */
747 void taskDone();
748
749 /**
750 * Dump the contents of the current ChangeReplay
751 * @since 4.8.1
752 */
753 [[nodiscard]] QString dumpNotificationListToString() const;
754
755 /**
756 * Dumps memory usage information to stdout.
757 * For now it outputs the result of glibc's mallinfo().
758 * This is useful to check if your memory problems are due to poor management by glibc.
759 * Look for a high value on fsmblks when interpreting results.
760 * man mallinfo for more details.
761 * @since 4.11
762 */
763 void dumpMemoryInfo() const;
764
765 /**
766 * Returns a string with memory usage information.
767 * @see dumpMemoryInfo()
768 *
769 * @since 4.11
770 */
771 [[nodiscard]] QString dumpMemoryInfoToString() const;
772
773 /**
774 * Dump the state of the scheduler
775 * @since 4.8.1
776 */
777 [[nodiscard]] QString dumpSchedulerToString() const;
778
779private:
780 static QString parseArguments(int argc, char **argv);
781
782 // dbus resource interface
783 friend class ::Akonadi__ResourceAdaptor;
784
785 void requestItemDelivery(const QList<qint64> &uids, const QByteArrayList &parts);
786
787private:
788 Q_DECLARE_PRIVATE(ResourceBase)
789
790 Q_PRIVATE_SLOT(d_func(), void slotAbortRequested())
791 Q_PRIVATE_SLOT(d_func(), void slotDeliveryDone(KJob *))
792 Q_PRIVATE_SLOT(d_func(), void slotCollectionSyncDone(KJob *))
793 Q_PRIVATE_SLOT(d_func(), void slotDeleteResourceCollection())
794 Q_PRIVATE_SLOT(d_func(), void slotDeleteResourceCollectionDone(KJob *))
795 Q_PRIVATE_SLOT(d_func(), void slotCollectionDeletionDone(KJob *))
796 Q_PRIVATE_SLOT(d_func(), void slotInvalidateCache(const Akonadi::Collection &))
797 Q_PRIVATE_SLOT(d_func(), void slotLocalListDone(KJob *))
798 Q_PRIVATE_SLOT(d_func(), void slotSynchronizeCollection(const Akonadi::Collection &))
799 Q_PRIVATE_SLOT(d_func(), void slotCollectionListDone(KJob *))
800 Q_PRIVATE_SLOT(d_func(), void slotSynchronizeCollectionAttributes(const Akonadi::Collection &))
801 Q_PRIVATE_SLOT(d_func(), void slotCollectionListForAttributesDone(KJob *))
802 Q_PRIVATE_SLOT(d_func(), void slotCollectionAttributesSyncDone(KJob *))
803 Q_PRIVATE_SLOT(d_func(), void slotItemSyncDone(KJob *))
804 Q_PRIVATE_SLOT(d_func(), void slotPercent(KJob *, quint64))
805 Q_PRIVATE_SLOT(d_func(), void slotDelayedEmitProgress())
806 Q_PRIVATE_SLOT(d_func(), void slotPrepareItemRetrieval(const Akonadi::Item &items))
807 Q_PRIVATE_SLOT(d_func(), void slotPrepareItemRetrievalResult(KJob *))
808 Q_PRIVATE_SLOT(d_func(), void slotPrepareItemsRetrieval(const QList<Akonadi::Item> &items))
809 Q_PRIVATE_SLOT(d_func(), void slotPrepareItemsRetrievalResult(KJob *))
810 Q_PRIVATE_SLOT(d_func(), void changeCommittedResult(KJob *))
811 Q_PRIVATE_SLOT(d_func(), void slotSessionReconnected())
812 Q_PRIVATE_SLOT(d_func(), void slotRecursiveMoveReplay(RecursiveMover *))
813 Q_PRIVATE_SLOT(d_func(), void slotRecursiveMoveReplayResult(KJob *))
814 Q_PRIVATE_SLOT(d_func(), void slotTagSyncDone(KJob *))
815 Q_PRIVATE_SLOT(d_func(), void slotSynchronizeTags())
816 Q_PRIVATE_SLOT(d_func(), void slotItemRetrievalCollectionFetchDone(KJob *))
817 Q_PRIVATE_SLOT(d_func(), void slotAttributeRetrievalCollectionFetchDone(KJob *))
818};
819
820}
821
822#ifndef AKONADI_RESOURCE_MAIN
823/**
824 * Convenience Macro for the most common main() function for Akonadi resources.
825 */
826#define AKONADI_RESOURCE_MAIN(resourceClass) \
827 int main(int argc, char **argv) \
828 { \
829 return Akonadi::ResourceBase::init<resourceClass>(argc, argv); \
830 }
831#endif
The base class for all Akonadi agents and resources.
Definition agentbase.h:73
Represents a collection of PIM items.
Definition collection.h:62
TransactionMode
Transaction mode used by ItemSync.
Definition itemsync.h:129
Represents a PIM item stored in Akonadi storage.
Definition item.h:100
The base class for all Akonadi resources.
virtual void retrieveCollections()=0
Retrieve the collection tree from the remote server and supply it via collectionsRetrieved() or colle...
SchedulePriority
Describes the scheduling priority of a task that has been queued for execution.
@ Prepend
The task will be executed as soon as the current task has finished.
@ AfterChangeReplay
The task is scheduled after the last ChangeReplay task in the queue.
void retrieveNextItemSyncBatch(int remainingBatchSize)
Emitted when the item synchronization processed the current batch and is ready for a new one.
void attributesSynchronized(qlonglong collectionId)
Emitted when a collection attributes synchronization has been completed.
virtual QString dumpResourceToString() const
Dump resource internals, for debugging.
void nameChanged(const QString &name)
This signal is emitted whenever the name of the resource has changed.
virtual void retrieveItems(const Akonadi::Collection &collection)=0
Retrieve all (new/changed) items in collection collection.
void collectionTreeSynchronized()
Emitted when a collection tree synchronization has been completed.
~ResourceBase() override
Destroys the base resource.
An Akonadi Tag.
Definition tag.h:26
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Nov 29 2024 11:49:11 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.