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

source code of qtpim/src/organizer/qorganizercollectionid.cpp