inc/engine/geocoder/GeoCoderQueryBase.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 GEOCODERQUERYBASE_H
  19 #define GEOCODERQUERYBASE_H
  20
  21 #include "common/HereMaps_global.h"
  22
  23 #include "common/BaseQuery.h"
  24
  25 HERE_MAPS_BEGIN_NAMESPACE
  26
  27 class ApplicationContext;
  28
  29 /**
  30  * This is the base class for implementations of geocoding query classes.
  31  *
  32  * The virtual method require implementation in derived classes.
  33  *
  34  * \ingroup geocoding
  35  */
  36 class EXPORT_API GeoCoderQueryBase : public BaseQuery
  37 {
  38 public:
  39     /**
  40      * This enumeration defines identifiers for response attribute switches that
  41      * indicate which attributes are to be included in query responses from the
  42      * server.
  43      */
  44     enum ResponseAttribute
  45     {
  46         RA_PerformedSearch,       ///< Indicates that completed searches are to be included in the response.
  47         RA_Label,                 ///< Indicates that labels are to be included in the response.
  48         RA_DidYouMeanSuggestion,  ///< Indicates that did-you-mean suggestions are to be included in the response.
  49         RA_MatchQuality,          ///< Indicates that match quality is to be included in the response.
  50         RA_MatchType,             ///< Indicates that match type specifiers are to be included in the response.
  51         RA_MatchCode,             ///< Indicates that match codes are to be included in the response.
  52         RA_ParsedRequest,         ///< Indicates that parsed requests are to be included in the response.
  53         RA_All,                   ///< Indicates that all attributes are to be included in the response.
  54         RA_None                   ///< Indicates that no attributes are to be included in the response.
  55     };
  56
  57     /**
  58      * This method is the destructor.
  59      *
  60      * @return
  61      */
  62     ~GeoCoderQueryBase();
  63
  64     /**
  65      * This method sets the properties defining a circular area within which a
  66      * search is to be conducted. The area is defined in terms of its center and
  67      * radius.
  68      *
  69      * @param rCoord A constant reference to an object containing the latitude
  70      *        and longitude of the center of the proximity area (search center).
  71      *
  72      * @param rRadius A value specifying the radius of the search area in meters.
  73      */
  74     virtual void SetProximity(const GeoCoordinates& rCoord, float fRadius = 0) = 0;
  75
  76     /**
  77      * This method detects whether coordinates/proximity (the center of search area
  78      * set or not).
  79      *
  80      * @return <code>true</code> if the proximity was set,
  81      *        otherwise <code>false</code>
  82      */
  83     virtual bool HasProximity() const = 0;
  84
  85     /**
  86      * This method adds a language code provided by the caller to the list of
  87      * preferred languages.
  88      *
  89      * @param sPreferredLang A constant reference to a string containing a BCP
  90      *        47 language code (see also  http://tools.ietf.org/html/rfc5646).
  91      *        identifying the preferred language.
  92      */
  93     void AppendPreferredLanguage(const String& sPreferredLang);
  94
  95     /**
  96      * This method retrieves a value indicating the number of preferred
  97      * languages that have been set.
  98      *
  99      * @return A value indicating how many preferred languages have been set.
 100      */
 101     size_t GetNumPreferredLanguages() const;
 102
 103     /**
 104      * This method retrieves the preferred language identifier at the index
 105      * specified by the caller. The identifier is a BCP 47 language code (see
 106      * also http://tools.ietf.org/html/rfc5646).
 107      *
 108      * @param idx A value representing an index into the array of preferred
 109      *        languages from which to retrieve the language identifier.
 110      *
 111      * @return A constant pointer to a string containing the language identifier
 112      *        or <code>NULL</code> if the supplied index is not valid.
 113      */
 114     const String* GetPreferredLanguage(size_t idx) const;
 115
 116     /**
 117      * This method sets a value indicating the maximum number of query results
 118      * to be returned.
 119      *
 120      * @param uMaxResults A value indicating the maximum number of query results
 121      * to be returned.
 122      */
 123     void SetMaxResults(size_t uMaxResults);
 124
 125     /**
 126      * This method sets a value indicating which page is to be returned in a
 127      * paging scenario. Note that the value has no effect unless a value
 128      * indicating the maximum number of results to retrieve has been specified
 129      * (see SetMaxResults).
 130      *
 131      * @param uPage An unsigned integer indicating the page number.
 132      */
 133     void SetPageInformation(size_t uPage);
 134
 135     /**
 136      * This method allows the caller to set a value that determines the
 137      * functionality and data delivered by the underlying version of the RESTful
 138      * service.
 139      *
 140      * @param iValue An integer value that determines the functionality of (and
 141      *        data delivered by) the underlying RESTful service:
 142      *        <ul>
 143      *        <li>0 - indicates the default behavior of the underlying RESTful
 144      *                service
 145      *         </li>
 146      *         <li>1 - indicates the default behavior of the underlying service and:
 147      *         <ul><li>reverse geocoding responses include area names if addresses
 148      *                cannot be determined</li>
 149      *             <li>addresses/locations can be matched at
 150      *                intersection level</li>
 151      *         </ul>
 152      *         </li>
 153      *         <li>2 - as 1 plus:
 154      *             <ul><li>reverse geocoding responses include the area
 155      *                 display position (center)</li>
 156      *                <li>map version can be requested (and
 157      *                   included in responses)</li>
 158      *            </ul>
 159      *        </li>
 160      *        </ul>
 161      */
 162      void SetGenParameter(int iValue);
 163
 164
 165     /**
 166      * This method adds a response attribute specified by the caller.
 167      *
 168      * @param aAttr A value identifying the response attribute to add.
 169      */
 170     void AddResponseAttribute(ResponseAttribute aAttr);
 171
 172     /**
 173      * This method removes the response attribute specified by the caller.
 174      *
 175      * @param aAttr A value identifying the response attribute to remove.
 176      */
 177     void RemoveResponseAttribute(ResponseAttribute aAttr);
 178
 179     /**
 180      * This method adds a key-value pair representing an additional parameter
 181      * and its value.
 182      *
 183      * @param sKey A constant reference to a string containing the name/key of
 184      *        the additional parameter.
 185      *
 186      * @param sValue A constant reference to a string containing the value of the
 187      *        additional parameter.
 188      */
 189     void AddAdditionalParameter(const String& sKey, const String& sValue);
 190
 191     /**
 192      * This method returns the base URI to be used for all subsequent
 193      * geo coder queries.
 194      *
 195      * @return A string containing the base URI.
 196      */
 197     virtual String GetBaseUri() const = 0;
 198
 199     /**
 200      * This method returns the base URI to be used for all subsequent
 201      * geo coder queries.
 202      *
 203      * @param sUri A constant reference to a string containing the base URI.
 204      */
 205     virtual void SetBaseUri(const String& sUri) = 0;
 206
 207 protected:
 208
 209     /**
 210      * This method is the default constructor.
 211      */
 212     GeoCoderQueryBase();
 213
 214     /**
 215      * This method obtains the base URL for the service named by the caller.
 216      *
 217      * @param sService A constant reference to a string that identifies the
 218      *        service whose base URL is to be obtained.
 219      *
 220      * @param sDst A reference to an object which is to receive the result.
 221      *
 222      * @return <code>true</code> if the base URL has been created successfully,
 223      *        otherwise <code>false</code>
 224      */
 225     bool CreateBaseUrl(const String& sService, String& sDst) const;
 226
 227
 228 private:
 229     HERE_MAPS_NO_COPY_NO_ASSIGN(GeoCoderQueryBase);
 230
 231     class GeoCoderQueryBaseImpl;
 232     GeoCoderQueryBaseImpl* m_pImpl;
 233 };
 234
 235 HERE_MAPS_END_NAMESPACE
 236
 237 #endif