inc/FSclAddress.h

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