Remove offset attribute from place content requests.

This complements 1d0966c6924876655c52725e779a7aa24866ff60

Not all service providers support arbitrary offsets when requesting
place content. The offset attribute has been removed, instead service
providers can supply a previous and next content request query in the
form of a QPlaceContentRequest.

Change-Id: I6239b42c31bed5dcd6645d86d5a48d7e6a667f46
Reviewed-by: Alex Blasche <alexander.blasche@digia.com>

10 files changed, 117 insertions, 45 deletions

diff --git a/src/location/doc/snippets/places/requesthandler.h b/src/location/doc/snippets/places/requesthandler.h
index 8771d294..e18b6276 100644
--- a/src/location/doc/snippets/places/requesthandler.h
+++ b/src/location/doc/snippets/places/requesthandler.h
@@ -122,9 +122,9 @@ public:
         //! [Image request]
         QPlaceContentRequest request;
         request.setContentType(QPlaceContent::ImageType);
-        request.setOffset(0);
+        request.setPlaceId(place.placeId());
         request.setLimit(5);
-        /*QPlaceContentReply * */ contentReply = manager->getPlaceContent(place.placeId(), request);
+        /*QPlaceContentReply * */ contentReply = manager->getPlaceContent(request);
         connect(contentReply, SIGNAL(finished()), this, SLOT(handleImagesReply()));
         //! [Image request]
     }
@@ -235,10 +235,10 @@ public:
         //! [Content request]
         QPlaceContentRequest request;
         request.setContentType(QPlaceContent::ImageType);
-        request.setOffset(9);
+        request.setPlaceId(place.placeId());
         request.setLimit(5);
 
-        QPlaceContentReply *contentReply = manager->getPlaceContent(place.placeId(), request);
+        QPlaceContentReply *contentReply = manager->getPlaceContent(request);
         //..connect signals..//
 
         //! [Content request]
diff --git a/src/location/places/qplacecontentreply.cpp b/src/location/places/qplacecontentreply.cpp
index 23252ea0..3b7d40f2 100644
--- a/src/location/places/qplacecontentreply.cpp
+++ b/src/location/places/qplacecontentreply.cpp
@@ -53,6 +53,8 @@ public:
     QPlaceContent::Collection contentCollection;
     int totalCount;
     QPlaceContentRequest contentRequest;
+    QPlaceContentRequest previousPageRequest;
+    QPlaceContentRequest nextPageRequest;
 };
 
 QT_END_NAMESPACE
@@ -145,6 +147,26 @@ QPlaceContentRequest QPlaceContentReply::request() const
 }
 
 /*!
+    Returns a place content request that can be used to request the previous batch of place content
+    results.
+*/
+QPlaceContentRequest QPlaceContentReply::previousPageRequest() const
+{
+    Q_D(const QPlaceContentReply);
+    return d->previousPageRequest;
+}
+
+/*!
+    Returns a place content request that can be used to request the next batch of place content
+    results.
+*/
+QPlaceContentRequest QPlaceContentReply::nextPageRequest() const
+{
+    Q_D(const QPlaceContentReply);
+    return d->nextPageRequest;
+}
+
+/*!
     Sets the content \a request used to generate this this reply.
 */
 void QPlaceContentReply::setRequest(const QPlaceContentRequest &request)
@@ -152,3 +174,23 @@ void QPlaceContentReply::setRequest(const QPlaceContentRequest &request)
     Q_D(QPlaceContentReply);
     d->contentRequest = request;
 }
+
+/*!
+    Sets the place content request that can be used to request the previous batch of place content
+    results to \a previous.
+*/
+void QPlaceContentReply::setPreviousPageRequest(const QPlaceContentRequest &previous)
+{
+    Q_D(QPlaceContentReply);
+    d->previousPageRequest = previous;
+}
+
+/*!
+    Sets the place content request that can be used to request the next batch of place content
+    results to \a next.
+*/
+void QPlaceContentReply::setNextPageRequest(const QPlaceContentRequest &next)
+{
+    Q_D(QPlaceContentReply);
+    d->nextPageRequest = next;
+}
diff --git a/src/location/places/qplacecontentreply.h b/src/location/places/qplacecontentreply.h
index 8d781a46..dcdcddc4 100644
--- a/src/location/places/qplacecontentreply.h
+++ b/src/location/places/qplacecontentreply.h
@@ -65,10 +65,15 @@ public:
 
     QPlaceContentRequest request() const;
 
+    QPlaceContentRequest previousPageRequest() const;
+    QPlaceContentRequest nextPageRequest() const;
+
 protected:
     void setContent(const QPlaceContent::Collection &content);
     void setTotalCount(int total);
     void setRequest(const QPlaceContentRequest &request);
