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 QtLocation module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL3$
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 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPLv3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or later as published by the Free
28** Software Foundation and appearing in the file LICENSE.GPL included in
29** the packaging of this file. Please review the following information to
30** ensure the GNU General Public License version 2.0 requirements will be
31** met: http://www.gnu.org/licenses/gpl-2.0.html.
32**
33** $QT_END_LICENSE$
34**
35****************************************************************************/
36
37#include "qplacereply.h"
38#include "qplacereply_p.h"
39
40QT_USE_NAMESPACE
41
42/*!
43 \class QPlaceReply
44 \inmodule QtLocation
45 \ingroup QtLocation-places
46 \ingroup QtLocation-places-replies
47 \since 5.6
48
49 \brief The QPlaceReply class manages an operation started by an instance of QPlaceManager and
50 serves as a base class for more specialized replies.
51
52 The QPlaceReply and each of its specialized subclasses manage the
53 state and results of their corresponding operations. The QPlaceReply itself is used
54 for operations that have no results, that is, it only necessary to know if the operation
55 succeeded or failed.
56
57 The finished() signal can be used to monitor the progress of an operation.
58 Once an operation is complete, the error() and errorString() methods provide information
59 on whether the operation completed successfully. If successful, the reply
60 will contain the results for that operation, that is, each subclass will have appropriate
61 functions to retrieve the results of an operation.
62
63 \sa QPlaceManager
64*/
65
66/*!
67 \enum QPlaceReply::Error
68
69 Describes an error which occurred during an operation.
70 \value NoError
71 No error has occurred
72 \value PlaceDoesNotExistError
73 A specified place could not be found
74 \value CategoryDoesNotExistError
75 A specified category could not be found
76 \value CommunicationError
77 An error occurred communicating with the service provider.
78 \value ParseError
79 The response from the service provider or an import file was in an unrecognizable format
80 \value PermissionsError
81 The operation failed because of insufficient permissions.
82 \value UnsupportedError
83 The operation was not supported by the service provider.
84 \value BadArgumentError.
85 A parameter that was provided was invalid.
86 \value CancelError
87 The operation was canceled.
88 \value UnknownError
89 An error occurred which does not fit into any of the other categories.
90*/
91
92/*!
93 \enum QPlaceReply::Type
94
95 Describes the reply's type.
96 \value Reply
97 This is a generic reply.
98 \value DetailsReply
99 This is a reply for the retrieval of place details
100 \value SearchReply
101 This is a reply for the place search operation.
102 \value SearchSuggestionReply
103 This is a reply for a search suggestion operation.
104 \value ContentReply
105 This is a reply for content associated with a place.
106 \value IdReply
107 This is a reply that returns an identifier of a place or category.
108 Typically used for place or category save and remove operations.
109 \value MatchReply
110 This is a reply that returns places that match
111 those from another provider.
112*/
113
114/*!
115 Constructs a reply object with a given \a parent.
116*/
117QPlaceReply::QPlaceReply(QObject *parent)
118 : QObject(parent),d_ptr(new QPlaceReplyPrivate)
119{
120}
121
122/*!
123 \internal
124*/
125QPlaceReply::QPlaceReply(QPlaceReplyPrivate *dd, QObject *parent)
126 : QObject(parent),d_ptr(dd)
127{
128}
129
130/*!
131 Destroys the reply object.
132*/
133QPlaceReply::~QPlaceReply()
134{
135 if (!isFinished()) {
136 abort();
137 }
138 delete d_ptr;
139}
140
141/*!
142 Return true if the reply has completed.
143*/
144bool QPlaceReply::isFinished() const
145{
146 return d_ptr->isFinished;
147}
148
149/*!
150 Returns the type of the reply.
151*/
152QPlaceReply::Type QPlaceReply::type() const
153{
154 return QPlaceReply::Reply;
155}
156
157/*!
158 Sets the status of whether the reply is \a finished
159 or not. This function does not cause the finished() signal
160 to be emitted.
161*/
162void QPlaceReply::setFinished(bool finished)
163{
164 d_ptr->isFinished = finished;
165}
166
167/*!
168 Sets the \a error and \a errorString of the reply.
169 This function does not cause the QPlaceReply::error(QPlaceReply::Error, const QString &errorString)
170 signal to be emitted.
171*/
172void QPlaceReply::setError(QPlaceReply::Error error, const QString &errorString)
173{
174 d_ptr->error = error;
175 d_ptr->errorString = errorString;
176}
177
178/*!
179 Returns the error string of the reply. The error string is intended to be
180 used by developers only and is not fit to be displayed to an end user.
181
182 If no error has occurred, the string is empty.
183*/
184QString QPlaceReply::errorString() const
185{
186 return d_ptr->errorString;
187}
188
189/*!
190 Returns the error code.
191*/
192QPlaceReply::Error QPlaceReply::error() const
193{
194 return d_ptr->error;
195}
196
197/*!
198 \fn void QPlaceReply::aborted()
199 \since 5.9
200
201 This signal is emitted when the operation has been cancelled.
202
203 \sa abort()
204*/
205
206/*!
207 Cancels the operation immediately.
208
209 \sa aborted()
210*/
211void QPlaceReply::abort()
212{
213 emit aborted();
214}
215
216/*!
217 \fn void QPlaceReply::finished()
218
219 This signal is emitted when this reply has finished processing.
220
221 If error() equals QPlaceReply::NoError then the processing
222 finished successfully.
223
224 This signal and QPlaceManager::finished() will be
225 emitted at the same time.
226
227 \note Do not delete this reply object in the slot connected to this
228 signal. Use deleteLater() instead.
229*/
230
231/*!
232 \fn void QPlaceReply::contentUpdated()
233
234 This signal is emitted when this reply has updated content available.
235 Depending on the plugin, this signal may never be emitted or emitted
236 multiple times before \l QPlaceReply::finished() is emitted, as some
237 backends are able to return the requested content asynchronously and
238 incrementally.
239
240 \note Do not delete or deleteLater this reply object in the slot
241 connected to this signal. Do it only upon \l QPlaceReply::finished.
242*/
243
244/*!
245 \fn void QPlaceReply::error(QPlaceReply::Error error, const QString &errorString)
246
247 This signal is emitted when an error has been detected in the processing of
248 this reply. The finished() signal will probably follow.
249
250 The error will be described by the error code \a error. If \a errorString is
251 not empty it will contain a textual description of the error meant for
252 developers and not end users.
253
254 This signal and QPlaceManager::error() will be emitted at the same time.
255
256 \note Do not delete this reply object in the slot connected to this
257 signal. Use deleteLater() instead.
258*/
259

source code of qtlocation/src/location/places/qplacereply.cpp