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          */
 292         result SetExtended(const Tizen::Base::String& extended);
 293
 294         /**
 295          * @if OSPCOMPAT
 296          * @page                CompAddressSetExtendedPage              Compatibility for SetExtended()
 297          * @section             CompAddressSetExtendedPageIssueSection          Issues
 298          * Implementing this method in OSP compatible applications has the following issue: @n
 299          * -# If the length of the extended address to be set is greater than @c 50 characters, E_INVALID_ARG is returned.
 300          *
 301          * @section             CompAddressSetExtendedPageSolutionSection               Resolutions
 302          * The issue mentioned above has been resolved in Tizen.
 303          * @endif
 304          */
 305
 306         /**
 307          * Sets the street of the address.
 308          *
 309          * @if OSPCOMPAT
 310          * @brief <i> [Compatibility] </i>
 311          * @endif
 312          * @since       2.0
 313          * @if OSPCOMPAT
 314          * @compatibility            This method has compatibility issues with OSP compatible applications. @n
 315          *                            For more information, see @ref CompAddressSetStreetPage "here".
 316          * @endif
 317          *
 318          * @return              An error code
 319          * @param[in]   street                  The new street value to set
 320          * @exception   E_SUCCESS               The method is successful.
 321          */
 322         result SetStreet(const Tizen::Base::String& street);
 323
 324         /**
 325          * @if OSPCOMPAT
 326          * @page                CompAddressSetStreetPage                Compatibility for SetStreet()
 327          * @section             CompAddressSetStreetPageIssueSection            Issues
 328          * Implementing this method in OSP compatible applications has the following issue: @n
 329          * -# If the length of the street to be set is greater than @c 50 characters, E_INVALID_ARG is returned.
 330          *
 331          * @section             CompAddressSetStreetPageSolutionSection         Resolutions
 332          * The issue mentioned above has been resolved in Tizen.
 333          * @endif
 334          */
 335
 336         /**
 337          * Sets the city of the address.
 338          *
 339          * @if OSPCOMPAT
 340          * @brief <i> [Compatibility] </i>
 341          * @endif
 342          * @since       2.0
 343          * @if OSPCOMPAT
 344          * @compatibility            This method has compatibility issues with OSP compatible applications. @n
 345          *                            For more information, see @ref CompAddressSetCityPage "here".
 346          * @endif
 347          *
 348          * @return              An error code
 349          * @param[in]   city                    The new city value to set
 350          * @exception   E_SUCCESS               The method is successful.
 351          */
 352         result SetCity(const Tizen::Base::String& city);
 353
 354         /**
 355          * @if OSPCOMPAT
 356          * @page                CompAddressSetCityPage          Compatibility for SetCity()
 357          * @section             CompAddressSetCityPageIssueSection              Issues
 358          * Implementing this method in OSP compatible applications has the following issue: @n
 359          * -# If the length of the city to be set is greater than @c 50 characters, E_INVALID_ARG is returned.
 360          *
 361          * @section             CompAddressSetCityPageSolutionSection           Resolutions
 362          * The issue mentioned above has been resolved in Tizen.
 363          * @endif
 364          */
 365
 366         /**
 367          * Sets the state of the address.
 368          *
 369          * @if OSPCOMPAT
 370          * @brief <i> [Compatibility] </i>
 371          * @endif
 372          * @since       2.0
 373          * @if OSPCOMPAT
 374          * @compatibility            This method has compatibility issues with OSP compatible applications. @n
 375          *                            For more information, see @ref CompAddressSetStatePage "here".
 376          * @endif
 377          *
 378          * @return              An error code
 379          * @param[in]   state                   The new state value to set
 380          * @exception   E_SUCCESS               The method is successful.
 381          */
 382         result SetState(const Tizen::Base::String& state);
 383
 384         /**
 385          * @if OSPCOMPAT
 386          * @page                CompAddressSetStatePage         Compatibility for SetState()
 387          * @section             CompAddressSetStatePageIssueSection             Issues
 388          * Implementing this method in OSP compatible applications has the following issue: @n
 389          * -# If the length of the state to be set is greater than @c 50 characters, E_INVALID_ARG is returned.
 390          *
 391          * @section             CompAddressSetStatePageSolutionSection          Resolutions
 392          * The issue mentioned above has been resolved in Tizen.
 393          * @endif
 394          */
 395
 396         /**
 397          * Sets the postal code of the address.
 398          *
 399          * @if OSPCOMPAT
 400          * @brief <i> [Compatibility] </i>
 401          * @endif
 402          * @since       2.0
 403          *
 404          * @if OSPCOMPAT
 405          * @compatibility            This method has compatibility issues with OSP compatible applications. @n
 406          *                            For more information, see @ref CompAddressSetPostalCodePage "here".
 407          * @endif
 408          *
 409          * @return              An error code
 410          * @param[in]   postalCode              The new postal code value to set
 411          * @exception   E_SUCCESS               The method is successful.
 412          */
 413         result SetPostalCode(const Tizen::Base::String& postalCode);
 414
 415         /**
 416          * @if OSPCOMPAT
 417          * @page                CompAddressSetPostalCodePage            Compatibility for SetPostalCode()
 418          * @section             CompAddressSetPostalCodePageIssueSection                Issues
 419          * Implementing this method in OSP compatible applications has the following issue: @n
 420          * -# If the length of the postal code to be set is greater than @c 20 characters, E_INVALID_ARG is returned.
 421          *
 422          * @section             CompAddressSetPostalCodePageSolutionSection             Resolutions
 423          * The issue mentioned above has been resolved in Tizen.
 424          * @endif
 425          */
 426
 427         /**
 428          * Sets the country of the address.
 429          *
 430          * @if OSPCOMPAT
 431          * @brief <i> [Compatibility] </i>
 432          * @endif
 433          * @since       2.0
 434          *
 435          * @if OSPCOMPAT
 436          * @compatibility            This method has compatibility issues with OSP compatible applications. @n
 437          *                            For more information, see @ref CompAddressSetCountryCodePage "here".
 438          * @endif
 439          *
 440          * @return              An error code
 441          * @param[in]   country                 The new country value to set
 442          * @exception   E_SUCCESS               The method is successful.
 443          */
 444         result SetCountry(const Tizen::Base::String& country);
 445
 446         /**
 447          * @if OSPCOMPAT
 448          * @page                CompAddressSetCountryCodePage           Compatibility for SetCountry()
 449          * @section             CompAddressSetCountryCodePageIssueSection               Issues
 450          * Implementing this method in OSP compatible applications has the following issue: @n
 451          * -# If the length of the country to be set is greater than @c 20 characters, E_INVALID_ARG is returned.
 452          *
 453          * @section             CompAddressSetCountryCodePageSolutionSection            Resolutions
 454          * The issue mentioned above has been resolved in Tizen.
 455          * @endif
 456          */
 457
 458         /**
 459          * Sets the post office box number of the address.
 460          *
 461          * @if OSPCOMPAT
 462          * @brief <i> [Compatibility] </i>
 463          * @endif
 464          * @since       2.0
 465          * @if OSPCOMPAT
 466          * @compatibility            This method has compatibility issues with OSP compatible applications. @n
 467          *                            For more information, see @ref CompAddressSetPostOfficeBoxNumberPage "here".
 468          * @endif
 469          *
 470          * @return              An error code
 471          * @param[in]   postOfficeBoxNumber             The new post office box number value to set
 472          * @exception   E_SUCCESS                       The method is successful.
 473          */
 474         result SetPostOfficeBoxNumber(const Tizen::Base::String& postOfficeBoxNumber);
 475
 476         /**
 477          * @if OSPCOMPAT
 478          * @page                CompAddressSetPostOfficeBoxNumberPage           Compatibility for SetPostOfficeBoxNumber()
 479          * @section             CompAddressSetPostOfficeBoxNumberPageIssueSection               Issues
 480          * Implementing this method in OSP compatible applications has the following issue: @n
 481          * -# If the length of the post office box number to be set is greater than @c 20 characters, E_INVALID_ARG is returned.
 482          *
 483          * @section             CompAddressSetPostOfficeBoxNumberPageSolutionSection            Resolutions
 484          * The issue mentioned above has been resolved in Tizen.
 485          * @endif
 486          */
 487
 488         /**
 489          * Gets the label of an address.
 490          *
 491          * @since       2.0
 492          *
 493          * @return      The address label
 494          * @see SetLabel()
 495          */
 496         Tizen::Base::String GetLabel(void) const;
 497
 498         /**
 499          * Sets the label of an address.
 500          *
 501          * @since       2.0
 502          *
 503          * @param[in]   label   The address label
 504          * @see GetLabel()
 505          */
 506         void SetLabel(const Tizen::Base::String& label);
 507
 508         /**
 509          * Copying of objects using this copy assignment operator is allowed.
 510          *
 511          * @since       2.0
 512          *
 513          * @param[in]   rhs             An instance of %Address
 514          */
 515         Address& operator =(const Address& rhs);
 516
 517         /**
 518          * Compares the specified instance of %Address with the calling instance.
 519          *
 520          * @since       2.0
 521          *
 522          * @return              @c true if the data of the specified instance is equal to the data of the current instance, @n
 523          *                              else @c false
 524          * @param[in]   rhs             The source data
 525          */
 526         bool operator ==(const Address& rhs) const;
 527
 528         /**
 529          * Compares the specified instance to the calling instance for inequality.
 530          *
 531          * @since       2.0
 532          *
 533          * @return              @c true if the data of the specified instance is not equal to the data of the current instance, @n
 534          *                              else @c false
 535          * @param[in]   rhs             The source data
 536          */
 537         bool operator !=(const Address& rhs) const;
 538
 539 private:
 540         friend class _AddressImpl;
 541         class _AddressImpl* __pAddressImpl;
 542 }; // Address
 543
 544 }} // Tizen::Social
 545
 546 #endif //_FSCL_ADDRESS_H_