inc/engine/finder/DiscoveryQuery.h

   1 /*
   2  * Copyright (C) 2013 HERE Global B.V. All rights reserved.
   3  * This software, including documentation, is protected by copyright controlled by
   4  * HERE Global B.V. (“Software”). All rights are reserved. Copying, including reproducing,
   5  * storing, adapting or translating, any or all of this material requires the prior
   6  * written consent of HERE Global B.V. You may use this
   7  * Software in accordance with the terms and conditions defined in the
   8  * HERE Location Platform Services Terms and Conditions, available at
   9  * http://developer.here.com/terms-conditions-base
  10  *
  11  * As an additional permission to the above, you may distribute Software,
  12  * in object code format as part of an Application, according to, and subject to, terms and
  13  * conditions defined in the Tizen Software Development kit (“SDK”) License Agreement.
  14  * You may distribute such object code format Application under terms of your choice,
  15  * provided that the header and source files of the Software have not been modified.
  16  */
  17
  18 #ifndef DISCOVERY_QUERY_H_
  19 #define DISCOVERY_QUERY_H_
  20
  21 #include "common/HereMaps_global.h"
  22 #include "common/BaseQuery.h"
  23 #include "finder/Category.h"
  24 #ifdef TIZEN_CUSTOMIZATION
  25 #include "common/GeoBoundingArea.h"
  26 #endif
  27
  28 HERE_MAPS_BEGIN_NAMESPACE
  29
  30 class QueryListener;
  31 class GeoCoordinates;
  32 class FinderQueryListener;
  33 class FinderError;
  34
  35 /**
  36  * This class encapsulates a places discovery query.
  37  *
  38  * \ingroup finder
  39  */
  40 class EXPORT_API DiscoveryQuery : public BaseQuery
  41 {
  42 public:
  43    /**
  44     * This enumeration defines identifiers for the supported discovery query
  45     * types.
  46     */
  47     enum QueryType
  48     {
  49         QT_SEARCH = 0, ///< Indicates a search query (based on the search terms
  50                        ///  supplied by the application user); results are
  51                        ///  paginated.
  52         QT_HERE,       ///< Indicates query that searches for places at or
  53                        ///  within 200 meters of a specific location; a category
  54                        ///  can be specified as an option.
  55         QT_AROUND,     ///< Indicates a query that searches for places within a
  56                        ///  certain radius around a location; results are
  57                        ///  paginated; a category can be specified as an option.
  58         QT_EXPLORE     ///< Indicates a query that searches for popular places
  59                        ///  based on a location context provided by the
  60                        ///  application user; results are paginated; a category
  61                        ///  can be specified as an option.
  62     };
  63
  64     /**
  65      * This enumeration defines identifiers for the supported discovery query
  66      * result types.
  67      */
  68     /*
  69      * The identifiers are not valid for search QueryTypes.
  70      */
  71     enum ResultTypes
  72     {
  73         SIT_PLACE = 0,      ///< Indicates that the result contains only place items
  74         SIT_SEARCH,         ///< Indicates that the result contains only search items
  75         SIT_PLACEANDSEARCH  ///< Indicates that the result contains place and search items
  76     };
  77
  78 public:
  79
  80     /**
  81      * This method is the default constructor.
  82      */
  83     DiscoveryQuery();
  84
  85     /**
  86      * This method is a constructor. It constructs a valid <code>DiscoveryQuery</code> from
  87      * a URL provided by the caller.
  88      *
  89      * @param sUrl A constant reference to the URL of the location whose details
  90      *        are to be retrieved from the server
  91      */
  92     DiscoveryQuery(const  String& sUrl);
  93
  94     /**
  95      * This method is the (virtual) destructor.
  96      */
  97     virtual ~DiscoveryQuery();
  98
  99     /**
 100      * This method retrieves a value indicating the query type.
 101      *
 102      * @return A value indicating the query type.
 103      */
 104     QueryType GetType() const;
 105
 106     /**
 107      * This method sets the query type.
 108      *
 109      * @param eType A value indicating the query type.
 110      */
 111     void SetType(QueryType eType);
 112
 113     /**
 114      * This method sets the search text (terms).
 115      *
 116      * @param sSearch A constant reference to a string containing the search
 117      *        terms.
 118      */
 119     void SetSearchText(const String& sSearch);
 120
 121     /**
 122      * This method retrieves the search text (terms).
 123      *
 124      * @return A string containing the search terms.
 125      */
 126     String GetSearchText() const;
 127
 128     /**
 129      * This method retrieves the search proximity.
 130      *
 131      * @return An object containing the geographic coordinates of the location
 132      *        around which the search is/was to be conducted and within whose
 133      *        proximity the results must lie.
 134      */
 135     GeoCoordinates GetProximity() const;
 136
 137     /**
 138      * This method sets search proximity.
 139      *
 140      * @param rCoord An object containing the geographic coordinates of the
 141      *        location around which the search is/was to be conducted and within
 142      *        whose proximity the results must lie.
 143      */
 144     void SetProximity(const GeoCoordinates& rCoord);
 145
 146 #ifdef TIZEN_CUSTOMIZATION
 147     /**
 148      * This method retrieves the bounding area.
 149      *
 150      * @return An object containing the geographic bounding area of the location
 151      *        around which the search is/was to be conducted and within whose
 152      *        area the results must lie.
 153      */
 154     GeoBoundingArea* GetArea() const;
 155
 156     /**
 157      * This method sets search bounding area.
 158      *
 159      * @param rArea An object containing the geographic bounding area of the
 160      *        location around which the search is/was to be conducted and within
 161      *        whose bounding area the results must lie.
 162      */
 163     void SetArea(const GeoBoundingArea &rArea);
 164 #endif
 165
 166     /**
 167      * This method retrieves a BCP 47 identifier of the search language.
 168      *
 169      * @return A string containing a BCP 47 identifier of the language.
 170      */
 171     String GetLanguage() const;
 172
 173     /**
 174      * This method sets the langauge, using a BCP 47 langauge code.
 175      *
 176      * @param sSearch A constant reference to a string containing a BCP 47
 177      *        identifier of the language.
 178      */
 179     void SetLanguage(const String& sLang);
 180
 181     /**
 182      * This method retrieves a value that indicates the maximum number of search
 183      * results to be retrieved in response to the query.
 184      *
 185      * @return An integer indicating the maximum number of results to be
 186      *        retrieved.
 187      */
 188     size_t GetMaxResults() const;
 189
 190     /**
 191      * This method sets a value that indicates the maximum number of search
 192      * results to be retrieved in response to the query.
 193      *
 194      * @param uMaxResults An integer indicating the maximum number of results to
 195      *        be retrieved.
 196      */
 197     void SetMaxResults(size_t uMaxResults);
 198
 199     /**
 200      * This method retrieves a value that indicates the search item types
 201      *  to be retrieved in response to the query.
 202      *
 203      * @return A value indicating the search item type of results to be
 204      *        retrieved.
 205      */
 206     ResultTypes GetResultTypes() const;
 207
 208     /**
 209      * This method sets a value that indicates the search item types
 210      * to be retrieved in response to the query.
 211      *
 212      * @param eItemType A value indicating the search item type of results to
 213      *        be retrieved.
 214      */
 215     void SetResultTypes(ResultTypes eItemType);
 216
 217     /**
 218      * This method retrieves a list of categories used by the query.
 219      *
 220      * @return An object containing a list of POI categories used by the query.
 221      */
 222     CategoryList GetCategoriesFilter() const;
 223
 224     /**
 225      * This method sets a list of categories used by the query.
 226      *
 227      * @param filters A constant reference to an object containing a list of POI
 228      *          categories used by the query.
 229      */
 230     void SetCategoriesFilter(const CategoryList& filters);
 231
 232     /**
 233      * This method attempts to establish a connection
 234      * with the server and then, if the connection has been established, it
 235      * builds and submits a query.
 236      *
 237      * @param rDst A reference to an object that is to be notified when the
 238      *        reply to the query has arrived from the server.
 239      *
 240      * @param pUserData A pointer to user data to be passed back within the
 241      *        corresponding reply object.
 242      *
 243      * @return Identifier of issued request.
 244      */
 245     RestItemHandle::RequestId Execute(FinderQueryListener& rListener, Tizen::Maps::HereObject* pUserData = NULL) const;
 246
 247     /**
 248      * This method retrieves error information associated with the query.
 249      *
 250      * @return A constant pointer to an object containing the error details.
 251      */
 252     const FinderError* GetError() const;
 253
 254     /**
 255      * This static method returns the base URI to be used for all subsequent
 256      * discovery queries.
 257      *
 258      * @return A string containing the base URI.
 259      */
 260     static String GetBaseUri();
 261
 262     /**
 263      * This static method returns the base URI to be used for all subsequent
 264      * discovery queries.
 265      *
 266      * @param sUri A constant reference to a string containing the base URI.
 267      */
 268     static void SetBaseUri(const String& sUri);
 269
 270 private:
 271
 272     /**
 273      * This method creates the URI for the request.
 274      *
 275      * @return URI request string.
 276      */
 277     String CreateUri() const;
 278
 279     bool AppendService(DiscoveryQuery::QueryType eType, String& sDst) const;
 280
 281 private:
 282     HERE_MAPS_NO_COPY_NO_ASSIGN(DiscoveryQuery);
 283
 284     class DiscoveryQueryImpl;
 285     DiscoveryQueryImpl* m_pImpl;
 286
 287     friend class DiscoveryReply;
 288
 289     static String s_sBaseUri;
 290
 291 };
 292
 293 HERE_MAPS_END_NAMESPACE
 294
 295 #endif // DISCOVERY_QUERY_H_