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 | |
40 | QT_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 | */ |
117 | QPlaceReply::QPlaceReply(QObject *parent) |
118 | : QObject(parent),d_ptr(new QPlaceReplyPrivate) |
119 | { |
120 | } |
121 | |
122 | /*! |
123 | \internal |
124 | */ |
125 | QPlaceReply::QPlaceReply(QPlaceReplyPrivate *dd, QObject *parent) |
126 | : QObject(parent),d_ptr(dd) |
127 | { |
128 | } |
129 | |
130 | /*! |
131 | Destroys the reply object. |
132 | */ |
133 | QPlaceReply::~QPlaceReply() |
134 | { |
135 | if (!isFinished()) { |
136 | abort(); |
137 | } |
138 | delete d_ptr; |
139 | } |
140 | |
141 | /*! |
142 | Return true if the reply has completed. |
143 | */ |
144 | bool QPlaceReply::isFinished() const |
145 | { |
146 | return d_ptr->isFinished; |
147 | } |
148 | |
149 | /*! |
150 | Returns the type of the reply. |
151 | */ |
152 | QPlaceReply::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 | */ |
162 | void 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 | */ |
172 | void 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 | */ |
184 | QString QPlaceReply::errorString() const |
185 | { |
186 | return d_ptr->errorString; |
187 | } |
188 | |
189 | /*! |
190 | Returns the error code. |
191 | */ |
192 | QPlaceReply::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 | */ |
211 | void 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 | |