Akonadi

preprocessorbase.h
1 /******************************************************************************
2  *
3  * SPDX-FileCopyrightText: 2009 Szymon Stefanek <s.stefanek at gmail dot com>
4  *
5  * SPDX-License-Identifier: LGPL-2.0-or-later
6  *
7  *****************************************************************************/
8 
9 #pragma once
10 
11 #include "agentbase.h"
12 #include "akonadiagentbase_export.h"
13 // AkonadiCore
14 #include <akonadi/collection.h>
15 #include <akonadi/item.h>
16 
17 namespace Akonadi
18 {
19 class ItemFetchScope;
20 
21 class PreprocessorBasePrivate;
22 
23 /**
24  * @short The base class for all Akonadi preprocessor agents.
25  *
26  * This class should be used as a base class by all preprocessor agents
27  * since it encapsulates large parts of the protocol between
28  * preprocessor agent, agent manager and the Akonadi storage.
29  *
30  * Preprocessor agents are special agents that are informed about newly
31  * added items before any other agents. This allows them to do filtering
32  * on the items or any other task that shall be done before the new item
33  * is visible in the Akonadi storage system.
34  *
35  * The method all the preprocessors must implement is processItem().
36  *
37  * @author Szymon Stefanek <[email protected]>
38  * @since 4.4
39  */
40 class AKONADIAGENTBASE_EXPORT PreprocessorBase : public AgentBase
41 {
42  Q_OBJECT
43 
44 public:
45  /**
46  * Describes the possible return values of the processItem() method.
47  */
48  enum ProcessingResult {
49  /**
50  * Processing completed successfully for this item.
51  * The Akonadi server will push in a new item when it's available.
52  */
53  ProcessingCompleted,
54 
55  /**
56  * Processing was delayed to a later stage.
57  * This must be returned when implementing asynchronous preprocessing.
58  *
59  * If this value is returned, finishProcessing() has to be called
60  * when processing is done.
61  */
62  ProcessingDelayed,
63 
64  /**
65  * Processing for this item failed (and the failure is unrecoverable).
66  * The Akonadi server will push in a new item when it's available,
67  * after possibly logging the failure.
68  */
69  ProcessingFailed,
70 
71  /**
72  * Processing for this item was refused. This is very
73  * similar to ProcessingFailed above but additionally remarks
74  * that the item that the Akonadi server pushed in wasn't
75  * meant for this Preprocessor.
76  * The Akonadi server will push in a new item when it's available,
77  * after possibly logging the failure and maybe taking some additional action.
78  */
79  ProcessingRefused
80  };
81 
82  /**
83  * This method must be implemented by every preprocessor subclass.
84  * @param item the item to process
85  * It must realize the preprocessing of the given @p item.
86  *
87  * The Akonadi server will push in for preprocessing any newly created item:
88  * it's your responsibility to decide if you want to process the item or not.
89  *
90  * The method should return ProcessingCompleted on success, ProcessingDelayed
91  * if processing is implemented asynchronously and
92  * ProcessingRefused or ProcessingFailed if the processing
93  * didn't complete.
94  *
95  * If your operation is asynchronous then you should also
96  * connect to the abortRequested() signal and handle it
97  * appropriately (as the server MAY abort your async job
98  * if it decides that it's taking too long).
99  */
100  virtual ProcessingResult processItem(const Item &item) = 0;
101 
102  /**
103  * This method must be called if processing is implemented asynchronously.
104  * @param result the processing result
105  * You should call it when you have completed the processing
106  * or if an abortRequest() signal arrives (and in this case you
107  * will probably use ProcessingFailed as result).
108  *
109  * Valid values for @p result are ProcessingCompleted,
110  * PocessingRefused and ProcessingFailed. Passing any
111  * other value will lead to a runtime assertion.
112  */
113  void finishProcessing(ProcessingResult result);
114 
115  /**
116  * Sets the item fetch scope.
117  *
118  * The ItemFetchScope controls how much of an item's data is fetched
119  * from the server, e.g. whether to fetch the full item payload or
120  * only meta data.
121  *
122  * @param fetchScope The new scope for item fetch operations.
123  *
124  * @see fetchScope()
125  */
126  void setFetchScope(const ItemFetchScope &fetchScope);
127 
128  /**
129  * Returns the item fetch scope.
130  *
131  * Since this returns a reference it can be used to conveniently modify the
132  * current scope in-place, i.e. by calling a method on the returned reference
133  * without storing it in a local variable. See the ItemFetchScope documentation
134  * for an example.
135  *
136  * @return a reference to the current item fetch scope
137  *
138  * @see setFetchScope() for replacing the current item fetch scope
139  */
140  ItemFetchScope &fetchScope();
141 
142 protected:
143  /**
144  * Creates a new preprocessor base agent.
145  *
146  * @param id The instance id of the preprocessor base agent.
147  */
148  PreprocessorBase(const QString &id);
149 
150  /**
151  * Destroys the preprocessor base agent.
152  */
153  ~PreprocessorBase() override;
154 
155 private:
156  /// @cond PRIVATE
157  Q_DECLARE_PRIVATE(PreprocessorBase)
158  /// @endcond
159 
160 }; // class PreprocessorBase
161 
162 } // namespace Akonadi
163 
164 #ifndef AKONADI_PREPROCESSOR_MAIN
165 /**
166  * Convenience Macro for the most common main() function for Akonadi preprocessors.
167  */
168 #define AKONADI_PREPROCESSOR_MAIN(preProcessorClass) \
169  int main(int argc, char **argv) \
170  { \
171  return Akonadi::PreprocessorBase::init<preProcessorClass>(argc, argv); \
172  }
173 #endif //! AKONADI_RESOURCE_MAIN
174 
ProcessingResult
Describes the possible return values of the processItem() method.
The base class for all Akonadi preprocessor agents.
Represents a PIM item stored in Akonadi storage.
Definition: item.h:104
Specifies which parts of an item should be fetched from the Akonadi storage.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Thu Jun 30 2022 03:51:46 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.