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 "qorganizerabstractrequest.h"
35#include "qorganizerabstractrequest_p.h"
36
37#ifndef QT_NO_DEBUG_STREAM
38#include <QtCore/qdebug.h>
39#endif
40
41QT_BEGIN_NAMESPACE_ORGANIZER
42
43/*!
44 \class QOrganizerAbstractRequest
45 \brief The QOrganizerAbstractRequest class provides a mechanism for asynchronous requests to be
46 made of a manager if it supports them.
47 \inmodule QtOrganizer
48 \ingroup organizer-main
49
50 It allows a client to asynchronously request some functionality of a particular QOrganizerManager.
51 Instances of the class will emit signals when the state of the request changes, or when more
52 results become available.
53
54 Clients should not attempt to create instances of this class directly, but should instead use
55 the use-case-specific classes derived from this class.
56
57 After creating any sort of request, the client retains ownership and must delete the request to
58 avoid leaking memory. The client may either do this directly (if not within a slot connected
59 to a signal emitted by the request) or by using the deleteLater() slot to schedule the request
60 for deletion when control returns to the event loop.
61 */
62
63/*!
64 \fn QOrganizerAbstractRequest::stateChanged(QOrganizerAbstractRequest::State newState)
65
66 This signal is emitted when the state of the request is changed. The new state of the request
67 will be contained in \a newState.
68 */
69
70/*!
71 \fn QOrganizerAbstractRequest::resultsAvailable()
72
73 This signal is emitted when new results are available. Results can include the operation error
74 which may be accessed via error(), or derived-class-specific results which are accessible through
75 the derived class API.
76
77 \sa error()
78 */
79
80/*!
81 \enum QOrganizerAbstractRequest::RequestType
82
83 Enumerates the various possible types of asynchronous requests.
84 \value InvalidRequest An invalid request.
85 \value ItemOccurrenceFetchRequest A request to fetch a list of occurrences of an organizer item.
86 \value ItemFetchRequest A request to fetch a list of organizer items.
87 \value ItemFetchForExportRequest A request to fetch a list of persisted organizer items and exceptions.
88 \value ItemIdFetchRequest A request to fetch a list of organizer item IDs.
89 \value ItemFetchByIdRequest A request to fetch a list of organizer items by the given IDs.
90 \value ItemRemoveRequest A request to remove a list of organizer items.
91 \value ItemRemoveByIdRequest A request to remove a list of organizer items by the given IDs.
92 \value ItemSaveRequest A request to save a list of organizer items.
93 \value CollectionFetchRequest A request to fetch a collection.
94 \value CollectionRemoveRequest A request to remove a collection.
95 \value CollectionSaveRequest A request to save a collection.
96 \value ItemFetchByIdRequest A request to fetch an organizer item by ID.
97 \value ItemRemoveByIdRequest A request to remove an organizer item by ID.
98
99 */
100
101/*!
102 \enum QOrganizerAbstractRequest::State
103
104 Enumerates the various states that a request may be in at any given time.
105 \value InactiveState Operation not yet started.
106 \value ActiveState Operation started, not yet finished.
107 \value CanceledState Operation is finished due to cancellation.
108 \value FinishedState Operation successfully completed.
109 */
110
111/*!
112 \internal
113 \fn QOrganizerAbstractRequest::QOrganizerAbstractRequest(QObject *parent)
114
115 Constructs a new, invalid asynchronous request with the specified \a parent.
116 */
117
118/*!
119 \internal
120
121 Constructs a new request from the given request data \a other with the given parent \a parent.
122*/
123QOrganizerAbstractRequest::QOrganizerAbstractRequest(QOrganizerAbstractRequestPrivate *other, QObject *parent)
124 : QObject(parent), d_ptr(other)
125{
126}
127
128/*!
129 Cleans up the memory used by this request.
130 */
131QOrganizerAbstractRequest::~QOrganizerAbstractRequest()
132{
133 d_ptr->m_mutex.lock();
134 QOrganizerManagerEngine *engine = QOrganizerManagerData::engine(manager: d_ptr->m_manager);
135 d_ptr->m_mutex.unlock();
136 if (engine)
137 engine->requestDestroyed(request: this);
138
139 delete d_ptr;
140 d_ptr = 0;
141}
142
143/*!
144 \fn bool QOrganizerAbstractRequest::isInactive() const
145
146 Returns true if the request is in the \l QOrganizerAbstractRequest::InactiveState state;
147 returns false otherwise.
148
149 \sa state(), isActive(), isCanceled(), isFinished()
150*/
151
152/*!
153 \fn bool QOrganizerAbstractRequest::isActive() const
154
155 Returns true if the request is in the \l QOrganizerAbstractRequest::ActiveState state;
156 returns false otherwise.
157
158 \sa state(), isInactive(), isCanceled(), isFinished()
159*/
160
161/*!
162 \fn bool QOrganizerAbstractRequest::isFinished() const
163
164 Returns true if the request is in the \l QOrganizerAbstractRequest::FinishedState;
165 returns false otherwise.
166
167 \sa state(), isActive(), isInactive(), isCanceled()
168*/
169
170/*!
171 \fn bool QOrganizerAbstractRequest::isCanceled() const
172
173 Returns true if the request is in the \l QOrganizerAbstractRequest::CanceledState;
174 returns false otherwise.
175
176 \sa state(), isActive(), isInactive(), isFinished()
177*/
178
179/*!
180 Returns the overall error of the most recent asynchronous operation.
181 */
182QOrganizerManager::Error QOrganizerAbstractRequest::error() const
183{
184 QMutexLocker ml(&d_ptr->m_mutex);
185 return d_ptr->m_error;
186}
187
188/*!
189 Returns the type of this asynchronous request.
190 */
191QOrganizerAbstractRequest::RequestType QOrganizerAbstractRequest::type() const
192{
193 return d_ptr->m_type;
194}
195
196/*!
197 Returns the current state of the request.
198 */
199QOrganizerAbstractRequest::State QOrganizerAbstractRequest::state() const
200{
201 QMutexLocker ml(&d_ptr->m_mutex);
202 return d_ptr->m_state;
203}
204
205/*!
206 Returns a pointer to the manager of which this request instance requests operations.
207*/
208QOrganizerManager *QOrganizerAbstractRequest::manager() const
209{
210 QMutexLocker ml(&d_ptr->m_mutex);
211 return d_ptr->m_manager;
212}
213
214/*!
215 Sets the manager of which this request instance requests operations to \a manager.
216
217 Note that if the current request is in active state, the manager can not be changed.
218*/
219void QOrganizerAbstractRequest::setManager(QOrganizerManager *manager)
220{
221 QMutexLocker ml(&d_ptr->m_mutex);
222
223 if (d_ptr->m_state == QOrganizerAbstractRequest::ActiveState && d_ptr->m_manager)
224 return;
225
226 d_ptr->m_manager = manager;
227 d_ptr->m_engine = QOrganizerManagerData::engine(manager: d_ptr->m_manager);
228}
229
230/*!
231 Attempts to start the request. Returns false if the request is in the QOrganizerAbstractRequest::Active
232 state, or if the request was unable to be performed by the manager engine; otherwise returns true.
233*/
234bool QOrganizerAbstractRequest::start()
235{
236 QMutexLocker ml(&d_ptr->m_mutex);
237 if (d_ptr->m_engine && d_ptr->m_state != QOrganizerAbstractRequest::ActiveState) {
238 ml.unlock();
239 return d_ptr->m_engine->startRequest(request: this);
240 }
241
242 return false;
243}
244
245/*!
246 Attempts to cancel the request. Returns false if the request is not in the QOrganizerAbstractRequest::Active
247 state, or if the request is unable to be cancelled by the manager engine; otherwise returns true.
248*/
249bool QOrganizerAbstractRequest::cancel()
250{
251 QMutexLocker ml(&d_ptr->m_mutex);
252 if (d_ptr->m_engine && d_ptr->m_state == QOrganizerAbstractRequest::ActiveState) {
253 ml.unlock();
254 return d_ptr->m_engine->cancelRequest(request: this);
255 }
256
257 return false;
258}
259
260/*!
261 Blocks until the request has been completed by the manager engine, or until \a msecs milliseconds
262 has elapsed.
263
264 If \a msecs is zero or negative, this function will block until the request is complete, regardless
265 of how long it takes.
266
267 Returns true if the request was cancelled or completed successfully within the given period,
268 otherwise false. Some backends are unable to support this operation safely, and will return false
269 immediately.
270 */
271bool QOrganizerAbstractRequest::waitForFinished(int msecs)
272{
273 QMutexLocker ml(&d_ptr->m_mutex);
274 if (d_ptr->m_engine) {
275 switch (d_ptr->m_state) {
276 case QOrganizerAbstractRequest::ActiveState:
277 ml.unlock();
278 return d_ptr->m_engine->waitForRequestFinished(request: this, msecs);
279 case QOrganizerAbstractRequest::CanceledState:
280 case QOrganizerAbstractRequest::FinishedState:
281 return true;
282 default:
283 return false;
284 }
285 }
286
287 return false;
288}
289
290#ifndef QT_NO_DEBUG_STREAM
291/*!
292 Outputs \a request to the debug stream \a dbg
293 */
294QDebug operator<<(QDebug dbg, const QOrganizerAbstractRequest &request)
295{
296 dbg.nospace() << "QOrganizerAbstractRequest(";
297 Q_ASSERT(request.d_ptr);
298 if (request.d_ptr->m_type != QOrganizerAbstractRequest::InvalidRequest) {
299 QMutexLocker locker(&request.d_ptr->m_mutex);
300 request.d_ptr->debugStreamOut(dbg);
301 } else {
302 dbg.nospace() << "(null)";
303 }
304 dbg.nospace() << ")";
305 return dbg.maybeSpace();
306}
307#endif
308
309#include "moc_qorganizerabstractrequest.cpp"
310
311QT_END_NAMESPACE_ORGANIZER
312

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