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

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