1 | /* |
2 | Copyright (c) 2009 Constantin Berzan <exit3219@gmail.com> |
3 | |
4 | This library is free software; you can redistribute it and/or modify it |
5 | under the terms of the GNU Library General Public License as published by |
6 | the Free Software Foundation; either version 2 of the License, or (at your |
7 | option) any later version. |
8 | |
9 | This library is distributed in the hope that it will be useful, but WITHOUT |
10 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
11 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public |
12 | License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to the |
16 | Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA |
17 | 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef MAILTRANSPORT_FILTERACTIONJOB_P_H |
21 | #define MAILTRANSPORT_FILTERACTIONJOB_P_H |
22 | |
23 | #include <mailtransport/mailtransport_export.h> |
24 | |
25 | #include <akonadi/item.h> |
26 | #include <akonadi/transactionsequence.h> |
27 | |
28 | namespace Akonadi { |
29 | |
30 | class Collection; |
31 | class ItemFetchScope; |
32 | class Job; |
33 | |
34 | class FilterActionJob; |
35 | |
36 | /** |
37 | * @short Base class for a filter/action for FilterActionJob. |
38 | * |
39 | * Abstract class defining an interface for a filter and an action for |
40 | * FilterActionJob. The virtual methods must be implemented in subclasses. |
41 | * |
42 | * @code |
43 | * class ClearErrorAction : public Akonadi::FilterAction |
44 | * { |
45 | * public: |
46 | * // reimpl |
47 | * virtual Akonadi::ItemFetchScope fetchScope() const |
48 | * { |
49 | * ItemFetchScope scope; |
50 | * scope.fetchFullPayload( false ); |
51 | * scope.fetchAttribute<ErrorAttribute>(); |
52 | * return scope; |
53 | * } |
54 | * |
55 | * virtual bool itemAccepted( const Akonadi::Item &item ) const |
56 | * { |
57 | * return item.hasAttribute<ErrorAttribute>(); |
58 | * } |
59 | * |
60 | * virtual Akonadi::Job *itemAction( const Akonadi::Item &item, |
61 | * Akonadi::FilterActionJob *parent ) const |
62 | * { |
63 | * Item cp = item; |
64 | * cp.removeAttribute<ErrorAttribute>(); |
65 | * return new ItemModifyJob( cp, parent ); |
66 | * } |
67 | * }; |
68 | * @endcode |
69 | * |
70 | * @see FilterActionJob |
71 | * |
72 | * @author Constantin Berzan <exit3219@gmail.com> |
73 | * @since 4.4 |
74 | */ |
75 | class MAILTRANSPORT_EXPORT FilterAction |
76 | { |
77 | public: |
78 | /** |
79 | * Destroys this filter action. |
80 | * |
81 | * A FilterActionJob will delete its FilterAction automatically. |
82 | */ |
83 | virtual ~FilterAction(); |
84 | |
85 | /** |
86 | * Returns an ItemFetchScope to use if the FilterActionJob needs |
87 | * to fetch the items from a collection. |
88 | * |
89 | * @note The items are not fetched unless FilterActionJob is |
90 | * constructed with a Collection parameter. |
91 | */ |
92 | virtual Akonadi::ItemFetchScope fetchScope() const = 0; |
93 | |
94 | /** |
95 | * Returns @c true if the @p item is accepted by the filter and should be |
96 | * acted upon by the FilterActionJob. |
97 | */ |
98 | virtual bool itemAccepted( const Akonadi::Item &item ) const = 0; |
99 | |
100 | /** |
101 | * Returns a job to act on the @p item. |
102 | * The FilterActionJob will finish when all such jobs are finished. |
103 | * @param item the item to work on |
104 | * @param parent the parent job |
105 | */ |
106 | virtual Akonadi::Job *itemAction( const Akonadi::Item &item, |
107 | Akonadi::FilterActionJob *parent ) const = 0; |
108 | }; |
109 | |
110 | /** |
111 | * @short Job to filter and apply an action on a set of items. |
112 | * |
113 | * This jobs filters through a set of items, and applies an action to the |
114 | * items which are accepted by the filter. The filter and action |
115 | * are provided by a functor class derived from FilterAction. |
116 | * |
117 | * For example, a MarkAsRead action/filter may be used to mark all messages |
118 | * in a folder as read. |
119 | * |
120 | * @code |
121 | * FilterActionJob *mjob = new FilterActionJob( LocalFolders::self()->outbox(), |
122 | * new ClearErrorAction, this ); |
123 | * connect( mjob, SIGNAL( result( KJob* ) ), this, SLOT( massModifyResult( KJob* ) ) ); |
124 | * @endcode |
125 | * |
126 | * @see FilterAction |
127 | * |
128 | * @author Constantin Berzan <exit3219@gmail.com> |
129 | * @since 4.4 |
130 | */ |
131 | class MAILTRANSPORT_EXPORT FilterActionJob : public TransactionSequence |
132 | { |
133 | Q_OBJECT |
134 | |
135 | public: |
136 | /** |
137 | * Creates a filter action job to act on a single item. |
138 | * |
139 | * @param item The item to act on. The item is not re-fetched. |
140 | * @param functor The FilterAction to use. |
141 | * @param parent The parent object. |
142 | */ |
143 | FilterActionJob( const Item &item, FilterAction *functor, QObject *parent = 0 ); |
144 | |
145 | /** |
146 | * Creates a filter action job to act on a set of items. |
147 | * |
148 | * @param items The items to act on. The items are not re-fetched. |
149 | * @param functor The FilterAction to use. |
150 | * @param parent The parent object. |
151 | */ |
152 | FilterActionJob( const Item::List &items, FilterAction *functor, QObject *parent = 0 ); |
153 | |
154 | /** |
155 | * Creates a filter action job to act on items in a collection. |
156 | * |
157 | * @param collection The collection to act on. |
158 | * The items of the collection are fetched using functor->fetchScope(). |
159 | * @param functor The FilterAction to use. |
160 | * @param parent The parent object. |
161 | */ |
162 | FilterActionJob( const Collection &collection, FilterAction *functor, QObject *parent = 0 ); |
163 | |
164 | /** |
165 | * Destroys the filter action job. |
166 | */ |
167 | ~FilterActionJob(); |
168 | |
169 | protected: |
170 | /* reimpl */ |
171 | virtual void doStart(); |
172 | |
173 | private: |
174 | //@cond PRIVATE |
175 | class Private; |
176 | Private *const d; |
177 | |
178 | Q_PRIVATE_SLOT( d, void fetchResult( KJob* ) ) |
179 | //@endcond |
180 | }; |
181 | |
182 | } // namespace Akonadi |
183 | |
184 | #endif // AKONADI_FILTERACTIONJOB_H |
185 | |