path: root/src/location/places/qplacemanager.cpp

/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the QtLocation module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Digia gives you certain additional
** rights.  These rights are described in the Digia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

#include "qplacemanager.h"
#include "qplacemanagerengine.h"
#include "qplacemanagerengine_p.h"

#include <QtCore/QDebug>

QT_BEGIN_NAMESPACE

/*!
    \class QPlaceManager
    \inmodule QtLocation
    \ingroup QtLocation-places
    \ingroup QtLocation-places-manager
    \since Qt Location 5.0

    \brief The QPlaceManager class provides the interface which allows clients to access
    places stored in a particular backend.

    The following table gives an overview of the functionality provided by the QPlaceManager
    \table
        \header
            \li Functionality
            \li Description
        \row
            \li Searching for places
            \li Using set of parameters such as a search term and search area, relevant places
               can be returned to the user.
        \row
            \li Categories
            \li Places can be classified as belonging to different categories.  The
               manager supports access to these categories.
        \row
            \li Search term suggestions
            \li Given a partially complete search term, a list of potential
               search terms can be given.
        \row
            \li Recommendations
            \li Given an existing place, a set of similar recommended places can
               be suggested to the user.
        \row
            \li Rich Content
            \li Rich content such as images, reviews etc can be retrieved in a paged
               fashion.
        \row
            \li Place or Category management
            \li Places and categories may be saved and removed.  It is possible
               for notifications to be given when this happens.
        \row
            \li Localization
            \li Different locales may be specified to return place
               data in different languages.
    \endtable

    \section1 Obtaining a QPlaceManager Instance
    Creation of a QPlaceManager is facilitated by the QGeoServiceProvider.
    See \l {Initializing a manager} for an example on how to create a manager.


    \section1 Asynchronous Interface.
    The QPlaceManager class provides an abstraction of the datastore which contains place information.
    The functions provided by the QPlaceManager and primarily asynchronous and follow
    a request-reply model.   Typically a request is given to the manager, consisting
    of a various set of parameters and a reply object is created.  The reply object
    has a signal to notify when the request is done, and once completed, the reply
    contains the results of the request, along with any errors that occurred, if any.

    An asynchronous request is generally handled as follows:
    \snippet places/requesthandler.h Simple search
    \dots
    \dots
    \snippet places/requesthandler.h Simple search handler

    See \l {Common Operations} for a list of examples demonstrating how the QPlaceManger
    is used.

    \section1 Category Initialization
    Sometime during startup of an application, the initializeCategories() function should
    be called to setup the categories.  Initializing the categories enables the usage of the
    following functions:

    \list
        \li QPlaceManager::childCategories()
        \li QPlaceManager::category()
        \li QPlaceManager::parentCategoryId()
        \li QPlaceManager::childCategoryIds();
    \endlist

    If the categories need to be refreshed or reloaded, the initializeCategories() function
    may be called again.

*/

/*!
    Constructs a new manager with the specified \a parent and with the
    implementation provided by \a engine.

    This constructor is used internally by QGeoServiceProviderFactory. Regular
    users should acquire instances of QGeoRoutingManager with
    QGeoServiceProvider::routingManager();
*/
QPlaceManager::QPlaceManager(QPlaceManagerEngine *engine, QObject *parent)
    : QObject(parent), d(engine)
{
    if (d) {
        d->setParent(this);
        d->d_ptr->manager = this;

        qRegisterMetaType<QPlaceCategory>("QPlaceCategory");

        connect(d, SIGNAL(finished(QPlaceReply*)), this, SIGNAL(finished(QPlaceReply*)));
        connect(d, SIGNAL(error(QPlaceReply*,QPlaceReply::Error)),
                this, SIGNAL(error(QPlaceReply*,QPlaceReply::Error)));

        connect(d, SIGNAL(placeAdded(QString)),
                this, SIGNAL(placeAdded(QString)), Qt::QueuedConnection);
        connect(d, SIGNAL(placeUpdated(QString)),
                this, SIGNAL(placeUpdated(QString)), Qt::QueuedConnection);
        connect(d, SIGNAL(placeRemoved(QString)),
                this, SIGNAL(placeRemoved(QString)), Qt::QueuedConnection);

        connect(d, SIGNAL(categoryAdded(QPlaceCategory,QString)),
                this, SIGNAL(categoryAdded(QPlaceCategory,QString)), Qt::QueuedConnection);
        connect(d, SIGNAL(categoryUpdated(QPlaceCategory,QString)),
                this, SIGNAL(categoryUpdated(QPlaceCategory,QString)), Qt::QueuedConnection);
        connect(d, SIGNAL(categoryRemoved(QString,QString)),
                this, SIGNAL(categoryRemoved(QString,QString)), Qt::QueuedConnection);
        connect(d, SIGNAL(dataChanged()),
                this, SIGNAL(dataChanged()), Qt::QueuedConnection);
    } else {
        qFatal("The place manager engine that was set for this place manager was NULL.");
    }
}

