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
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.
18 #ifndef DISCOVERY_QUERY_H_
19 #define DISCOVERY_QUERY_H_
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"
28 HERE_MAPS_BEGIN_NAMESPACE
32 class FinderQueryListener;
36 * This class encapsulates a places discovery query.
40 class EXPORT_API DiscoveryQuery : public BaseQuery
44 * This enumeration defines identifiers for the supported discovery query
49 QT_SEARCH = 0, ///< Indicates a search query (based on the search terms
50 /// supplied by the application user); results are
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.
65 * This enumeration defines identifiers for the supported discovery query
69 * The identifiers are not valid for search QueryTypes.
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
81 * This method is the default constructor.
86 * This method is a constructor. It constructs a valid <code>DiscoveryQuery</code> from
87 * a URL provided by the caller.
89 * @param sUrl A constant reference to the URL of the location whose details
90 * are to be retrieved from the server
92 DiscoveryQuery(const String& sUrl);
95 * This method is the (virtual) destructor.
97 virtual ~DiscoveryQuery();
100 * This method retrieves a value indicating the query type.
102 * @return A value indicating the query type.
104 QueryType GetType() const;
107 * This method sets the query type.
109 * @param eType A value indicating the query type.
111 void SetType(QueryType eType);
114 * This method sets the search text (terms).
116 * @param sSearch A constant reference to a string containing the search
119 void SetSearchText(const String& sSearch);
122 * This method retrieves the search text (terms).
124 * @return A string containing the search terms.
126 String GetSearchText() const;
129 * This method retrieves the search proximity.
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.
135 GeoCoordinates GetProximity() const;
138 * This method sets search proximity.
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.
144 void SetProximity(const GeoCoordinates& rCoord);
146 #ifdef TIZEN_CUSTOMIZATION
148 * This method retrieves the bounding area.
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.
154 GeoBoundingArea* GetArea() const;
157 * This method sets search bounding area.
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.
163 void SetArea(const GeoBoundingArea &rArea);
167 * This method retrieves a BCP 47 identifier of the search language.
169 * @return A string containing a BCP 47 identifier of the language.
171 String GetLanguage() const;
174 * This method sets the langauge, using a BCP 47 langauge code.
176 * @param sSearch A constant reference to a string containing a BCP 47
177 * identifier of the language.
179 void SetLanguage(const String& sLang);
182 * This method retrieves a value that indicates the maximum number of search
183 * results to be retrieved in response to the query.
185 * @return An integer indicating the maximum number of results to be
188 size_t GetMaxResults() const;
191 * This method sets a value that indicates the maximum number of search
192 * results to be retrieved in response to the query.
194 * @param uMaxResults An integer indicating the maximum number of results to
197 void SetMaxResults(size_t uMaxResults);
200 * This method retrieves a value that indicates the search item types
201 * to be retrieved in response to the query.
203 * @return A value indicating the search item type of results to be
206 ResultTypes GetResultTypes() const;
209 * This method sets a value that indicates the search item types
210 * to be retrieved in response to the query.
212 * @param eItemType A value indicating the search item type of results to
215 void SetResultTypes(ResultTypes eItemType);
218 * This method retrieves a list of categories used by the query.
220 * @return An object containing a list of POI categories used by the query.
222 CategoryList GetCategoriesFilter() const;
225 * This method sets a list of categories used by the query.
227 * @param filters A constant reference to an object containing a list of POI
228 * categories used by the query.
230 void SetCategoriesFilter(const CategoryList& filters);
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.
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.
240 * @param pUserData A pointer to user data to be passed back within the
241 * corresponding reply object.
243 * @return Identifier of issued request.
245 RestItemHandle::RequestId Execute(FinderQueryListener& rListener, Tizen::Maps::HereObject* pUserData = NULL) const;
248 * This method retrieves error information associated with the query.
250 * @return A constant pointer to an object containing the error details.
252 const FinderError* GetError() const;
255 * This static method returns the base URI to be used for all subsequent
258 * @return A string containing the base URI.
260 static String GetBaseUri();
263 * This static method returns the base URI to be used for all subsequent
266 * @param sUri A constant reference to a string containing the base URI.
268 static void SetBaseUri(const String& sUri);
273 * This method creates the URI for the request.
275 * @return URI request string.
277 String CreateUri() const;
279 bool AppendService(DiscoveryQuery::QueryType eType, String& sDst) const;
282 HERE_MAPS_NO_COPY_NO_ASSIGN(DiscoveryQuery);
284 class DiscoveryQueryImpl;
285 DiscoveryQueryImpl* m_pImpl;
287 friend class DiscoveryReply;
289 static String s_sBaseUri;
293 HERE_MAPS_END_NAMESPACE
295 #endif // DISCOVERY_QUERY_H_