1/****************************************************************************
2**
3** Copyright (C) 2015 The Qt Company Ltd.
4** Copyright (C) 2015 Canonical Ltd
5** Contact: http://www.qt.io/licensing/
6**
7** This file is part of the QtContacts module of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:LGPL21$
10** Commercial License Usage
11** Licensees holding valid commercial Qt licenses may use this file in
12** accordance with the commercial license agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and The Qt Company. For licensing terms
15** and conditions see http://www.qt.io/terms-conditions. For further
16** information use the contact form at http://www.qt.io/contact-us.
17**
18** GNU Lesser General Public License Usage
19** Alternatively, this file may be used under the terms of the GNU Lesser
20** General Public License version 2.1 or version 3 as published by the Free
21** Software Foundation and appearing in the file LICENSE.LGPLv21 and
22** LICENSE.LGPLv3 included in the packaging of this file. Please review the
23** following information to ensure the GNU Lesser General Public License
24** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
25** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
26**
27** As a special exception, The Qt Company gives you certain additional
28** rights. These rights are described in The Qt Company LGPL Exception
29** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
30**
31** $QT_END_LICENSE$
32**
33****************************************************************************/
34
35#include "qcontactcollection.h"
36#include "qcontactcollection_p.h"
37
38#ifndef QT_NO_DATASTREAM
39#include <QtCore/qdatastream.h>
40#endif
41#ifndef QT_NO_DEBUG_STREAM
42#include <QtCore/qdebug.h>
43#endif
44
45QT_BEGIN_NAMESPACE_CONTACTS
46
47/*!
48 \class QContactCollection
49 \brief The QContactCollection class represents a collection of contacts in a manager.
50 \inmodule QtContacts
51 \ingroup contacts-main
52
53 A collection has an ID and optionally some metadata, and contains zero or more contacts.
54 Each different manager will have different requirements before a collection may be saved
55 in it. Some managers do not allow collections to be saved at all, while others may require
56 a collection to have some minimal amount of metadata defined in it prior to save.
57 For example, most managers require a valid value for the QContactCollection::KeyName
58 meta data key to be set prior to save.
59
60 Every QContact is contained within a collection when stored in a manager.
61 To save an contact in a collection, the client should call QContact::setCollectionId()
62 on the contact, passing in the ID of the destination collection as the argument, and then
63 save the contact in the manager. To move an contact from one collection to another, the client
64 must fetch the contact from the manager, set the collection ID in the contact to the ID of the
65 collection to which the client wishes the contact to be moved, and then resave the contact in the
66 manager. That is, the collection which a contact is part of is treated as a property of the
67 contact.
68 */
69
70/*!
71 \enum QContactCollection::MetaDataKey
72
73 This enumeration describes the key of the contact collection metadata.
74
75 \value KeyName This metadata describes the name of the collection.
76 \value KeyDescription This metadata gives a description of the collection.
77 \value KeyColor This metadata describes the color of the collection.
78 \value KeySecondaryColor This metadata describes the secondary color of the collection.
79 \value KeyImage This metadata describes the image of the collection.
80 \value KeyExtended This is an extened metadata, which is stored as a QVariantMap.
81 */
82
83/*!
84 Constructs a new collection.
85 */
86QContactCollection::QContactCollection()
87 : d(new QContactCollectionData)
88{
89}
90
91/*!
92 Cleans up any memory in use by the collection.
93 */
94QContactCollection::~QContactCollection()
95{
96}
97
98/*!
99 Constructs a new copy of the \a other collection.
100 */
101QContactCollection::QContactCollection(const QContactCollection &other)
102 : d(other.d)
103{
104}
105
106/*!
107 Assigns this collection to be equal to the \a other collection.
108 */
109QContactCollection &QContactCollection::operator=(const QContactCollection &other)
110{
111 d = other.d;
112 return *this;
113}
114
115/*!
116 Returns true if the collection is the same as that of the \a other collection, false if either
117 the ID or any of the stored metadata are not the same.
118 */
119bool QContactCollection::operator==(const QContactCollection &other) const
120{
121 if (d == other.d)
122 return true;
123
124 if (d->m_id != other.d->m_id
125 || d->m_metaData.size() != other.d->m_metaData.size()) {
126 return false;
127 }
128
129 QMap<QContactCollection::MetaDataKey, QVariant>::const_iterator i = d->m_metaData.constBegin();
130 while (i != d->m_metaData.constEnd()) {
131 if (i.value() != other.d->m_metaData.value(akey: i.key()))
132 return false;
133 ++i;
134 }
135
136 return true;
137}
138
139/*!
140 \fn QContactCollection::operator!=(const QContactCollection &other) const
141
142 Returns true if the collection is not the same as the \a other collection.
143 */
144
145/*!
146 Returns the ID of the collection.
147 */
148QContactCollectionId QContactCollection::id() const
149{
150 return d->m_id;
151}
152
153/*!
154 Sets the ID of the collection to \a id.
155
156 If the ID is set to a null (default-constructed) ID, saving the collection will cause the manager
157 to save the collection as a new collection.
158 */
159void QContactCollection::setId(const QContactCollectionId &id)
160{
161 d->m_id = id;
162}
163
164/*!
165 Sets the metadata of the collection to be \a metaData.
166 */
167void QContactCollection::setMetaData(const QMap<QContactCollection::MetaDataKey, QVariant> &metaData)
168{
169 d->m_metaData = metaData;
170}
171
172/*!
173 Returns the meta data of the collection.
174 */
175QMap<QContactCollection::MetaDataKey, QVariant> QContactCollection::metaData() const
176{
177 return d->m_metaData;
178}
179
180/*!
181 Sets the meta data of the collection for the given \a key to the given \a value.
182 */
183void QContactCollection::setMetaData(MetaDataKey key, const QVariant &value)
184{
185 d->m_metaData.insert(akey: key, avalue: value);
186}
187
188/*!
189 Sets the value of the extended metadata with the given \a key to \a value.
190 */
191void QContactCollection::setExtendedMetaData(const QString &key, const QVariant &value)
192{
193 QVariantMap variantMap = d->m_metaData.value(akey: QContactCollection::KeyExtended).toMap();
194 variantMap.insert(akey: key, avalue: value);
195 d->m_metaData.insert(akey: QContactCollection::KeyExtended, avalue: variantMap);
196}
197
198/*!
199 Returns the value of extended metadata with the given \a key.
200 */
201QVariant QContactCollection::extendedMetaData(const QString &key) const
202{
203 return d->m_metaData.value(akey: QContactCollection::KeyExtended).toMap().value(akey: key);
204}
205
206/*!
207 Returns the meta data of the collection for the given \a key.
208 */
209QVariant QContactCollection::metaData(MetaDataKey key) const
210{
211 return d->m_metaData.value(akey: key);
212}
213
214/*!
215 \relates QContactCollection
216 Returns the hash value for \a key.
217 */
218Q_CONTACTS_EXPORT uint qHash(const QContactCollection &key)
219{
220 uint hash = qHash(id: key.id());
221 QMap<QContactCollection::MetaDataKey, QVariant>::const_iterator i = key.d->m_metaData.constBegin();
222 while (i != key.d->m_metaData.constEnd()) {
223 if (i.key() == QContactCollection::KeyExtended) {
224 QVariantMap variantMap = i.value().toMap();
225 QVariantMap::const_iterator j = variantMap.constBegin();
226 while (j != variantMap.constEnd()) {
227 hash += QT_PREPEND_NAMESPACE(qHash)(key: j.key()) + QT_PREPEND_NAMESPACE(qHash)(key: j.value().toString());
228 ++j;
229 }
230 } else {
231 hash += QT_PREPEND_NAMESPACE(qHash)(key: i.key()) + QT_PREPEND_NAMESPACE(qHash)(key: i.value().toString());
232 }
233 ++i;
234 }
235 return hash;
236}
237
238#ifndef QT_NO_DEBUG_STREAM
239/*!
240 \relates QContactCollection
241 Streams the \a collection to the given debug stream \a dbg, and returns the stream.
242 */
243QDebug operator<<(QDebug dbg, const QContactCollection& collection)
244{
245 dbg.nospace() << "QContactCollection(id=" << collection.id();
246
247 QMap<QContactCollection::MetaDataKey, QVariant> metaData = collection.metaData();
248 QMap<QContactCollection::MetaDataKey, QVariant>::const_iterator i = metaData.constBegin();
249 while (i != metaData.constEnd()) {
250 dbg.nospace() << ", " << i.key() << '=' << i.value();
251 ++i;
252 }
253 dbg.nospace() << ')';
254 return dbg.maybeSpace();
255}
256#endif // QT_NO_DEBUG_STREAM
257
258#ifndef QT_NO_DATASTREAM
259/*!
260 \relates QContactCollection
261 Writes \a collection to the stream \a out.
262 */
263QDataStream &operator<<(QDataStream &out, const QContactCollection &collection)
264{
265 quint8 formatVersion = 1;
266 return out << formatVersion
267 << collection.id().toString()
268 << collection.metaData();
269}
270
271/*!
272 \relates QContactCollection
273 Reads a contact collection from stream \a in into \a collection.
274 */
275QDataStream &operator>>(QDataStream &in, QContactCollection &collection)
276{
277 quint8 formatVersion;
278 in >> formatVersion;
279 if (formatVersion == 1) {
280 QString idString;
281 QMap<int, QVariant> values;
282 in >> idString >> values;
283
284 collection = QContactCollection();
285 collection.setId(QContactCollectionId::fromString(idString));
286
287 QMap<int, QVariant>::const_iterator i = values.constBegin();
288 while (i != values.constEnd()) {
289 collection.setMetaData(key: static_cast<QContactCollection::MetaDataKey>(i.key()), value: i.value());
290 ++i;
291 }
292 } else {
293 in.setStatus(QDataStream::ReadCorruptData);
294 }
295 return in;
296}
297#endif // QT_NO_DATASTREAM
298
299QT_END_NAMESPACE_CONTACTS
300

source code of qtpim/src/contacts/qcontactcollection.cpp