Support explore functionality.

Add support for Nokia's explore functionality in places. This adds the
ProposedSearchResult search result type. The proposed search result has
a QPlaceSearchRequest, which can be submitted to
QPlaceManager::search() to perform the proposed search.

This has the added advantage that any arbitrary search request can be
returned as a search result. To facilitate this further a search
context field has been added to the place search request. This field
can be used by backends to store additional search context. Other
relevant fields should also be filled in. This allows additional search
context to be kept.

The Nokia v2 places implementation has be updated to use the explore
feature and to return ProposedSearchResults as well as place results.

Task-number: QTBUG-24874
Change-Id: Ib20c5a8c8a60e6bf16f38dcd75961a752b8b1b32
Reviewed-by: Alex <alexander.blasche@digia.com>

10 files changed, 318 insertions, 5 deletions

diff --git a/src/location/places/places.pri b/src/location/places/places.pri
index dc7e1af6..4c3a0667 100644
--- a/src/location/places/places.pri
+++ b/src/location/places/places.pri
@@ -19,6 +19,7 @@ PUBLIC_HEADERS += \
 #result
     places/qplacesearchresult.h \
     places/qplaceresult.h \
+    places/qproposedsearchresult.h \
 #request classes
     places/qplacecontentrequest.h \
     places/qplacematchrequest.h \
@@ -46,6 +47,7 @@ PRIVATE_HEADERS += \
     places/qplaceimage_p.h \
     places/qplaceratings_p.h \
     places/qplaceresult_p.h \
+    places/qproposedsearchresult_p.h \
     places/qplacereview_p.h \
     places/qplacesupplier_p.h \
     places/qplacesearchresult_p.h \
@@ -74,6 +76,7 @@ SOURCES += \
 #result
     places/qplacesearchresult.cpp \
     places/qplaceresult.cpp \
+    places/qproposedsearchresult.cpp \
 #request classes
     places/qplacecontentrequest.cpp \
     places/qplacematchrequest.cpp \
diff --git a/src/location/places/qplaceresult_p.h b/src/location/places/qplaceresult_p.h
index 01442d90..f6a21460 100644
--- a/src/location/places/qplaceresult_p.h
+++ b/src/location/places/qplaceresult_p.h
@@ -54,7 +54,7 @@ public:
 
     ~QPlaceResultPrivate();
 
-    bool compare(const QPlaceSearchResultPrivate *other) const;
+    bool compare(const QPlaceSearchResultPrivate *other) const Q_DECL_OVERRIDE;
 
     Q_DEFINE_SEARCHRESULT_PRIVATE_HELPER(QPlaceResult, QPlaceSearchResult::PlaceResult)
 
diff --git a/src/location/places/qplacesearchrequest.cpp b/src/location/places/qplacesearchrequest.cpp
index 4af49102..c5878b22 100644
--- a/src/location/places/qplacesearchrequest.cpp
+++ b/src/location/places/qplacesearchrequest.cpp
@@ -45,6 +45,7 @@
 
 #include <QtCore/QSharedData>
 #include <QtCore/QList>
+#include <QtCore/QVariant>
 
 QT_BEGIN_NAMESPACE
 
@@ -68,6 +69,7 @@ public:
     QPlaceSearchRequest::RelevanceHint relevanceHint;
     int limit;
     int offset;
+    QVariant searchContext;
 };
 
 QPlaceSearchRequestPrivate::QPlaceSearchRequestPrivate()
