inc/engine/geocoder/GeoCoderQuery.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 GEOCODERQUERY_H_
  19 #define GEOCODERQUERY_H_
  20
  21 #include "common/HereMaps_global.h"
  22
  23 #include "geocoder/GeoCoderQueryBase.h"
  24
  25 HERE_MAPS_BEGIN_NAMESPACE
  26
  27 class Address;
  28 class GeoCoderReply;
  29 class GeoBoundingBox;
  30 class ApplicationContext;
  31 class GeoCoderQueryListener;
  32
  33 /**
  34  * This class represents a geocoding query.
  35  *
  36  * Instances of this class are used to obtain the geographic coordinates of
  37  * locations on the basis of an address (complete or partial) and/or a free text
  38  * search string.
  39  *
  40  * @ingroup geocoding
  41  */
  42 class EXPORT_API GeoCoderQuery : public GeoCoderQueryBase
  43 {
  44 public:
  45
  46     /**
  47      * This is the default constructor.
  48      */
  49     GeoCoderQuery();
  50
  51     /**
  52      * This method is a constructor.
  53      *
  54      * @param rAddress A constant reference to an object providing the details
  55      *        of an address to use in the query.
  56      */
  57     GeoCoderQuery(const Address& rAddress);
  58
  59     /**
  60      * This method is a constructor.
  61      *
  62      * @param rAddress A constant reference to an object that provides the details
  63      *        of an address to use in the query.
  64      *
  65      * @param sSearch A constant reference to a string containing the search
  66      *        text to use in the query.
  67      */
  68     GeoCoderQuery(const Address& rAddress, const String& sSearch);
  69
  70     /**
  71      * This method is a constructor.
  72      *
  73      * @param sSearch A constant reference to a string containing the search
  74      *        text to use in the query.
  75      */
  76     GeoCoderQuery(const String& sSearch);
  77
  78     /**
  79      * This method is a virtual destructor.
  80      */
  81     virtual ~GeoCoderQuery();
  82
  83     /**
  84      * This method sets the properties defining a circular area within which a
  85      * search is to be conducted. The area is defined in terms of its center and
  86      * radius.
  87      *
  88      * @param rCoord A constant reference to an object containing the latitude
  89      *        and longitude of the center of the proximity area (search center).
  90      *
  91      * @param rRadius A value specifying the radius of the search area in meters.
  92      */
  93     void SetProximity(const GeoCoordinates& rCoord, float fRadius = 0);
  94
  95     /**
  96      * This method detects whether coordinates/proximity (the center of search area
  97      * set or not).
  98      *
  99      * @return <code>true</code> if the proximity was set,
 100      *        otherwise <code>false</code>
 101      */
 102     bool HasProximity() const;
 103
 104     /**
 105      * This method sets the address to be used in the query.
 106      *
 107      * @param rAddress A constant reference to an object providing the details
 108      *        of an address to use in the query.
 109      */
 110     void SetAddress(const Address& rAddress);
 111
 112     /**
 113      * This method sets the search text to be used in the query.
 114      *
 115      * @param sSearch A constant reference to a string containing the search
 116      *        text to use in the query.
 117      */
 118     void SetSearchtext(const String& sSearch);
 119
 120     /**
 121      * This method sets the map view using the bounding box object provided by
 122      * the caller. The map view is a soft filter, which means that the
 123      * response includes relevant results from within the map view, but also
 124      * possibly from a wider area, and even relevant global results are
 125      * also returned.
 126      *
 127      * @param rMapView A constant reference to a bounding box object that
 128      *        defines the map view in terms of the geographic coordinates of
 129      *        the top-left and bottom-right corners.
 130      */
 131     void SetMapView(const GeoBoundingBox& rMapView);
 132
 133     /**
 134      * This method sets the bounding box to be used in the query. The bounding
 135      * box is a hard filter in that the response includes relevant results from
 136      * within the area it defines.
 137      *
 138      * @param A constant reference to an instance of
 139      *        <code>GeoBoundingBox</code>, representing a geographic area within
 140      *        which to perform the search.
 141      */
 142     void SetBoundingBox(const GeoBoundingBox& rBoundingBox);
 143
 144     /**
 145      * This method sets the location identifier to be used in the query.
 146      *
 147      * @param sID a constant reference to a string containing the location
 148      *        identifier.
 149      */
 150
 151     void SetLocationId(const String& sId);
 152
 153     /**
 154      * This method attempts to establish a connection
 155      * with the server and then, if the connection has been established, it
 156      * builds and submits a query.
 157      *
 158      * @param rListener A reference to an object that is to be notified when
 159      *        the reply to the query has arrived from the server.
 160      *
 161      * @param pUserData A pointer to user data to be passed back within the
 162      *        corresponding reply object.
 163      *
 164      * @return Identifier of issued request.
 165      */
 166     RestItemHandle::RequestId Execute(GeoCoderQueryListener& rListener, Tizen::Maps::HereObject* pUserData = NULL) const;
 167
 168     /**
 169      * This method returns the base URI to be used for all subsequent
 170      * geo coder queries.
 171      *
 172      * @return A string containing the base URI.
 173      */
 174     String GetBaseUri() const;
 175
 176     /**
 177      * This method returns the base URI to be used for all subsequent
 178      * geo coder queries.
 179      *
 180      * @param sUri A constant reference to a string containing the base URI.
 181      */
 182     void SetBaseUri(const String& sUri);
 183
 184 private:
 185     /**
 186      * This method creates the URI for the request.
 187      *
 188      * @return URI request string.
 189      */
 190     String CreateUri() const;
 191
 192 private:
 193     HERE_MAPS_NO_COPY_NO_ASSIGN(GeoCoderQuery);
 194
 195     class GeoCoderQueryImpl;
 196     GeoCoderQueryImpl* m_pImpl;
 197 };
 198
 199 HERE_MAPS_END_NAMESPACE
 200
 201 #endif /* GEOCODERQUERY_H_ */