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 "qcontactfetchhint.h"
35#include "qcontactfetchhint_p.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
44QT_BEGIN_NAMESPACE_CONTACTS
45
46/*!
47 \class QContactFetchHint
48
49 \inmodule QtContacts
50
51 \brief The QContactFetchHint class provides hints to the manager about which contact
52 information needs to be retrieved in an asynchronous fetch request or a synchronous
53 function call.
54
55 All of the hints may be ignored at the discretion of the manager, however if a manager
56 is able to optimize retrieval of contacts due to hints, it may do so. If a manager
57 ignores a hint, it must retrieve the full set of data that the hint refers to.
58
59 The fetch hint contains:
60 \list
61 \li a list of detail types which the client is interested
62 in (empty if interested in all detail types)
63 \li a list of relationship types which the client is interested in
64 (empty if interested in all relationships)
65 \li some optimization flags which allow the client to tell the backend if they are
66 not interested in any relationships, any action preferences, or any binary blobs (images etc).
67 \li a preferred size for any images, if the backend supports multiple sizes or scaling
68 \endlist
69
70 Important note: a client should not make changes to a contact which has been retrieved
71 using a fetch hint other than the default fetch hint. Doing so can result in information
72 loss when saving the contact back to the manager (as the "new" restricted contact will
73 replace the previously saved contact in the backend).
74 */
75
76/*!
77 \enum QContactFetchHint::OptimizationHint
78
79 This enum defines flags which may be set to inform the backend that the client does
80 not require certain information. The backend may safely ignore the hint, but then
81 must return the full set of information relating to the optimization hint.
82
83 \value AllRequired Tells the backend that all information is required
84 \value NoRelationships Tells the backend that the client does not require retrieved contacts to include a cache of relationships
85 \value NoActionPreferences Tells the backend that the client does not require retrieved contacts to include a cache of action preferences
86 \value NoBinaryBlobs Tells the backend that the client does not require retrieved contacts to include binary blobs
87 */
88
89/*!
90 Constructs a new contact fetch hint which requests that the backend fetch all information
91 */
92QContactFetchHint::QContactFetchHint()
93 : d(new QContactFetchHintPrivate)
94{
95}
96
97/*!
98 Constructs a new contact fetch hint as a copy of \a other
99 */
100QContactFetchHint::QContactFetchHint(const QContactFetchHint &other)
101 : d(other.d)
102{
103}
104
105/*!
106 Frees any memory in use by the fetch hint
107 */
108QContactFetchHint::~QContactFetchHint()
109{
110}
111
112/*!
113 Assigns this fetch hint to be equal to the \a other fetch hint
114 */
115QContactFetchHint& QContactFetchHint::operator=(const QContactFetchHint& other)
116{
117 d = other.d;
118 return *this;
119}
120
121/*!
122 Returns the list of detail types that identify which detail type
123 the manager should (at a minimum) retrieve when fetching contacts.
124 This hint may be ignored by the backend, in which case it will return the full set of details for
125 each contact retrieved.
126
127 \sa setDetailTypesHint()
128 */
129QList<QContactDetail::DetailType> QContactFetchHint::detailTypesHint() const
130{
131 return d.constData()->m_typesHint;
132}
133
134/*!
135 Sets the list of detail types that identify which detail type
136 the manager should (at a minimum) retrieve when fetching contacts to \a types.
137 This hint may be ignored by the backend, in which case it will return the full set of details for
138 each contact retrieved.
139
140 \sa detailTypesHint()
141 */
142void QContactFetchHint::setDetailTypesHint(const QList<QContactDetail::DetailType> &types)
143{
144 d->m_typesHint = types;
145}
146
147/*!
148 Returns the list of relationship types that the manager should (at a minimum) retrieve
149 when fetching contacts.
150 This hint may be ignored by the backend, in which case it will return the full set of
151 relationships for each contact retrieved.
152
153 \sa setRelationshipTypesHint(), QContact::relationships()
154 */
155QStringList QContactFetchHint::relationshipTypesHint() const
156{
157 return d.constData()->m_relationshipsHint;
158}
159
160/*!
161 Sets the list of relationship types that the manager should (at a minimum) retrieve
162 when fetching contacts to \a relationshipTypes.
163 This hint may be ignored by the backend, in which case it will return the full set of
164 relationships for each contact retrieved.
165
166 \sa relationshipTypesHint(), QContact::relationships()
167 */
168void QContactFetchHint::setRelationshipTypesHint(const QStringList& relationshipTypes)
169{
170 d->m_relationshipsHint = relationshipTypes;
171}
172
173/*!
174 Returns the preferred pixel dimensions for any images returned
175 by the manager for a given request. This hint may be ignored
176 by the manager.
177
178 This is useful when the backend supports multiple sizes of an
179 image (or the image is natively scaleable) in order to get an
180 image that will look good at the indicated dimensions.
181
182 The caller should be prepared for images of any dimensions,
183 in any case.
184 */
185QSize QContactFetchHint::preferredImageSize() const
186{
187 return d.constData()->m_preferredImageSize;
188}
189
190/*!
191 Sets the preferred pixel dimensions for any images returned
192 by the manager for the given request to \a size. This hint
193 may be ignored by the manager.
194
195 This is useful when the backend supports multiple sizes of an
196 image (or the image is natively scaleable) in order to get an
197 image that will look good at the indicated dimensions.
198
199 The caller should be prepared for images of any dimensions,
200 in any case.
201 */
202void QContactFetchHint::setPreferredImageSize(const QSize& size)
203{
204 d->m_preferredImageSize = size;
205}
206
207/*!
208 Returns the optimization hint flags specified by the client.
209 These hints may be ignored by the backend, in which case it will return
210 the full set of information accessible in a contact, including
211 relationships, action preferences, and binary blobs.
212
213 \sa setOptimizationHints()
214 */
215QContactFetchHint::OptimizationHints QContactFetchHint::optimizationHints() const
216{
217 return d.constData()->m_optimizationHints;
218}
219
220/*!
221 Sets the optimization hint flags specified by the client to \a hints.
222 These hints may be ignored by the backend, in which case it will return
223 the full set of information accessible in a contact, including
224 relationships, action preferences, and binary blobs.
225
226 \sa optimizationHints()
227 */
228void QContactFetchHint::setOptimizationHints(OptimizationHints hints)
229{
230 d->m_optimizationHints = hints;
231}
232
233/*!
234 Returns the number of results which the client considers to be the
235 maximum number of useful results. The client is only interested
236 in this number of results, so returning any more results
237 would be superfluous to the client's requirements.
238 Note that this fetch hint only affects operations where the
239 backend would return a list of contacts; this hint specifies
240 the maximum number of contacts in the list which would be useful
241 to the client. The backend may ignore this hint, in which case it
242 must return all contacts which would otherwise have been returned
243 as a result of the operation.
244
245 A negative value for count denotes that the client wishes to
246 retrieve all results. The default value is -1.
247 */
248int QContactFetchHint::maxCountHint() const
249{
250 return d.constData()->m_maxCount;
251}
252
253/*!
254 Sets the maximum number of results which the client is interested in
255 to \a count. The client is only interested in this number of results,
256 so returning any more results would be superfluous to the client's
257 requirements. Note that this fetch hint only affects operations where
258 the backend would return a list of contacts; this hint specifies
259 the maximum number of contacts in the list which would be useful
260 to the client. The backend may ignore this hint, in which case it
261 must return all contacts which would otherwise have been returned
262 as a result of the operation.
263
264 A negative value for count denotes that the client wishes to
265 retrieve all results. The default value is -1.
266*/
267void QContactFetchHint::setMaxCountHint(int count)
268{
269 count < 0 ? (d->m_maxCount = -1) : (d->m_maxCount = count);
270}
271
272#ifndef QT_NO_DATASTREAM
273QDataStream& operator<<(QDataStream& out, const QContactFetchHint& hint)
274{
275 quint8 formatVersion = 2; // Version of QDataStream format for QContactFetchHint
276 QList<quint32> detailTypeHintHelper;
277 foreach (QContactDetail::DetailType hintType, hint.detailTypesHint())
278 detailTypeHintHelper.append(t: static_cast<quint32>(hintType));
279
280 return out << formatVersion
281 << detailTypeHintHelper
282 << hint.relationshipTypesHint()
283 << static_cast<quint32>(hint.optimizationHints())
284 << hint.preferredImageSize()
285 << hint.maxCountHint();
286}
287
288QDataStream& operator>>(QDataStream& in, QContactFetchHint& hint)
289{
290 hint = QContactFetchHint();
291 quint8 formatVersion;
292 in >> formatVersion;
293 if (formatVersion == 1 || formatVersion == 2) {
294 QList<quint32> detailTypeHintsHelper;
295 QList<QContactDetail::DetailType> detailTypeHints;
296 QStringList relationshipTypeHints;
297 quint32 optimizations;
298 QSize dimensions;
299 in >> detailTypeHintsHelper >> relationshipTypeHints >> optimizations >> dimensions;
300 foreach (quint32 hintType, detailTypeHintsHelper)
301 detailTypeHints.append(t: QContactDetail::DetailType(hintType));
302
303 hint.setDetailTypesHint(detailTypeHints);
304 hint.setRelationshipTypesHint(relationshipTypeHints);
305 hint.setOptimizationHints(QContactFetchHint::OptimizationHints(optimizations));
306 hint.setPreferredImageSize(dimensions);
307
308 // version two also has a maximum fetch count hint.
309 if (formatVersion == 2) {
310 int maxCountHint = -1;
311 in >> maxCountHint;
312 hint.setMaxCountHint(maxCountHint);
313 }
314 } else {
315 in.setStatus(QDataStream::ReadCorruptData);
316 }
317 return in;
318}
319
320#endif
321
322#ifndef QT_NO_DEBUG_STREAM
323/*!
324 Outputs \a hint to the debug stream \a dbg
325 */
326QDebug operator<<(QDebug dbg, const QContactFetchHint& hint)
327{
328 dbg.nospace() << "QContactFetchHint("
329 << "detailTypeHint=" << hint.detailTypesHint() << ","
330 << "relationshipTypesHint=" << hint.relationshipTypesHint() << ","
331 << "optimizationHints=" << static_cast<quint32>(hint.optimizationHints()) << ","
332 << "preferredImageSize=" << hint.preferredImageSize()
333 << "maxCountHint=" << hint.maxCountHint()
334 << ")";
335 return dbg.maybeSpace();
336}
337#endif
338
339QT_END_NAMESPACE_CONTACTS
340

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