1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
/******************************************************************************
*
* Copyright (c) 2009 Szymon Stefanek <s.stefanek at gmail dot com>
*
* This library is free software; you can redistribute it and/or modify it
* under the terms of the GNU Library General Public License as published by
* the Free Software Foundation; either version 2 of the License, or (at your
* option) any later version.
*
* This library is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
* License for more details.
*
* You should have received a copy of the GNU Library General Public License
* along with this library; see the file COPYING.LIB. If not, write to the
* Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
* MA, 02110-1301, USA.
*
*****************************************************************************/
#ifndef AKONADI_PREPROCESSORBASE_H
#define AKONADI_PREPROCESSORBASE_H
#include "akonadi_export.h"
#include <akonadi/agentbase.h>
#include <akonadi/collection.h>
#include <akonadi/item.h>
namespace Akonadi
{
class ItemFetchScope;
class PreprocessorBasePrivate;
/**
* @short The base class for all Akonadi preprocessor agents.
*
* This class should be used as a base class by all preprocessor agents
* since it encapsulates large parts of the protocol between
* preprocessor agent, agent manager and the Akonadi storage.
*
* Preprocessor agents are special agents that are informed about newly
* added items before any other agents. This allows them to do filtering
* on the items or any other task that shall be done before the new item
* is visible in the Akonadi storage system.
*
* The method all the preprocessors must implement is processItem().
*
* @author Szymon Stefanek <s.stefanek@gmail.com>
* @since 4.4
*/
class AKONADI_EXPORT PreprocessorBase : public AgentBase
{
Q_OBJECT
public:
/**
* Describes the possible return values of the processItem() method.
*/
enum ProcessingResult
{
/**
* Processing completed successfully for this item.
* The Akonadi server will push in a new item when it's available.
*/
ProcessingCompleted,
/**
* Processing was delayed to a later stage.
* This must be returned when implementing asynchronous preprocessing.
*
* If this value is returned, finishProcessing() has to be called
* when processing is done.
*/
ProcessingDelayed,
/**
* Processing for this item failed (and the failure is unrecoverable).
* The Akonadi server will push in a new item when it's available,
* after possibly logging the failure.
*/
ProcessingFailed,
/**
* Processing for this item was refused. This is very
* similar to ProcessingFailed above but additionally remarks
* that the item that the Akonadi server pushed in wasn't
* meant for this Preprocessor.
* The Akonadi server will push in a new item when it's available,
* after possibly logging the failure and maybe taking some additional action.
*/
ProcessingRefused
};
/**
* This method must be implemented by every preprocessor subclass.
*
* It must realize the preprocessing of the given @p item.
*
* The Akonadi server will push in for preprocessing any newly created item:
* it's your responsibility to decide if you want to process the item or not.
*
* The method should return ProcessingCompleted on success, ProcessingDelayed
* if processing is implemented asynchronously and
* ProcessingRefused or ProcessingFailed if the processing
* didn't complete.
*
* If your operation is asynchronous then you should also
* connect to the abortRequested() signal and handle it
* appropriately (as the server MAY abort your async job
* if it decides that it's taking too long).
*/
virtual ProcessingResult processItem( const Item &item ) = 0;
/**
* This method must be called if processing is implemented asynchronously.
*
* You should call it when you have completed the processing
* or if an abortRequest() signal arrives (and in this case you
* will probably use ProcessingFailed as result).
*
* Valid values for @p result are ProcessingCompleted,
* PocessingRefused and ProcessingFailed. Passing any
* other value will lead to a runtime assertion.
*/
void finishProcessing( ProcessingResult result );
/**
* Sets the item fetch scope.
*
* The ItemFetchScope controls how much of an item's data is fetched
* from the server, e.g. whether to fetch the full item payload or
* only meta data.
*
* @param fetchScope The new scope for item fetch operations.
*
* @see fetchScope()
*/
void setFetchScope( const ItemFetchScope &fetchScope );
/**
* Returns the item fetch scope.
*
* Since this returns a reference it can be used to conveniently modify the
* current scope in-place, i.e. by calling a method on the returned reference
* without storing it in a local variable. See the ItemFetchScope documentation
* for an example.
*
* @return a reference to the current item fetch scope
*
* @see setFetchScope() for replacing the current item fetch scope
*/
ItemFetchScope &fetchScope();
protected:
/**
* Creates a new preprocessor base agent.
*
* @param id The instance id of the preprocessor base agent.
*/
PreprocessorBase( const QString &id );
/**
* Destroys the preprocessor base agent.
*/
virtual ~PreprocessorBase();
private:
//@cond PRIVATE
Q_DECLARE_PRIVATE( PreprocessorBase )
//@endcond
}; // class PreprocessorBase
} // namespace Akonadi
#ifndef AKONADI_PREPROCESSOR_MAIN
/**
* Convenience Macro for the most common main() function for Akonadi preprocessors.
*/
#define AKONADI_PREPROCESSOR_MAIN( preProcessorClass ) \
int main( int argc, char **argv ) \
{ \
return Akonadi::PreprocessorBase::init<preProcessorClass>( argc, argv ); \
}
#endif //!AKONADI_RESOURCE_MAIN
#endif //!_PREPROCESSORBASE_H_
|