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

KDE's Doxygen guidelines are available online.