Akonadi

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

KDE's Doxygen guidelines are available online.