← Back to branch summary

~ubuntu-branches/ubuntu/quantal/qtmobility/quantal

« back to all changes in this revision

Viewing changes to src/organizer/qorganizerabstractrequest.cpp

  • Committer: Bazaar Package Importer
  • Author(s): Jonathan Riddell
  • Date: 2010-11-16 16:18:07 UTC
  • mfrom: (1.1.3 upstream)
  • Revision ID: james.westby@ubuntu.com-20101116161807-k2dzt2nyse975r3l
Tags: 1.1.0-0ubuntu1
* New upstream release
* Syncronise with Debian, no remaining changes

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/organizer/qorganizerabstractrequest.cpp
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
 
4
** All rights reserved.
 
5
** OrganizerItem: Nokia Corporation (qt-info@nokia.com)
 
6
**
 
7
** This file is part of the Qt Mobility Components.
 
8
**
 
9
** $QT_BEGIN_LICENSE:LGPL$
 
10
** Commercial Usage
 
11
** Licensees holding valid Qt Commercial licenses may use this file in 
 
12
** accordance with the Qt Commercial License Agreement provided with
 
13
** the Software or, alternatively, in accordance with the terms
 
14
** contained in a written agreement between you and Nokia.
 
15
**
 
16
** GNU Lesser General Public License Usage
 
17
** Alternatively, this file may be used under the terms of the GNU Lesser
 
18
** General Public License version 2.1 as published by the Free Software
 
19
** Foundation and appearing in the file LICENSE.LGPL included in the
 
20
** packaging of this file.  Please review the following information to
 
21
** ensure the GNU Lesser General Public License version 2.1 requirements
 
22
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
 
23
**
 
24
** In addition, as a special exception, Nokia gives you certain additional
 
25
** rights.  These rights are described in the Nokia Qt LGPL Exception
 
26
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
 
27
**
 
28
** GNU General Public License Usage
 
29
** Alternatively, this file may be used under the terms of the GNU
 
30
** General Public License version 3.0 as published by the Free Software
 
31
** Foundation and appearing in the file LICENSE.GPL included in the
 
32
** packaging of this file.  Please review the following information to
 
33
** ensure the GNU General Public License version 3.0 requirements will be
 
34
** met: http://www.gnu.org/copyleft/gpl.html.
 
35
**
 
36
** If you are unsure which license is appropriate for your use, please
 
37
** contact the sales department at qt-sales@nokia.com.
 
38
** $QT_END_LICENSE$
 
39
**
 
40
****************************************************************************/
 
41
 
 
42
#include "qorganizerabstractrequest.h"
 
43
#include "qorganizerabstractrequest_p.h"
 
44
#include "qorganizermanager.h"
 
45
#include "qorganizermanager_p.h"
 
46
#include "qorganizermanagerengine.h"
 
47
 
 
48
 
 
49
QTM_BEGIN_NAMESPACE
 
50
 
 
51
/*!
 
52
  \class QOrganizerAbstractRequest
 
53
 
 
54
  \brief The QOrganizerAbstractRequest class provides a mechanism for
 
55
  asynchronous requests to be made of a manager if it supports them.
 
56
 
 
57
  \inmodule QtOrganizer
 
58
 
 
59
  \ingroup organizer-main
 
60
 
 
61
  It allows a client to asynchronously request some functionality of a
 
62
  particular QOrganizerManager.  Instances of the class will emit signals
 
63
  when the state of the request changes, or when more results become
 
64
  available.
 
65
 
 
66
  Clients should not attempt to create instances of this class directly,
 
67
  but should instead use the use-case-specific classes derived from this
 
68
  class.
 
69
 
 
70
  After creating any sort of request, the client retains ownership and
 
71
  must delete the request to avoid leaking memory.  The client may either
 
72
  do this directly (if not within a slot connected to a signal emitted
 
73
  by the request) or by using the deleteLater() slot to schedule the
 
74
  request for deletion when control returns to the event loop.
 
75
 */
 
76
 
 
77
/*!
 
78
  \fn QOrganizerAbstractRequest::stateChanged(QOrganizerAbstractRequest::State newState)
 
79
  This signal is emitted when the state of the request is changed.  The new state of
 
80
  the request will be contained in \a newState.
 
81
 */
 
82
 
 
83
 
 
84
/*!
 
85
  \fn QOrganizerAbstractRequest::resultsAvailable()
 
86
  This signal is emitted when new results are available.  Results can include
 
87
  the operation error which may be accessed via error(), or derived-class-specific
 
88
  results which are accessible through the derived class API.
 
89
 
 
90
  \sa error()
 
91
 */
 