/*!
    Destroys the manager.  This destructor is used internally by QGeoServiceProvider
    and should never need to be called in application code.
*/
QPlaceManager::~QPlaceManager()
{
    delete d;
}

/*!
    Returns the name of the manager
*/
QString QPlaceManager::managerName() const
{
    return d->managerName();
}

/*!
    Returns the manager version.
*/
int QPlaceManager::managerVersion() const
{
    return d->managerVersion();
}

/*!
    Retrieves a details of place corresponding to the given \a placeId.

    See \l {QML Places API#Fetching Place Details}{Fetching Place Details} for an example of usage.
*/
QPlaceDetailsReply *QPlaceManager::getPlaceDetails(const QString &placeId) const
{
    return d->getPlaceDetails(placeId);
}

/*!
    Retrieves content for a place according to the parameters specified in \a request.

    See \l {Fetching Rich Content} for an example of usage.
*/
QPlaceContentReply *QPlaceManager::getPlaceContent(const QPlaceContentRequest &request) const
{
    return d->getPlaceContent(request);
}

/*!
    Searches for places according to the parameters specified in \a request.

    See \l {Discovery/Search} for an example of usage.
*/
QPlaceSearchReply *QPlaceManager::search(const QPlaceSearchRequest &request) const
{
    return d->search(request);
}

/*!
    Requests a set of search term suggestions  according to the parameters specified in \a request.
    The \a request can hold the incomplete search term, along with other data such
    as a search area to narrow down relevant results.

    See \l {Search Suggestions} for an example of usage.
*/
QPlaceSearchSuggestionReply *QPlaceManager::searchSuggestions(const QPlaceSearchRequest &request) const
{
    return d->searchSuggestions(request);
}

/*!
    Saves a specified \a place.

    See \l {Saving a place cpp} for an example of usage.
*/
QPlaceIdReply *QPlaceManager::savePlace(const QPlace &place)
{
    return d->savePlace(place);
}

/*!
    Removes the place corresponding to \a placeId from the manager.

    See \l {Removing a place cpp} for an example of usage.
*/
QPlaceIdReply *QPlaceManager::removePlace(const QString &placeId)
{
    return d->removePlace(placeId);
}

/*!
    Saves a \a category that is a child of the category specified by \a parentId.
    An empty \a parentId means \a category is saved as a top level category.

    See \l {Saving a category} for an example of usage.
*/
QPlaceIdReply *QPlaceManager::saveCategory(const QPlaceCategory &category, const QString &parentId)
{
    return d->saveCategory(category, parentId);
}

/*!
    Removes the category corresponding to \a categoryId from the manager.

    See \l {Removing a category} for an example of usage.
*/
QPlaceIdReply *QPlaceManager::removeCategory(const QString &categoryId)
{
    return d->removeCategory(categoryId);
}

/*!
    Initializes the categories of the manager.

    See \l {Using Categories} for an example of usage.
*/
QPlaceReply *QPlaceManager::initializeCategories()
{
    return d->initializeCategories();
}

/*!
    Returns the parent category identifier of the category corresponding to \a categoryId.
*/
QString QPlaceManager::parentCategoryId(const QString &categoryId) const
{
    return d->parentCategoryId(categoryId);
}

/*!
    Returns the child category identifiers of the category corresponding to \a parentId.
    If \a parentId is empty then all top level category identifiers are returned.
*/
QStringList QPlaceManager::childCategoryIds(const QString &parentId) const
{
    return d->childCategoryIds(parentId);
}

/*!
    Returns the category corresponding to the given \a categoryId.
*/
QPlaceCategory QPlaceManager::category(const QString &categoryId) const
{
    return d->category(categoryId);
}

/*!
    Returns a list of categories that are children of the category corresponding to \a parentId.
    If \a parentId is empty, all the top level categories are returned.
*/
QList<QPlaceCategory> QPlaceManager::childCategories(const QString &parentId) const
{
    return d->childCategories(parentId);
}

/*!
    Returns a list of preferred locales. The locales are used as a hint to the manager for what language
    place and category details should be returned in.

    If the first specified locale cannot be accommodated, the manager falls back to the next and so forth.
    Some manager backends may not support a set of locales which are rigidly defined.  An arbitrary
    example is that some places in France could have French and English localizations, while
    certain areas in America may only have the English localization available.  In this example,
    the set of supported locales is context dependent on the search location.

    If the manager cannot accommodate any of the preferred locales, the manager falls
    back to using a supported language that is backend specific.

    Support for locales may vary from provider to provider.  For those that do support it,
    by default, the global default locale is set as the manager's only locale.

    For managers that do not support locales, the locale list is always empty.
*/
QList<QLocale> QPlaceManager::locales() const
{
    return d->locales();
}

