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 "qorganizeritemfetchhint_p.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
43QT_BEGIN_NAMESPACE_ORGANIZER
44
45/*!
46 \class QOrganizerItemFetchHint
47 \brief The QOrganizerItemFetchHint class provides hints to the manager about which organizer item
48 information needs to be retrieved.
49 \inmodule QtOrganizer
50 \ingroup organizer-filters
51
52 All of the hints may be ignored at the discretion of the manager, however if a manager
53 is able to optimize retrieval of organizer items due to hints, it may do so. If a manager
54 ignores a hint, it must retrieve the full set of data that the hint refers to.
55
56 The fetch hint contains:
57 \list
58 \li a list of detail definition names which the client is interested
59 in (empty if interested in all detail definitions)
60 \li some optimization flags which allow the client to tell the backend if they are
61 not interested in binary blobs (images etc).
62 \endlist
63
64 Important note: if certain organizer item is retrieved with fetch hint set, normal saving will
65 result in the loss of information that is not retrieved. Partial save should be used to avoid
66 information loss.
67 */
68
69/*!
70 \enum QOrganizerItemFetchHint::OptimizationHint
71
72 This enum defines flags which may be set to inform the backend that the client does
73 not require certain information.
74
75 \value AllRequired Tells the backend that all information is required.
76 \value NoActionPreferences Tells the backend that the client does not require retrieved
77 organizer items to include a cache of action preferences.
78 \value NoBinaryBlobs Tells the backend that the client does not require retrieved
79 organizer items to include binary blobs such as thumbnail images.
80 */
81
82/*!
83 Constructs a new organizer item fetch hint which requests that the backend fetch all information.
84 */
85QOrganizerItemFetchHint::QOrganizerItemFetchHint()
86 : d(new QOrganizerItemFetchHintPrivate)
87{
88}
89
90/*!
91 Constructs a new organizer item fetch hint as a copy of \a other.
92 */
93QOrganizerItemFetchHint::QOrganizerItemFetchHint(const QOrganizerItemFetchHint &other)
94 : d(other.d)
95{
96}
97
98/*!
99 Frees any memory in use by the fetch hint.
100 */
101QOrganizerItemFetchHint::~QOrganizerItemFetchHint()
102{
103}
104
105/*!
106 Assigns this fetch hint to the \a other.
107 */
108QOrganizerItemFetchHint& QOrganizerItemFetchHint::operator=(const QOrganizerItemFetchHint &other)
109{
110 d = other.d;
111 return *this;
112}
113
114/*!
115 Returns true if this fetch hint is the same as that of the \a other fetch hint; false otherwise.
116
117 \sa operator!=()
118*/
119bool QOrganizerItemFetchHint::operator==(const QOrganizerItemFetchHint &other) const
120{
121 if (d == other.d)
122 return true;
123
124 return d->m_optimizationHints == other.d->m_optimizationHints && d->m_detailTypesHint == other.d->m_detailTypesHint;
125}
126
127/*!
128 \fn QOrganizerItemFetchHint::operator!=(const QOrganizerItemFetchHint &other) const
129
130 Returns true if this fetch hint is not the same as that of the \a other fetch hint.
131
132 \sa operator==()
133*/
134
135/*!
136 Returns the list of detail types that identify details which should be retrieved by the manager
137 when fetching items.
138
139 \sa setDetailTypesHint()
140 */
141QList<QOrganizerItemDetail::DetailType> QOrganizerItemFetchHint::detailTypesHint() const
142{
143 return d->m_detailTypesHint;
144}
145
146/*!
147 Sets the list of detail types to \a detailTypes that identify details which should be retrieved'
148 by the manager when fetching items.
149
150 \sa detailTypesHint()
151 */
152void QOrganizerItemFetchHint::setDetailTypesHint(const QList<QOrganizerItemDetail::DetailType> &detailTypes)
153{
154 d->m_detailTypesHint = detailTypes;
155}
156
157/*!
158 Returns the optimization hint flags specified by the client.
159
160 \sa setOptimizationHints()
161 */
162QOrganizerItemFetchHint::OptimizationHints QOrganizerItemFetchHint::optimizationHints() const
163{
164 return d->m_optimizationHints;
165}
166
167/*!
168 Sets the optimization hint flags specified by the client to \a hints.
169
170 \sa optimizationHints()
171 */
172void QOrganizerItemFetchHint::setOptimizationHints(OptimizationHints hints)
173{
174 d->m_optimizationHints = hints;
175}
176
177#ifndef QT_NO_DATASTREAM
178/*!
179 \relates QOrganizerItemFetchHint
180 Streams \a hint to the data stream \a out.
181 */
182QDataStream &operator<<(QDataStream &out, const QOrganizerItemFetchHint &hint)
183{
184 quint8 formatVersion = 1;
185 return out << formatVersion
186 << hint.detailTypesHint()
187 << static_cast<quint32>(hint.optimizationHints());
188}
189
190/*!
191 \relates QOrganizerItemFetchHint
192 Streams \a hint in from the data stream \a in.
193 */
194QDataStream &operator>>(QDataStream &in, QOrganizerItemFetchHint &hint)
195{
196 quint8 formatVersion;
197 in >> formatVersion;
198 if (formatVersion == 1) {
199 QList<quint32> detailTypesHint;
200 quint32 optimizations;
201 in >> detailTypesHint >> optimizations;
202
203 QList<QOrganizerItemDetail::DetailType> types;
204 foreach (quint32 detailType, detailTypesHint)
205 types.append(t: static_cast<QOrganizerItemDetail::DetailType>(detailType));
206 hint.setDetailTypesHint(types);
207
208 hint.setOptimizationHints(static_cast<QOrganizerItemFetchHint::OptimizationHints>(optimizations));
209 } else {
210 in.setStatus(QDataStream::ReadCorruptData);
211 }
212 return in;
213}
214#endif // QT_NO_DATASTREAM
215
216#ifndef QT_NO_DEBUG_STREAM
217/*!
218 \relates QOrganizerItemFetchHint
219 Outputs \a hint to the debug stream \a dbg.
220 */
221QDebug operator<<(QDebug dbg, const QOrganizerItemFetchHint &hint)
222{
223 dbg.nospace() << "QOrganizerItemFetchHint(";
224 dbg.nospace() << "detailDefinitionsHint=";
225 dbg.nospace() << hint.detailTypesHint();
226 dbg.nospace() << ",";
227 dbg.nospace() << "optimizationHints=";
228 dbg.nospace() << static_cast<quint32>(hint.optimizationHints());
229 dbg.nospace() << ")";
230 return dbg.maybeSpace();
231}
232#endif // QT_NO_DEBUG_STREAM
233
234QT_END_NAMESPACE_ORGANIZER
235

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