1/*
2 This file is part of the kcalcore library.
3
4 Copyright (c) 2002,2006,2010 David Jarvie <djarvie@kde.org>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
20*/
21/**
22 @file
23 This file is part of the API for handling calendar data and
24 defines the CustomProperties class.
25
26 @author David Jarvie \<djarvie@kde.org\>
27*/
28
29#ifndef KCALCORE_CUSTOMPROPERTIES_H
30#define KCALCORE_CUSTOMPROPERTIES_H
31
32#include "kcalcore_export.h"
33
34#include <QtCore/QMap>
35#include <QtCore/QString>
36
37namespace KCalCore {
38
39/**
40 @brief
41 A class to manage custom calendar properties.
42
43 This class represents custom calendar properties.
44 It is used as a base class for classes which represent calendar components.
45 A custom property name written by the kcalcore library has the form X-KDE-APP-KEY
46 where APP represents the application name, and KEY distinguishes individual
47 properties for the application.
48 In keeping with RFC2445, property names must be composed only of the
49 characters A-Z, a-z, 0-9 and '-'.
50*/
51class KCALCORE_EXPORT CustomProperties
52{
53 friend KCALCORE_EXPORT QDataStream &operator<<(QDataStream &s,
54 const KCalCore::CustomProperties &properties);
55 friend KCALCORE_EXPORT QDataStream &operator>>(QDataStream &s,
56 KCalCore::CustomProperties &properties);
57public:
58 /**
59 Constructs an empty custom properties instance.
60 */
61 CustomProperties();
62
63 /**
64 Copy constructor.
65 @param other is the one to copy.
66 */
67 CustomProperties(const CustomProperties &other);
68
69 /**
70 Destructor.
71 */
72 virtual ~CustomProperties();
73
74 /**
75 Compare this with @p properties for equality.
76 @param properties is the one to compare.
77 @warning The comparison is not polymorphic.
78 */
79 bool operator==(const CustomProperties &properties) const;
80
81 /**
82 Create or modify a custom calendar property.
83
84 @param app Application name as it appears in the custom property name.
85 @param key Property identifier specific to the application.
86 @param value The property's value. A call with a value of QString()
87 will be ignored.
88 @see removeCustomProperty().
89 */
90 void setCustomProperty(const QByteArray &app, const QByteArray &key,
91 const QString &value);
92
93 /**
94 Delete a custom calendar property.
95
96 @param app Application name as it appears in the custom property name.
97 @param key Property identifier specific to the application.
98 @see setCustomProperty().
99 */
100 void removeCustomProperty(const QByteArray &app, const QByteArray &key);
101
102 /**
103 Return the value of a custom calendar property.
104
105 @param app Application name as it appears in the custom property name.
106 @param key Property identifier specific to the application.
107 @return Property value, or QString() if (and only if) the property
108 does not exist.
109 */
110 QString customProperty(const QByteArray &app, const QByteArray &key) const;
111
112 /**
113 Validate and return the full name of a custom calendar property.
114
115 @param app Application name as it appears in the custom property name.
116 @param key Property identifier specific to the application.
117 @return Full property name, or empty string if it would contain invalid
118 characters
119 */
120 static QByteArray customPropertyName(const QByteArray &app, const QByteArray &key);
121
122 /**
123 Create or modify a non-KDE or non-standard custom calendar property.
124
125 @param name Full property name
126 @param value The property's value. A call with a value of QString()
127 will be ignored.
128 @param parameters The formatted list of parameters for the
129 property. They should be formatted as RFC specifies, that is,
130 KEY=VALUE;KEY2=VALUE2. We're mostly concerned about passing them
131 through as-is albeit they can be of course parsed if need be.
132 @see removeNonKDECustomProperty().
133 */
134 void setNonKDECustomProperty(const QByteArray &name, const QString &value,
135 const QString &parameters = QString());
136
137 /**
138 Delete a non-KDE or non-standard custom calendar property.
139
140 @param name Full property name
141 @see setNonKDECustomProperty().
142 */
143 void removeNonKDECustomProperty(const QByteArray &name);
144
145 /**
146 Return the value of a non-KDE or non-standard custom calendar property.
147
148 @param name Full property name
149 @return Property value, or QString() if (and only if) the property
150 does not exist.
151 */
152 QString nonKDECustomProperty(const QByteArray &name) const;
153
154 /**
155 Return the parameters of a non-KDE or non-standard custom
156 calendar property.
157
158 @param name Full property name
159 @return The parameters for the given property. Empty string is
160 returned if none are set.
161 */
162 QString nonKDECustomPropertyParameters(const QByteArray &name) const;
163
164 /**
165 Initialise the alarm's custom calendar properties to the specified
166 key/value pairs.
167 @param properties is a QMap of property key/value pairs.
168 @see customProperties().
169 */
170 void setCustomProperties(const QMap<QByteArray, QString> &properties);
171
172 /**
173 Returns all custom calendar property key/value pairs.
174 @see setCustomProperties().
175 */
176 QMap<QByteArray, QString> customProperties() const;
177
178 /**
179 Assignment operator.
180 @warning The assignment is not polymorphic.
181 @param other is the CustomProperty to assign.
182 */
183 CustomProperties &operator=(const CustomProperties &other);
184
185protected:
186 /**
187 Called before a custom property will be changed.
188 The default implementation does nothing: override in derived classes
189 to perform change processing.
190 */
191 virtual void customPropertyUpdate();
192
193 /**
194 Called when a custom property has been changed.
195 The default implementation does nothing: override in derived classes
196 to perform change processing.
197 */
198 virtual void customPropertyUpdated();
199
200 /**
201 @copydoc
202 IncidenceBase::virtual_hook()
203 */
204 virtual void virtual_hook(int id, void *data);
205
206private:
207 //@cond PRIVATE
208 class Private;
209 Private *const d;
210 //@endcond
211};
212
213/**
214 Serializes the @p properties object into the @p stream.
215*/
216KCALCORE_EXPORT QDataStream &operator<<(QDataStream &stream,
217 const KCalCore::CustomProperties &properties);
218
219/**
220 Initializes the @p properties object from the @p stream.
221*/
222KCALCORE_EXPORT QDataStream &operator>>(QDataStream &stream,
223 KCalCore::CustomProperties &properties);
224
225}
226
227#endif
228