inc/engine/geocoder/MultiReverseQuery.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 MULTIREVERSEQUERY_H
  19 #define MULTIREVERSEQUERY_H
  20
  21 #include "common/HereMaps_global.h"
  22 #include "common/GeoCoordinates.h"
  23
  24 #include "geocoder/GeoCoderQueryBase.h"
  25
  26 TIZEN_MAPS_BEGIN_NAMESPACE
  27
  28 class MultiReverseReply;
  29 class MultiReverseQueryListener;
  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 MultiReverseQuery : public Here::Maps::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     MultiReverseQuery();
  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     MultiReverseQuery(const Here::Maps::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     MultiReverseQuery(const Here::Maps::GeoCoordinates& rCoordinate, ReverseMode aMode, float fRadius);
  83
  84     /**
  85      * This method is the (virtual) destructor.
  86      */
  87     virtual ~MultiReverseQuery();
  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 Here::Maps::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 sets the get a list of locations to reverse-geocode.
 119      *
 120      * @param rGeocodeList A list of locations to reverse-geocode.
 121      */
 122     void SetGeocodeList(const Here::Maps::GeoCoordinateList& rGeocodeList);
 123     /**
 124      * This method attempts to establish a connection
 125      * with the server and then, if the connection has been established, it
 126      * builds and submits a query.
 127      *
 128      * @param rListener A shared pointer to an object that is to be notified when
 129      *        the reply to the query has arrived from the server.
 130      *
 131      * @param pUserData A pointer to user data to be echoed in the reply object.
 132      *
 133      * @return A value representing the identifier of the issued request.
 134      */
 135     Here::Maps::RestItemHandle::RequestId Execute(MultiReverseQueryListener& rListener,
 136         Tizen::Maps::HereObject* pUserData = NULL) const;
 137
 138     /**
 139      * This method returns the base URI to be used for all subsequent
 140      * reverse geocoder queries.
 141      *
 142      * @return A string containing the base URI.
 143      */
 144     String GetBaseUri() const;
 145
 146     /**
 147      * This method returns the base URI to be used for all subsequent
 148      * reverse geocoder queries.
 149      *
 150      * @param sUri A constant reference to a string containing the base URI.
 151      */
 152     void SetBaseUri(const String& sUri);
 153
 154 private:
 155     /**
 156      * This method creates the URI for the request.
 157      *
 158      * @return URI request string.
 159      */
 160     String CreateUri() const;
 161
 162 #ifdef TIZEN_SUPPORT_POST_METHOD
 163     /**
 164      * This method creates the URI for the request.
 165      *
 166      * @return URI request string.
 167      */
 168     String CreatePostData() const;
 169 #endif
 170
 171 private:
 172     HERE_MAPS_NO_COPY_NO_ASSIGN(MultiReverseQuery);
 173
 174     class MultiReverseQueryImpl;
 175     MultiReverseQueryImpl* m_pImpl;
 176 };
 177
 178 TIZEN_MAPS_END_NAMESPACE
 179
 180 #endif