1/*
2 Copyright (c) 2006 - 2008 Volker Krause <vkrause@kde.org>
3
4 This library is free software; you can redistribute it and/or modify it
5 under the terms of the GNU Library General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
8
9 This library is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to the
16 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 02110-1301, USA.
18*/
19
20#ifndef AKONADI_ATTRIBUTE_H
21#define AKONADI_ATTRIBUTE_H
22
23#include "akonadi_export.h"
24
25#include <QtCore/QList>
26
27namespace Akonadi {
28
29/**
30 * @short Provides interface for custom attributes for Entity.
31 *
32 * This class is an interface for custom attributes, that can be stored
33 * in an entity. Attributes should be meta data, e.g. ACLs, quotas etc.
34 * that are not part of the entities' data itself.
35 *
36 * Note that attributes are per user, i.e. when an attribute is added to
37 * an entity, it only applies to the current user.
38 *
39 * To provide custom attributes, you have to subclass from this interface
40 * and reimplement the pure virtual methods.
41 *
42 * @code
43 *
44 * class SecrecyAttribute : public Akonadi::Attribute
45 * {
46 * public:
47 * enum Secrecy
48 * {
49 * Public,
50 * Private,
51 * Confidential
52 * };
53 *
54 * SecrecyAttribute( Secrecy secrecy = Public )
55 * : mSecrecy( secrecy )
56 * {
57 * }
58 *
59 * void setSecrecy( Secrecy secrecy )
60 * {
61 * mSecrecy = secrecy;
62 * }
63 *
64 * Secrecy secrecy() const
65 * {
66 * return mSecrecy;
67 * }
68 *
69 * virtual QByteArray type() const
70 * {
71 * return "secrecy";
72 * }
73 *
74 * virtual Attribute* clone() const
75 * {
76 * return new SecrecyAttribute( mSecrecy );
77 * }
78 *
79 * virtual QByteArray serialized() const
80 * {
81 * switch ( mSecrecy ) {
82 * case Public: return "public"; break;
83 * case Private: return "private"; break;
84 * case Confidential: return "confidential"; break;
85 * }
86 * }
87 *
88 * virtual void deserialize( const QByteArray &data )
89 * {
90 * if ( data == "public" )
91 * mSecrecy = Public;
92 * else if ( data == "private" )
93 * mSecrecy = Private;
94 * else if ( data == "confidential" )
95 * mSecrecy = Confidential;
96 * }
97 * }
98 *
99 * @endcode
100 *
101 * Additionally, you need to register your attribute with Akonadi::AttributeFactory
102 * for automatic deserialization during retrieving of collecitons or items:
103 *
104 * @code
105 * AttributeFactory::registerAttribute<SecrecyAttribute>();
106 * @endcode
107 *
108 * Third party attributes need to be registered once by each application that uses
109 * them. So the above snippet needs to be in the resource that adds the attribute,
110 * and each application that uses the resource. This may be simplified in the future.
111 *
112 * The custom attributes can be used in the following way:
113 *
114 * @code
115 *
116 * Akonadi::Item item( "text/directory" );
117 * SecrecyAttribute* attr = item.attribute<SecrecyAttribute>( Item::AddIfMissing );
118 * attr->setSecrecy( SecrecyAttribute::Confidential );
119 *
120 * @endcode
121 *
122 * and
123 *
124 * @code
125 *
126 * Akonadi::Item item = ...
127 *
128 * if ( item.hasAttribute<SecrecyAttribute>() ) {
129 * SecrecyAttribute *attr = item.attribute<SecrecyAttribute>();
130 *
131 * SecrecyAttribute::Secrecy secrecy = attr->secrecy();
132 * ...
133 * }
134 * @endcode
135 *
136 * @author Volker Krause <vkrause@kde.org>
137 */
138class AKONADI_EXPORT Attribute
139{
140public:
141 /**
142 * Describes a list of attributes.
143 */
144 typedef QList<Attribute *> List;
145
146 /**
147 * Returns the type of the attribute.
148 */
149 virtual QByteArray type() const = 0;
150
151 /**
152 * Destroys this attribute.
153 */
154 virtual ~Attribute();
155
156 /**
157 * Creates a copy of this attribute.
158 */
159 virtual Attribute *clone() const = 0;
160
161 /**
162 * Returns a QByteArray representation of the attribute which will be
163 * storaged. This can be raw binary data, no encoding needs to be applied.
164 */
165 virtual QByteArray serialized() const = 0;
166
167 /**
168 * Sets the data of this attribute, using the same encoding
169 * as returned by toByteArray().
170 *
171 * @param data The encoded attribute data.
172 */
173 virtual void deserialize(const QByteArray &data) = 0;
174};
175
176}
177
178#endif
179