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 "qcontactcollectionid.h"
36
37#ifndef QT_NO_DATASTREAM
38#include <QtCore/qdatastream.h>
39#endif
40#ifndef QT_NO_DEBUG_STREAM
41#include <QtCore/qdebug.h>
42#endif
43
44#include "qcontactmanager_p.h"
45
46QT_BEGIN_NAMESPACE_CONTACTS
47
48/*!
49 \class QContactCollectionId
50 \brief The QContactCollectionId class provides information that uniquely identifies a collection
51 in a particular manager.
52 \inmodule QtContact
53 \ingroup contact-main
54
55 It consists of a manager URI which identifies the manager which contains the collection,
56 and the engine specific ID of the collection in that manager.
57
58 An invalid QContactCollectionId has an empty manager URI.
59*/
60
61/*!
62 \fn QContactCollectionId::QContactCollectionId()
63
64 Constructs a new, invalid collection ID.
65*/
66
67// TODO: Document and remove internal once the correct signature has been determined
68/*!
69 \fn QContactCollectionId::QContactCollectionId(const QString &managerUri, const QByteArray &localId)
70 \internal
71
72 Constructs an ID from the supplied manager URI \a managerUri and the engine
73 specific \a localId string.
74*/
75
76/*!
77 \fn bool QContactCollectionId::operator==(const QContactCollectionId &other) const
78
79 Returns true if this collection ID has the same manager URI and
80 engine specific ID as \a other. Returns true also, if both IDs are null.
81*/
82
83/*!
84 \fn bool QContactCollectionId::operator!=(const QContactCollectionId &other) const
85
86 Returns true if either the manager URI or engine specific ID of this
87 collection ID is different to that of \a other.
88*/
89
90/*!
91 \fn bool operator<(const QContactCollectionId &id1, const QContactCollectionId &id2)
92 \relates QContactCollectionId
93
94 Returns true if the collection ID \a id1 will be considered less than
95 the collection ID \a id2 if the manager URI of ID \a id1 is alphabetically
96 less than the manager URI of the \a id2 ID. If both IDs have the same
97 manager URI, ID \a id1 will be considered less than the ID \a id2
98 if the the engine specific ID of \a id1 is less than the engine specific ID of \a id2.
99
100 The invalid, null collection ID consists of an empty manager URI and a null engine ID,
101 and hence will be less than any valid, non-null collection ID.
102
103 This operator is provided primarily to allow use of a QContactCollectionId as a key in a QMap.
104*/
105
106/*!
107 \fn uint qHash(const QContactCollectionId &id)
108 \relates QContactCollectionId
109
110 Returns the hash value for \a id.
111*/
112
113/*!
114 \fn bool QContactCollectionId::isValid() const
115
116 Returns true if the manager URI part is not null; returns false otherwise.
117
118 Note that valid ID may be null at the same time, which means new collection.
119
120 \sa isNull()
121*/
122
123/*!
124 \fn bool QContactCollectionId::isNull() const
125
126 Returns true if the engine specific ID part is a null (default constructed);
127 returns false otherwise.
128
129 \sa isValid()
130*/
131
132/*!
133 \fn QString QContactCollectionId::managerUri() const
134
135 Returns the URI of the manager which contains the collection identified by this ID.
136
137 \sa localId()
138*/
139
140/*!
141 \fn QByteArray QContactCollectionId::localId() const
142
143 Returns the collection's engine specific ID part.
144
145 \sa managerUri()
146*/
147
148/*!
149 Serializes the collection ID to a string. The format of the string will be:
150 "qtcontacts:managerName:params:localId", where localId is encoded binary data
151 formatted as hexadecimal to ensure it is in a printable form.
152
153 \sa fromString(), toByteArray()
154*/
155QString QContactCollectionId::toString() const
156{
157 if (!isNull()) {
158 // Ensure the localId component has a valid string representation by hex encoding
159 const QByteArray encodedLocalId(m_localId.toHex());
160 return QString::fromUtf8(str: QContactManagerData::buildIdData(managerUri: m_managerUri, localId: encodedLocalId));
161 }
162
163 return QString();
164}
165
166/*!
167 Deserializes the given \a idString. Returns a default-constructed (null)
168 collection ID if the given \a idString is not a valid, serialized collection ID.
169
170 \sa toString(), fromByteArray()
171*/
172QContactCollectionId QContactCollectionId::fromString(const QString &idString)
173{
174 QString managerUri;
175 QByteArray localId;
176
177 if (QContactManagerData::parseIdData(idData: idString.toUtf8(), managerName: 0, params: 0, managerUri: &managerUri, localId: &localId)) {
178 // The localId component must be decoded from hex
179 return QContactCollectionId(managerUri, QByteArray::fromHex(hexEncoded: localId));
180 }
181
182 return QContactCollectionId();
183}
184
185/*!
186 Serializes the collection ID to a byte array.
187
188 \sa fromByteArray(), toString()
189*/
190QByteArray QContactCollectionId::toByteArray() const
191{
192 if (!isNull())
193 return QContactManagerData::buildIdData(managerUri: m_managerUri, localId: m_localId);
194
195 return QByteArray();
196}
197
198/*!
199 Deserializes the given \a idData. Returns a default-constructed (null)
200 collection ID if the given \a idData does not contain a valid, serialized collection ID.
201
202 \sa toByteArray(), fromString()
203*/
204QContactCollectionId QContactCollectionId::fromByteArray(const QByteArray &idData)
205{
206 QString managerUri;
207 QByteArray localId;
208
209 if (QContactManagerData::parseIdData(idData, managerName: 0, params: 0, managerUri: &managerUri, localId: &localId))
210 return QContactCollectionId(managerUri, localId);
211
212 return QContactCollectionId();
213}
214
215#ifndef QT_NO_DEBUG_STREAM
216/*!
217 \relates QContactCollectionId
218 Outputs \a id to the debug stream \a dbg.
219*/
220QDebug operator<<(QDebug dbg, const QContactCollectionId &id)
221{
222 dbg.nospace() << "QContactCollectionId(" << id.toString().toUtf8().constData() << ")";
223 return dbg.maybeSpace();
224}
225#endif // QT_NO_DEBUG_STREAM
226
227#ifndef QT_NO_DATASTREAM
228/*!
229 \relates QContactCollectionId
230 Streams \a id to the data stream \a out.
231*/
232QDataStream &operator<<(QDataStream &out, const QContactCollectionId &id)
233{
234 out << id.toByteArray();
235 return out;
236}
237
238/*!
239 \relates QContactCollectionId
240 Streams \a id in from the data stream \a in.
241*/
242QDataStream &operator>>(QDataStream &in, QContactCollectionId &id)
243{
244 QByteArray idData;
245 in >> idData;
246 id = QContactCollectionId::fromByteArray(idData);
247 return in;
248}
249#endif // QT_NO_DATASTREAM
250
251QT_END_NAMESPACE_CONTACTS
252

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