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
27class QString;
28class QStringList;
29
30namespace Akonadi {
31class Collection;
32class Item;
33class 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 */
109class AKONADI_EXPORT MimeTypeChecker
110{
111public:
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
248private:
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