Akonadi

attribute.h
1 /*
2  SPDX-FileCopyrightText: 2006-2008 Volker Krause <[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 <QList>
12 
13 namespace Akonadi
14 {
15 /**
16  * @short Provides interface for custom attributes for Entity.
17  *
18  * This class is an interface for custom attributes, that can be stored
19  * in an entity. Attributes should be meta data, e.g. ACLs, quotas etc.
20  * that are not part of the entities' data itself.
21  *
22  * Note that attributes are per user, i.e. when an attribute is added to
23  * an entity, it only applies to the current user.
24  *
25  * To provide custom attributes, you have to subclass from this interface
26  * and reimplement the pure virtual methods.
27  *
28  * @code
29  *
30  * class SecrecyAttribute : public Akonadi::Attribute
31  * {
32  * Q_GADGET
33  *
34  * public:
35  * enum Secrecy
36  * {
37  * Public,
38  * Private,
39  * Confidential
40  * };
41  * Q_ENUM(Secrecy);
42  *
43  * SecrecyAttribute(Secrecy secrecy = Public)
44  * : mSecrecy(secrecy)
45  * {
46  * }
47  *
48  * void setSecrecy(Secrecy secrecy)
49  * {
50  * mSecrecy = secrecy;
51  * }
52  *
53  * Secrecy secrecy() const
54  * {
55  * return mSecrecy;
56  * }
57  *
58  * virtual QByteArray type() const
59  * {
60  * return "secrecy";
61  * }
62  *
63  * virtual Attribute* clone() const
64  * {
65  * return new SecrecyAttribute(mSecrecy);
66  * }
67  *
68  * virtual QByteArray serialized() const
69  * {
70  * switch (mSecrecy) {
71  * case Public:
72  * return "public";
73  * case Private:
74  * return "private";
75  * case Confidential:
76  * return "confidential";
77  * }
78  * }
79  *
80  * virtual void deserialize(const QByteArray &data)
81  * {
82  * if (data == "public") {
83  * mSecrecy = Public;
84  * } else if (data == "private") {
85  * mSecrecy = Private;
86  * } else if (data == "confidential") {
87  * mSecrecy = Confidential;
88  * }
89  * }
90  * }
91  *
92  * @endcode
93  *
94  * Additionally, you need to register your attribute with Akonadi::AttributeFactory
95  * for automatic deserialization during retrieving of collections or items:
96  *
97  * @code
98  * AttributeFactory::registerAttribute<SecrecyAttribute>();
99  * @endcode
100  *
101  * Third party attributes need to be registered once by each application that uses
102  * them. So the above snippet needs to be in the resource that adds the attribute,
103  * and each application that uses the resource. This may be simplified in the future.
104  *
105  * The custom attributes can be used in the following way:
106  *
107  * @code
108  *
109  * Akonadi::Item item(QStringLiteral("text/directory"));
110  * SecrecyAttribute* attr = item.attribute<SecrecyAttribute>(Item::AddIfMissing);
111  * attr->setSecrecy(SecrecyAttribute::Confidential);
112  *
113  * @endcode
114  *
115  * and
116  *
117  * @code
118  *
119  * Akonadi::Item item = ...
120  *
121  * if (item.hasAttribute<SecrecyAttribute>()) {
122  * SecrecyAttribute *attr = item.attribute<SecrecyAttribute>();
123  *
124  * SecrecyAttribute::Secrecy secrecy = attr->secrecy();
125  * ...
126  * }
127  * @endcode
128  *
129  * @author Volker Krause <[email protected]>
130  */
131 class AKONADICORE_EXPORT Attribute // clazy:exclude=copyable-polymorphic
132 {
133 public:
134  /**
135  * Describes a list of attributes.
136  */
138 
139  /**
140  * Returns the type of the attribute.
141  */
142  virtual QByteArray type() const = 0;
143 
144  /**
145  * Destroys this attribute.
146  */
147  virtual ~Attribute();
148 
149  /**
150  * Creates a copy of this attribute.
151  */
152  virtual Attribute *clone() const = 0;
153 
154  /**
155  * Returns a QByteArray representation of the attribute which will be
156  * storaged. This can be raw binary data, no encoding needs to be applied.
157  */
158  virtual QByteArray serialized() const = 0;
159 
160  /**
161  * Sets the data of this attribute, using the same encoding
162  * as returned by toByteArray().
163  *
164  * @param data The encoded attribute data.
165  */
166  virtual void deserialize(const QByteArray &data) = 0;
167 
168 protected:
169  explicit Attribute() = default;
170  Attribute(const Attribute &) = default;
171 };
172 
173 } // namespace Akonadi
Provides interface for custom attributes for Entity.
Definition: attribute.h:131
Definition: item.h:29
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Sep 29 2023 03:51:13 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.