92
 
 
93
/*!
 
94
  \enum QOrganizerAbstractRequest::RequestType
 
95
  Enumerates the various possible types of asynchronous requests
 
96
  \value InvalidRequest An invalid request
 
97
  \value ItemOccurrenceFetchRequest A request to fetch a list of occurrences of an organizer item
 
98
  \value ItemFetchRequest A request to fetch a list of organizer items
 
99
  \value ItemFetchForExportRequest A request to fetch a list of persisted organizer items and exceptions
 
100
  \value ItemIdFetchRequest A request to fetch a list of organizer item ids
 
101
  \value ItemRemoveRequest A request to remove a list of organizer items
 
102
  \value ItemSaveRequest A request to save a list of organizer items
 
103
  \value DetailDefinitionFetchRequest A request to fetch a collection of detail definitions
 
104
  \value DetailDefinitionRemoveRequest A request to remove a list of detail definitions
 
105
  \value DetailDefinitionSaveRequest A request to save a list of detail definitions
 
106
  \value CollectionFetchRequest A request to fetch a collection.
 
107
  \value CollectionRemoveRequest A request to remove a collection.
 
108
  \value CollectionSaveRequest A request to save a collection.
 
109
 */
 
110
 
 
111
/*!
 
112
  \enum QOrganizerAbstractRequest::State
 
113
  Enumerates the various states that a request may be in at any given time
 
114
  \value InactiveState Operation not yet started
 
115
  \value ActiveState Operation started, not yet finished
 
116
  \value CanceledState Operation is finished due to cancellation
 
117
  \value FinishedState Operation successfully completed
 
118
 */
 
119
 
 
120
/*!
 
121
  \fn QOrganizerAbstractRequest::QOrganizerAbstractRequest(QObject* parent)
 
122
  Constructs a new, invalid asynchronous request with the specified \a parent
 
123
 */
 
124
 
 
125
/*!
 
126
  \internal
 
127
  Constructs a new request from the given request data \a otherd with
 
128
  the given parent \a parent
 
129
*/
 
130
QOrganizerAbstractRequest::QOrganizerAbstractRequest(QOrganizerAbstractRequestPrivate* otherd, QObject* parent)
 
131
    : QObject(parent), d_ptr(otherd)
 
132
{
 
133
}
 
134
 
 
135
/*! Cleans up the memory used by this request */
 
136
QOrganizerAbstractRequest::~QOrganizerAbstractRequest()
 
137
{
 
138
    if (d_ptr) {
 
139
        QOrganizerManagerEngine *engine = QOrganizerManagerData::engine(d_ptr->m_manager);
 
140
        if (engine) {
 
141
            engine->requestDestroyed(this);
 
142
        }
 
143
 
 
144
        delete d_ptr;
 
145
    }
 
146
}
 
147
 
 
148
/*!
 
149
  Returns true if the request is in the \c QOrganizerAbstractRequest::InactiveState state; otherwise, returns false
 
150
 
 
151
  \sa state()
 
152
 */
 
153
bool QOrganizerAbstractRequest::isInactive() const
 
154
{
 
155
    QMutexLocker ml(&d_ptr->m_mutex);
 
156
    return (d_ptr->m_state == QOrganizerAbstractRequest::InactiveState);
 
157
}
 
158
 
 
159
/*!
 
160
  Returns true if the request is in the \c QOrganizerAbstractRequest::ActiveState state; otherwise, returns false
 
161
 
 
162
  \sa state()
 
163
 */
 
164
bool QOrganizerAbstractRequest::isActive() const
 
165
{
 
166
    QMutexLocker ml(&d_ptr->m_mutex);
 
167
    return (d_ptr->m_state == QOrganizerAbstractRequest::ActiveState);
 
168
}
 
169
 
 
170
/*!
 
171
  Returns true if the request is in the \c QOrganizerAbstractRequest::FinishedState; otherwise, returns false
 
172
 
 
173
  \sa state()
 
174
 */
 
175
bool QOrganizerAbstractRequest::isFinished() const
 
176
{
 
177
    QMutexLocker ml(&d_ptr->m_mutex);
 
178
    return (d_ptr->m_state == QOrganizerAbstractRequest::FinishedState);
 
179
}
 
180
 
 
181
/*!
 
182
  Returns true if the request is in the \c QOrganizerAbstractRequest::CanceledState; otherwise, returns false
 
183
 
 
184
  \sa state()
 
185
 */
 
186
bool QOrganizerAbstractRequest::isCanceled() const
 
187
{
 
188
    QMutexLocker ml(&d_ptr->m_mutex);
 
189
    return (d_ptr->m_state == QOrganizerAbstractRequest::CanceledState);
 
190
}
 
191
 
 
192
/*! Returns the overall error of the most recent asynchronous operation */
 
193
QOrganizerManager::Error QOrganizerAbstractRequest::error() const
 
194
{
 
195
    QMutexLocker ml(&d_ptr->m_mutex);
 
196
    return d_ptr->m_error;
 
197
}
 
