Akonadi

mimetypechecker.h
1 /*
2  SPDX-FileCopyrightText: 2009 Kevin Krammer <[email protected]>
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 
13 class QString;
14 #include <QStringList>
15 
16 namespace Akonadi
17 {
18 class Collection;
19 class Item;
20 class 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() == QLatin1String( "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( QLatin1String( "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( QLatin1String( "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 <[email protected]>
93  *
94  * @since 4.3
95  */
96 class AKONADICORE_EXPORT MimeTypeChecker
97 {
98 public:
99  /**
100  * Creates an empty MIME type checker.
101  *
102  * An empty checker will not report any items or collections as wanted.
103  */
104  MimeTypeChecker();
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  */
114  ~MimeTypeChecker();
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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT static bool isWantedCollection(const Collection &collection, const QString &wantedMimeType);
246 
247 private:
248  /// @cond PRIVATE
250  /// @endcond
251 };
252 
253 }
254 
Represents a collection of PIM items.
Definition: collection.h:61
Helper for checking MIME types of Collections and Items.
Represents a PIM item stored in Akonadi storage.
Definition: item.h:104
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Jul 2 2022 06:41:48 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.