inc/FSclAddress.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17 /**
  18  * @file        FSclAddress.h
  19  * @brief       This is the header file for the %Address class.
  20  *
  21  * This header file contains the declarations of the %Address class.
  22  */
  23 #ifndef _FSCL_ADDRESS_H_
  24 #define _FSCL_ADDRESS_H_
  25
  26 #include <FBaseResult.h>
  27 #include <FBaseObject.h>
  28 #include <FBaseString.h>
  29 #include <FSclTypes.h>
  30
  31 namespace Tizen { namespace Social
  32 {
  33
  34 /**
  35  * @if OSPDEPREC
  36  * The maximum length of the extended field.
  37  *
  38  * @brief <i> [Deprecated]  </i>
  39  * @deprecated  This constant is deprecated because there is no limitation any more.
  40  * @since       2.0
  41  * @endif
  42  */
  43 static const int MAX_ADDR_EXTENDED_LENGTH = 50;
  44
  45 /**
  46  * @if OSPDEPREC
  47  * The maximum length of the street field.
  48  *
  49  * @brief <i> [Deprecated]  </i>
  50  * @deprecated  This constant is deprecated because there is no limitation any more.
  51  * @since       2.0
  52  * @endif
  53  */
  54 static const int MAX_ADDR_STREET_LENGTH = 50;
  55
  56 /**
  57  * @if OSPDEPREC
  58  * The maximum length of the city field.
  59  *
  60  * @brief <i> [Deprecated]  </i>
  61  * @deprecated  This constant is deprecated because there is no limitation any more.
  62  * @since       2.0
  63  * @endif
  64  */
  65 static const int MAX_ADDR_CITY_LENGTH = 50;
  66
  67 /**
  68  * @if OSPDEPREC
  69  * The maximum length of the state field.
  70  *
  71  * @brief <i> [Deprecated]  </i>
  72  * @deprecated  This constant is deprecated because there is no limitation any more.
  73  * @since       2.0
  74  * @endif
  75  */
  76 static const int MAX_ADDR_STATE_LENGTH = 50;
  77
  78 /**
  79  * @if OSPDEPREC
  80  * The maximum length of the postal code field.
  81  *
  82  * @brief <i> [Deprecated]  </i>
  83  * @deprecated  This constant is deprecated because there is no limitation any more.
  84  * @since       2.0
  85  * @endif
  86  */
  87 static const int MAX_ADDR_POSTAL_CODE_LENGTH = 20;
  88
  89 /**
  90  * @if OSPDEPREC
  91  * The maximum length of the country field.
  92  *
  93  * @brief <i> [Deprecated]  </i>
  94  * @deprecated  This constant is deprecated because the maximum length of the country name has been changed.
  95 * @since        2.0
  96  * @endif
  97  */
  98 static const int MAX_ADDR_COUNTRY_LENGTH = 20;
  99
 100 /**
 101  * @if OSPDEPREC
 102  * The maximum length of the post office box number field.
 103  *
 104  * @brief <i> [Deprecated]  </i>
 105  * @deprecated  This constant is deprecated because there is no limitation any more.
 106 * @since        2.0
 107  * @endif
 108  */
 109 static const int MAX_ADDR_POBOXNUM_LENGTH = 20;
 110
 111 /**
 112  * @class       Address
 113  * @brief       This class represents the structured address type representing the ADR type definition of the vCard.
 114  *
 115  * @since       2.0
 116  *
 117  * @final       This class is not intended for extension.
 118  *
 119  * The %Address class represents the structured address type representing the ADR type definition of the vCard.
 120  *      It is based on the MIME directory profile specification (RFC 2426).
 121  * The address information consists of country, city, state, street, post office box number, postal code, and the address type.
 122  * This class represents the structured address type representing the ADR type definition of the vCard.
 123  * It is based on the MIME directory profile specification (RFC 2426).
 124  *
 125  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/social/addressbook_namespace.htm">Addressbook</a>.
 126  */
 127 class _OSP_EXPORT_ Address
 128         : public Tizen::Base::Object
 129 {
 130 public:
 131         /**
 132          * This is the default constructor for this class. @n
 133          * It creates a fully initialized instance of the %Address class.
 134          *
 135          * @since       2.0
 136          */
 137         Address(void);
 138
 139         /**
 140          * Copying of objects using this copy constructor is allowed.
 141          *
 142          * @since       2.0
 143          *
 144          * @param[in]   rhs             An instance of %Address
 145          */
 146         Address(const Address& rhs);
 147
 148         /**
 149          * This destructor overrides Tizen::Base::Object::~Object().
 150          *
 151          * @since       2.0
 152          */
 153         virtual ~Address(void);
 154
 155         /**
 156          * Checks whether the value of the specified instance is equal to the value of the current instance of Tizen::Base::Object.
 157          *
 158          * @since       2.0
 159          *
 160          * @return      @c true if the value of the specified instance of Tizen::Base::Object is equal to the value of the current instance of %Tizen::Base::Object, @n
 161          *                      else @c false
 162          * @param[in]   rhs             An instance of Tizen::Base::Object to compare
 163          */
 164         virtual bool Equals(const Tizen::Base::Object& rhs) const;
 165
 166         /**
 167          * Gets the hash value of the current instance of Tizen::Base::Object.
 168          *
 169          * @since       2.0
 170          *
 171          * @return      An integer value indicating the hash value of the current instance of Tizen::Base::Object
 172          */
 173         virtual int GetHashCode(void) const;
 174
 175         /**
 176          * Gets the type of the address.
 177          *
 178          * @if OSPCOMPAT
 179          * @brief <i> [Compatibility] </i>
 180          * @endif
 181          * @since       2.0
 182          * @if OSPCOMPAT
 183          * @compatibility            This method has compatibility issues with OSP compatible applications. @n
 184          *                           For more information, see @ref CompAddressGetTypePage "here".
 185          * @endif
 186          *
 187          * @return      The type of the address
 188          */
 189         AddressType GetType(void) const;
 190
 191         /**
 192          * @if OSPCOMPAT
 193          * @page                CompAddressGetTypePage         Compatibility for GetType()
 194          * @section             CompAddressGetTypePageIssueSection             Issues
 195          * Implementing this method in OSP compatible applications has the following issue: @n
 196          * -# ADDRESS_TYPE_CUSTOM is not supported. If the type of the address is ADDRESS_TYPE_CUSTOM, ADDRESS_TYPE_OTHER is returned instead.
 197          *
 198          * @section             CompAddressGetTypePageSolutionSection          Resolutions
 199          * The issue mentioned above has been resolved in Tizen.
 200          * @endif
 201          */
 202
 203         /**
 204          * Gets the extended field of the address.
 205          *
 206          * @since       2.0
 207          *
 208          * @return      The extended field of the address
 209          */
 210         Tizen::Base::String GetExtended(void) const;
 211
 212         /**
 213          * Gets the street of the address.
 214          *
 215          * @since       2.0
 216          *
 217          * @return      The street of the address
 218          */
 219         Tizen::Base::String GetStreet(void) const;
 220
 221         /**
 222          * Gets the city of the address.
 223          *
 224          * @since       2.0
 225          *
 226          * @return      The city of the address
 227          */
 228         Tizen::Base::String GetCity(void) const;
 229
 230         /**
 231          * Gets the state of the address.
 232          *
 233          * @since       2.0
 234          *
 235          * @return      The state of the address
 236          */
 237         Tizen::Base::String GetState(void) const;
 238
 239         /**
 240          * Gets the postal code of the address.
 241          *
 242          * @since       2.0
 243          *
 244          * @return      The postal code of the address
 245          */
 246         Tizen::Base::String GetPostalCode(void) const;
 247
 248         /**
 249          * Gets the country of the address.
 250          *
 251          * @since       2.0
 252          *
 253          * @return      The country of the address
 254          */
 255         Tizen::Base::String GetCountry(void) const;
 256
 257         /**
 258          * Gets the post office box number of the address.
 259          *
 260          * @since       2.0
 261          *
 262          * @return      The post office box number of the address
 263          */
 264         Tizen::Base::String GetPostOfficeBoxNumber(void) const;
 265
 266         /**
 267          * Sets the type of the address.
 268          *
 269          * @since       2.0
 270          *
 271          * @param[in]   type    The address type to set
 272          * @see AddressType()
 273          */
 274         void SetType(AddressType type);
 275
 276         /**
 277          * Sets the extended field of the address.
 278          *
 279          * @if OSPCOMPAT
 280          * @brief <i> [Compatibility] </i>
 281          * @endif
 282          * @since       2.0
 283          * @if OSPCOMPAT
 284          * @compatibility            This method has compatibility issues with OSP compatible applications. @n
 285          *                            For more information, see @ref CompAddressSetExtendedPage "here".
 286          * @endif
 287          *
 288          * @return              An error code
 289          * @param[in]   extended                The new extended value to set
 290          * @exception   E_SUCCESS               The method is successful.
 291          * @exception   E_INVALID_ARG   The length of the specified @c extended exceeds #MAX_ADDR_EXTENDED_LENGTH.
 292          */
 293         result SetExtended(const Tizen::Base::String& extended);
 294
 295         /**
 296          * @if OSPCOMPAT
 297          * @page                CompAddressSetExtendedPage              Compatibility for SetExtended()
 298          * @section             CompAddressSetExtendedPageIssueSection          Issues
 299          * Implementing this method in OSP compatible applications has the following issue: @n
 300          * -# If the length of the extended address to be set is greater than @c 50 characters, E_INVALID_ARG is returned.
 301          *
 302          * @section             CompAddressSetExtendedPageSolutionSection               Resolutions
 303          * The issue mentioned above has been resolved in Tizen.
 304          * @endif
 305          */
 306
 307         /**
 308          * Sets the street of the address.
 309          *
 310          * @if OSPCOMPAT
 311          * @brief <i> [Compatibility] </i>
 312          * @endif
 313          * @since       2.0
 314          * @if OSPCOMPAT
 315          * @compatibility            This method has compatibility issues with OSP compatible applications. @n
 316          *                            For more information, see @ref CompAddressSetStreetPage "here".
 317          * @endif
 318          *
 319          * @return              An error code
 320          * @param[in]   street                  The new street value to set
 321          * @exception   E_SUCCESS               The method is successful.
 322          * @exception   E_INVALID_ARG   The specified @c street is an empty string.
 323          */
 324         result SetStreet(const Tizen::Base::String& street);
 325
 326         /**
 327          * @if OSPCOMPAT
 328          * @page                CompAddressSetStreetPage                Compatibility for SetStreet()
 329          * @section             CompAddressSetStreetPageIssueSection            Issues
 330          * Implementing this method in OSP compatible applications has the following issue: @n
 331          * -# If the length of the street to be set is greater than @c 50 characters, E_INVALID_ARG is returned.
 332          *
 333          * @section             CompAddressSetStreetPageSolutionSection         Resolutions
 334          * The issue mentioned above has been resolved in Tizen.
 335          * @endif
 336          */
 337
 338         /**
 339          * Sets the city of the address.
 340          *
 341          * @if OSPCOMPAT
 342          * @brief <i> [Compatibility] </i>
 343          * @endif
 344          * @since       2.0
 345          * @if OSPCOMPAT
 346          * @compatibility            This method has compatibility issues with OSP compatible applications. @n
 347          *                            For more information, see @ref CompAddressSetCityPage "here".
 348          * @endif
 349          *
 350          * @return              An error code
 351          * @param[in]   city                    The new city value to set
 352          * @exception   E_SUCCESS               The method is successful.
 353          * @exception   E_INVALID_ARG   The specified @c city is an empty string.
 354          */
 355         result SetCity(const Tizen::Base::String& city);
 356
 357         /**
 358          * @if OSPCOMPAT
 359          * @page                CompAddressSetCityPage          Compatibility for SetCity()
 360          * @section             CompAddressSetCityPageIssueSection              Issues
 361          * Implementing this method in OSP compatible applications has the following issue: @n
 362          * -# If the length of the city to be set is greater than @c 50 characters, E_INVALID_ARG is returned.
 363          *
 364          * @section             CompAddressSetCityPageSolutionSection           Resolutions
 365          * The issue mentioned above has been resolved in Tizen.
 366          * @endif
 367          */
 368
 369         /**
 370          * Sets the state of the address.
 371          *
 372          * @if OSPCOMPAT
 373          * @brief <i> [Compatibility] </i>
 374          * @endif
 375          * @since       2.0
 376          * @if OSPCOMPAT
 377          * @compatibility            This method has compatibility issues with OSP compatible applications. @n
 378          *                            For more information, see @ref CompAddressSetStatePage "here".
 379          * @endif
 380          *
 381          * @return              An error code
 382          * @param[in]   state                   The new state value to set
 383          * @exception   E_SUCCESS               The method is successful.
 384          * @exception   E_INVALID_ARG   The specified @c state is an empty string.
 385          */
 386         result SetState(const Tizen::Base::String& state);
 387
 388         /**
 389          * @if OSPCOMPAT
 390          * @page                CompAddressSetStatePage         Compatibility for SetState()
 391          * @section             CompAddressSetStatePageIssueSection             Issues
 392          * Implementing this method in OSP compatible applications has the following issue: @n
 393          * -# If the length of the state to be set is greater than @c 50 characters, E_INVALID_ARG is returned.
 394          *
 395          * @section             CompAddressSetStatePageSolutionSection          Resolutions
 396          * The issue mentioned above has been resolved in Tizen.
 397          * @endif
 398          */
 399
 400         /**
 401          * Sets the postal code of the address.
 402          *
 403          * @if OSPCOMPAT
 404          * @brief <i> [Compatibility] </i>
 405          * @endif
 406          * @since       2.0
 407          *
 408          * @if OSPCOMPAT
 409          * @compatibility            This method has compatibility issues with OSP compatible applications. @n
 410          *                            For more information, see @ref CompAddressSetPostalCodePage "here".
 411          * @endif
 412          *
 413          * @return              An error code
 414          * @param[in]   postalCode              The new postal code value to set
 415          * @exception   E_SUCCESS               The method is successful.
 416          * @exception   E_INVALID_ARG   The specified @c postalCode is an empty string.
 417          */
 418         result SetPostalCode(const Tizen::Base::String& postalCode);
 419
 420         /**
 421          * @if OSPCOMPAT
 422          * @page                CompAddressSetPostalCodePage            Compatibility for SetPostalCode()
 423          * @section             CompAddressSetPostalCodePageIssueSection                Issues
 424          * Implementing this method in OSP compatible applications has the following issue: @n
 425          * -# If the length of the postal code to be set is greater than @c 20 characters, E_INVALID_ARG is returned.
 426          *
 427          * @section             CompAddressSetPostalCodePageSolutionSection             Resolutions
 428          * The issue mentioned above has been resolved in Tizen.
 429          * @endif
 430          */
 431
 432         /**
 433          * Sets the country of the address.
 434          *
 435          * @if OSPCOMPAT
 436          * @brief <i> [Compatibility] </i>
 437          * @endif
 438          * @since       2.0
 439          *
 440          * @if OSPCOMPAT
 441          * @compatibility            This method has compatibility issues with OSP compatible applications. @n
 442          *                            For more information, see @ref CompAddressSetCountryCodePage "here".
 443          * @endif
 444          *
 445          * @return              An error code
 446          * @param[in]   country                 The new country value to set
 447          * @exception   E_SUCCESS               The method is successful.
 448          * @exception   E_INVALID_ARG   The specified @c country is an empty string.
 449          */
 450         result SetCountry(const Tizen::Base::String& country);
 451
 452         /**
 453          * @if OSPCOMPAT
 454          * @page                CompAddressSetCountryCodePage           Compatibility for SetCountry()
 455          * @section             CompAddressSetCountryCodePageIssueSection               Issues
 456          * Implementing this method in OSP compatible applications has the following issue: @n
 457          * -# If the length of the country to be set is greater than @c 20 characters, E_INVALID_ARG is returned.
 458          *
 459          * @section             CompAddressSetCountryCodePageSolutionSection            Resolutions
 460          * The issue mentioned above has been resolved in Tizen.
 461          * @endif
 462          */
 463
 464         /**
 465          * Sets the post office box number of the address.
 466          *
 467          * @if OSPCOMPAT
 468          * @brief <i> [Compatibility] </i>
 469          * @endif
 470          * @since       2.0
 471          * @if OSPCOMPAT
 472          * @compatibility            This method has compatibility issues with OSP compatible applications. @n
 473          *                            For more information, see @ref CompAddressSetPostOfficeBoxNumberPage "here".
 474          * @endif
 475          *
 476          * @return              An error code
 477          * @param[in]   postOfficeBoxNumber             The new post office box number value to set
 478          * @exception   E_SUCCESS                       The method is successful.
 479          * @exception   E_INVALID_ARG                   The specified @c postOfficeBoxNumber is an empty string.
 480          */
 481         result SetPostOfficeBoxNumber(const Tizen::Base::String& postOfficeBoxNumber);
 482
 483         /**
 484          * @if OSPCOMPAT
 485          * @page                CompAddressSetPostOfficeBoxNumberPage           Compatibility for SetPostOfficeBoxNumber()
 486          * @section             CompAddressSetPostOfficeBoxNumberPageIssueSection               Issues
 487          * Implementing this method in OSP compatible applications has the following issue: @n
 488          * -# If the length of the post office box number to be set is greater than @c 20 characters, E_INVALID_ARG is returned.
 489          *
 490          * @section             CompAddressSetPostOfficeBoxNumberPageSolutionSection            Resolutions
 491          * The issue mentioned above has been resolved in Tizen.
 492          * @endif
 493          */
 494
 495         /**
 496          * Gets the label of an address.
 497          *
 498          * @since       2.0
 499          *
 500          * @return      The address label
 501          * @see SetLabel()
 502          */
 503         Tizen::Base::String GetLabel(void) const;
 504
 505         /**
 506          * Sets the label of an address.
 507          *
 508          * @since       2.0
 509          *
 510          * @param[in]   label   The address label
 511          * @see GetLabel()
 512          */
 513         void SetLabel(const Tizen::Base::String& label);
 514
 515         /**
 516          * Copying of objects using this copy assignment operator is allowed.
 517          *
 518          * @since       2.0
 519          *
 520          * @param[in]   rhs             An instance of %Address
 521          */
 522         Address& operator =(const Address& rhs);
 523
 524         /**
 525          * Compares the specified instance of %Address with the calling instance.
 526          *
 527          * @since       2.0
 528          *
 529          * @return              @c true if the data of the specified instance is equal to the data of the current instance, @n
 530          *                              else @c false
 531          * @param[in]   rhs             The source data
 532          */
 533         bool operator ==(const Address& rhs) const;
 534
 535         /**
 536          * Compares the specified instance to the calling instance for inequality.
 537          *
 538          * @since       2.0
 539          *
 540          * @return              @c true if the data of the specified instance is not equal to the data of the current instance, @n
 541          *                              else @c false
 542          * @param[in]   rhs             The source data
 543          */
 544         bool operator !=(const Address& rhs) const;
 545
 546 private:
 547         friend class _AddressImpl;
 548         class _AddressImpl* __pAddressImpl;
 549 }; // Address
 550
 551 }} // Tizen::Social
 552
 553 #endif //_FSCL_ADDRESS_H_