Akonadi

tag.h
1 /*
2  SPDX-FileCopyrightText: 2014 Christian Mollekopf <[email protected]>
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 
17 namespace Akonadi
18 {
19 class TagModifyJob;
20 class TagPrivate;
21 
22 /**
23  * An Akonadi Tag.
24  */
25 class AKONADICORE_EXPORT Tag
26 {
27 public:
28  using List = QVector<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> inline T *attribute(CreateOption option = DontCreate);
127 
128  /**
129  * Returns the attribute of the requested type or 0 if it is not available.
130  */
131  template<typename T> inline const T *attribute() const;
132 
133  /**
134  * Removes and deletes the attribute of the requested type.
135  */
136  template<typename T> inline void removeAttribute();
137 
138  /**
139  * Returns whether the entity has an attribute of the requested type.
140  */
141  template<typename T> inline bool hasAttribute() const;
142 
143  /**
144  * Returns the url of the tag.
145  */
146  QUrl url() const;
147 
148  /**
149  * Sets the unique @p identifier of the tag.
150  */
151  void setId(Id identifier);
152 
153  /**
154  * Returns the unique identifier of the tag.
155  */
156  Id id() const;
157 
158  void setGid(const QByteArray &gid);
159  QByteArray gid() const;
160 
161  void setRemoteId(const QByteArray &remoteId);
162  QByteArray remoteId() const;
163 
164  void setType(const QByteArray &type);
165  QByteArray type() const;
166 
167  void setName(const QString &name);
168  QString name() const;
169 
170  void setParent(const Tag &parent);
171  Tag parent() const;
172 
173  bool isValid() const;
174 
175  /**
176  * Returns true if the tag is immutable (cannot be modified after creation).
177  * Note that the immutability does not affect the attributes.
178  */
179  bool isImmutable() const;
180 
181  /**
182  * Returns a GENERIC tag with the given name and a valid gid
183  */
184  static Tag genericTag(const QString &name);
185 
186 private:
187  bool checkAttribute(const Attribute *attr, const QByteArray &type) const;
188  void markAttributeModified(const QByteArray &type);
189 
190  /// @cond PRIVATE
191  friend class TagModifyJob;
192  friend class TagFetchJob;
193  friend class ProtocolHelper;
194 
196  /// @endcond
197 };
198 
199 AKONADICORE_EXPORT uint qHash(const Akonadi::Tag &);
200 
201 template<typename T> inline T *Tag::attribute(CreateOption option)
202 {
203  const QByteArray type = T().type();
204  markAttributeModified(type);
205  if (hasAttribute(type)) {
206  T *attr = dynamic_cast<T *>(attribute(type));
207  if (checkAttribute(attr, type)) {
208  return attr;
209  }
210  } else if (option == AddIfMissing) {
211  T *attr = new T();
212  addAttribute(attr);
213  return attr;
214  }
215 
216  return nullptr;
217 }
218 
219 template<typename T> inline const T *Tag::attribute() const
220 {
221  const QByteArray type = T().type();
222  if (hasAttribute(type)) {
223  const T *attr = dynamic_cast<const T *>(attribute(type));
224  if (checkAttribute(attr, type)) {
225  return attr;
226  }
227  }
228 
229  return nullptr;
230 }
231 
232 template<typename T> inline void Tag::removeAttribute()
233 {
234  const T dummy;
235  removeAttribute(dummy.type());
236 }
237 
238 template<typename T> inline bool Tag::hasAttribute() const
239 {
240  const T dummy;
241  return hasAttribute(dummy.type());
242 }
243 
244 } // namespace Akonadi
245 
246 AKONADICORE_EXPORT QDebug operator<<(QDebug debug, const Akonadi::Tag &tag);
247 
248 Q_DECLARE_METATYPE(Akonadi::Tag)
249 Q_DECLARE_METATYPE(Akonadi::Tag::List)
250 Q_DECLARE_METATYPE(QSet<Akonadi::Tag>)
251 Q_DECLARE_TYPEINFO(Akonadi::Tag, Q_MOVABLE_TYPE);
252 
An Akonadi Tag.
Definition: tag.h:25
QDataStream & operator<<(QDataStream &out, const KDateTime &dateTime)
Provides interface for custom attributes for Entity.
Definition: attribute.h:124
const T * attribute() const
Returns the attribute of the requested type or 0 if it is not available.
Definition: tag.h:219
Job that fetches tags from the Akonadi storage.
Definition: tagfetchjob.h:28
@ AddIfMissing
Creates the attribute if it is missing.
Definition: tag.h:115
bool hasAttribute() const
Returns whether the entity has an attribute of the requested type.
Definition: tag.h:238
KCALENDARCORE_EXPORT uint qHash(const KCalendarCore::Period &key)
void addAttribute(Attribute *attribute)
Adds an attribute to the entity.
Definition: tag.cpp:98
CreateOption
Describes the options that can be passed to access attributes.
Definition: tag.h:114
void removeAttribute()
Removes and deletes the attribute of the requested type.
Definition: tag.h:232
Helper integration between Akonadi and Qt.
Job that modifies a tag in the Akonadi storage.
Definition: tagmodifyjob.h:21
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat May 28 2022 04:06:29 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.