1/****************************************************************************
2**
3** Copyright (C) 2015 The Qt Company Ltd.
4** Contact: http://www.qt.io/licensing/
5**
6** This file is part of the QtVersit module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL21$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see http://www.qt.io/terms-conditions. For further
15** information use the contact form at http://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 2.1 or version 3 as published by the Free
20** Software Foundation and appearing in the file LICENSE.LGPLv21 and
21** LICENSE.LGPLv3 included in the packaging of this file. Please review the
22** following information to ensure the GNU Lesser General Public License
23** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
24** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25**
26** As a special exception, The Qt Company gives you certain additional
27** rights. These rights are described in The Qt Company LGPL Exception
28** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29**
30** $QT_END_LICENSE$
31**
32****************************************************************************/
33
34#include "qversitproperty.h"
35#include "qversitproperty_p.h"
36
37#ifndef QT_NO_DEBUG_STREAM
38#include <QtCore/qdebug.h>
39#endif
40#include <QtCore/qtextcodec.h>
41
42#include "qversitdocument.h"
43
44QT_BEGIN_NAMESPACE_VERSIT
45
46/*!
47 \class QVersitProperty
48 \brief The QVersitProperty class stores the name, value, groups and parameters of a Versit property.
49 \ingroup versit
50 \inmodule QtVersit
51
52 A vCard is represented in abstract form as a QVersitDocument that consists of a number of
53 properties such as a name (N), a telephone number (TEL) and an email address (EMAIL), for
54 instance. Each of these properties is stored as an instance of a QVersitProperty in a
55 QVersitDocument.
56
57 A QVersitProperty consists of a list of groups, a name, a list of parameters (key/value pairs),
58 and a value.
59
60 The value of a QVersitProperty is stored as a QVariant and should always be one of four types:
61 QString for textual values, QByteArray for binary data (eg. images), QStringList for structured
62 textual data, or QVersitDocument for nested documents. The \l QVersitReader will parse Versit
63 properties and assign the correct type of object to the property value. The \l QVersitWriter will
64 serialize objects of these types correctly into the (text-based) Versit format.
65
66 For example, a property might appear in a vCard as:
67 \code
68 ADR;TYPE=home,postal:;;123 Main Street;Any Town;CA;91921-1234
69 \endcode
70 This would be stored as a QVersitProperty with the name \tt{ADR} and two parameters (both named
71 \tt{TYPE} and with values \tt{home} and \tt{postal} respectively. The value of the
72 QVersitProperty is a QStringList with six strings, and the valueType is CompoundType.
73
74 QVersitProperty supports implicit sharing. The property name and parameter names of a
75 QVersitProperty are converted to upper-case when they are stored to a QVersitProperty.
76
77 \sa QVersitDocument
78 */
79
80/*!
81 \enum QVersitProperty::ValueType
82 Describes the type of data held in the property's value.
83
84 The vCard and iCalendar specifications allows a property value to hold a string, binary data, or a
85 nested document. String values can either be unstructured or structured. Structured strings can
86 be either of compound type or list type. A compound value is one that is delimited by semicolons,
87 allows empty components, and has a property-specific cardinality and ordering. A list value is
88 one that is delimited by commas, does not have empty components, and has no restrictions on
89 cardinality or ordering.
90
91 \value PlainType The property value holds an unstructured string and can be retrieved with
92 QVersitProperty::value()
93 \value CompoundType The property value holds a compound string and can be retrieved with
94 QVersitProperty::value<QStringList>()
95 \value ListType The property value holds a list of strings and can be retrieved with
96 QVersitProperty::value<QStringList>()
97 \value BinaryType The property value holds a binary value and can be retrieved with
98 QVersitProperty::value<QByteArray>()
99 \value VersitDocumentType The property value holds a nested Versit document and can be retrieved
100 \value PreformattedType The property value holds a string that represents exactly the text for
101 the property in the vCard file, bar line-wrapping. That is, if the property were to be written
102 to file it should be written as-is, with no backslash escaping.
103 */
104
105/*! Constructs a new empty property */
106QVersitProperty::QVersitProperty() : d(new QVersitPropertyPrivate())
107{
108}
109
110/*! Constructs a property that is a copy of \a other */
111QVersitProperty::QVersitProperty(const QVersitProperty& other) : d(other.d)
112{
113}
114
115/*! Frees the memory used by the property */
116QVersitProperty::~QVersitProperty()
117{
118}
119
120/*! Assigns this property to \a other */
121QVersitProperty& QVersitProperty::operator=(const QVersitProperty& other)
122{
123 if (this != &other)
124 d = other.d;
125 return *this;
126}
127
128/*! Returns true if this is equal to \a other; false otherwise. */
129bool QVersitProperty::operator==(const QVersitProperty& other) const
130{
131 bool equal = d->mGroups == other.d->mGroups &&
132 d->mName == other.d->mName &&
133 d->mParameters == other.d->mParameters &&
134 d->mValueType == other.d->mValueType;
135 if (!equal)
136 return false;
137
138 // QVariant doesn't support == on QVersitDocuments - do it manually
139 if (d->mValue.userType() == qMetaTypeId<QVersitDocument>())
140 return other.d->mValue.userType() == qMetaTypeId<QVersitDocument>()
141 && d->mValue.value<QVersitDocument>() == other.d->mValue.value<QVersitDocument>();
142 else
143 return d->mValue == other.d->mValue;
144}
145
146/*! Returns true if this is not equal to \a other; false otherwise. */
147bool QVersitProperty::operator!=(const QVersitProperty& other) const
148{
149 return !(*this == other);
150}
151
152/*! Returns the hash value for \a key. */
153uint qHash(const QVersitProperty &key)
154{
155 uint hash = QT_PREPEND_NAMESPACE(qHash)(key: key.name()) + QT_PREPEND_NAMESPACE(qHash)(key: key.value());
156 foreach (const QString& group, key.groups()) {
157 hash += QT_PREPEND_NAMESPACE(qHash)(key: group);
158 }
159 QHash<QString,QString>::const_iterator it = key.parameters().constBegin();
160 QHash<QString,QString>::const_iterator end = key.parameters().constEnd();
161 while (it != end) {
162 hash += QT_PREPEND_NAMESPACE(qHash)(key: it.key()) + QT_PREPEND_NAMESPACE(qHash)(key: it.value());
163 ++it;
164 }
165 return hash;
166}
167
168#ifndef QT_NO_DEBUG_STREAM
169QDebug operator<<(QDebug dbg, const QVersitProperty& property)
170{
171 QStringList groups = property.groups();
172 QString name = property.name();
173 QMultiHash<QString,QString> parameters = property.parameters();
174 dbg.nospace() << "QVersitProperty(";
175 foreach (const QString& group, groups) {
176 dbg.nospace() << group << '.';
177 }
178 dbg.nospace() << name;
179 QHash<QString,QString>::const_iterator it;
180 for (it = parameters.constBegin(); it != parameters.constEnd(); ++it) {
181 dbg.nospace() << ';' << it.key() << '=' << it.value();
182 }
183 if (property.valueType() == QVersitProperty::VersitDocumentType)
184 dbg.nospace() << ':' << property.value<QVersitDocument>();
185 else
186 dbg.nospace() << ':' << property.variantValue();
187 dbg.nospace() << ')';
188 return dbg.maybeSpace();
189}
190#endif
191
192/*!
193 * Sets the groups in the property to the given list of \a groups.
194 */
195void QVersitProperty::setGroups(const QStringList& groups)
196{
197 d->mGroups.clear();
198 foreach (const QString& group, groups) {
199 d->mGroups.append(t: group);
200 }
201}
202
203/*!
204 * Gets the groups of the property.
205 */
206QStringList QVersitProperty::groups() const
207{
208 return d->mGroups;
209}
210
211/*!
212 * Sets the \a name of the property.
213 * The \a name is converted to upper-case.
214 */
215void QVersitProperty::setName(const QString& name)
216{
217 d->mName = name.toUpper();
218}
219
220/*!
221 * Gets the name of the property in upper-case.
222 */
223QString QVersitProperty::name() const
224{
225 return d->mName;
226}
227
228/*!
229 * Replaces all the parameters with \a parameters.
230 * The names of the parameters are converted to upper-case.
231 */
232void QVersitProperty::setParameters(const QMultiHash<QString,QString>& parameters)
233{
234 d->mParameters.clear();
235 // Traverse parameters in the reverse order, because they are added to
236 // d->mParameters using insert in QVersitProperty::addParameter
237 QList<QString> keys = parameters.uniqueKeys();
238 for (int i=keys.count()-1; i >= 0; i--) {
239 QString key = keys.at(i);
240 QList<QString> values = parameters.values(akey: key);
241 for (int j=values.count()-1; j >= 0; j--) {
242 // Convert all the parameter names and values to upper case
243 insertParameter(name: key,value: values.at(i: j));
244 }
245 }
246}
247
248/*!
249 * Adds a new parameter with \a name and \a value.
250 * The parameter name is converted to upper-case.
251 */
252void QVersitProperty::insertParameter(const QString& name, const QString& value)
253{
254 d->mParameters.insert(akey: name.toUpper(), avalue: value);
255}
256
257/*!
258 * Removes a parameter with \a name and \a value.
259 *
260 * \sa removeParameters()
261 */
262void QVersitProperty::removeParameter(const QString& name, const QString& value)
263{
264 d->mParameters.remove(key: name.toUpper(), value);
265}
266
267/*!
268 * Removes all parameters with the given \a name.
269 *
270 * \sa removeParameter()
271 */
272void QVersitProperty::removeParameters(const QString& name)
273{
274 d->mParameters.remove(akey: name.toUpper());
275}
276
277/*!
278 * Return a copy of the contained list of parameters.
279 * Note that actual the parameters cannot be modified using the copy.
280 */
281QMultiHash<QString,QString> QVersitProperty::parameters() const
282{
283 return d->mParameters;
284}
285
286/*!
287 * Sets the property value to \a value.
288 */
289void QVersitProperty::setValue(const QVariant& value)
290{
291 d->mValue = value;
292}
293
294/*!
295 * Returns the value of the property.
296 */
297QVariant QVersitProperty::variantValue() const
298{
299 return d->mValue;
300}
301
302/*!
303 * \fn T QVersitProperty::value() const
304 * \overload
305 * Returns the value of the property as a \tt T.
306 */
307
308/*!
309 * Returns the value of the property as a string if possible, otherwise return an empty string.
310 * If the property is stored as a QByteArray, it is decoded using the charset specified in the
311 * property's parameters.
312 * \sa QVariant::toString()
313 */
314QString QVersitProperty::value() const
315{
316 if (d->mValue.type() == QVariant::ByteArray) {
317 if (d->mParameters.contains(QStringLiteral("CHARSET"))) {
318 QTextCodec* codec = QTextCodec::codecForName(
319 name: d->mParameters.value(QStringLiteral("CHARSET")).toLatin1());
320 if (codec != NULL) {
321 return codec->toUnicode(d->mValue.toByteArray());
322 }
323 }
324 return QString();
325 } else {
326 return d->mValue.toString();
327 }
328}
329
330/*!
331 * Sets the type of value held in the property to \a type.
332 */
333void QVersitProperty::setValueType(QVersitProperty::ValueType type)
334{
335 d->mValueType = type;
336}
337
338/*!
339 * Returns the type of value held in the property.
340 */
341QVersitProperty::ValueType QVersitProperty::valueType() const
342{
343 return d->mValueType;
344}
345
346/*!
347 * Returns true if the property is empty.
348 */
349bool QVersitProperty::isEmpty() const
350{
351 return d->mGroups.isEmpty()
352 && d->mName.isEmpty()
353 && d->mParameters.isEmpty()
354 && !d->mValue.isValid();
355}
356
357/*!
358 * Clears the contents of this property.
359 */
360void QVersitProperty::clear()
361{
362 d->mGroups.clear();
363 d->mName.clear();
364 d->mValue.clear();
365 d->mParameters.clear();
366 d->mValueType = QVersitProperty::PlainType;
367}
368
369QT_END_NAMESPACE_VERSIT
370

source code of qtpim/src/versit/qversitproperty.cpp