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 = 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 
190 private:
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 
203 AKONADICORE_EXPORT uint qHash(const Akonadi::Tag &);
204 
205 template<typename T>
206 inline 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 
224 template<typename T>
225 inline 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 
238 template<typename T>
239 inline void Tag::removeAttribute()
240 {
241  const T dummy;
242  removeAttribute(dummy.type());
243 }
244 
245 template<typename T>
246 inline bool Tag::hasAttribute() const
247 {
248  const T dummy;
249  return hasAttribute(dummy.type());
250 }
251 
252 } // namespace Akonadi
253 
254 AKONADICORE_EXPORT QDebug operator<<(QDebug debug, const Akonadi::Tag &tag);
255 
256 Q_DECLARE_METATYPE(Akonadi::Tag)
257 Q_DECLARE_METATYPE(Akonadi::Tag::List)
258 Q_DECLARE_METATYPE(QSet<Akonadi::Tag>)
259 Q_DECLARE_TYPEINFO(Akonadi::Tag, Q_RELOCATABLE_TYPE);
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
An Akonadi Tag.
Definition: tag.h:25
Provides interface for custom attributes for Entity.
Definition: attribute.h:131
const T * attribute() const
Returns the attribute of the requested type or 0 if it is not available.
Definition: tag.h:225
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:246
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:239
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-2023 The KDE developers.
Generated on Tue Oct 3 2023 04:02:00 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.