1 | /* |
2 | Copyright (c) 2009 Kevin Krammer <kevin.krammer@gmx.at> |
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 MIMETYPECHECKER_H |
21 | #define MIMETYPECHECKER_H |
22 | |
23 | #include "akonadi_export.h" |
24 | |
25 | #include <QtCore/QSharedDataPointer> |
26 | |
27 | class QString; |
28 | class QStringList; |
29 | |
30 | namespace Akonadi { |
31 | class Collection; |
32 | class Item; |
33 | class MimeTypeCheckerPrivate; |
34 | |
35 | /** |
36 | * @short Helper for checking MIME types of Collections and Items. |
37 | * |
38 | * When it is necessary to decide whether an item has a certain MIME type |
39 | * or whether a collection can contain a certain MIME type, direct string |
40 | * comparison might not render the desired result because MIME types can |
41 | * have aliases and be a node in an "inheritance" hierachy. |
42 | * |
43 | * For example a check like this |
44 | * @code |
45 | * if ( item.mimeType() == QLatin1String( "text/directory" ) ) |
46 | * @endcode |
47 | * would fail to detect @c "text/x-vcard" as being the same MIME type. |
48 | * |
49 | * @note KDE deals with this inside the KMimeType framework, this class is just |
50 | * a convenience helper for common Akonadi related checks. |
51 | * |
52 | * Example: Checking whether an Akonadi::Item is contact MIME type |
53 | * @code |
54 | * Akonadi::MimeTypeChecker checker; |
55 | * checker.addWantedMimeType( KABC::Addressee::mimeType() ); |
56 | * |
57 | * if ( checker.isWantedItem( item ) ){ |
58 | * // item.mimeType() is equal KABC::Addressee::mimeType(), an aliases |
59 | * // or a sub type. |
60 | * } |
61 | * @endcode |
62 | * |
63 | * Example: Checking whether an Akonadi::Collection could contain calendar |
64 | * items |
65 | * @code |
66 | * Akonadi::MimeTypeChecker checker; |
67 | * checker.addWantedMimeType( QLatin1String( "text/calendar" ) ); |
68 | * |
69 | * if ( checker.isWantedCollection( collection ) ) { |
70 | * // collection.contentMimeTypes() contains @c "text/calendar" |
71 | * // or a sub type. |
72 | * } |
73 | * @endcode |
74 | * |
75 | * Example: Checking whether an Akonadi::Collection could contain |
76 | * Calendar Event items (i.e. KCal::Event), making use of the respective |
77 | * MIME type "subclassing" provided by Akonadi's MIME type extensions. |
78 | * @code |
79 | * Akonadi::MimeTypeChecker checker; |
80 | * checker.addWantedMimeType( QLatin1String( "application/x-vnd.akonadi.calendar.event" ) ); |
81 | * |
82 | * if ( checker.isWantedCollection( collection ) ) { |
83 | * // collection.contentMimeTypes() contains @c "application/x-vnd.akonadi.calendar.event" |
84 | * // or a sub type, but just containing @c "text/calendar" would not |
85 | * // get here |
86 | * } |
87 | * @endcode |
88 | * |
89 | * Example: Checking for items of more than one MIME type and treat one |
90 | * of them specially. |
91 | * @code |
92 | * Akonadi::MimeTypeChecker mimeFilter; |
93 | * mimeFilter.setWantedMimeTypes( QStringList() << KABC::Addressee::mimeType() |
94 | * << KABC::ContactGroup::mimeType() ); |
95 | * |
96 | * if ( mimeFilter.isWantedItem( item ) ) { |
97 | * if ( Akonadi::MimeTypeChecker::isWantedItem( item, KABC::ContactGroup::mimeType() ) { |
98 | * // treat contact group's differently |
99 | * } |
100 | * } |
101 | * @endcode |
102 | * |
103 | * This class is implicitly shared. |
104 | * |
105 | * @author Kevin Krammer <kevin.krammer@gmx.at> |
106 | * |
107 | * @since 4.3 |
108 | */ |
109 | class AKONADI_EXPORT MimeTypeChecker |
110 | { |
111 | public: |
112 | /** |
113 | * Creates an empty MIME type checker. |
114 | * |
115 | * An empty checker will not report any items or collections as wanted. |
116 | */ |
117 | MimeTypeChecker(); |
118 | |
119 | /** |
120 | * Creates a new MIME type checker from an @p other. |
121 | */ |
122 | MimeTypeChecker(const MimeTypeChecker &other); |
123 | |
124 | /** |
125 | * Destroys the MIME type checker. |
126 | */ |
127 | ~MimeTypeChecker(); |
128 | |
129 | /** |
130 | * Assigns the @p other to this checker and returns a reference to this checker. |
131 | */ |
132 | MimeTypeChecker &operator=(const MimeTypeChecker &other); |
133 | |
134 | /** |
135 | * Returns the list of wanted MIME types this instance checks against. |
136 | * |
137 | * @see setWantedMimeTypes() |
138 | */ |
139 | QStringList wantedMimeTypes() const; |
140 | |
141 | /** |
142 | * Sets the list of wanted MIME types this instance checks against. |
143 | * |
144 | * @param mimeTypes The list of MIME types to check against. |
145 | * |
146 | * @see wantedMimeTypes() |
147 | */ |
148 | void setWantedMimeTypes(const QStringList &mimeTypes); |
149 | |
150 | /** |
151 | * Adds another MIME type to the list of wanted MIME types this instance checks against. |
152 | * |
153 | * @param mimeType The MIME types to add to the checklist. |
154 | * |
155 | * @see setWantedMimeTypes() |
156 | */ |
157 | void addWantedMimeType(const QString &mimeType); |
158 | |
159 | /** |
160 | * Removes a MIME type from the list of wanted MIME types this instance checks against. |
161 | * |
162 | * @param mimeType The MIME type to remove from the checklist. |
163 | * |
164 | * @see addWantedMimeType() |
165 | */ |
166 | void removeWantedMimeType(const QString &mimeType); |
167 | |
168 | /** |
169 | * Checks whether a given @p item has one of the wanted MIME types |
170 | * |
171 | * @param item The item to check the MIME type of. |
172 | * |
173 | * @return @c true if the @p item MIME type is one of the wanted ones, |
174 | * @c false if it isn't, the item is invalid or has an empty MIME type. |
175 | * |
176 | * @see setWantedMimeTypes() |
177 | * @see Item::mimeType() |
178 | */ |
179 | bool isWantedItem(const Item &item) const; |
180 | |
181 | /** |
182 | * Checks whether a given @p collection has one of the wanted MIME types |
183 | * |
184 | * @param collection The collection to check the content MIME types of. |
185 | * |
186 | * @return @c true if one of the @p collection content MIME types is |
187 | * one of the wanted ones, @c false if non is, the collection |
188 | * is invalid or has an empty content MIME type list. |
189 | * |
190 | * @see setWantedMimeTypes() |
191 | * @see Collection::contentMimeTypes() |
192 | */ |
193 | bool isWantedCollection(const Collection &collection) const; |
194 | |
195 | /** |
196 | * Checks whether a given mime type is covered by one of the wanted MIME types. |
197 | * |
198 | * @param mimeType The mime type to check. |
199 | * |
200 | * @return @c true if the mime type @p mimeType is coverd by one of the |
201 | * wanted MIME types, @c false otherwise. |
202 | * |
203 | * @since 4.6 |
204 | */ |
205 | bool isWantedMimeType(const QString &mimeType) const; |
206 | |
207 | /** |
208 | * Checks whether any of the given MIME types is covered by one of the wanted MIME types. |
209 | * |
210 | * @param mimeTypes The MIME types to check. |
211 | * |
212 | * @return @c true if any of the MIME types in @p mimeTypes is coverd by one of the |
213 | * wanted MIME types, @c false otherwise. |
214 | * |
215 | * @since 4.6 |
216 | */ |
217 | bool containsWantedMimeType(const QStringList &mimeTypes) const; |
218 | |
219 | /** |
220 | * Checks whether a given @p item has the given wanted MIME type |
221 | * |
222 | * @param item The item to check the MIME type of. |
223 | * @param wantedMimeType The MIME type to check against. |
224 | * |
225 | * @return @c true if the @p item MIME type is the given one, |
226 | * @c false if it isn't, the item is invalid or has an empty MIME type. |
227 | * |
228 | * @see setWantedMimeTypes() |
229 | * @see Item::mimeType() |
230 | */ |
231 | static bool isWantedItem(const Item &item, const QString &wantedMimeType); |
232 | |
233 | /** |
234 | * Checks whether a given @p collection has the given MIME type |
235 | * |
236 | * @param collection The collection to check the content MIME types of. |
237 | * @param wantedMimeType The MIME type to check against. |
238 | * |
239 | * @return @c true if one of the @p collection content MIME types is |
240 | * the given wanted one, @c false if it isn't, the collection |
241 | * is invalid or has an empty content MIME type list. |
242 | * |
243 | * @see setWantedMimeTypes() |
244 | * @see Collection::contentMimeTypes() |
245 | */ |
246 | static bool isWantedCollection(const Collection &collection, const QString &wantedMimeType); |
247 | |
248 | private: |
249 | //@cond PRIVATE |
250 | QSharedDataPointer<MimeTypeCheckerPrivate> d; |
251 | //@endcond |
252 | }; |
253 | |
254 | } |
255 | |
256 | #endif |
257 | // kate: space-indent on; indent-width 2; replace-tabs on; |
258 | |