+    void setPreviousPageRequest(const QPlaceContentRequest &previous);
+    void setNextPageRequest(const QPlaceContentRequest &next);
 
 private:
     Q_DISABLE_COPY(QPlaceContentReply)
diff --git a/src/location/places/qplacecontentrequest.cpp b/src/location/places/qplacecontentrequest.cpp
index 1353ada4..9ad82149 100644
--- a/src/location/places/qplacecontentrequest.cpp
+++ b/src/location/places/qplacecontentrequest.cpp
@@ -46,14 +46,13 @@
 QT_BEGIN_NAMESPACE
 
 QPlaceContentRequestPrivate::QPlaceContentRequestPrivate()
-    : QSharedData(), contentType(QPlaceContent::NoType),
-      limit(-1), offset(0)
+:   QSharedData(), contentType(QPlaceContent::NoType), limit(-1)
 {
 }
 
 QPlaceContentRequestPrivate::QPlaceContentRequestPrivate(const QPlaceContentRequestPrivate &other)
-    : QSharedData(other), contentType(other.contentType),
-      limit(other.limit), offset(other.offset)
+:   QSharedData(other), contentType(other.contentType), placeId(other.placeId),
+    contentContext(other.contentContext), limit(other.limit)
 {
 }
 
@@ -64,15 +63,13 @@ QPlaceContentRequestPrivate::~QPlaceContentRequestPrivate()
 bool QPlaceContentRequestPrivate::operator==(const QPlaceContentRequestPrivate &other) const
 {
     return contentType == other.contentType
-            && limit == other.limit
-            && offset == other.offset;
+            && limit == other.limit;
 }
 
 void QPlaceContentRequestPrivate::clear()
 {
     contentType = QPlaceContent::NoType;
     limit = -1;
-    offset = 0;
 }
 
 /*!
@@ -171,48 +168,75 @@ void QPlaceContentRequest::setContentType(QPlaceContent::Type type)
 }
 
 /*!
-    Returns the maximum number of content items to retrieve.
+    Returns the identifier of the place content is to be fetched for.
+*/
+QString QPlaceContentRequest::placeId() const
+{
+    Q_D(const QPlaceContentRequest);
+    return d->placeId;
+}
 
-    A negative value for limit means that it is undefined.  It is left up to the backend
-    provider to choose an appropriate number of items to return.
+/*!
+    Sets the identifier of the place to fetch content for to \a identifier.
+*/
+void QPlaceContentRequest::setPlaceId(const QString &identifier)
+{
+    Q_D(QPlaceContentRequest);
+    d->placeId = identifier;
+}
 
-    The default limit is -1.
+/*!
+    Returns backend specific additional content context associated with this place content request.
 */
-int QPlaceContentRequest::limit() const
+QVariant QPlaceContentRequest::contentContext() const
 {
     Q_D(const QPlaceContentRequest);
-    return d->limit;
+    return d->contentContext;
 }
 
 /*!
-    Set the maximum number of content items to retrieve to
-    \a limit.
+    Sets the content context to \a context.
+
+    \note This method is intended to be used by geo service plugins when returning place content
+    results.
+
+    The content context is used by backends to store additional content context related to the
+    content request. Other relevant fields should also be filled in. For example, if the content
+    request is for image content the content type should also be set with \l setContentType(). The
+    content context allows additional context to be kept which is not directly accessible via the
+    Qt Location API.
+
+    The content context can be of any type storable in a QVariant. The value of the content context
+    is not intended to be used directly by applications.
 */
-void QPlaceContentRequest::setLimit(int limit)
+void QPlaceContentRequest::setContentContext(const QVariant &context)
 {
     Q_D(QPlaceContentRequest);
-    d->limit = limit;
+    d->contentContext = context;
 }
 
 /*!
-    Returns the offset index of the first item that is to be retrieved.
+    Returns the maximum number of content items to retrieve.
 
-    The default offset is 0.
+    A negative value for limit means that it is undefined.  It is left up to the backend
+    provider to choose an appropriate number of items to return.
+
+    The default limit is -1.
 */
-int QPlaceContentRequest::offset() const
+int QPlaceContentRequest::limit() const
 {
     Q_D(const QPlaceContentRequest);
-    return d->offset;
+    return d->limit;
 }
 
 /*!
-    Sets the starting index of the first item to be retrieved
-    to \a offset.
+    Set the maximum number of content items to retrieve to
+    \a limit.
 */