/*!
    Convenience function which sets the manager's list of preferred locales
    to a single \a locale.
*/
void QPlaceManager::setLocale(const QLocale &locale)
{
    QList<QLocale> locales;
    locales << locale;
    d->setLocales(locales);
}

/*!
    Set the list of preferred \a locales.
*/
void QPlaceManager::setLocales(const QList<QLocale> &locales)
{
    d->setLocales(locales);
}

/*!
    Returns a pruned or modified version of the \a original place
    which is suitable to be saved into this manager.

    Only place details that are supported by this manager is
    present in the modified version.  Manager specific data such
    as the place id, is not copied over from the \a original.
*/
QPlace QPlaceManager::compatiblePlace(const QPlace &original)
{
    return d->compatiblePlace(original);
}

/*!
    Returns a reply which contains a list of places which correspond/match those
    specified in the \a request.  The places specified in the request come from a
    different manager.
*/
QPlaceMatchReply *QPlaceManager::matchingPlaces(const QPlaceMatchRequest &request) const
{
    return d->matchingPlaces(request);
}

/*!
    \fn void QPlaceManager::finished(QPlaceReply *reply)

    This signal is emitted when \a reply has finished processing.

    If reply->error() equals QPlaceReply::NoError then the processing
    finished successfully.

    This signal and QPlaceReply::finished() will be emitted at the same time.

    \note Do not delete the \a reply object in the slot connected to this signal.
    Use deleteLater() instead.
*/

/*!
    \fn void QPlaceManager::error(QPlaceReply *reply, QPlaceReply::Error error, const QString &errorString)

    This signal is emitted when an error has been detected in the processing of
    \a reply.  The QPlaceManager::finished() signal will probably follow.

    The error will be described by the error code \a error.  If \a errorString is
    not empty it will contain a textual description of the error meant for developers
    and not end users.

    This signal and QPlaceReply::error() will be emitted at the same time.

    \note Do not delete the \a reply object in the slot connected to this signal.
    Use deleteLater() instead.
*/

/*!
    \fn void QPlaceManager::placeAdded(const QString &placeId)

    This signal is emitted if a place has been added to the manager engine's datastore.
    The particular added place is specified by \a placeId.

    This signal is only emitted by managers that support the QPlaceManager::NotificationsFeature.
    \sa dataChanged()
*/

/*!
    \fn void QPlaceManager::placeUpdated(const QString &placeId)

    This signal is emitted if a place has been modified in the manager's datastore.
    The particular modified place is specified by \a placeId.

    This signal is only emitted by managers that support the QPlaceManager::NotificationsFeature.
    \sa dataChanged()
*/

/*!
    \fn void QPlaceManager::placeRemoved(const QString &placeId)

    This signal is emitted if a place has been removed from the manager's datastore.
    The particular place that has been removed is specified by \a placeId.

    This signal is only emitted by managers that support the QPlaceManager::NotificationsFeature.
    \sa dataChanged()
*/

/*!
    \fn void QPlaceManager::categoryAdded(const QPlaceCategory &category, const QString &parentId)

    This signal is emitted if a \a category has been added to the manager's datastore.
    The parent of the \a category is specified by \a parentId.

    This signal is only emitted by managers that support the QPlaceManager::NotificationsFeature.
    \sa dataChanged()
*/

/*!
    \fn void QPlaceManager::categoryUpdated(const QPlaceCategory &category, const QString &parentId)

    This signal is emitted if a \a category has been modified in the manager's datastore.
    The parent of the modified category is specified by \a parentId.

    This signal is only emitted by managers that support the QPlaceManager::NotificationsFeature.
    \sa dataChanged()
*/

/*!
    \fn void QPlaceManager::categoryRemoved(const QString &categoryId, const QString &parentId)

    This signal is emitted when the category corresponding to \a categoryId has
    been removed from the manager's datastore.  The parent of the removed category
    is specified by \a parentId.

    This signal is only emitted by managers that support the QPlaceManager::NotificationsFeature.
    \sa dataChanged()
*/

/*!
    \fn QPlaceManager::dataChanged()
    This signal is emitted by the manager if there are large scale changes to its
    underlying datastore and the manager considers these changes radical enough
    to require clients to reload all data.

    If the signal is emitted, no other signals will be emitted for the associated changes.

    This signal is only emitted by managers that support the QPlaceManager::NotificationsFeature.
*/

QT_END_NAMESPACE