198
 
 
199
/*!
 
200
  Returns the type of this asynchronous request
 
201
 */
 
202
QOrganizerAbstractRequest::RequestType QOrganizerAbstractRequest::type() const
 
203
{
 
204
    QMutexLocker ml(&d_ptr->m_mutex);
 
205
    return d_ptr->type();
 
206
}
 
207
 
 
208
/*!
 
209
  Returns the current state of the request.
 
210
 */
 
211
QOrganizerAbstractRequest::State QOrganizerAbstractRequest::state() const
 
212
{
 
213
    QMutexLocker ml(&d_ptr->m_mutex);
 
214
    return d_ptr->m_state;
 
215
}
 
216
 
 
217
/*! Returns a pointer to the manager of which this request instance requests operations */
 
218
QOrganizerManager* QOrganizerAbstractRequest::manager() const
 
219
{
 
220
    QMutexLocker ml(&d_ptr->m_mutex);
 
221
    return d_ptr->m_manager;
 
222
}
 
223
 
 
224
/*! Sets the manager of which this request instance requests operations to \a manager */
 
225
void QOrganizerAbstractRequest::setManager(QOrganizerManager* manager)
 
226
{
 
227
    QMutexLocker ml(&d_ptr->m_mutex);
 
228
    // In theory we might have been active and the manager didn't cancel/finish us
 
229
    if (d_ptr->m_state == QOrganizerAbstractRequest::ActiveState && d_ptr->m_manager)
 
230
        return;
 
231
    d_ptr->m_manager = manager;
 
232
    d_ptr->m_engine = QOrganizerManagerData::engine(d_ptr->m_manager);
 
233
}
 
234
 
 
235
/*! Attempts to start the request.  Returns false if the request is not in the \c QOrganizerAbstractRequest::Inactive, \c QOrganizerAbstractRequest::Finished or \c QOrganizerAbstractRequest::Cancelled states,
 
236
    or if the request was unable to be performed by the manager engine; otherwise returns true. */
 
237
bool QOrganizerAbstractRequest::start()
 
238
{
 
239
    QMutexLocker ml(&d_ptr->m_mutex);
 
240
    if (d_ptr->m_engine && (d_ptr->m_state == QOrganizerAbstractRequest::CanceledState
 
241
                   || d_ptr->m_state == QOrganizerAbstractRequest::FinishedState
 
242
                   || d_ptr->m_state == QOrganizerAbstractRequest::InactiveState)) {
 
243
        ml.unlock();
 
244
        return d_ptr->m_engine->startRequest(this);
 
245
    }
 
246
 
 
247
    return false; // unable to start operation; another operation already in progress or no engine.
 
248
}
 
249
 
 
250
/*! Attempts to cancel the request.  Returns false if the request is not in the \c QOrganizerAbstractRequest::Active state,
 
251
    or if the request is unable to be cancelled by the manager engine; otherwise returns true. */
 
252
bool QOrganizerAbstractRequest::cancel()
 
253
{
 
254
    QMutexLocker ml(&d_ptr->m_mutex);
 
255
    if (d_ptr->m_engine && d_ptr->m_state == QOrganizerAbstractRequest::ActiveState) {
 
256
        ml.unlock();
 
257
        return d_ptr->m_engine->cancelRequest(this);
 
258
    }
 
259
 
 
260
    return false; // unable to cancel operation; not in progress or no engine.
 
261
}
 
262
 
 
263
/*! Blocks until the request has been completed by the manager engine, or until \a msecs milliseconds has elapsed.
 
264
    If \a msecs is zero or negative, this function will block until the request is complete, regardless of how long it takes.
 
265
    Returns true if the request was cancelled or completed successfully within the given period, otherwise false.
 
266
    Some backends are unable to support this operation safely, and will return false immediately.
 
267
 */
 
268
bool QOrganizerAbstractRequest::waitForFinished(int msecs)
 
269
{
 
270
    QMutexLocker ml(&d_ptr->m_mutex);
 
271
    if (d_ptr->m_engine) {
 
272
        switch (d_ptr->m_state) {
 
273
        case QOrganizerAbstractRequest::ActiveState:
 
274
            ml.unlock();
 
275
            return d_ptr->m_engine->waitForRequestFinished(this, msecs);
 
276
        case QOrganizerAbstractRequest::CanceledState:
 
277
        case QOrganizerAbstractRequest::FinishedState:
 
278
            return true;
 
279
        default:
 
280
            return false;
 
281
        }
 
282
    }
 
283
 
 
284
    return false; // unable to wait for operation; not in progress or no engine
 
285
}
 
286
 
 
287
#include "moc_qorganizerabstractrequest.cpp"
 
288
 
 
289
QTM_END_NAMESPACE
 
290