-void QPlaceContentRequest::setOffset(int offset)
+void QPlaceContentRequest::setLimit(int limit)
 {
     Q_D(QPlaceContentRequest);
-    d->offset = offset;
+    d->limit = limit;
 }
 
 /*!
diff --git a/src/location/places/qplacecontentrequest.h b/src/location/places/qplacecontentrequest.h
index b535a133..164c4df9 100644
--- a/src/location/places/qplacecontentrequest.h
+++ b/src/location/places/qplacecontentrequest.h
@@ -65,8 +65,12 @@ public:
     QPlaceContent::Type contentType() const;
     void setContentType(QPlaceContent::Type type);
 
-    int offset() const;
-    void setOffset(int offset);
+    QString placeId() const;
+    void setPlaceId(const QString &identifier);
+
+    QVariant contentContext() const;
+    void setContentContext(const QVariant &context);
+
     int limit() const;
     void setLimit(int limit);
 
diff --git a/src/location/places/qplacecontentrequest_p.h b/src/location/places/qplacecontentrequest_p.h
index 05fb580b..213bdb58 100644
--- a/src/location/places/qplacecontentrequest_p.h
+++ b/src/location/places/qplacecontentrequest_p.h
@@ -43,7 +43,8 @@
 #define QPLACECONTENTREQUEST_P_H
 
 #include <QtCore/QSharedData>
-#include "qplacecontent.h"
+#include <QtCore/QVariant>
+#include <QtLocation/QPlaceContent>
 
 QT_BEGIN_NAMESPACE
 
@@ -60,8 +61,9 @@ public:
     void clear();
 
     QPlaceContent::Type contentType;
+    QString placeId;
+    QVariant contentContext;
     int limit;
-    int offset;
 };
 
 QT_END_NAMESPACE
diff --git a/src/location/places/qplacemanager.cpp b/src/location/places/qplacemanager.cpp
index d0e91312..863e8adc 100644
--- a/src/location/places/qplacemanager.cpp
+++ b/src/location/places/qplacemanager.cpp
@@ -208,14 +208,13 @@ QPlaceDetailsReply *QPlaceManager::getPlaceDetails(const QString &placeId) const
 }
 
 /*!
-    Retrieves content for the place corresponding to \a placeId, according to the parameters specified in
-    \a request.
+    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 QString &placeId, const QPlaceContentRequest &request) const
+QPlaceContentReply *QPlaceManager::getPlaceContent(const QPlaceContentRequest &request) const
 {
-    return d->getPlaceContent(placeId, request);
+    return d->getPlaceContent(request);
 }
 
 /*!
diff --git a/src/location/places/qplacemanager.h b/src/location/places/qplacemanager.h
index 786fdc1d..a29e5ea6 100644
--- a/src/location/places/qplacemanager.h
+++ b/src/location/places/qplacemanager.h
@@ -76,7 +76,7 @@ public:
 
     QPlaceDetailsReply *getPlaceDetails(const QString &placeId) const;
 
-    QPlaceContentReply *getPlaceContent(const QString &placeId, const QPlaceContentRequest &request) const;
+    QPlaceContentReply *getPlaceContent(const QPlaceContentRequest &request) const;
 
     QPlaceSearchReply *search(const QPlaceSearchRequest &query) const;
 
diff --git a/src/location/places/qplacemanagerengine.cpp b/src/location/places/qplacemanagerengine.cpp
index 89bf6100..74d96f0f 100644
--- a/src/location/places/qplacemanagerengine.cpp
+++ b/src/location/places/qplacemanagerengine.cpp
@@ -151,13 +151,10 @@ QPlaceDetailsReply *QPlaceManagerEngine::getPlaceDetails(const QString &placeId)
 }
 
 /*!
-    Retrieves content for the place corresponding to \a placeId, according to the parameters
-    specified in \a request.
+    Retrieves content for a place according to the parameters specified in \a request.
 */
-QPlaceContentReply *QPlaceManagerEngine::getPlaceContent(const QString &placeId,
-                                                         const QPlaceContentRequest &request)
+QPlaceContentReply *QPlaceManagerEngine::getPlaceContent(const QPlaceContentRequest &request)
 {
-    Q_UNUSED(placeId)
     Q_UNUSED(request)
 
     return new QPlaceContentReplyUnsupported(this);
diff --git a/src/location/places/qplacemanagerengine.h b/src/location/places/qplacemanagerengine.h
index 13512955..0eefa7ca 100644
--- a/src/location/places/qplacemanagerengine.h
+++ b/src/location/places/qplacemanagerengine.h
@@ -66,8 +66,7 @@ public:
 
     virtual QPlaceDetailsReply *getPlaceDetails(const QString &placeId);
 
-    virtual QPlaceContentReply *getPlaceContent(const QString &placeId,
-                                                const QPlaceContentRequest &request);
+    virtual QPlaceContentReply *getPlaceContent(const QPlaceContentRequest &request);
 
     virtual QPlaceSearchReply *search(const QPlaceSearchRequest &request);