inc/engine/geocoder/Result.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 RESULT_H
  19 #define RESULT_H
  20
  21 #include "common/HereMaps_global.h"
  22
  23 HERE_MAPS_BEGIN_NAMESPACE
  24
  25 class GeoLocation;
  26
  27 /**
  28  * This class encapsulates a result item returned by the server in response to a
  29  * geocoding or reverse geocoding request.
  30  *
  31  * \ingroup geocoding
  32  */
  33 class EXPORT_API Result
  34 {
  35 public:
  36     /**
  37      * This enumeration defines identifiers for match levels -- they reflect how
  38      * closely (to what level of detail) the result matches the request.
  39      */
  40     enum MatchLevel
  41     {
  42         ML_Unknown = -1,  ///< Indicates that the match level is unknown.
  43         ML_Country = 0,   ///< Indicates country match.
  44         ML_State,         ///< Indicates state match.
  45         ML_County,        ///< Indicates county match.
  46         ML_City,          ///< Indicates city match.
  47         ML_District,      ///< Indicates district match.
  48         ML_Street,        ///< Indicates street match.
  49         ML_Intersection,  ///< Indicates intersection match.
  50         ML_HouseNumber,   ///< Indicates house-number match.
  51         ML_PostalCode,    ///< Indicates postal code match.
  52         ML_Suite,         ///< Indicates suite match.
  53         ML_Floor          ///< Indicates floor match.
  54     };
  55
  56     /**
  57      * This method is the default constructor.
  58      */
  59     Result();
  60
  61     /**
  62      * This method is the destructor.
  63      */
  64     ~Result();
  65
  66     /**
  67      * This method sets location details for the given result.
  68      *
  69      * @param rLocation A constant reference to an object containing the
  70      *        location details.
  71      */
  72     void SetLocation(const GeoLocation& rLocation);
  73
  74     /**
  75      * This method retrieves the location details from the given result object.
  76      *
  77      * @param rLocation A constant reference to an object containing the
  78      *        location details.
  79      */
  80     const GeoLocation& GetLocation() const;
  81
  82     /**
  83      * This method sets the relevance value on the given result.
  84      *
  85      * @param A float indicating the relevance of the given result in the range
  86      *        [0..1], where 1 indicates maximum relevance.
  87      */
  88     void SetRelevance(float fValue);
  89
  90     /**
  91      * This method retrieves a value indicating the relevance of the given result.
  92      *
  93      * @param A float indicating the relevance of the given result; the value is
  94      *        in the range [0..1], where 1 indicates maximum relevance.
  95      */
  96     float GetRelevance() const;
  97
  98 #ifdef TIZEN_CUSTOMIZATION
  99     /**
 100      * This method sets a value representing the distance for the given result.
 101      *
 102      * @param fValue A value indicating distance.
 103      */
 104     void SetDistance(float fValue);
 105
 106     /**
 107      * This method retrieves a value representing the distance for the given
 108      * result.
 109      *
 110      * @return A value indicating distance.
 111      */
 112     float GetDistance() const;
 113 #endif
 114
 115     /**
 116      * This method sets a value representing the match level for the given
 117      * result.
 118      *
 119      * @param aLevel A value indicating match level (see also
 120      *        <code>Result::MatchLevel</code>).
 121      */
 122    void SetMatchLevel(MatchLevel aLevel);
 123
 124     /**
 125      * This method sets a value representing the match level for the given
 126      * result.
 127      *
 128      * @param sLevel A constant reference to a string indicating the match level
 129      *        to set (see also <code>Result::MatchLevel</code>). The value of
 130      *        the string must be one of "country", "state", "county", "city",
 131      *        "street", "intersection", "housenumber", "postalcode", "suite",
 132      *        "floor", "district".
 133      */
 134     void SetMatchLevel(const String& sLevel);
 135
 136     /**
 137      * This method retrieves a value representing the match level for the given
 138      * result.
 139      *
 140      * @return A value indicating match level (see also
 141      *        <code>Result::MatchLevel</code>).
 142      */
 143     MatchLevel GetMatchLevel() const;
 144
 145     /**
 146      * This method adds a match level indicator and sets the associated match
 147      * quality value.
 148      *
 149      * @param aMatchLevel A value indicating the match level to set (see also
 150      *        <code>Result::MatchLevel</code>).
 151      *
 152      * @param fQuality A float value indicating the match quality.
 153      */
 154     void AddMatchQuality(MatchLevel aMatchLevel, float fQuality);
 155
 156     /**
 157      * This method adds a match level indicator and sets the associated match
 158      * qualityf value.
 159      *
 160      * @param sLevel A constant reference to a string indicating the match level
 161      *        to set (see also <code>Result::MatchLevel</code>). The value of
 162      *        the string must be one of "country", "state", "county", "city",
 163      *        "street", "intersection", "housenumber", "postalcode", "suite",
 164      *        "floor", "district".
 165      *
 166      * @param fQuality A float value indicating the match quality.
 167      */
 168     void AddMatchQuality(const String& sLevel, float fQuality);
 169
 170     /**
 171      * This method retrieves a value representing match quality of the given
 172      * result for the match level specified by the caller.
 173      *
 174      * @param aMatchLevel A value indicating the match level to set (see also
 175      *        <code>Result::MatchLevel</code>).
 176      *
 177      * @return A float value indicating the match quality.
 178     */
 179     float GetMatchQuality(MatchLevel aMatchLevel) const;
 180
 181     /**
 182      * This method retrieves the number of match quality values available for
 183      * the given result.
 184      *
 185      * @return A value indicating the number of match quality values.
 186      */
 187     unsigned int GetNumMatchQualities() const;
 188
 189     /**
 190      * This method retrieves a value identifying the match level at the index
 191      * specified by the caller.
 192      *
 193      * @param uIdx A value representing the index from which to retrieve the
 194      *        match level indicator (value). Note that the index must not be
 195      *        greater than the return value from
 196      *        <code>Result::GetNumMatchQualities()</code>.
 197      *
 198      * @return  A value indicating the match level at the index specified by the
 199      *        caller (see also <code>Result::MatchLevel</code>).
 200      */
 201     MatchLevel GetMatchQualityLevel(unsigned int uIdx) const;
 202
 203 private:
 204     HERE_MAPS_NO_COPY_NO_ASSIGN(Result);
 205
 206     class ResultImpl;
 207     ResultImpl* m_pImpl;
 208 };
 209
 210 HERE_MAPS_END_NAMESPACE
 211
 212 #endif