inc/engine/common/Address.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 ADDRESS_H
  19 #define ADDRESS_H
  20
  21 #include "HereMaps_global.h"
  22
  23 HERE_MAPS_BEGIN_NAMESPACE
  24
  25 /**
  26  * This class encapsulates a street address. It is used both in geocoding
  27  * requests and in responses received from the server.
  28  *
  29  */
  30 class EXPORT_API Address
  31 {
  32 public:
  33
  34     /**
  35      * This is the default constructor.
  36      */
  37     Address();
  38
  39     /**
  40      * This method is the copy constructor.
  41      *
  42      * @param rRhs A constant reference to an <code>Address</code> object to
  43      *        copy.
  44      */
  45     Address(const Address& rRhs);
  46
  47     /**
  48      * This method is the destructor.
  49      */
  50     ~Address();
  51
  52     /**
  53      * This is the assignment operator.
  54      *
  55      * @param rRhs A constant reference to an <code>Address</code> object to
  56      *        copy.
  57      *
  58      * @return A reference to the given instance of <code>Address</code> whose
  59      *        contents now mirror those of the object supplied by the caller.
  60      */
  61     Address& operator=(const Address& rRhs);
  62
  63     /**
  64      * This method sets the name of the country.
  65      *
  66      * @param sCountry A constant reference to a string containing the name of
  67      *        a country.
  68      */
  69     void SetCountry(const String& sCountry);
  70
  71     /**
  72      * This method retrieves the country code.
  73      *
  74      * @return A constant reference to a string containing the country code.
  75      */
  76     const String& GetCountryCode() const;
  77
  78     /**
  79      * This method sets the country code.
  80      *
  81      * @param sCountryCode A constant reference to a string containing the
  82      *        country code.
  83      */
  84     void SetCountryCode(const String& sCountryCode);
  85
  86     /**
  87      * This method retrieves the name of the country.
  88      *
  89      * @return A constant reference to a string containing the name of
  90      *        a country.
  91      */
  92     const String& GetCountry() const;
  93
  94     /**
  95      * This method sets the name of the county.
  96      *
  97      * @param sCounty A constant reference to a string containing the name of
  98      *        a county.
  99      */
 100     void SetCounty(const String& sCounty);
 101
 102     /**
 103      * This method retrieves the name of the county.
 104      *
 105      * @return A constant reference to a string containing the name of
 106      *        a county.
 107      */
 108     const String& GetCounty() const;
 109
 110     /**
 111      * This method sets the address label.
 112      *
 113      * @param sLabel A constant reference to a string containing the label.
 114      */
 115     void SetLabel(const String& sLabel);
 116
 117     /**
 118      * This method retrieves the address label.
 119      *
 120      * @return A constant reference to a string containing the label.
 121      */
 122     const String& GetLabel() const;
 123
 124     /**
 125      * This method sets the identifier of the state. State corresponds to a state
 126      * in the USA or Bundesland in Germany.
 127      *
 128      * @param sState A constant reference to a string containing the name or the
 129      *        abbreviation of the name of the state.
 130      */
 131     void SetState(const String& sState);
 132
 133     /**
 134      * This method retrieves the identifier the state. State corresponds to a
 135      * state in the USA or Bundesland in Germany.
 136      *
 137      * @return A constant reference to a string containing the identifier of the
 138      *        state.
 139      */
 140     const String& GetState() const;
 141
 142     /**
 143      * This method sets the name of the city.
 144      *
 145      * @param sCity A constant reference to a string containing the name of the
 146      *        city.
 147      */
 148     void SetCity(const String& sCity);
 149
 150     /**
 151      * This method retrieves the name of the city.
 152      *
 153      * @return A constant reference to a string containing the name of the
 154      *        city.
 155      */
 156     const String& GetCity() const;
 157
 158     /**
 159      * This method sets the name of the district. A district corresponds either to
 160      * an administrative area within a city or a neighborhood, for example "Greenwich
 161      * Village", "Kreuzberg" (in Berlin).
 162      *
 163      * @param sDistrict A constant reference to a string containing the name of the
 164      *        district.
 165      */
 166     void SetDistrict(const String& sDistrict);
 167
 168     /**
 169      * This method retrieves the name of the district. A district corresponds
 170      * either to an administrative area within a city or a neighborhood, for
 171      * example "Greenwich Village", "Kreuzberg" (in Berlin).
 172      *
 173      * @return A constant reference to a string containing the name of the
 174      *        district.
 175      */
 176     const String& GetDistrict() const;
 177
 178     /**
 179      * This method sets the street name.
 180      *
 181      * @param sStreet A constant reference to a string containing the name of the
 182      *        street.
 183      */
 184     void SetStreet(const String& sStreet);
 185
 186     /**
 187      * This method retrieves the street name.
 188      *
 189      * @return A constant reference to a string containing the name of the
 190      *        street.
 191      */
 192     const String& GetStreet() const;
 193
 194     /**
 195      * This method sets the house number (or house name if appropriate).
 196      *
 197      * @param sHouseNumber A constant reference to a string containing the
 198      *        house number (or the house name if appropriate).
 199      */
 200     void SetHouseNumber(const String& sHouseNumber);
 201
 202     /**
 203      * This method retrieves the house number (or house name if appropriate).
 204      *
 205      * @return A constant reference to a string containing the
 206      *        house number (or the house name if appropriate).
 207      */
 208     const String& GetHouseNumber() const;
 209
 210     /**
 211      * This method sets the post code.
 212      *
 213      * @param sPostalCode A constant reference to a string containing the post
 214      *        code.
 215      */
 216     void SetPostalCode(const String& sPostalCode);
 217
 218     /**
 219      * This method retrieves the post code.
 220      *
 221      * @return A constant reference to a string containing the post
 222      *        code.
 223      */
 224     const String& GetPostalCode() const;
 225
 226     /**
 227      * This method sets the identifier of the floor (within a building).
 228      *
 229      * @param sFloor A constant reference to a string containing the identifier
 230      *        of the floor.
 231      */
 232     void SetFloor(const String& sFloor);
 233
 234     /**
 235      * This method retrieves the identifier of the floor (within a building).
 236      *
 237      * @return A constant reference to a string containing the identifier
 238      *        of the floor.
 239      */
 240     const String& GetFloor() const;
 241
 242     /**
 243      * This method sets the identifier of suite (within a building).
 244      *
 245      * @param sSuite A constant reference to a string containing the identifier
 246      *        of the suite.
 247      */
 248     void SetSuite(const String& sSuite);
 249
 250     /**
 251      * This method retrieves the identifier of suite (within a building).
 252      *
 253      * @return A constant reference to a string containing the identifier
 254      *        of the suite.
 255      */
 256     const String& GetSuite() const;
 257
 258     /**
 259      * This method associates an adidtional data item with the given address.
 260      *
 261      * @param sKey A constant reference to a string containing the key
 262      *        that identifies the data item (in a map of additional data items).
 263      *
 264      * @param sValue A constant reference to a string containing the value of
 265      *        the data item identified by <code>sKey</code>.
 266      */
 267     void AddAdditionalData(const String& sKey, const String& sValue);
 268
 269     /**
 270      * This method retrieves the value of an additional address data item on the
 271      * basis of a key provided by the caller.
 272      *
 273      * @param sKey A constant reference to a string containing the key
 274      *        that identifies the data item to retrieve.
 275      */
 276     const String* GetAdditionalDataValue(const String& sKey) const;
 277
 278     /**
 279      * This method retrieves a value indicating how many additional address data
 280      * items have been associated with the given instance of
 281      * <code>Address</code>.
 282      *
 283      * @return An integer indicating the number of additional data items that
 284      *        are associated with the given instance of <code>Address</code>.
 285      */
 286     size_t GetNumAdditionalDataEntries() const;
 287
 288     /**
 289      * This method retrieves the key of the additional data item at the index
 290      * specified by the caller.
 291      *
 292      * @param idx An integer value specifying the index of the additional address
 293      *        data item whose key is to be retrieved.
 294      *
 295      * @return A constant pointer to a string containing the key
 296      *        for an additional address data item.
 297      */
 298     const String* GetAdditionalDataKey(size_t idx) const;
 299
 300 private:
 301     class AddressImpl;
 302     AddressImpl* m_pImpl;
 303 };
 304
 305 HERE_MAPS_END_NAMESPACE
 306
 307 #endif