@@ -87,7 +89,8 @@ QPlaceSearchRequestPrivate::QPlaceSearchRequestPrivate(const QPlaceSearchRequest
       visibilityScope(other.visibilityScope),
       relevanceHint(other.relevanceHint),
       limit(other.limit),
-      offset(other.offset)
+      offset(other.offset),
+      searchContext(other.searchContext)
 {
 }
 
@@ -106,6 +109,7 @@ QPlaceSearchRequestPrivate &QPlaceSearchRequestPrivate::operator=(const QPlaceSe
         relevanceHint = other.relevanceHint;
         limit = other.limit;
         offset = other.offset;
+        searchContext = other.searchContext;
     }
 
     return *this;
@@ -120,7 +124,8 @@ bool QPlaceSearchRequestPrivate::operator==(const QPlaceSearchRequestPrivate &ot
            visibilityScope == other.visibilityScope &&
            relevanceHint == other.relevanceHint &&
            limit == other.limit &&
-           offset == other.offset;
+           offset == other.offset &&
+           searchContext == other.searchContext;
 }
 
 void QPlaceSearchRequestPrivate::clear()
@@ -133,6 +138,7 @@ void QPlaceSearchRequestPrivate::clear()
     recommendationId.clear();
     visibilityScope = QLocation::UnspecifiedVisibility;
     relevanceHint = QPlaceSearchRequest::UnspecifiedHint;
+    searchContext.clear();
 }
 
 /*!
@@ -329,6 +335,38 @@ void QPlaceSearchRequest::setRecommendationId(const QString &placeId)
 }
 
 /*!
+    Returns backend specific additional search context associated with this place search request.
+    The search context is typically set as part of a
+    \l {QPlaceSearchResult::ProposedSearchResult}{proposed search results}.
+*/
+QVariant QPlaceSearchRequest::searchContext() const
+{
+    Q_D(const QPlaceSearchRequest);
+    return d->searchContext;
+}
+
+/*!
+    Sets the search context to \a context.
+
+    \note This method is intended to be used by geo service plugins when returning search results
+    of type \l QPlaceSearchResult::ProposedSearchResult.
+
+    The search context is used by backends to store additional search context related to the search
+    request. Other relevant fields should also be filled in. For example, if the search context
+    encodes a text search the search term should also be set with \l setSearchTerm(). The search
+    context allows additional search context to be kept which is not directly accessible via the
+    Qt Location API.
+
+    The search context can be of any type storable in a QVariant. The value of the search context
+    is not intended to be use directly by applications.
+*/
+void QPlaceSearchRequest::setSearchContext(const QVariant &context)
+{
+    Q_D(QPlaceSearchRequest);
+    d->searchContext = context;
+}
+
+/*!
     Returns the visibility scope used when searching for places.  The default value is
     QLocation::UnspecifiedVisibility meaning that no explicit scope has been assigned.
     Places of any scope may be returned during the search.
diff --git a/src/location/places/qplacesearchrequest.h b/src/location/places/qplacesearchrequest.h
index 5fe93179..65ca3fe0 100644
--- a/src/location/places/qplacesearchrequest.h
+++ b/src/location/places/qplacesearchrequest.h
@@ -85,6 +85,9 @@ public:
     QString recommendationId() const;
     void setRecommendationId(const QString &recommendationId);
 
+    QVariant searchContext() const;
+    void setSearchContext(const QVariant &context);
+
     QLocation::VisibilityScope visibilityScope() const;
     void setVisibilityScope(QLocation::VisibilityScope visibilityScopes);
 
diff --git a/src/location/places/qplacesearchresult.cpp b/src/location/places/qplacesearchresult.cpp
index 124299f5..4b6ab6de 100644
--- a/src/location/places/qplacesearchresult.cpp
+++ b/src/location/places/qplacesearchresult.cpp
@@ -96,9 +96,12 @@ bool QPlaceSearchResultPrivate::compare(const QPlaceSearchResultPrivate *other)
 
 /*!
     \enum QPlaceSearchResult::SearchResultType
+
     Defines the type of search result
-    \value PlaceResult The search result contains a place.
+
     \value UnknownSearchResult The contents of the search result are unknown.
+    \value PlaceResult The search result contains a place.
+    \value ProposedSearchResult The search result contains a proposed search which may be relevant.
 */
 
 /*!
diff --git a/src/location/places/qplacesearchresult.h b/src/location/places/qplacesearchresult.h
index f8f0a5fc..4bcdf6d8 100644
--- a/src/location/places/qplacesearchresult.h
+++ b/src/location/places/qplacesearchresult.h
@@ -57,7 +57,9 @@ QT_BEGIN_NAMESPACE
 #define Q_DECLARE_SEARCHRESULT_COPY_CTOR(Class) \
     Class(const QPlaceSearchResult &other);
 
+class QPlaceSearchRequest;
 class QPlaceSearchResultPrivate;
+class QPlaceIcon;
 
 class Q_LOCATION_EXPORT QPlaceSearchResult
 {
@@ -76,7 +78,8 @@ public:
 
     enum SearchResultType {
         UnknownSearchResult = 0,
-        PlaceResult
+        PlaceResult,
+        ProposedSearchResult
     };
 
     SearchResultType type() const;
diff --git a/src/location/places/qplacesearchresult_p.h b/src/location/places/qplacesearchresult_p.h
index f6a72f72..f12a9f70 100644
--- a/src/location/places/qplacesearchresult_p.h
+++ b/src/location/places/qplacesearchresult_p.h
@@ -43,6 +43,7 @@
 #define QPLACESEARCHRESULT_P_H
 
 #include "qplacesearchresult.h"
+#include "qplacesearchrequest.h"
 
 #include <QSharedData>
 #include <QtLocation/QPlaceIcon>
diff --git a/src/location/places/qproposedsearchresult.cpp b/src/location/places/qproposedsearchresult.cpp
new file mode 100644
index 00000000..94581b89
--- /dev/null
+++ b/src/location/places/qproposedsearchresult.cpp
@@ -0,0 +1,121 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Aaron McCarthy <mccarthy.aaron@gmail.com>
+** 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 "qproposedsearchresult.h"
+#include "qproposedsearchresult_p.h"
+
+QT_BEGIN_NAMESPACE
+
+QProposedSearchResultPrivate::QProposedSearchResultPrivate()
+{
+}
+
+QProposedSearchResultPrivate::QProposedSearchResultPrivate(const QProposedSearchResultPrivate &other)
+:   QPlaceSearchResultPrivate(other), searchRequest(other.searchRequest)
+{
+}
+
+QProposedSearchResultPrivate::~QProposedSearchResultPrivate()
+{
+}
+
+bool QProposedSearchResultPrivate::compare(const QPlaceSearchResultPrivate *other) const
+{
+    const QProposedSearchResultPrivate *od = static_cast<const QProposedSearchResultPrivate *>(other);
+    return QPlaceSearchResultPrivate::compare(other) && searchRequest == od->searchRequest;
+}
+
+/*!
+    \class QProposedSearchResult
+    \inmodule QtLocation
+    \ingroup QtLocation-places
+    \ingroup QtLocation-places-data
+    \since Qt Location 5.2
+
+    \brief The QProposedSearchResult class represents a search result containing a proposed search.
+
+    \sa QPlaceSearchResult
+*/
+
+/*!
+    Constructs a new proposed search result.
+*/
+QProposedSearchResult::QProposedSearchResult()
+:   QPlaceSearchResult(new QProposedSearchResultPrivate)
+{
+}
+
+/*!
+    \fn QProposedSearchResult::QProposedSearchResult(const QPlaceSearchRequest &other)
+
+    Contructs a copy of \a other if possible, otherwise constructs a default proposed search
+    result.
+*/
+Q_IMPLEMENT_SEARCHRESULT_COPY_CTOR(QProposedSearchResult)
+
+Q_IMPLEMENT_SEARCHRESULT_D_FUNC(QProposedSearchResult)
+
+/*!
+    Destroys the proposed search result.
+*/
+QProposedSearchResult::~QProposedSearchResult()
+{
+}
+
+/*!
+    Returns a place search request that can be used to perform an additional proposed search.
+*/
+QPlaceSearchRequest QProposedSearchResult::searchRequest() const
+{
+    Q_D(const QProposedSearchResult);
+    return d->searchRequest;
+}
+
+/*!
+    Sets the proposed search request to \a request.
+*/
+void QProposedSearchResult::setSearchRequest(const QPlaceSearchRequest &request)
+{
+    Q_D(QProposedSearchResult);
+    d->searchRequest = request;
+}
+
+QT_END_NAMESPACE
diff --git a/src/location/places/qproposedsearchresult.h b/src/location/places/qproposedsearchresult.h
new file mode 100644
index 00000000..8c937324
--- /dev/null
+++ b/src/location/places/qproposedsearchresult.h
@@ -0,0 +1,75 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Aaron McCarthy <mccarthy.aaron@gmail.com>
+** 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$
+**
+****************************************************************************/
+
+#ifndef QPROPOSEDSEARCHRESULT_H
+#define QPROPOSEDSEARCHRESULT_H
+
+#include <QtLocation/QPlaceSearchResult>
+
+QT_BEGIN_NAMESPACE
+
+class QProposedSearchResultPrivate;
+
+class Q_LOCATION_EXPORT QProposedSearchResult : public QPlaceSearchResult
+{
+public:
+    QProposedSearchResult();
+
+#ifdef Q_QDOC
+    QProposedSearchResult(const QPlaceSearchRequest &other);
+#else
+    Q_DECLARE_SEARCHRESULT_COPY_CTOR(QProposedSearchResult)
+#endif
+
+    ~QProposedSearchResult();
+
+    QPlaceSearchRequest searchRequest() const;
+    void setSearchRequest(const QPlaceSearchRequest &request);
+
+private:
+    Q_DECLARE_SEARCHRESULT_D_FUNC(QProposedSearchResult)
+};
+
+Q_DECLARE_TYPEINFO(QProposedSearchResult, Q_MOVABLE_TYPE);
+
+QT_END_NAMESPACE
+
+#endif // QPROPOSEDSEARCHRESULT_H
diff --git a/src/location/places/qproposedsearchresult_p.h b/src/location/places/qproposedsearchresult_p.h
new file mode 100644
index 00000000..37df3447
--- /dev/null
+++ b/src/location/places/qproposedsearchresult_p.h
@@ -0,0 +1,66 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Aaron McCarthy <mccarthy.aaron@gmail.com>
+** 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$
+**
+****************************************************************************/
+
+#ifndef QPROPOSEDSEARCHRESULT_P_H
+#define QPROPOSEDSEARCHRESULT_P_H
+
+#include "qplacesearchresult_p.h"
+
+QT_BEGIN_NAMESPACE
+
+class QProposedSearchResultPrivate : public QPlaceSearchResultPrivate
+{
+public:
+    QProposedSearchResultPrivate();
+    QProposedSearchResultPrivate(const QProposedSearchResultPrivate &other);
+
+    ~QProposedSearchResultPrivate();
+
+    bool compare(const QPlaceSearchResultPrivate *other) const Q_DECL_OVERRIDE;
+
+    Q_DEFINE_SEARCHRESULT_PRIVATE_HELPER(QProposedSearchResult, QPlaceSearchResult::ProposedSearchResult)
+
+    QPlaceSearchRequest searchRequest;
+};
+
+QT_END_NAMESPACE
+
+#endif // QPROPOSEDSEARCHRESULT_P_H