inc/FSclAddressbook.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         FSclAddressbook.h
  18 * @brief        This is the header file for the %Addressbook class.
  19 *
  20 * This header file contains the declarations of the %Addressbook class.
  21 */
  22
  23 #ifndef _FSCL_ADDRESSBOOK_H_
  24 #define _FSCL_ADDRESSBOOK_H_
  25
  26 #include <FBaseObject.h>
  27 #include <FBaseTypes.h>
  28 #include <FSclRecord.h>
  29 #include <FSclTypes.h>
  30
  31 namespace Tizen { namespace Base
  32 {
  33 class String;
  34 namespace Collection
  35 {
  36 class IList;
  37 template<class Type> class IListT;
  38 }
  39 }}
  40
  41 namespace Tizen { namespace Social
  42 {
  43 class Category;
  44 class Contact;
  45 class UserProfile;
  46 class IRecordEventListener;
  47 class IAddressbookEventListener;
  48 class IAddressbookChangeEventListener;
  49 class IRecordEventListener;
  50
  51 /**
  52  * @class       Addressbook
  53  * @brief       This class handles the address book database.
  54  *
  55  * @since       2.0
  56  *
  57  * @final       This class is not intended for extension.
  58  *
  59  * The %Addressbook class handles the %Addressbook database, which is a centralized database used by multiple applications to store a subset of the contact information.
  60  * It also supports the categorizing of the contacts.
  61  *
  62  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/social/addressbook_namespace.htm">Address Book</a>.
  63  *
  64  * The following example demonstrates how to use the %Addressbook class to create the categories and add contacts to them.
  65  *
  66  * @code
  67  *
  68         #include <FSocial.h>
  69
  70         using namespace Tizen::Social;
  71         using namespace Tizen::Base;
  72
  73         void
  74         AddressbookExample::CreateExample(void)
  75         {
  76                 result r = E_SUCCESS;
  77
  78                 // Get default addressbook instance
  79                 Addressbook* pAddressbook = AddressbookManager::GetInstance()->GetAddressbookN();
  80
  81                 // Creates and constructs a contact
  82                 Contact contact;
  83
  84                 // Sets the contact's properties: first name and last name
  85                 contact.SetValue(CONTACT_PROPERTY_ID_FIRST_NAME , L"Thomas");
  86                 contact.SetValue(CONTACT_PROPERTY_ID_LAST_NAME , L"Anderson");
  87
  88                 // Sets the contact's properties: add a phone number
  89                 PhoneNumber phoneNumber(PHONENUMBER_TYPE_MOBILE, L"820223459876");
  90                 contact.AddPhoneNumber(phoneNumber);
  91
  92                 // Sets the contact's properties: add an address
  93                 Address address;
  94                 address.SetCountry(L"KOR");
  95                 address.SetCity(L"Seoul");
  96                 contact.AddAddress(address);
  97
  98                 // Adds the contact to the address book (when it is added, the recordId is created)
  99                 r = pAddressbook->AddContact(contact);
 100                 if (IsFailed(r))
 101                 {
 102                         AppLogException( "Fails to add a contact");
 103
 104                         delete pAddressbook;
 105                         return;
 106                 }
 107
 108                 // Creates and constructs a category ("Friends")
 109                 Category category;
 110                 category.SetName(L"Friends");
 111
 112
 113                 // Adds the category to the address book
 114                 r = pAddressbook->AddCategory(category);
 115                 if (IsFailed(r))
 116                 {
 117                         delete pAddressbook;
 118                         return;
 119                 }
 120
 121                 // Adds the contact to the category
 122                 r = pAddressbook->AddMemberToCategory(category.GetRecordId(), contact.GetRecordId());
 123                 if (IsFailed(r))
 124                 {
 125                         delete pAddressbook;
 126                         return;
 127                 }
 128
 129                 delete pAddressbook;
 130         }
 131  *
 132  * @endcode
 133  *
 134  * The following example demonstrates how to use the %Addressbook class to retrieve the contacts associated with each category.
 135  * @code
 136  *
 137         #include <FSocial.h>
 138
 139         using namespace Tizen::Base;
 140         using namespace Tizen::Base::Collection;
 141         using namespace Tizen::Social;
 142
 143         void
 144         AddressbookExample::GetContactsExample(void)
 145         {
 146                 result r = E_SUCCESS;
 147
 148                 // Get default addressbook instance
 149                 Addressbook* pAddressbook = AddressbookManager::GetInstance()->GetAddressbookN();
 150
 151                 // Gets all the categories.
 152                 IList* pCategoryList = pAddressbook->GetAllCategoriesN();
 153                 if (pCategoryList == null)
 154                 {
 155                         delete pAddressbook;
 156                         return;
 157                 }
 158
 159                 Category* pCategory = null;
 160                 Contact* pContact = null;
 161                 IList* pContactList = null;
 162                 IEnumerator* pContactEnum = null;
 163                 String firstName;
 164                 String lastName;
 165                 IEnumerator* pCategoryEnum = pCategoryList->GetEnumeratorN();
 166                 while (pCategoryEnum->MoveNext() == E_SUCCESS)
 167                 {
 168                         pCategory = static_cast<Category*>(pCategoryEnum->GetCurrent());
 169
 170                         // Gets all the contacts of each category.
 171                         pContactList = pAddressbook->GetContactsByCategoryN(pCategory->GetRecordId());
 172                         if (pContactList == null)
 173                         {
 174                                 continue;
 175                         }
 176
 177                         pContactEnum = pContactList->GetEnumeratorN();
 178                         while (pContactEnum->MoveNext() == E_SUCCESS)
 179                         {
 180                                 pContact = static_cast<Contact*>(pContactEnum->GetCurrent());
 181
 182                                 //Gets the name.
 183                                 pContact->GetValue(CONTACT_PROPERTY_ID_FIRST_NAME, firstName);
 184                                 pContact->GetValue(CONTACT_PROPERTY_ID_LAST_NAME, lastName);
 185
 186                                 // Displays the first name and last name.
 187                                 // ...
 188                         }
 189                         delete pContactEnum;
 190                         pContactList->RemoveAll(true);
 191                         delete pContactList;
 192                 }
 193
 194                 delete pCategoryEnum;
 195                 pCategoryList->RemoveAll(true);
 196                 delete pCategoryList;
 197
 198                 delete pAddressbook;
 199         }
 200
 201  *
 202  * @endcode
 203  *
 204  * The following example demonstrates how to use the %Addressbook class to search for a contact.
 205  *
 206  * @code
 207  *
 208         #include <FSocial.h>
 209
 210         using namespace Tizen::Base;
 211         using namespace Tizen::Base::Collection;
 212         using namespace Tizen::Social;
 213
 214         void
 215         AddressbookExample::SearchExample(void)
 216         {
 217                 result r = E_SUCCESS;
 218
 219                 // Get default addressbook instance
 220                 Addressbook* pAddressbook = AddressbookManager::GetInstance()->GetAddressbookN();
 221
 222                 //Searches contacts by name ("Anderson").
 223                 IList* pContactList = pAddressbook->SearchContactsByNameN(L"Anderson");
 224                 if (pContactList == null)
 225                 {
 226                         delete pAddressbook;
 227
 228                         return;
 229                 }
 230
 231                 Contact* pContact = null;
 232                 String firstName;
 233                 String lastName;
 234                 IEnumerator* pContactEnum = pContactList->GetEnumeratorN();
 235                 while (pContactEnum->MoveNext() == E_SUCCESS)
 236                 {
 237                         pContact = static_cast<Contact*>(pContactEnum->GetCurrent());
 238
 239                         //Gets the contact's name.
 240                         pContact->GetValue(CONTACT_PROPERTY_ID_FIRST_NAME, firstName);
 241                         pContact->GetValue(CONTACT_PROPERTY_ID_LAST_NAME, lastName);
 242
 243                         // Displays the first name and last name.
 244                         // ...
 245                 }
 246
 247                 delete pContactEnum;
 248                 pContactList->RemoveAll(true);
 249                 delete pContactList;
 250
 251                 delete pAddressbook;
 252         }
 253  *
 254  * @endcode
 255  */
 256 class _OSP_EXPORT_ Addressbook
 257         : public Tizen::Base::Object
 258 {
 259 public:
 260         /**
 261          *
 262          * The object is not fully constructed after this constructor is called. @n
 263          * An application must use AddressbookManager::GetAddressbookN() to get fully constructed %Addressbook instance.
 264          * @since       2.0
 265          *
 266          * @see AddressbookManager::GetAddressbookN()
 267          *
 268          * The following example demonstrates how to create an %Addressbook instance.
 269          * @code
 270          * result
 271          * MyApplication::UpdateContact(Contact* pContact)
 272          * {
 273          *    Addressbook* pAddressbook = AddressbookManager::GetInstance()->GetAddressbookN();
 274          *
 275          *    result r = pAddressbook->UpdateContact(*pContact);
 276          *
 277          *    delete pAddressbook;
 278          *
 279          *    return r;
 280          * }
 281          * @endcode
 282          */
 283         Addressbook(void);
 284
 285         /**
 286          * This destructor overrides Tizen::Base::Object::~Object().
 287          *
 288          * @since       2.0
 289          */
 290         virtual ~Addressbook(void);
 291
 292         /**
 293          * @if OSPDEPREC
 294          * Initializes this instance of %Addressbook with a specified listener.
 295          *
 296          * @brief <i> [Deprecated] </i>
 297          * @deprecated This method and IRecordEventListener are deprecated. Instead of using this method, use AddressbookManager::GetAddressbookN() and SetEventListener().
 298          *
 299          * @since       2.0
 300          *
 301          * @return      An error code
 302          * @param[in]   pListener               The event listener to register
 303          * @exception   E_SUCCESS                               The method is successful.
 304          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 305          * @endif
 306          */
 307         result Construct(IRecordEventListener* pListener = null);
 308
 309         /**
 310          * Sets addressbook change event listener. @n
 311          * The listener is called when a contact or a category has been changed.
 312          * To reset the event listener, @c null must be passed.
 313          *
 314          * @brief <i> [Deprecated] </i>
 315          * @deprecated This method and IAddressbookEventListener are deprecated. Instead of using this method, use SetAddressbookChangeEventListener()
 316          * and IAddressbookChangeEventListener.
 317          *
 318          * @since       2.0
 319          * @privlevel   public
 320          * @privilege   %http://tizen.org/privilege/contact.read
 321          *
 322          * @return      An error code
 323          * @param[in]   pListener       The event listener
 324          * @exception   E_SUCCESS       The method is successful.
 325          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 326          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 327          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
 328          */
 329         result SetEventListener(IAddressbookEventListener* pListener);
 330
 331         /**
 332          * Sets addressbook change event listener. @n
 333          * The listener is called when a contact or a category has been changed.
 334          * To reset the event listener, @c null must be passed.
 335          *
 336          * @since       2.1
 337          * @privlevel   public
 338          * @privilege   %http://tizen.org/privilege/contact.read
 339          *
 340          * @return      An error code
 341          * @param[in]   pListener       The event listener
 342          * @exception   E_SUCCESS       The method is successful.
 343          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 344          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method.
 345          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error
 346          */
 347         result SetAddressbookChangeEventListener(IAddressbookChangeEventListener* pListener);
 348
 349         /**
 350          * Adds a contact to the address book. @n
 351          * At least one property of the contact must have been set. @n
 352          * If the contact has been added successfully, a contact ID is assigned to it.
 353          *
 354          * @since       2.0
 355          * @privlevel   public
 356          * @privilege   %http://tizen.org/privilege/contact.write
 357          *
 358          * @return      An error code
 359          * @param[in,out]       contact                 The contact to add
 360          * @exception   E_SUCCESS               The method is successful.
 361          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 362          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 363          * @exception   E_INVALID_ARG           The contact ID is not #INVALID_RECORD_ID, or
 364          *                                                                      the properties of the contact have not been set.
 365          * @exception   E_STORAGE_FULL          The storage is insufficient.
 366          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 367          * @remarks   The #CONTACT_PROPERTY_ID_DISPLAY_NAME and #CONTACT_PROPERTY_ID_LAST_REVISION properties cannot be set.
 368          * @n #CONTACT_PROPERTY_ID_DISPLAY_NAME is automatically generated from the first name and last name.
 369          * And #CONTACT_PROPERTY_ID_LAST_REVISION automatically updated with the last update time.
 370          */
 371         result AddContact(Contact& contact);
 372
 373         /**
 374          * Removes a contact from the address book. @n
 375          * After this operation is done successfully, the ID of the Contact instance is #INVALID_RECORD_ID.
 376          *
 377          * @since       2.0
 378          * @privlevel   public
 379          * @privilege   %http://tizen.org/privilege/contact.write
 380          *
 381          * @return      An error code
 382          * @param[in,out]       contact                 The contact to remove
 383          * @exception   E_SUCCESS               The method is successful.
 384          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 385          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 386          * @exception   E_INVALID_ARG           The specified @c contact is invalid.
 387          * @exception   E_OBJ_NOT_FOUND         The specified @c contact does not exist.
 388          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 389          */
 390         result RemoveContact(Contact& contact);
 391
 392         /**
 393          * Removes a contact from the address book.
 394          *
 395          * @since       2.0
 396          * @privlevel   public
 397          * @privilege   %http://tizen.org/privilege/contact.write
 398          *
 399          * @return      An error code
 400          * @param[in]   contactId               The contact ID
 401          * @exception   E_SUCCESS               The method is successful.
 402          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 403          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 404          * @exception   E_INVALID_ARG           The specified @c contactId is invalid.
 405          * @exception   E_OBJ_NOT_FOUND         The specified @c contactId does not exist.
 406          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 407          */
 408         result RemoveContact(RecordId contactId);
 409
 410         /**
 411          * Updates a specified contact. @n
 412          * At least one property of the contact must have been set.
 413          *
 414          * @since       2.0
 415          * @privlevel   public
 416          * @privilege   %http://tizen.org/privilege/contact.write
 417          *
 418          * @return      An error code
 419          * @param[in]   contact                 The contact to update
 420          * @exception   E_SUCCESS               The method is successful.
 421          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 422          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 423          * @exception   E_OBJ_NOT_FOUND         The specified @c contact does not exist in this address book.
 424          * @exception   E_INVALID_ARG           The specified @c contact is invalid, or
 425          *                                                                      the properties of the specified @c contact have not been set.
 426          * @exception   E_STORAGE_FULL          The storage is insufficient.
 427          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 428          */
 429         result UpdateContact(const Contact& contact);
 430
 431         /**
 432          * Adds a category to the address book. @n
 433          * If the category has been added successfully, a category ID is assigned to it.
 434          *
 435          * @if OSPCOMPAT
 436          * @brief <i> [Compatibility] </i>
 437          * @endif
 438          * @since       2.0
 439          * @if OSPCOMPAT
 440          * @compatibility            This method has compatibility issues with OSP compatible applications. @n
 441          *                      For more information, see @ref CompAddressbookAddCategoryPage "here".
 442          * @endif
 443          * @privlevel   public
 444          * @privilege   %http://tizen.org/privilege/contact.write
 445          *
 446          * @return      An error code
 447          * @param[in,out]       category                The category to add
 448          * @exception   E_SUCCESS               The method is successful.
 449          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 450          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 451          * @exception   E_INVALID_ARG           Either of the following conditions has occurred: @n
 452          *                                                                      - The name of the category has not been set. @n
 453          *                                                                      - The category ID of the @c category is not #INVALID_RECORD_ID. @n
 454          *                                                                      - One of the contact members is invalid.
 455          * @exception   E_STORAGE_FULL          The storage is insufficient.
 456          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 457          */
 458         result AddCategory(Category& category);
 459
 460         /**
 461          * @if OSPCOMPAT
 462          * @page                CompAddressbookAddCategoryPage         Compatibility for AddCategory()
 463          * @section             CompAddressbookAddCategoryPageIssueSection             Issues
 464          * Implementing this method in OSP compatible applications has the following issue: @n
 465          * -# If there already exist a category which has the same name, E_OBJ_ALREADY_EXIST is returned.
 466          *
 467          * @section             CompAddressbookAddCategoryPageSolutionSection          Resolutions
 468          * The issue mentioned above has been resolved in Tizen.
 469          * @endif
 470         */
 471
 472
 473         /**
 474          * Removes a category from the address book. @n
 475          * If the category has been deleted successfully, the record ID of this instance is #INVALID_RECORD_ID.
 476          *
 477          * @since       2.0
 478          * @privlevel   public
 479          * @privilege   %http://tizen.org/privilege/contact.write
 480          *
 481          * @return      An error code
 482          * @param[in,out]       category                The category to remove
 483          * @exception   E_SUCCESS               The method is successful.
 484          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 485          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 486          * @exception   E_INVALID_ARG           The specified @c category is invalid or a default category.
 487          * @exception   E_OBJ_NOT_FOUND         The specified @c category does not exist in this address book.
 488          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 489          * @see         Category::IsDefault()
 490          */
 491         result RemoveCategory(Category& category);
 492
 493         /**
 494          * Removes a category from the address book.
 495          *
 496          * @since       2.0
 497          * @privlevel   public
 498          * @privilege   %http://tizen.org/privilege/contact.write
 499          *
 500          * @return      An error code
 501          * @param[in]   categoryId              The category ID
 502          * @exception   E_SUCCESS               The method is successful.
 503          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 504          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 505          * @exception   E_INVALID_ARG           The specified @c categoryId is invalid or the category specified by @ categoryId is a default category.
 506          * @exception   E_OBJ_NOT_FOUND         The specified @c categoryId does not exist in this address book.
 507          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 508          * @see         Category::IsDefault()
 509          */
 510         result RemoveCategory(RecordId categoryId);
 511
 512         /**
 513          * Updates a category in the address book.
 514          *
 515          * @if OSPCOMPAT
 516          * @brief <i> [Compatibility] </i>
 517          * @endif
 518          * @since       2.0
 519          * @if OSPCOMPAT
 520          * @compatibility            This method has compatibility issues with OSP compatible applications. @n
 521          *                            For more information, see @ref CompAddressbookUpdateCategoryPage "here".
 522          * @endif
 523          * @privlevel   public
 524          * @privilege   %http://tizen.org/privilege/contact.write
 525          *
 526          * @return      An error code
 527          * @param[in]   category                The category to update
 528          * @exception   E_SUCCESS               The method is successful.
 529          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 530          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 531          * @exception   E_OBJ_NOT_FOUND         The specified @c category does not exist in this address book.
 532          * @exception   E_INVALID_ARG           The specified @c category is invalid, or
 533          *                                                                      one of the contact members is invalid.
 534          * @exception   E_STORAGE_FULL          The storage is insufficient.
 535          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 536          */
 537         result UpdateCategory(const Category& category);
 538
 539         /**
 540          * @if OSPCOMPAT
 541          * @page                CompAddressbookUpdateCategoryPage         Compatibility for UpdateCategory()
 542          * @section             CompAddressbookUpdateCategoryPageIssueSection             Issues
 543          * Implementing this method in OSP compatible applications has the following issue: @n
 544          * -# If there already exist a category which has the same name, E_OBJ_ALREADY_EXIST is returned.
 545          *
 546          * @section             CompAddressbookAddCategoryPageSolutionSection          Resolutions
 547          * The issue mentioned above has been resolved in Tizen.
 548          * @endif
 549          */
 550
 551
 552         /**
 553          * Gets all contacts in the addressbook. @n
 554          * The contacts are ordered by display name.
 555          *
 556          * @since       2.0
 557          * @privlevel   public
 558          * @privilege   %http://tizen.org/privilege/contact.read
 559          *
 560          * @return      A list of all contacts in the addressbook, @n
 561          *                                  else an empty list if there is no contact, or @c null if an exception occurs (@ref Contact list)
 562          * @exception   E_SUCCESS                       The method is successful.
 563          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 564          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 565          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 566          * @remarks
 567          *              - The specific error code can be accessed using the GetLastResult() method.
 568          *              - There is a high probability for an occurrence of an out-of-memory exception.
 569          *                If possible, check whether the exception is E_OUT_OF_MEMORY or not. @n
 570          *                For more information on how to handle the out-of-memory exception, refer
 571          *                <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
 572          */
 573         Tizen::Base::Collection::IList* GetAllContactsN(void) const;
 574
 575         /**
 576          * Gets the member contacts of a specified category. @n
 577          * If the specified @c category is INVALID_RECORD_ID, this method returns the list of contacts that are not member of any category.
 578          * The contacts are ordered by display name.
 579          *
 580          * @since       2.0
 581          * @privlevel   public
 582          * @privilege   %http://tizen.org/privilege/contact.read
 583          *
 584          * @return      A list of contacts that are members of a specified category, @n
 585          *                                  else an empty list if there is no contact, or @c null if an exception occurs (@ref Contact list)
 586          * @param[in]   categoryId              The category ID
 587          * @exception   E_SUCCESS                       The method is successful.
 588          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 589          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 590          * @exception   E_INVALID_ARG           The specified @c categoryId is less than INVALID_RECORD_ID.
 591          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 592          * @remarks
 593          *              - The specific error code can be accessed using the GetLastResult() method.
 594          *              - There is a high probability for an occurrence of an out-of-memory exception.
 595          *                If possible, check whether the exception is E_OUT_OF_MEMORY or not. @n
 596          *                For more information on how to handle the out-of-memory exception, refer
 597          *                <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
 598          */
 599         Tizen::Base::Collection::IList* GetContactsByCategoryN(RecordId categoryId) const;
 600
 601         /**
 602          * Gets contacts in a specified range in the address book. @n
 603          * The contacts are ordered by display name.
 604          *
 605          * @since       2.0
 606          * @privlevel   public
 607          * @privilege   %http://tizen.org/privilege/contact.read
 608          *
 609          * @return      A list of contacts in a specified range, @n
 610          *                              else an empty list if there is no contact, or @c null if an exception occurs (@ref Contact list)
 611          * @param[in]   pageNo                  The page number of the result list @n
 612          *                                                                      It starts from @c 1.
 613          * @param[in]   countPerPage            The maximum count of the result items on a page
 614          * @exception   E_SUCCESS               The method is successful.
 615          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 616          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 617          * @exception   E_OUT_OF_RANGE          The specified @c pageNo or @c countPerPage is less than @c 1.
 618          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 619          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 620          * @remarks
 621          *              - The specific error code can be accessed using the GetLastResult() method.
 622          *              - There is a high probability for an occurrence of an out-of-memory exception.
 623          *                If possible, check whether the exception is E_OUT_OF_MEMORY or not. @n
 624          *                For more information on how to handle the out-of-memory exception, refer
 625          *                <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
 626
 627          */
 628         Tizen::Base::Collection::IList* GetContactsN(int pageNo, int countPerPage) const;
 629
 630         /**
 631          * Gets contacts that are in the specified range of a specified category. @n
 632          * The contacts are ordered by display name.
 633          *
 634          * @since       2.0
 635          * @privlevel   public
 636          * @privilege   %http://tizen.org/privilege/contact.read
 637          *
 638          * @return      A list of contacts in the specified range of a specified category, @n
 639          *                              else an empty list if there is no contact, or @c null if an exception occurs (@ref Contact list)
 640          * @param[in]   category                The category
 641          * @param[in]   pageNo                  The page number of the result list, which starts from @c 1
 642          * @param[in]   countPerPage            The maximum count of the result items on a page
 643          * @exception   E_SUCCESS               The method is successful.
 644          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 645          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 646          * @exception   E_OUT_OF_RANGE          The specified @c pageNo or @c countPerPage is less than @c 1.
 647          * @exception   E_INVALID_ARG           The specified @c category is invalid, or
 648          *                                                                      one of the contact members is invalid.
 649          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 650          * @remarks
 651          *              - The specific error code can be accessed using the GetLastResult() method.
 652          *              - There is a high probability for an occurrence of an out-of-memory exception.
 653          *                If possible, check whether the exception is E_OUT_OF_MEMORY or not. @n
 654          *                For more information on how to handle the out-of-memory exception, refer
 655          *                <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
 656          */
 657         Tizen::Base::Collection::IList* GetContactsInN(const Category& category, int pageNo, int countPerPage) const;
 658
 659         /**
 660          * Gets the contact with a specified contact ID.
 661          *
 662          * @since       2.0
 663          * @privlevel   public
 664          * @privilege   %http://tizen.org/privilege/contact.read
 665          *
 666          * @return              The matched contact, @n
 667          *                              else @c null if no contact matches the specified contact ID
 668          * @param[in]   contactId               The contact ID
 669          * @exception   E_SUCCESS               The method is successful.
 670          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 671          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 672          * @exception   E_INVALID_ARG           The specified @c contactId is invalid.
 673          * @exception   E_OBJ_NOT_FOUND         The specified @c contactId is not found.
 674          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 675          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 676          */
 677         Contact* GetContactN(RecordId contactId) const;
 678
 679         /**
 680          * Gets the number of contacts in the address book.
 681          *
 682          * @since       2.0
 683          * @privlevel   public
 684          * @privilege   %http://tizen.org/privilege/contact.read
 685          *
 686          * @return              The number of contacts in the address book, @n
 687          *                              else @c -1 if an error occurs
 688          * @exception   E_SUCCESS               The method is successful.
 689          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 690          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 691          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 692          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 693          */
 694         int GetContactCount(void) const;
 695
 696         /**
 697          * Adds a specified contact to a specified category.
 698          *
 699          * @since       2.0
 700          * @privlevel   public
 701          * @privilege   %http://tizen.org/privilege/contact.write
 702          *
 703          * @return      An error code
 704          * @param [in]  categoryId              The category ID
 705          * @param [in]  contactId               The contact ID
 706          * @exception   E_SUCCESS               The method is successful.
 707          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 708          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 709          * @exception   E_INVALID_ARG           The specified contact or category does not exist, or the specified contact and category are not in this addressbook.
 710          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 711          * @remarks If the contact is already a member of the category, this method does nothing.
 712          */
 713         result AddMemberToCategory(RecordId categoryId, RecordId contactId);
 714
 715         /**
 716          * Removes a specified contact from a specified category.
 717          *
 718          * @since       2.0
 719          * @privlevel   public
 720          * @privilege   %http://tizen.org/privilege/contact.write
 721          *
 722          * @return      An error code
 723          * @param [in]  categoryId              The category ID
 724          * @param [in]  contactId               The contact ID
 725          * @exception   E_SUCCESS               The method is successful.
 726          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 727          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 728          * @exception   E_INVALID_ARG           The specified contact or category does not exist, or the specified contact and category are not in this addressbook.
 729          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 730          * @remarks If the contact is not a member of the category, this method does nothing.
 731          */
 732         result RemoveMemberFromCategory(RecordId categoryId, RecordId contactId);
 733
 734         /**
 735          * Gets all categories in the address book. @n
 736          * The categories are ordered by name.
 737          *
 738          * @since       2.0
 739          * @privlevel   public
 740          * @privilege   %http://tizen.org/privilege/contact.read
 741          *
 742          * @return      A list of categories in the address book, @n
 743          *                              else an empty list if there is no category, or @c null if an exception occurs (@ref Category list)
 744          * @exception   E_SUCCESS                       The method is successful.
 745          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 746          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 747          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 748          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 749          */
 750         Tizen::Base::Collection::IList* GetAllCategoriesN(void) const;
 751
 752         /**
 753          * Gets all categories whose member is the specified contact. @n
 754          * The categories are ordered by name.
 755          *
 756          * @since       2.0
 757          * @privlevel   public
 758          * @privilege   %http://tizen.org/privilege/contact.read
 759          *
 760          * @return              A list of categories that has a specified contact as a member, @n
 761          *                                  else an empty list if there is no category, or @c null if an exception occurs (@ref Category list)
 762          * @param[in] contactId         The contact ID
 763          * @exception   E_SUCCESS               The method is successful.
 764          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 765          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 766          * @exception   E_INVALID_ARG           The specified @c contactId is invalid.
 767          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 768          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 769          */
 770         Tizen::Base::Collection::IList* GetCategoriesByContactN(RecordId contactId) const;
 771
 772         /**
 773          * Gets the number of categories in the address book.
 774          *
 775          * @since       2.0
 776          * @privlevel   public
 777          * @privilege   %http://tizen.org/privilege/contact.read
 778          *
 779          * @return              The number of categories in the address book, @n
 780          *                              else @c -1 if an error occurs
 781          * @exception   E_SUCCESS                       The method is successful.
 782          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 783          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 784          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 785          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 786          */
 787         int GetCategoryCount(void) const;
 788
 789         /**
 790          * Gets the category with a specified category ID.
 791          *
 792          * @since       2.0
 793          * @privlevel   public
 794          * @privilege   %http://tizen.org/privilege/contact.read
 795          *
 796          * @return              The matched category, @n
 797          *                              else @c null if no category matches the specified category ID
 798          * @param[in]   categoryId              The category ID
 799          * @exception   E_SUCCESS               The method is successful.
 800          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 801          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 802          * @exception   E_INVALID_ARG           The specified @c categoryId is invalid.
 803          * @exception   E_OBJ_NOT_FOUND         The specified record is not found.
 804          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 805          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 806          */
 807         Category* GetCategoryN(RecordId categoryId) const;
 808
 809         /**
 810          * Searches the contacts whose email address contains the specified @c email string. @n
 811          * The search operation is performed with a case insensitive key (param: @c email). @n
 812          * The contacts are ordered by display name.
 813          *
 814          * @since       2.0
 815          * @privlevel   public
 816          * @privilege   %http://tizen.org/privilege/contact.read
 817          *
 818          * @return      A list of all the matched contacts, @n
 819          *                              else an empty list if there is no matched contact, or @c null if an exception occurs (@ref Contact list)
 820          * @param[in]   email                   The substring of the email to search
 821          * @exception   E_SUCCESS               The method is successful.
 822          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 823          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 824          * @exception   E_INVALID_ARG           The specified @c email is an empty string.
 825          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 826          * @remarks
 827          *              - The specific error code can be accessed using the GetLastResult() method.
 828          *              - There is a high probability for an occurrence of an out-of-memory exception. @n If possible, check whether the exception is E_OUT_OF_MEMORY or not. @n
 829          *                For more information on how to handle the out-of-memory exception, refer
 830          *                <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
 831          */
 832         Tizen::Base::Collection::IList* SearchContactsByEmailN(const Tizen::Base::String& email) const;
 833
 834         /**
 835          * Searches the contacts that have the specified @c name as a substring of their display name. @n
 836          * The search operation is performed with a case insensitive key (param: @c name). @n
 837          * The contacts are ordered by display name.
 838          *
 839          * @since       2.0
 840          * @privlevel   public
 841          * @privilege   %http://tizen.org/privilege/contact.read
 842          *
 843          * @return      A list of all the matched contacts, @n
 844          *                              else an empty list if there is no matched contact, or @c null if an exception occurs (@ref Contact list)
 845          * @param[in]   name                    The substring of the name to search
 846          * @exception   E_SUCCESS               The method is successful.
 847          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 848          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 849          * @exception   E_INVALID_ARG           The specified @c name is an empty string.
 850          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 851          * @remarks
 852          *              - The specific error code can be accessed using the GetLastResult() method.
 853          *              - There is a high probability for an occurrence of an out-of-memory exception.@n If possible, check whether the exception is E_OUT_OF_MEMORY or not.@n
 854          *                For more information on how to handle the out-of-memory exception, refer
 855          *                <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
 856          */
 857         Tizen::Base::Collection::IList* SearchContactsByNameN(const Tizen::Base::String& name) const;
 858
 859         /**
 860          * Searches the contacts that have the specified @c phoneNumber string as a substring of one of their phone numbers. @n
 861          * The %SearchContactsByPhoneNumberN() method returns the contacts whose phone number match the value of the specified @c phoneNumber. @n
 862          * The search operation is performed with a case insensitive key (param: @c phoneNumber). @n
 863          * The contacts are ordered by display name.
 864          *
 865          * @since       2.0
 866          * @privlevel   public
 867          * @privilege   %http://tizen.org/privilege/contact.read
 868          *
 869          * @return      A list of all the matched contacts, @n
 870          *                                  else an empty list if there is no contact, or @c null if an exception occurs (@ref Contact list)
 871          * @param[in]   phoneNumber             The substring of the phone number to search
 872          * @exception   E_SUCCESS               The method is successful.
 873          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 874          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 875          * @exception   E_INVALID_ARG           The specified @c phoneNumber is an empty string.
 876          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 877          * @remarks
 878          *              - The specific error code can be accessed using the GetLastResult() method.
 879          *              - There is a high probability for an occurrence of an out-of-memory exception. @n If possible, check whether the exception is E_OUT_OF_MEMORY or not. @n
 880          *                For more information on how to handle the out-of-memory exception, refer
 881          *                <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
 882          */
 883         Tizen::Base::Collection::IList* SearchContactsByPhoneNumberN(const Tizen::Base::String& phoneNumber) const;
 884
 885         /**
 886          * Gets the latest change version of the address book.
 887          *
 888          * @since       2.0
 889          * @privlevel   public
 890          * @privilege   %http://tizen.org/privilege/contact.read
 891          *
 892          * @return              The latest change version, @c
 893          *                      else @c -1 if an exception occurs
 894          * @exception   E_SUCCESS               The method is successful.
 895          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 896          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 897          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 898          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 899          * @see GetChangedContactsAfterN()
 900          * @see GetChangedCategoriesAfterN()
 901          */
 902         int GetLatestVersion(void) const;
 903
 904         /**
 905          * Gets the change information of the contacts that have been changed after a specified change version. @n
 906          *
 907          * @brief <i> [Deprecated] </i>
 908          * @deprecated This method is deprecated. Instead of using this method, use GetChangedContactInfoListN().
 909          *
 910          * @since       2.0
 911          * @privlevel   public
 912          * @privilege   %http://tizen.org/privilege/contact.read
 913          *
 914          * @return      A list of contact change information, @n
 915          *                                  else an empty list if there is no changed contact, or @c null if an exception occurs (@ref ContactChangeInfo list)
 916          * @param[in]   version                 The change version
 917          * @param[out]  latestVersion   The latest change version among the changed contacts
 918          * @exception   E_SUCCESS               The method is successful.
 919          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 920          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 921          * @exception   E_INVALID_ARG           The specified @c version is invalid.
 922          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 923          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 924          * @see GetLatestVersion()
 925          *
 926          * The following example demonstrates how to use the %GetChangedContactsAfterN() method.
 927          * @code
 928          * void
 929          * MyApplication::GetChangedContacts(void)
 930          * {
 931          *    IList* pChangedContacts = __pAddressbook->GetChangedContactsAfterN(__version, __version);
 932          *
 933          *    IEnumerator* pEnum = pChangedContacts->GetEnumeratorN();
 934          *    while (pEnum->MoveNext() == E_SUCCESS)
 935          *    {
 936          *      ContactChangeInfo* pInfo = (ContactChangeInfo*) pEnum->GetCurrent();
 937          *
 938          *      AppLog("Contact changed: type(%d), id(%d), version(%d)", pInfo->GetChangeType(), pInfo->GetContctId(), pInfo->GetVersion());
 939          *    }
 940          *    delete pEnum;
 941          *    pChangedContacts->RemoveAll(true);
 942          *    delete pChangedContacts;
 943          * }
 944          * @endcode
 945          */
 946         Tizen::Base::Collection::IList* GetChangedContactsAfterN(int version, int& latestVersion) const;
 947
 948         /**
 949          * Gets the change information of the contacts that have been changed after a specified change version.
 950          *
 951          * @since       2.1
 952          * @privlevel   public
 953          * @privilege   %http://tizen.org/privilege/contact.read
 954          *
 955          * @return      A list of contact change information, @n
 956          *                                  else an empty list if there is no changed contact or @c null if an exception occurs (@ref ContactChangeInfo list)
 957          * @param[in]   version                 The change version
 958          * @param[out]  latestVersion   The latest change version among the changed contacts
 959          * @exception   E_SUCCESS               The method is successful.
 960          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 961          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method.
 962          * @exception   E_INVALID_ARG           The specified @c version is invalid.
 963          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error
 964          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 965          * @see GetLatestVersion()
 966          *
 967          * The following example demonstrates how to use the %GetChangedContactInfoListN() method.
 968          * @code
 969          * void
 970          * MyApplication::GetChangedContacts(void)
 971          * {
 972          *    IList* pChangedContacts = __pAddressbook->GetChangedContactInfoListN (__version, __version);
 973          *
 974          *    IEnumerator* pEnum = pChangedContacts->GetEnumeratorN();
 975          *    while (pEnum->MoveNext() == E_SUCCESS)
 976          *    {
 977          *      ContactChangeInfo* pInfo = (ContactChangeInfo*) pEnum->GetCurrent();
 978          *
 979          *      AppLog("Contact changed: type(%d), id(%d), version(%d)", pInfo->GetChangeType(), pInfo->GetContctId(), pInfo->GetVersion());
 980          *    }
 981          *    delete pEnum;
 982          *    pChangedContacts->RemoveAll(true);
 983          *    delete pChangedContacts;
 984          * }
 985          * @endcode
 986          */
 987         Tizen::Base::Collection::IList* GetChangedContactInfoListN(int version, int& latestVersion) const;
 988
 989         /**
 990          * Gets the change information of the categories that have been changed after a specified version.
 991          *
 992         * @brief <i> [Deprecated] </i>
 993         * @deprecated This method is deprecated. Instead of using this method, use GetChangedCategoryInfoListN().
 994         *
 995          * @since       2.0
 996          * @privlevel   public
 997          * @privilege   %http://tizen.org/privilege/contact.read
 998          *
 999          * @return      A list of category change information, @n
1000          *                                  else an empty list if there is no changed category, or @c null if an exception occurs (@ref CategoryChangeInfo list)
1001          *
1002          * @param[in]   version                 The change version
1003          * @param[out]  latestVersion   The latest change version among the changed categories
1004          * @exception   E_SUCCESS               The method is successful.
1005          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
1006          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
1007          * @exception   E_INVALID_ARG           The specified @c version is invalid.
1008         * @exception    E_SYSTEM                The method cannot proceed due to a severe system error.
1009          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1010         * @see GetLatestVersion()
1011         *
1012         * The following example demonstrates how to use the %GetChangedCategoriesAfterN() method.
1013         * @code
1014         * void
1015         * MyApplication::GetChangedCategories(void)
1016         * {
1017         *    IList* pChangedCategories = __pAddressbook->GetChangedCategoriesAfterN(__version, __version);
1018         *
1019         *    IEnumerator* pEnum = pChangedCategories->GetEnumeratorN();
1020         *    while (pEnum->MoveNext() == E_SUCCESS)
1021         *    {
1022         *      CategoryChangeInfo* pInfo = (CategoryChangeInfo*) pEnum->GetCurrent();
1023         *
1024         *      AppLog("Category changed: type(%d), id(%d), version(%d)", pInfo->GetChangeType(), pInfo->GetCategoryId(), pInfo->GetVersion());
1025         *    }
1026         *    delete pEnum;
1027         *    pChangedCategories->RemoveAll(true);
1028         *    delete pChangedCategories;
1029         * }
1030         * @endcode
1031         */
1032         Tizen::Base::Collection::IList* GetChangedCategoriesAfterN(int version, int& latestVersion) const;
1033
1034         /**
1035          * Gets the change information of the categories that have been changed after a specified version.
1036          *
1037          * @since       2.1
1038          * @privlevel   public
1039          * @privilege   %http://tizen.org/privilege/contact.read
1040          *
1041          * @return      A list of category change information, @n
1042          *                                  else an empty list if there is no changed category or @c null if an exception occurs (@ref CategoryChangeInfo list)
1043          *
1044          * @param[in]   version                 The change version
1045          * @param[out]  latestVersion           The latest change version among the changed categories
1046          * @exception   E_SUCCESS               The method is successful.
1047          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
1048          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method.
1049          * @exception   E_INVALID_ARG           The specified @c version is invalid.
1050          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error
1051          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1052          * @see GetLatestVersion()
1053          *
1054          * The following example demonstrates how to use the %GetChangedCategoryInfoListN() method.
1055          * @code
1056          * void
1057          * MyApplication::GetChangedCategories(void)
1058          * {
1059          *    IList* pChangedCategories = __pAddressbook->GetChangedCategoryInfoN(__version, __version);
1060          *
1061          *    IEnumerator* pEnum = pChangedCategories->GetEnumeratorN();
1062          *    while (pEnum->MoveNext() == E_SUCCESS)
1063          *    {
1064          *      CategoryChangeInfo* pInfo = (CategoryChangeInfo*) pEnum->GetCurrent();
1065          *
1066          *      AppLog("Category changed: type(%d), id(%d), version(%d)", pInfo->GetChangeType(), pInfo->GetCategoryId(), pInfo->GetVersion());
1067          *    }
1068          *    delete pEnum;
1069          *    pChangedCategories->RemoveAll(true);
1070          *    delete pChangedCategories;
1071          * }
1072          * @endcode
1073          */
1074         Tizen::Base::Collection::IList* GetChangedCategoryInfoListN(int version, int& latestVersion) const;
1075
1076         /**
1077          * Sets a user profile of this addressbook. @n
1078          * If user profile exists, removes existing user profile and adds new user profile. @n
1079          * To update the user profile, gets existing user profile and modifies the user profile and sets modified user profile. @n
1080          * To remove the user profile, @c null must be passed.
1081          *
1082          * @since                       2.1
1083          * @privlevel           public
1084          * @privilege           %http://tizen.org/privilege/userprofile.write
1085          *
1086          * @return              An error code
1087          * @param[in]           pUserProfile    The user profile to set
1088          * @exception   E_SUCCESS       The method is successful.
1089          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
1090          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method.
1091          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
1092          */
1093         result SetUserProfile(const UserProfile* pUserProfile);
1094
1095         /**
1096          * Gets a user profile of this addressbook.
1097          *
1098          * @since                       2.1
1099          * @privlevel           public
1100          * @privilege           %http://tizen.org/privilege/userprofile.read
1101          *
1102          * @return              The user profile, @n
1103          *                              else @c null if the user profile does not exist, or if an exception has occurred
1104          * @exception   E_SUCCESS       The method is successful.
1105          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
1106          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method.
1107          * @exception   E_SYSTEM        The method cannot proceed due to a severe system error.
1108          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1109          */
1110         UserProfile* GetUserProfileN(void) const;
1111
1112         /**
1113          * Checks whether the user profile of this address book has been changed after a specified version or not.
1114          * If the user profile does not exist, this method returns @c false.
1115          *
1116          * @since       2.1
1117          * @privlevel           public
1118          * @privilege   %http://tizen.org/privilege/userprofile.read
1119          *
1120          * @return     @c true if the user profile has been changed, @n
1121          *              else @c false
1122          * @param[in]   version                  The changed version
1123          * @exception   E_SUCCESS               The method is successful.
1124          * @exception   E_PRIVILEGE_DENIED     The application does not have the privilege to call this method.
1125          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method.
1126          * @exception   E_INVALID_ARG           The specified @c version is invalid.
1127          * @exception   E_SYSTEM                 The method cannot proceed due to a severe system error.
1128          * @remarks     The specific error code can be accessed using the GetLastResult() method.
1129          * @see SetUserProfile()
1130          */
1131         bool IsUserProfileChangedAfter(int version) const;
1132
1133         /**
1134          * Gets the addressbook name.
1135          *
1136          * @since       2.0
1137          *
1138          * @return              The addressbook name
1139          */
1140         Tizen::Base::String GetName(void) const;
1141
1142         /**
1143          * Gets the addressbook ID.
1144          *
1145          * @since       2.0
1146          *
1147          * @return              The addressbook ID
1148          */
1149         AddressbookId GetId(void) const;
1150
1151         /**
1152          * Gets the account ID associated with the addressbook.
1153          *
1154          * @since       2.0
1155          *
1156          * @return              The account ID
1157          */
1158         AccountId GetAccountId(void) const;
1159
1160         /**
1161         * Adds the contacts to the addressbook.
1162         *
1163         * @since                2.1
1164         * @privlevel    public
1165         * @privilege    %http://tizen.org/privilege/contact.write
1166         *
1167         * @return               An error code
1168         * @param[in]    contactList                             The contacts to add @n The list should contain the Contact instances.
1169         * @param[out]   pContactIdList                  A pointer to the list of contact IDs that have been added successfully @n Pass @c null if the contact IDs are not necessary.
1170         * @exception    E_SUCCESS                               The method is successful.
1171         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
1172         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method.
1173         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred:
1174         *                                                                                                               - The specified @c contactList is empty.
1175         *                                                                                                               - The specified @c contactList contains an empty contact.
1176         *                                                                                                               - The specified @c contactList contains a contact whose ID is not INVALID_RECORD_ID.
1177         * @exception    E_SYSTEM                                The method cannot proceed due to a severe system error.
1178         * @remarks              If an exception occurs during adding contacts, the changes are getting rollbacked. @n
1179         *                               This method blocks the execution of the calling thread until all contacts in the list has been added to the addressbook or if an exception occurs.
1180         *                               It is recommended to call this method on any thread other than the main thread.
1181         */
1182         result AddContacts(const Tizen::Base::Collection::IList& contactList, Tizen::Base::Collection::IListT<RecordId>* pContactIdList = null);
1183
1184         /**
1185         * Updates the contacts.
1186         *
1187         * @since                2.1
1188         * @privlevel    public
1189         * @privilege    %http://tizen.org/privilege/contact.write
1190         *
1191         * @return               An error code
1192         * @param[in]    contactList                             The contacts to update @n The list should contain the Contact instances.
1193         * @exception    E_SUCCESS                               The method is successful.
1194         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
1195         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method.
1196         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred:
1197         *                                                                                                               - The specified @c contactList is empty.
1198         *                                                                                                               - The specified @c contactList contains an empty contact.
1199         *                                                                                                               - The specified @c contactList contains a contact whose ID is invalid.
1200         * @exception    E_OBJ_NOT_FOUND                 The specified @c contact does not exist.
1201         * @exception    E_SYSTEM                                The method cannot proceed due to a severe system error.
1202         * @remarks              If an exception occurs during updating contacts, the changes are getting rollbacked. @n
1203         *                               This method blocks the execution of the calling thread until all contacts in the list has been updated or if an exception occurs. @n
1204         *                               It is recommended to call this method on any thread other than the main thread.
1205         */
1206         result UpdateContacts(const Tizen::Base::Collection::IList& contactList);
1207
1208         /**
1209         * Removes the contacts. @n If the contact specified by a contact ID in the list does not exist, the contact ID is ignored.
1210         *
1211         * @since                2.1
1212         * @privlevel    public
1213         * @privilege    %http://tizen.org/privilege/contact.write
1214         *
1215         * @return               An error code
1216         * @param[in]    contactIdList                   The list of contact IDs to delete
1217         * @exception    E_SUCCESS                               The method is successful.
1218         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
1219         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method.
1220         * @exception    E_INVALID_ARG                   The specified @c contactIdList is empty or contains an invalid ID.
1221         * @exception    E_SYSTEM                                The method cannot proceed due to a severe system error.
1222         * @remarks              If an exception occurs during removing contacts, the changes are getting rollbacked. @n
1223         *                               This method blocks the execution of the calling thread until all contacts in the list has been removed or if an exception occurs. @n
1224         *                               It is recommended to call this method on any thread other than the main thread.
1225         */
1226         result RemoveContacts(const Tizen::Base::Collection::IListT<RecordId>& contactIdList);
1227
1228 private:
1229         /**
1230          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
1231          *
1232          * @since       2.0
1233          */
1234         Addressbook(const Addressbook& rhs);
1235
1236         /**
1237          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
1238          *
1239          * @since       2.0
1240          */
1241         Addressbook& operator =(const Addressbook& rhs);
1242
1243 private:
1244         friend class _AddressbookImpl;
1245         class _AddressbookImpl* __pAddressbookImpl;
1246 };      // Addressbook
1247
1248 }}      // Tizen::Social
1249
1250 #endif //_FSCL_ADDRESSBOOK_H_