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 "qplacemanagerengine.h"
38#include "qplacemanagerengine_p.h"
39#include "unsupportedreplies_p.h"
40
41#include <QtCore/QMetaType>
42
43#include "qplaceicon.h"
44
45QT_BEGIN_NAMESPACE
46
47/*!
48 \class QPlaceManagerEngine
49 \inmodule QtLocation
50 \ingroup QtLocation-impl
51 \ingroup QtLocation-places
52 \ingroup QtLocation-places-manager
53 \since 5.6
54
55 \brief The QPlaceManagerEngine class provides an interface for
56 implementers of QGeoServiceProvider plugins who want to provide access to place
57 functionality.
58
59 Application developers need not concern themselves with the QPlaceManagerEngine.
60 Backend implementers however will need to derive from QPlaceManagerEngine and provide
61 implementations for the abstract virtual functions.
62
63 For more information on writing a backend see the \l {Places Backend} documentation.
64
65 \sa QPlaceManager
66*/
67
68/*!
69 Constructs a new engine with the specified \a parent, using \a parameters to pass any
70 implementation specific data to the engine.
71*/
72QPlaceManagerEngine::QPlaceManagerEngine(const QVariantMap &parameters,
73 QObject *parent)
74: QObject(parent), d_ptr(new QPlaceManagerEnginePrivate)
75{
76 qRegisterMetaType<QPlaceReply::Error>();
77 qRegisterMetaType<QPlaceReply *>();
78 Q_UNUSED(parameters);
79}
80
81/*!
82 Destroys this engine.
83*/
84QPlaceManagerEngine::~QPlaceManagerEngine()
85{
86 delete d_ptr;
87}
88
89/*!
90 \internal
91 Sets the name which this engine implementation uses to distinguish itself
92 from the implementations provided by other plugins to \a managerName.
93
94 This function does not need to be called by engine implementers,
95 it is implicitly called by QGeoServiceProvider to set the manager
96 name to be the same as the provider's.
97*/
98void QPlaceManagerEngine::setManagerName(const QString &managerName)
99{
100 d_ptr->managerName = managerName;
101}
102
103/*!
104 Returns the name which this engine implementation uses to distinguish
105 itself from the implementations provided by other plugins.
106
107 The manager name is automatically set to be the same
108 as the QGeoServiceProviderFactory::providerName().
109*/
110QString QPlaceManagerEngine::managerName() const
111{
112 return d_ptr->managerName;
113}
114
115/*!
116 \internal
117 Sets the version of this engine implementation to \a managerVersion.
118
119 The combination of managerName() and managerVersion() should be unique
120 amongst plugin implementations.
121*/
122void QPlaceManagerEngine::setManagerVersion(int managerVersion)
123{
124 d_ptr->managerVersion = managerVersion;
125}
126
127/*!
128 Returns the version of this engine implementation.
129
130 The manager version is automatically set to be the same
131 as the QGeoServiceProviderFactory::providerVersion().
132*/
133int QPlaceManagerEngine::managerVersion() const
134{
135 return d_ptr->managerVersion;
136}
137
138/*!
139 Retrieves details of place corresponding to the given \a placeId.
140*/
141QPlaceDetailsReply *QPlaceManagerEngine::getPlaceDetails(const QString &placeId)
142{
143 Q_UNUSED(placeId);
144
145 return new QPlaceDetailsReplyUnsupported(this);
146}
147
148/*!
149 Retrieves content for a place according to the parameters specified in \a request.
150*/
151QPlaceContentReply *QPlaceManagerEngine::getPlaceContent(const QPlaceContentRequest &request)
152{
153 Q_UNUSED(request);
154
155 return new QPlaceContentReplyUnsupported(this);
156}
157
158/*!
159 Searches for places according to the parameters specified in \a request.
160*/
161QPlaceSearchReply *QPlaceManagerEngine::search(const QPlaceSearchRequest &request)
162{
163 Q_UNUSED(request);
164
165 return new QPlaceSearchReplyUnsupported(QPlaceReply::UnsupportedError,
166 QStringLiteral("Place search is not supported."), this);
167}
168
169/*!
170 Requests a set of search term suggestions according to the parameters specified in \a request.
171*/
172QPlaceSearchSuggestionReply *QPlaceManagerEngine::searchSuggestions(
173 const QPlaceSearchRequest &request)
174{
175 Q_UNUSED(request);
176
177 return new QPlaceSearchSuggestionReplyUnsupported(this);
178}
179
180/*!
181 Saves a specified \a place to the manager engine's datastore.
182*/
183QPlaceIdReply *QPlaceManagerEngine::savePlace(const QPlace &place)
184{
185 Q_UNUSED(place);
186
187 return new QPlaceIdReplyUnsupported(QStringLiteral("Save place is not supported"),
188 QPlaceIdReply::SavePlace, this);
189}
190
191/*!
192 Removes the place corresponding to \a placeId from the manager engine's datastore.
193*/
194QPlaceIdReply *QPlaceManagerEngine::removePlace(const QString &placeId)
195{
196 Q_UNUSED(placeId);
197
198 return new QPlaceIdReplyUnsupported(QStringLiteral("Remove place is not supported"),
199 QPlaceIdReply::RemovePlace, this);
200}
201
202/*!
203 Saves a \a category that is a child of the category specified by \a parentId. An empty
204 \a parentId means \a category is saved as a top level category.
205*/
206QPlaceIdReply *QPlaceManagerEngine::saveCategory(const QPlaceCategory &category,
207 const QString &parentId)
208{
209 Q_UNUSED(category);
210 Q_UNUSED(parentId);
211
212 return new QPlaceIdReplyUnsupported(QStringLiteral("Save category is not supported"),
213 QPlaceIdReply::SaveCategory, this);
214}
215
216/*!
217 Removes the category corresponding to \a categoryId from the manager engine's datastore.
218*/
219
220QPlaceIdReply *QPlaceManagerEngine::removeCategory(const QString &categoryId)
221{
222 Q_UNUSED(categoryId);
223
224 return new QPlaceIdReplyUnsupported(QStringLiteral("Remove category is not supported"),
225 QPlaceIdReply::RemoveCategory, this);
226}
227
228/*!
229 Initializes the categories of the manager engine.
230*/
231QPlaceReply *QPlaceManagerEngine::initializeCategories()
232{
233 return new QPlaceReplyUnsupported(QStringLiteral("Categories are not supported."), this);
234}
235
236/*!
237 Returns the parent category identifier of the category corresponding to \a categoryId.
238*/
239QString QPlaceManagerEngine::parentCategoryId(const QString &categoryId) const
240{
241 Q_UNUSED(categoryId);
242
243 return QString();
244}
245
246/*!
247 Returns the child category identifiers of the category corresponding to \a categoryId. If
248 \a categoryId is empty then all top level category identifiers are returned.
249*/
250QStringList QPlaceManagerEngine::childCategoryIds(const QString &categoryId) const
251{
252 Q_UNUSED(categoryId);
253
254 return QStringList();
255}
256
257/*!
258 Returns the category corresponding to the given \a categoryId.
259*/
260QPlaceCategory QPlaceManagerEngine::category(const QString &categoryId) const
261{
262 Q_UNUSED(categoryId);
263
264 return QPlaceCategory();
265}
266
267/*!
268 Returns a list of categories that are children of the category corresponding to \a parentId.
269 If \a parentId is empty, all the top level categories are returned.
270*/
271QList<QPlaceCategory> QPlaceManagerEngine::childCategories(const QString &parentId) const
272{
273 Q_UNUSED(parentId);
274
275 return QList<QPlaceCategory>();
276}
277
278/*!
279 Returns a list of preferred locales. The locales are used as a hint to the manager engine for
280 what language place and category details should be returned in.
281
282 If the first specified locale cannot be accommodated, the manager engine falls back to the next
283 and so forth.
284
285 Support for locales may vary from provider to provider. For those that do support it, by
286 default, the \l {QLocale::setDefault()}{global default locale} will be used. If the manager
287 engine has no locales assigned to it, it implicitly uses the global default locale. For
288 engines that do not support locales, the locale list is always empty.
289*/
290QList<QLocale> QPlaceManagerEngine::locales() const
291{
292 return QList<QLocale>();
293}
294
295/*!
296 Set the list of preferred \a locales.
297*/
298void QPlaceManagerEngine::setLocales(const QList<QLocale> &locales)
299{
300 Q_UNUSED(locales);
301}
302
303/*!
304 Returns the manager instance used to create this engine.
305*/
306QPlaceManager *QPlaceManagerEngine::manager() const
307{
308 return d_ptr->manager;
309}
310
311/*!
312 Returns a pruned or modified version of the \a original place
313 which is suitable to be saved by the manager engine.
314
315 Only place details that are supported by this manager is
316 present in the modified version. Manager specific data such
317 as the place id, is not copied over from the \a original.
318*/
319QPlace QPlaceManagerEngine::compatiblePlace(const QPlace &original) const
320{
321 Q_UNUSED(original);
322 return QPlace();
323}
324
325/*!
326 Returns a reply which contains a list of places which correspond/match those
327 specified in \a request.
328*/
329QPlaceMatchReply * QPlaceManagerEngine::matchingPlaces(const QPlaceMatchRequest &request)
330{
331 Q_UNUSED(request);
332
333 return new QPlaceMatchReplyUnsupported(this);
334}
335
336/*!
337 QUrl QPlaceManagerEngine::constructIconUrl(const QPlaceIcon &icon, const QSize &size)
338
339 Constructs an icon url from a given \a icon, \a size. The URL of the icon
340 image that most closely matches the given parameters is returned.
341*/
342QUrl QPlaceManagerEngine::constructIconUrl(const QPlaceIcon &icon, const QSize &size) const
343{
344 Q_UNUSED(icon);
345 Q_UNUSED(size);
346
347 return QUrl();
348}
349
350QPlaceManagerEnginePrivate::QPlaceManagerEnginePrivate()
351 : managerVersion(-1), manager(0)
352{
353}
354
355QPlaceManagerEnginePrivate::~QPlaceManagerEnginePrivate()
356{
357}
358
359/*!
360 \fn void QPlaceManagerEngine::finished(QPlaceReply *reply)
361
362 This signal is emitted when \a reply has finished processing.
363
364 If reply->error() equals QPlaceReply::NoError then the processing
365 finished successfully.
366
367 This signal and QPlaceReply::finished() will be emitted at the same time.
368
369 \note Do not delete the \a reply object in the slot connected to this signal.
370 Use deleteLater() instead.
371*/
372
373/*!
374 \fn void QPlaceManagerEngine::error(QPlaceReply * reply, QPlaceReply::Error error, const QString &errorString = QString());
375
376 This signal is emitted when an error has been detected in the processing of
377 \a reply. The QPlaceManager::finished() signal will probably follow.
378
379 The error will be described by the error code \a error. If \a errorString is
380 not empty it will contain a textual description of the error meant for developers
381 and not end users.
382
383 This signal and QPlaceReply::error() will be emitted at the same time.
384
385 \note Do not delete the \a reply object in the slot connected to this signal.
386 Use deleteLater() instead.
387*/
388
389/*!
390 \fn void QPlaceManagerEngine::placeAdded(const QString &placeId)
391
392 This signal is emitted if a place has been added to the manager engine's datastore.
393 The particular added place is specified by \a placeId.
394
395 This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature.
396 \sa dataChanged()
397*/
398
399/*!
400 \fn void QPlaceManagerEngine::placeUpdated(const QString &placeId)
401
402 This signal is emitted if a place has been modified in the manager engine's datastore.
403 The particular modified place is specified by \a placeId.
404
405 This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature.
406 \sa dataChanged()
407*/
408
409/*!
410 \fn void QPlaceManagerEngine::placeRemoved(const QString &placeId)
411
412 This signal is emitted if a place has been removed from the manager engine's datastore.
413 The particular place that has been removed is specified by \a placeId.
414
415 This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature.
416 \sa dataChanged()
417*/
418
419/*!
420 \fn void QPlaceManagerEngine::categoryAdded(const QPlaceCategory &category, const QString &parentId)
421
422 This signal is emitted if a \a category has been added to the manager engine's datastore.
423 The parent of the \a category is specified by \a parentId.
424
425 This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature.
426 \sa dataChanged()
427*/
428
429/*!
430 \fn void QPlaceManagerEngine::categoryUpdated(const QPlaceCategory &category, const QString &parentId)
431
432 This signal is emitted if a \a category has been modified in the manager engine's datastore.
433 The parent of the modified category is specified by \a parentId.
434
435 This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature.
436 \sa dataChanged()
437*/
438
439/*!
440 \fn void QPlaceManagerEngine::categoryRemoved(const QString &categoryId, const QString &parentId)
441
442 This signal is emitted when the category corresponding to \a categoryId has
443 been removed from the manager engine's datastore. The parent of the removed category
444 is specified by \a parentId.
445
446 This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature.
447 \sa dataChanged()
448*/
449
450/*!
451 * \fn QPlaceManagerEngine::dataChanged()
452
453 This signal is emitted by the engine if there are large scale changes to its
454 underlying datastore and the engine considers these changes radical enough
455 to require clients to reload all data.
456
457 If the signal is emitted, no other signals will be emitted for the associated changes.
458*/
459
460QT_END_NAMESPACE
461

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