Akonadi

attribute.h
1/*
2 SPDX-FileCopyrightText: 2006-2008 Volker Krause <vkrause@kde.org>
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
13namespace 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 <vkrause@kde.org>
130 */
131class AKONADICORE_EXPORT Attribute // clazy:exclude=copyable-polymorphic
132{
133public:
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
168protected:
169 explicit Attribute() = default;
170 Attribute(const Attribute &) = default;
171};
172
173} // namespace Akonadi
Provides interface for custom attributes for Entity.
Definition attribute.h:132
virtual ~Attribute()
Destroys this attribute.
virtual void deserialize(const QByteArray &data)=0
Sets the data of this attribute, using the same encoding as returned by toByteArray().
virtual QByteArray serialized() const =0
Returns a QByteArray representation of the attribute which will be storaged.
virtual Attribute * clone() const =0
Creates a copy of this attribute.
virtual QByteArray type() const =0
Returns the type of the attribute.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:38:51 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.