Akonadi

tag.h
1/*
2 SPDX-FileCopyrightText: 2014 Christian Mollekopf <mollekopf@kolabsys.com>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#pragma once
8
9#include "akonadicore_export.h"
10#include "attribute.h"
11
12#include <QDebug>
13#include <QSharedPointer>
14#include <QString>
15#include <QUrl>
16
17namespace Akonadi
18{
19class TagModifyJob;
20class TagPrivate;
21
22/**
23 * An Akonadi Tag.
24 */
25class AKONADICORE_EXPORT Tag
26{
27public:
28 using List = QList<Tag>;
29 using Id = qint64;
30
31 /**
32 * The PLAIN type has the following properties:
33 * * gid == displayName
34 * * immutable
35 * * no hierarchy (no parent)
36 *
37 * PLAIN tags are general purpose tags that are easy to map by backends.
38 */
39 static const char PLAIN[];
40
41 /**
42 * The GENERIC type has the following properties:
43 * * mutable
44 * * gid is RFC 4122 compatible
45 * * no hierarchy (no parent)
46 *
47 * GENERIC tags are general purpose tags, that are used, if you can change tag name.
48 */
49 static const char GENERIC[];
50
51 Tag();
52 explicit Tag(Id id);
53 /**
54 * Creates a PLAIN tag
55 */
56 explicit Tag(const QString &name);
57
58 Tag(const Tag &);
59
60 Tag(Tag &&) noexcept;
61
62 ~Tag();
63
64 Tag &operator=(const Tag &);
65 Tag &operator=(Tag &&) noexcept;
66 // Avoid slicing
67 bool operator==(const Tag &) const;
68 bool operator!=(const Tag &) const;
69
70 static Tag fromUrl(const QUrl &url);
71
72 /**
73 * Adds an attribute to the entity.
74 *
75 * If an attribute of the same type name already exists, it is deleted and
76 * replaced with the new one.
77 *
78 * @param attribute The new attribute.
79 *
80 * @note The entity takes the ownership of the attribute.
81 */
82 void addAttribute(Attribute *attribute);
83
84 /**
85 * Removes and deletes the attribute of the given type @p name.
86 */
87 void removeAttribute(const QByteArray &name);
88
89 /**
90 * Returns @c true if the entity has an attribute of the given type @p name,
91 * false otherwise.
92 */
93 bool hasAttribute(const QByteArray &name) const;
94
95 /**
96 * Returns a list of all attributes of the entity.
97 */
98 Attribute::List attributes() const;
99
100 /**
101 * Removes and deletes all attributes of the entity.
102 */
103 void clearAttributes();
104
105 /**
106 * Returns the attribute of the given type @p name if available, 0 otherwise.
107 */
108 const Attribute *attribute(const QByteArray &name) const;
109 Attribute *attribute(const QByteArray &name);
110
111 /**
112 * Describes the options that can be passed to access attributes.
113 */
115 AddIfMissing, ///< Creates the attribute if it is missing
116 DontCreate ///< Does not create an attribute if it is missing (default)
117 };
118
119 /**
120 * Returns the attribute of the requested type.
121 * If the entity has no attribute of that type yet, a new one
122 * is created and added to the entity.
123 *
124 * @param option The create options.
125 */
126 template<typename T>
127 inline T *attribute(CreateOption option = DontCreate);
128
129 /**
130 * Returns the attribute of the requested type or 0 if it is not available.
131 */
132 template<typename T>
133 inline const T *attribute() const;
134
135 /**
136 * Removes and deletes the attribute of the requested type.
137 */
138 template<typename T>
139 inline void removeAttribute();
140
141 /**
142 * Returns whether the entity has an attribute of the requested type.
143 */
144 template<typename T>
145 inline bool hasAttribute() const;
146
147 /**
148 * Returns the url of the tag.
149 */
150 QUrl url() const;
151
152 /**
153 * Sets the unique @p identifier of the tag.
154 */
155 void setId(Id identifier);
156
157 /**
158 * Returns the unique identifier of the tag.
159 */
160 Id id() const;
161
162 void setGid(const QByteArray &gid);
163 QByteArray gid() const;
164
165 void setRemoteId(const QByteArray &remoteId);
166 QByteArray remoteId() const;
167
168 void setType(const QByteArray &type);
169 QByteArray type() const;
170
171 void setName(const QString &name);
172 QString name() const;
173
174 void setParent(const Tag &parent);
175 Tag parent() const;
176
177 bool isValid() const;
178
179 /**
180 * Returns true if the tag is immutable (cannot be modified after creation).
181 * Note that the immutability does not affect the attributes.
182 */
183 bool isImmutable() const;
184
185 /**
186 * Returns a GENERIC tag with the given name and a valid gid
187 */
188 static Tag genericTag(const QString &name);
189
190private:
191 bool checkAttribute(const Attribute *attr, const QByteArray &type) const;
192 void markAttributeModified(const QByteArray &type);
193
194 /// @cond PRIVATE
195 friend class TagModifyJob;
196 friend class TagFetchJob;
197 friend class ProtocolHelper;
198
200 /// @endcond
201};
202
203AKONADICORE_EXPORT size_t qHash(const Akonadi::Tag &, size_t sed = 0) noexcept;
204
205template<typename T>
206inline T *Tag::attribute(CreateOption option)
207{
208 const QByteArray type = T().type();
209 markAttributeModified(type);
210 if (hasAttribute(type)) {
211 T *attr = dynamic_cast<T *>(attribute(type));
212 if (checkAttribute(attr, type)) {
213 return attr;
214 }
215 } else if (option == AddIfMissing) {
216 T *attr = new T();
217 addAttribute(attr);
218 return attr;
219 }
220
221 return nullptr;
222}
223
224template<typename T>
225inline const T *Tag::attribute() const
226{
227 const QByteArray type = T().type();
228 if (hasAttribute(type)) {
229 const T *attr = dynamic_cast<const T *>(attribute(type));
230 if (checkAttribute(attr, type)) {
231 return attr;
232 }
233 }
234
235 return nullptr;
236}
237
238template<typename T>
240{
241 const T dummy;
242 removeAttribute(dummy.type());
243}
244
245template<typename T>
246inline bool Tag::hasAttribute() const
247{
248 const T dummy;
249 return hasAttribute(dummy.type());
250}
251
252} // namespace Akonadi
253
254AKONADICORE_EXPORT QDebug operator<<(QDebug debug, const Akonadi::Tag &tag);
255
256Q_DECLARE_METATYPE(Akonadi::Tag)
257Q_DECLARE_METATYPE(Akonadi::Tag::List)
258Q_DECLARE_METATYPE(QSet<Akonadi::Tag>)
259Q_DECLARE_TYPEINFO(Akonadi::Tag, Q_RELOCATABLE_TYPE);
Provides interface for custom attributes for Entity.
Definition attribute.h:132
Job that fetches tags from the Akonadi storage.
Definition tagfetchjob.h:29
Job that modifies a tag in the Akonadi storage.
An Akonadi Tag.
Definition tag.h:26
void removeAttribute()
Removes and deletes the attribute of the requested type.
Definition tag.h:239
CreateOption
Describes the options that can be passed to access attributes.
Definition tag.h:114
@ AddIfMissing
Creates the attribute if it is missing.
Definition tag.h:115
const T * attribute() const
Returns the attribute of the requested type or 0 if it is not available.
Definition tag.h:225
bool hasAttribute() const
Returns whether the entity has an attribute of the requested type.
Definition tag.h:246
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:13:38 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.