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 "qorganizeritemid.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 QOrganizerItemId
49 \brief The QOrganizerItemId class provides information that uniquely identifies an organizer
50 item 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 organizer item,
55 and the engine specific ID of the organizer item in that manager.
56
57 An invalid QOrganizerItemId has an empty manager URI.
58*/
59
60/*!
61 \fn QOrganizerItemId::QOrganizerItemId()
62
63 Constructs a new, invalid organizer item ID.
64*/
65
66// TODO: Document and remove internal once the correct signature has been determined
67/*!
68 \fn QOrganizerItemId::QOrganizerItemId(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 QOrganizerItemId::operator==(const QOrganizerItemId &other) const
77
78 Returns true if this organizer item 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 QOrganizerItemId::operator!=(const QOrganizerItemId &other) const
84
85 Returns true if either the manager URI or engine specific ID of this
86 organizer item ID is different to that of \a other.
87*/
88
89/*!
90 \fn bool operator<(const QOrganizerItemId &id1, const QOrganizerItemId &id2)
91 \relates QOrganizerItemId
92
93 Returns true if the organizer item ID \a id1 will be considered less than
94 the organizer item 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 organizer item ID consists of an empty manager URI and a null engine ID,
100 and hence will be less than any valid, non-null organizer item ID.
101
102 This operator is provided primarily to allow use of a QOrganizerItemId as a key in a QMap.
103*/
104
105/*!
106 \fn uint qHash(const QOrganizerItemId &id)
107 \relates QOrganizerItemId
108
109 Returns the hash value for \a id.
110*/
111
112/*!
113 \fn bool QOrganizerItemId::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 organizer item.
118
119 \sa isNull()
120*/
121
122/*!
123 \fn bool QOrganizerItemId::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 QOrganizerItemId::managerUri() const
133
134 Returns the URI of the manager which contains the organizer item identified by this ID.
135
136 \sa localId()
137*/
138
139/*!
140 \fn QByteArray QOrganizerItemId::localId() const
141
142 Returns the organizer item's engine specific ID part.
143
144 \sa managerUri()
145*/
146
147/*!
148 Serializes the organizer item 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 QOrganizerItemId::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 item ID if the given \a idString is not a valid, serialized item ID.
168
169 \sa toString(), fromByteArray()
170*/
171QOrganizerItemId QOrganizerItemId::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 QOrganizerItemId(managerUri, QByteArray::fromHex(hexEncoded: localId));
179 }
180
181 return QOrganizerItemId();
182}
183
184/*!
185 Serializes the organizer item ID to a byte array.
186
187 \sa fromByteArray(), toString()
188*/
189QByteArray QOrganizerItemId::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 item ID if the given \a idData does not contain a valid, serialized item ID.
200
201 \sa toByteArray(), fromString()
202*/
203QOrganizerItemId QOrganizerItemId::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 QOrganizerItemId(managerUri, localId);
210
211 return QOrganizerItemId();
212}
213
214#ifndef QT_NO_DEBUG_STREAM
215/*!
216 \relates QOrganizerItemId
217 Outputs \a id to the debug stream \a dbg.
218*/
219Q_ORGANIZER_EXPORT QDebug operator<<(QDebug dbg, const QOrganizerItemId &id)
220{
221 dbg.nospace() << "QOrganizerItemId(" << qPrintable(id.toString()) << ")";
222 return dbg.maybeSpace();
223}
224#endif // QT_NO_DEBUG_STREAM
225
226#ifndef QT_NO_DATASTREAM
227/*!
228 \relates QOrganizerItemId
229 Streams \a id to the data stream \a out.
230*/
231Q_ORGANIZER_EXPORT QDataStream &operator<<(QDataStream &out, const QOrganizerItemId &id)
232{
233 out << id.toByteArray();
234 return out;
235}
236
237/*!
238 \relates QOrganizerItemId
239 Streams \a id in from the data stream \a in.
240*/
241Q_ORGANIZER_EXPORT QDataStream &operator>>(QDataStream &in, QOrganizerItemId &id)
242{
243 QByteArray idData;
244 in >> idData;
245 id = QOrganizerItemId::fromByteArray(idData);
246 return in;
247}
248#endif // QT_NO_DATASTREAM
249
250QT_END_NAMESPACE_ORGANIZER
251

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