inc/engine/geocoder/ReverseGeoCoderQuery.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 REVERSEGEOCODERQUERY_H
  19 #define REVERSEGEOCODERQUERY_H
  20
  21 #include "common/HereMaps_global.h"
  22
  23 #include "geocoder/GeoCoderQueryBase.h"
  24
  25 HERE_MAPS_BEGIN_NAMESPACE
  26
  27 class GeoCoderReply;
  28 class GeoCoordinates;
  29 class GeoCoderQueryListener;
  30
  31 /**
  32  * This class represents a reverse geocoding query.
  33  *
  34  * Instances of the class are used to obtain an address (or a set of addresses)
  35  * corresponding to a set of geographic coordinates.
  36  *
  37  * @ingroup geocoding
  38  */
  39 class EXPORT_API ReverseGeoCoderQuery : public GeoCoderQueryBase
  40 {
  41 public:
  42     /**
  43      * This enumeration defines identifiers for reverse geocoding modes. A mode
  44      * indicates whether addresses are to be returned or
  45      * administrative area names (such as city, county, state, country).
  46      */
  47     enum ReverseMode
  48     {
  49         RM_RetrieveAreas,    ///< Indicates that administrative area names are to be retrieved.
  50         RM_RetrieveAddresses ///< Indicates that addresses are to be retrieved.
  51     };
  52
  53     /**
  54      * This method is the default constructor.
  55      */
  56     ReverseGeoCoderQuery();
  57
  58     /**
  59      * This method is a constructor that initializes the query with the location
  60      * to reverse-geocode and the mode.
  61      *
  62      * @param rCoordinate A constant reference to an object containing the geographic
  63      *        coordinates of the location to reverse-geocode.
  64      *
  65      * @param aMode A value indicating the reverse geocoding mode to use.
  66      */
  67     ReverseGeoCoderQuery(const GeoCoordinates& rCoordinate, ReverseMode aMode);
  68
  69     /**
  70      * This method is a constructor that initializes the query with the location
  71      * to reverse-geocode, the mode and the radius within which to conduct the
  72      * search.
  73      *
  74      * @param rCoordinate A constant reference to an object containing the geographic
  75      *        coordinates of the location to reverse-geocode.
  76      *
  77      * @param aMode A value indicating the reverse geocoding mode to use.
  78      *
  79      * @param fRadius A float value indicating the radius (in meters) within
  80      *        which to search.
  81      */
  82     ReverseGeoCoderQuery(const GeoCoordinates& rCoordinate, ReverseMode aMode, float fRadius);
  83
  84     /**
  85      * This method is the (virtual) destructor.
  86      */
  87     virtual ~ReverseGeoCoderQuery();
  88
  89     /**
  90      * This method sets the properties defining a circular area within which a
  91      * search is to be conducted. The area is defined in terms of its center and
  92      * radius.
  93      *
  94      * @param rCoord A constant reference to an object containing the latitude
  95      *        and longitude of the center of the proximity area (search center).
  96      *
  97      * @param rRadius A value specifying the radius of the search area in meters.
  98      */
  99     void SetProximity(const GeoCoordinates& rCoord, float fRadius = 0);
 100
 101     /**
 102      * This method detects whether coordinates/proximity (the center of search area
 103      * set or not).
 104      *
 105      * @return <code>true</code> if the proximity was set,
 106      *        otherwise <code>false</code>
 107      */
 108     bool HasProximity() const;
 109
 110     /**
 111      * This method sets the reverse geocoding mode to apply to the query.
 112      *
 113      * @param aMode A value indicating the reverse geocoding mode to use.
 114      */
 115     void SetMode(ReverseMode aMode);
 116
 117     /**
 118      * This method attempts to establish a connection
 119      * with the server and then, if the connection has been established, it
 120      * builds and submits a query.
 121      *
 122      * @param rListener A shared pointer to an object that is to be notified when
 123      *        the reply to the query has arrived from the server.
 124      *
 125      * @param pUserData A pointer to user data to be echoed in the reply object.
 126      *
 127      * @return A value representing the identifier of the issued request.
 128      */
 129     RestItemHandle::RequestId Execute(GeoCoderQueryListener& rListener, Tizen::Maps::HereObject* pUserData = NULL) const;
 130
 131     /**
 132      * This method returns the base URI to be used for all subsequent
 133      * reverse geocoder queries.
 134      *
 135      * @return A string containing the base URI.
 136      */
 137     String GetBaseUri() const;
 138
 139     /**
 140      * This method returns the base URI to be used for all subsequent
 141      * reverse geocoder queries.
 142      *
 143      * @param sUri A constant reference to a string containing the base URI.
 144      */
 145     void SetBaseUri(const String& sUri);
 146
 147 private:
 148     /**
 149      * This method creates the URI for the request.
 150      *
 151      * @return URI request string.
 152      */
 153     String CreateUri() const;
 154
 155 private:
 156     HERE_MAPS_NO_COPY_NO_ASSIGN(ReverseGeoCoderQuery);
 157
 158     class ReverseGeoCoderQueryImpl;
 159     ReverseGeoCoderQueryImpl* m_pImpl;
 160 };
 161
 162 HERE_MAPS_END_NAMESPACE
 163
 164 #endif