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
17namespace Akonadi
18{
19class ItemFetchScope;
20
21class 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 <s.stefanek@gmail.com>
38 * @since 4.4
39 */
40class AKONADIAGENTBASE_EXPORT PreprocessorBase : public AgentBase
41{
42 Q_OBJECT
43
44public:
45 /**
46 * Describes the possible return values of the processItem() method.
47 */
49 /**
50 * Processing completed successfully for this item.
51 * The Akonadi server will push in a new item when it's available.
52 */
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 */
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 */
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
142protected:
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
155private:
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
The base class for all Akonadi agents and resources.
Definition agentbase.h:73
Specifies which parts of an item should be fetched from the Akonadi storage.
Represents a PIM item stored in Akonadi storage.
Definition item.h:100
The base class for all Akonadi preprocessor agents.
virtual ProcessingResult processItem(const Item &item)=0
This method must be implemented by every preprocessor subclass.
ProcessingResult
Describes the possible return values of the processItem() method.
@ ProcessingDelayed
Processing was delayed to a later stage.
@ ProcessingCompleted
Processing completed successfully for this item.
@ ProcessingFailed
Processing for this item failed (and the failure is unrecoverable).
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.