inc/FSclAddressbookManager.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        FSclAddressbookManager.h
  18  * @brief       This is the header file for the %AddressbookManager class.
  19  *
  20  * This header file contains the declarations of the %AddressbookManager class.
  21  */
  22 #ifndef _FSCL_ADDRESSBOOK_MANAGER_H_
  23 #define _FSCL_ADDRESSBOOK_MANAGER_H_
  24
  25 #include <unique_ptr.h>
  26 #include <FBaseTypes.h>
  27 #include <FBaseObject.h>
  28 #include <FBaseString.h>
  29 #include <FBaseByteBuffer.h>
  30 #include <FSclTypes.h>
  31
  32 namespace Tizen { namespace Base
  33 {
  34 namespace Collection
  35 {
  36 class IList;
  37 template<class Type1> class IListT;
  38 }
  39 }}
  40
  41 namespace Tizen { namespace Social
  42 {
  43 class Category;
  44 class Contact;
  45 class Person;
  46 class UserProfile;
  47 class Addressbook;
  48 class AddressbookFilter;
  49 class IAddressbookEventListener;
  50 class IAddressbookChangeEventListener;
  51
  52 /**
  53  * @class       AddressbookManager
  54  * @brief       This class manages addressbooks and contacts in the device storage.
  55  *
  56  * @since       2.0
  57  *
  58  * @final       This class is not intended for extension.
  59  *
  60  * The %AddressbookManager class provides methods for managing addressbooks and contacts in the device storage.
  61  */
  62 class _OSP_EXPORT_ AddressbookManager
  63         : public Tizen::Base::Object
  64 {
  65 public:
  66         /**
  67          * Creates an addressbook with the specified account ID and name. @n
  68          * The accountId must specify a valid account and only one addressbook can be created per account. @n
  69          * The name of the addressbook must be specified and the name must be unique among existing addressbooks on the device.
  70          *
  71          * @since       2.0
  72          * @privlevel   public
  73          * @privilege   %http://tizen.org/privilege/contact.write
  74          *
  75          * @return      An addressbook instance
  76          * @param[in]   accountId       The account ID
  77          * @param[in]   name            The addressbook name
  78          * @exception   E_SUCCESS                       The method is successful.
  79          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
  80          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
  81          * @exception   E_INVALID_ARG       Either of the following conditions has occurred:
  82          *                                                                      - The specified @c accountId is invalid.
  83          *                                                                      - The specified @c name is an empty string.
  84          * @exception   E_OBJ_ALREADY_EXIST The addressbook with the specified @c accountId or @c name already exists.
  85          * @exception   E_STORAGE_FULL          The storage is insufficient.
  86          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
  87          * @remarks             The specific error code can be accessed using the GetLastResult() method.
  88          */
  89         Addressbook* CreateAddressbookN(AccountId accountId, const Tizen::Base::String& name);
  90
  91         /**
  92          * Deletes an addressbook. @n
  93          * If the addressbook has been deleted successfully,
  94          * the contacts and categories that belong to the addressbook are also deleted.
  95          *
  96          * @since       2.0
  97          * @privlevel   public
  98          * @privilege   %http://tizen.org/privilege/contact.write
  99          *
 100          * @return      An error code
 101          * @param[in]   addressbookId   The addressbook ID
 102          * @exception   E_SUCCESS                       The method is successful.
 103          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 104          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 105          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
 106          *                                                                      - The specified @c addressbookId is invalid.
 107          *                                                                      - The addressbook specified by the @c addressbookId is a default addressbook.
 108          * @exception   E_OBJ_NOT_FOUND     The specified @c addressbookId does not exist.
 109          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 110          */
 111         result DeleteAddressbook(AddressbookId addressbookId);
 112
 113         /**
 114          * Gets the addressbooks associated with the specified account ID.
 115          *
 116          * @since       2.0
 117          * @privlevel   public
 118          * @privilege   %http://tizen.org/privilege/contact.read
 119          *
 120          * @return      The list of addressbooks, @n
 121          *                                  else an empty list if there is no addressbook, or @c null if an exception occurs (@ref Addressbook list)
 122          * @param[in]   accountId       The account ID
 123          * @exception   E_SUCCESS               The method is successful.
 124          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 125          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 126          * @exception   E_INVALID_ARG           The specified @c accountId is invalid.
 127          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 128          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 129          */
 130         Tizen::Base::Collection::IList* GetAddressbooksByAccountN(AccountId accountId) const;
 131
 132         /**
 133          * Gets the list of addressbooks.
 134          *
 135          * @since       2.0
 136          * @privlevel   public
 137          * @privilege   %http://tizen.org/privilege/contact.read
 138          *
 139          * @return      The list of addressbooks, @n
 140          *                                  else an empty list if there is no addressbook, or @c null if an exception occurs (@ref Addressbook list)
 141          * @exception   E_SUCCESS                       The method is successful.
 142          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 143          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 144          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 145          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 146          */
 147          Tizen::Base::Collection::IList* GetAllAddressbooksN(void) const;
 148
 149         /**
 150          * Gets an instance of the addressbook specified by the addressbook ID.
 151          *
 152          * @since       2.0
 153          * @privlevel   public
 154          * @privilege   %http://tizen.org/privilege/contact.read
 155          *
 156          * @return      An addressbook instance
 157          * @param[in]   addressbookId           The addressbook ID
 158          * @exception   E_SUCCESS                       The method is successful.
 159          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 160          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 161          * @exception   E_INVALID_ARG           The specified @c addressbookId is invalid.
 162          * @exception   E_OBJ_NOT_FOUND     The specified @c addressbookId does not exist.
 163          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 164          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 165          */
 166          Addressbook* GetAddressbookN(AddressbookId addressbookId = DEFAULT_ADDRESSBOOK_ID) const;
 167
 168          /**
 169           * Sets an addressbook change event listener. @n
 170           * The listener is called when a contact or a category has been changed.
 171           * To reset the event listener, @c null must be passed.
 172           *
 173           * @brief <i> [Deprecated] </i>
 174           * @deprecated This method and IAddressbookEventListener are deprecated. Instead of using this method, use SetAddressbookChangeEventListener()
 175           * and IAddressbookChangeEventListener.
 176           *
 177           * @since      2.0
 178           * @privlevel  public
 179           * @privilege  %http://tizen.org/privilege/contact.read
 180           *
 181           * @return     An error code
 182           * @param[in]  pListener       The event listener
 183           * @exception  E_SUCCESS               The method is successful.
 184           * @exception  E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 185           * @exception  E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 186           * @exception  E_SYSTEM                The method cannot proceed due to a severe system error.
 187           */
 188          result SetEventListener(IAddressbookEventListener* pListener);
 189
 190         /**
 191          * Sets an addressbook change event listener. @n
 192          * The listener is called when a contact or a category has been changed.
 193          * To reset the event listener, @c null must be passed.
 194          *
 195          * @since       2.1
 196          * @privlevel   public
 197          * @privilege   %http://tizen.org/privilege/contact.read
 198          *
 199          * @return      An error code
 200          * @param[in]   pListener       The event listener
 201          * @exception   E_SUCCESS       The method is successful.
 202          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 203          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method.
 204          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error
 205          */
 206          result SetAddressbookChangeEventListener(IAddressbookChangeEventListener* pListener);
 207
 208         /**
 209          * Adds a contact to the specified addressbook. @n
 210          * At least one property of the contact must have been set. @n
 211          * If the contact has been added successfully, a contact ID is assigned to it.
 212          *
 213          * @since       2.0
 214          * @privlevel   public
 215          * @privilege   %http://tizen.org/privilege/contact.write
 216          *
 217          * @return              An error code
 218          * @param[in,out]       contact         The contact to add
 219          * @param[in]           addressbookId   The addressbook ID
 220          * @exception   E_SUCCESS                       The method is successful.
 221          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 222          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 223          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
 224          *                                                                      - The contact ID is not #INVALID_RECORD_ID.
 225          *                                                                      - The properties of the specified @c contact have not been set.
 226          *                                                                      - The specified @c addressbookId is invalid.
 227          * @exception   E_OBJ_NOT_FOUND         The specified addressbook is not found.
 228          * @exception   E_STORAGE_FULL          The storage is insufficient.
 229          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 230          * @remarks     The #CONTACT_PROPERTY_ID_DISPLAY_NAME and #CONTACT_PROPERTY_ID_LAST_REVISION
 231          * properties cannot be set. @n #CONTACT_PROPERTY_ID_DISPLAY_NAME is automatically generated from the first name and
 232          * the last name. And #CONTACT_PROPERTY_ID_LAST_REVISION is automatically updated with the last update time.
 233          */
 234         result AddContact(Contact& contact, AddressbookId addressbookId);
 235
 236         /**
 237          * Removes a contact.
 238          *
 239          * @since       2.0
 240          * @privlevel   public
 241          * @privilege   %http://tizen.org/privilege/contact.write
 242          *
 243          * @return      An error code
 244          * @param[in]   contactId               The contact ID
 245          * @exception   E_SUCCESS                       The method is successful.
 246          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 247          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 248          * @exception   E_INVALID_ARG           The specified @c contactId is invalid.
 249          * @exception   E_OBJ_NOT_FOUND     The specified @c contactId does not exist.
 250          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 251          */
 252         result RemoveContact(RecordId contactId);
 253
 254         /**
 255          * Updates the specified contact. @n
 256          * At least one property of the contact must have been set.
 257          *
 258          * @since       2.0
 259          * @privlevel   public
 260          * @privilege   %http://tizen.org/privilege/contact.write
 261          *
 262          * @return      An error code
 263          * @param[in]   contact                 The contact to update
 264          * @exception   E_SUCCESS               The method is successful.
 265          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 266          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 267          * @exception   E_OBJ_NOT_FOUND     The specified @c contact does not exist in this address book.
 268          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
 269          *                                                                      - The specified @c contact is invalid.
 270          *                                                                      - The properties of the specified @c contact have not been set.
 271          * @exception   E_STORAGE_FULL          The storage is insufficient.
 272          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 273          */
 274         result UpdateContact(const Contact& contact);
 275
 276         /**
 277          * Adds a category to the specified addressbook. @n
 278          * The name of the category must have been set. @n
 279          * If the category has been added successfully, a category ID is assigned to it.
 280          *
 281          * @since       2.0
 282          * @privlevel   public
 283          * @privilege   %http://tizen.org/privilege/contact.write
 284          *
 285          * @return      An error code
 286          * @param[in,out]       category        The category to add
 287          * @param[in]           addressbookId   The addressbook ID
 288          * @exception   E_SUCCESS               The method is successful.
 289          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 290          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 291          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
 292          *                                                                      - The name of the category has not been set.
 293          *                                                                      - One of the member contacts is invalid.
 294          *                                                                      - The category ID of the specified @c category is not #INVALID_RECORD_ID.
 295          *                                                                      - The specified @c addressbookId is invalid.
 296          * @exception   E_STORAGE_FULL          The storage is insufficient.
 297          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 298          */
 299         result AddCategory(Category& category, AddressbookId addressbookId);
 300
 301         /**
 302          * Removes a category.
 303          *
 304          * @since       2.0
 305          * @privlevel   public
 306          * @privilege   %http://tizen.org/privilege/contact.write
 307          *
 308          * @return      An error code
 309          * @param[in]   categoryId              The category ID
 310          * @exception   E_SUCCESS                       The method is successful.
 311          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 312          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 313          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
 314          *                                                                      - The specified @c categoryId is invalid.
 315          *                                                                      - The category specified by the @c categoryId is a default category.
 316          * @exception   E_OBJ_NOT_FOUND     The specified @c categoryId does not exist in this address book.
 317          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 318          * @see Category::IsDefault()
 319          */
 320         result RemoveCategory(RecordId categoryId);
 321
 322         /**
 323          * Updates a category.
 324          *
 325          * @since       2.0
 326          * @privlevel   public
 327          * @privilege   %http://tizen.org/privilege/contact.write
 328          *
 329          * @return      An error code
 330          * @param[in]   category                The category to update
 331          * @exception   E_SUCCESS                       The method is successful.
 332          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 333          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 334          * @exception   E_OBJ_NOT_FOUND     The specified @c category does not exist in this address book.
 335          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
 336          *                                                                      - The specified @c category is invalid.
 337          *                                                                      - One of the contact members is invalid.
 338          * @exception   E_STORAGE_FULL          The storage is insufficient.
 339          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 340          */
 341         result UpdateCategory(const Category& category);
 342
 343         /**
 344          * Gets all the contacts on the device. @n
 345          * The contacts are ordered by display name.
 346          *
 347          * @since       2.0
 348          * @privlevel   public
 349          * @privilege   %http://tizen.org/privilege/contact.read
 350          *
 351          * @return              The list of contacts on the device, @n
 352          *                               else an empty list if there is no contact, or @c null if an exception occurs (@ref Contact list)
 353          * @exception   E_SUCCESS                       The method is successful.
 354          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 355          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 356          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 357          * @remarks
 358          *              - The specific error code can be accessed using the GetLastResult() method.
 359          *              - There is a high probability for an occurrence of an out-of-memory exception.
 360          *              If possible, check whether the exception is @c E_OUT_OF_MEMORY or not. @n
 361          *              For more information on how to handle the out-of-memory exception, refer
 362          *              <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
 363          */
 364         Tizen::Base::Collection::IList* GetAllContactsN(void) const;
 365
 366         /**
 367          * Gets the member contacts of the specified category. @n
 368          * If the specified @c categoryId is ::INVALID_RECORD_ID, this method returns the list of contacts that are not a member of any category.
 369          * The contacts are ordered by display name.
 370          *
 371          * @since       2.0
 372          * @privlevel   public
 373          * @privilege   %http://tizen.org/privilege/contact.read
 374          *
 375          * @return              The list of contacts that are members of the specified category, @n
 376          *                              else an empty list if there is no contact, or @c null if an exception occurs (@ref Contact list)
 377          * @param[in]   categoryId              The category ID
 378          * @exception   E_SUCCESS                       The method is successful.
 379          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 380          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 381          * @exception   E_INVALID_ARG           The specified @c categoryId is less than ::INVALID_RECORD_ID.
 382          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 383          * @remarks
 384          *              - The specific error code can be accessed using the GetLastResult() method.
 385          *              - There is a high probability for an occurrence of an out-of-memory exception.
 386          *              If possible, check whether the exception is @c E_OUT_OF_MEMORY or not. @n
 387          *              For more information on how to handle the out-of-memory exception, refer
 388          *              <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
 389          */
 390         Tizen::Base::Collection::IList* GetContactsByCategoryN(RecordId categoryId) const;
 391
 392         /**
 393          * Gets the contacts linked to the person specified by the person ID.
 394          *
 395          * @since       2.0
 396          * @privlevel   public
 397          * @privilege   %http://tizen.org/privilege/contact.read
 398          *
 399          * @return      The list of contacts that are linked to this person, @n
 400          *              else @c null if an exception occurs (@ref Contact list)
 401          * @param[in]   personId                The person ID
 402          * @exception   E_SUCCESS               The method is successful.
 403          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 404          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 405          * @exception   E_INVALID_ARG           The specified @c personId is invalid.
 406          * @exception   E_SYSTEM      The method cannot proceed due to a severe system error.
 407          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 408          */
 409         Tizen::Base::Collection::IList* GetContactsByPersonN(PersonId personId) const;
 410
 411         /**
 412          * Gets the categories whose member is the person specified by the person ID. @n
 413          * A person is a member of a category if a contact linked to it is a member of the category.
 414          * The categories are ordered by name.
 415          *
 416          * @since       2.0
 417          * @privlevel   public
 418          * @privilege   %http://tizen.org/privilege/contact.read
 419          *
 420          * @return      The list of categories that has the specified person as a member, @n
 421          *              else an empty list if there is no category, or @c null if an exception occurs (@ref Category list)
 422          * @param[in]   personId                The person ID
 423          * @exception   E_SUCCESS               The method is successful.
 424          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 425          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 426          * @exception   E_INVALID_ARG           The specified @c personId is invalid.
 427          * @exception   E_SYSTEM      The method cannot proceed due to a severe system error.
 428          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 429          */
 430         Tizen::Base::Collection::IList* GetCategoriesByPersonN(PersonId personId) const;
 431
 432         /**
 433          * Gets the contact with the specified contact ID.
 434          *
 435          * @since       2.0
 436          * @privlevel   public
 437          * @privilege   %http://tizen.org/privilege/contact.read
 438          *
 439          * @return              The matched contact, @n
 440          *                              else @c null if no contact matches the specified contact ID
 441          * @param[in]   contactId               The contact ID
 442          * @exception   E_SUCCESS                       The method is successful.
 443          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 444          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 445          * @exception   E_INVALID_ARG           The specified @c contactId is invalid.
 446          * @exception   E_OBJ_NOT_FOUND         The specified @c contactId is not found.
 447          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 448          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 449          */
 450         Contact* GetContactN(RecordId contactId) const;
 451
 452         /**
 453          * Gets the number of contacts in all the addressbooks.
 454          *
 455          * @since       2.0
 456          * @privlevel   public
 457          * @privilege   %http://tizen.org/privilege/contact.read
 458          *
 459          * @return              The number of contacts in the address book, @n
 460          *                              else @c -1 if an error occurs
 461          * @exception   E_SUCCESS                       The method is successful.
 462          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 463          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 464          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 465          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 466          */
 467         int GetContactCount(void) const;
 468
 469         /**
 470          * Adds the specified contact to the specified category.
 471          *
 472          * @since       2.0
 473          * @privlevel   public
 474          * @privilege   %http://tizen.org/privilege/contact.write
 475          *
 476          * @return      An error code
 477          * @param [in]  categoryId              The category ID
 478          * @param [in]  contactId               The contact ID
 479          * @exception   E_SUCCESS                       The method is successful.
 480          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 481          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 482          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
 483          *                                                                      - The specified contact or category does not exist.
 484          *                                                                      - The specified contact and category are not in the same addressbook.
 485          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 486          * @remarks If the contact is already a member of the category, this method does nothing.
 487          */
 488         result AddMemberToCategory(RecordId categoryId, RecordId contactId);
 489
 490         /**
 491          * Removes the specified contact from the specified category.
 492          *
 493          * @since       2.0
 494          * @privlevel   public
 495          * @privilege   %http://tizen.org/privilege/contact.write
 496          *
 497          * @return      An error code
 498          * @param [in]  categoryId              The category ID
 499          * @param [in]  contactId               The contact ID
 500          * @exception   E_SUCCESS                       The method is successful.
 501          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 502          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 503          * @exception   E_INVALID_ARG           The specified contact or category does not exist.
 504          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 505          * @remarks If the contact is not a member of the category, this method does nothing.
 506          */
 507         result RemoveMemberFromCategory(RecordId categoryId, RecordId contactId);
 508
 509         /**
 510          * Gets all the categories on the device. @n
 511          * The categories are ordered by name.
 512          *
 513          * @since       2.0
 514          * @privlevel   public
 515          * @privilege   %http://tizen.org/privilege/contact.read
 516          *
 517          * @return              The list of categories on the device, @n
 518          *                              else an empty list if there is no category, or @c null if an exception occurs (@ref Category list)
 519          * @exception   E_SUCCESS                       The method is successful.
 520          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 521          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 522          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 523          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 524          */
 525         Tizen::Base::Collection::IList* GetAllCategoriesN(void) const;
 526
 527         /**
 528          * Gets all the categories whose member is the specified contact. @n
 529          * The categories are ordered by name.
 530          *
 531          * @since       2.0
 532          * @privlevel   public
 533          * @privilege   %http://tizen.org/privilege/contact.read
 534          *
 535          * @return              The list of categories that has the specified contact as a member, @n
 536          *                              else an empty list if there is no category, or @c null if an exception occurs (@ref Category list)
 537          * @param[in] contactId         The contact ID
 538          * @exception   E_SUCCESS                       The method is successful.
 539          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 540          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 541          * @exception   E_INVALID_ARG           The specified @c contactId is invalid.
 542          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 543          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 544          */
 545         Tizen::Base::Collection::IList* GetCategoriesByContactN(RecordId contactId) const;
 546
 547         /**
 548          * Gets the number of categories on the device.
 549          *
 550          * @since       2.0
 551          * @privlevel   public
 552          * @privilege   %http://tizen.org/privilege/contact.read
 553          *
 554          * @return              The number of categories on the device, @n
 555          *                              else @c -1 if an error occurs
 556          * @exception   E_SUCCESS                   The method is successful.
 557          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 558          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 559          * @exception   E_SYSTEM                    The method cannot proceed due to a severe system error.
 560          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 561          */
 562         int GetCategoryCount(void) const;
 563
 564         /**
 565          * Gets the category with the specified category ID.
 566          *
 567          * @since       2.0
 568          * @privlevel   public
 569          * @privilege   %http://tizen.org/privilege/contact.read
 570          *
 571          * @return              The matched category, @n
 572          *                              else @c null if no category matches the specified category ID
 573          * @param[in]   categoryId              The category ID
 574          * @exception   E_SUCCESS                       The method is successful.
 575          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 576          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 577          * @exception   E_INVALID_ARG           The specified @c categoryId is invalid.
 578          * @exception   E_OBJ_NOT_FOUND     The specified record is not found.
 579          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 580          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 581          */
 582         Category* GetCategoryN(RecordId categoryId) const;
 583
 584         /**
 585          * Searches the contacts whose email address contains the specified @c email string. @n
 586          * The search operation is performed with a case insensitive key (param: @c email). @n
 587          * The contacts are ordered by display name.
 588          *
 589          * @since       2.0
 590          * @privlevel   public
 591          * @privilege   %http://tizen.org/privilege/contact.read
 592          *
 593          * @return      The list of all matched contacts, @n
 594          *                              else an empty list if there is no matched contact, or @c null if an exception occurs (@ref Contact list)
 595          * @param[in]   email                   The substring of the email to search
 596          * @exception   E_SUCCESS                       The method is successful.
 597          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 598          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 599          * @exception   E_INVALID_ARG           The specified @c email is an empty string.
 600          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 601          * @remarks
 602          *              - The specific error code can be accessed using the GetLastResult() method.
 603          *              - There is a high probability for an occurrence of an out-of-memory exception.
 604          *              If possible, check whether the exception is @c E_OUT_OF_MEMORY or not. @n
 605          *              For more information on how to handle the out-of-memory exception, refer
 606          *              <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
 607          */
 608         Tizen::Base::Collection::IList* SearchContactsByEmailN(const Tizen::Base::String& email) const;
 609
 610         /**
 611          * Searches the contacts that have the specified @c name as a substring of their display name. @n
 612          * The display name is a concatenation of the first name, space, and the last name. @n
 613          * The search operation is performed with a case insensitive key (param: @c name). @n
 614          * The contacts are ordered by display name.
 615          *
 616          * @since       2.0
 617          * @privlevel   public
 618          * @privilege   %http://tizen.org/privilege/contact.read
 619          *
 620          * @return      The list of all matched contacts, @n
 621          *                              else an empty list if there is no matched contact, or @c null if an exception occurs (@ref Contact list)
 622          * @param[in]   name                    The substring of the name to search
 623          * @exception   E_SUCCESS                       The method is successful.
 624          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 625          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 626          * @exception   E_INVALID_ARG           The specified @c name is an empty string.
 627          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 628          * @remarks
 629          *              - The specific error code can be accessed using the GetLastResult() method.
 630          *              - There is a high probability for an occurrence of an out-of-memory exception.
 631          *              If possible, check whether the exception is @c E_OUT_OF_MEMORY or not. @n
 632          *              For more information on how to handle the out-of-memory exception, refer
 633          *              <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
 634          */
 635         Tizen::Base::Collection::IList* SearchContactsByNameN(const Tizen::Base::String& name) const;
 636
 637         /**
 638          * Searches the contacts that have the specified @c phoneNumber string as a substring of one of their phone numbers. @n
 639          * This method returns the contacts whose phone number match the value of the specified @c phoneNumber. @n
 640          * The search operation is performed with a case insensitive key (param: @c phoneNumber). @n
 641          * The contacts are ordered by display name.
 642          *
 643          * @since       2.0
 644          * @privlevel   public
 645          * @privilege   %http://tizen.org/privilege/contact.read
 646          *
 647          * @return      The list of all matched contacts, @n
 648          *                                  else an empty list if there is no contact, or @c null if an exception occurs (@ref Contact list)
 649          * @param[in]   phoneNumber             The substring of the phone number to search
 650          * @exception   E_SUCCESS               The method is successful.
 651          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 652          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 653          * @exception   E_INVALID_ARG           The specified @c phoneNumber is an empty string.
 654          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
 655          * @remarks
 656          *              - The specific error code can be accessed using the GetLastResult() method.
 657          *              - There is a high probability for an occurrence of an out-of-memory exception.
 658          *              If possible, check whether the exception is @c E_OUT_OF_MEMORY or not. @n
 659          *              For more information on how to handle the out-of-memory exception, refer
 660          *              <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
 661          */
 662         Tizen::Base::Collection::IList* SearchContactsByPhoneNumberN(const Tizen::Base::String& phoneNumber) const;
 663
 664         /**
 665          * Gets the latest change version.
 666          *
 667          * @since       2.0
 668          * @privlevel   public
 669          * @privilege   %http://tizen.org/privilege/contact.read
 670          *
 671          * @return              The latest change version, @n
 672          *                              else @c -1 if an exception occurs
 673          * @exception   E_SUCCESS                       The method is successful.
 674          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 675          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 676          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 677          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 678          * @see GetChangedContactsAfterN()
 679          * @see GetChangedCategoriesAfterN()
 680          */
 681         int GetLatestVersion(void) const;
 682
 683         /**
 684          * Gets the change information of the contacts that have been changed after the specified change version.
 685          *
 686          * @brief <i> [Deprecated] </i>
 687          * @deprecated This method is deprecated.
 688          *
 689          * @since       2.0
 690          * @privlevel   public
 691          * @privilege   %http://tizen.org/privilege/contact.read
 692          *
 693          * @return      The list of contact change information, @n
 694          *                                  else an empty list if there is no changed contact, or @c null if an exception occurs (@ref ContactChangeInfo list)
 695          * @param[in]   version                 The change version
 696          * @param[out]  latestVersion   The latest change version among the changed contacts
 697          * @exception   E_SUCCESS                       The method is successful.
 698          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 699          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 700          * @exception   E_INVALID_ARG           The specified @c version is invalid.
 701          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 702          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 703          * @see GetLatestVersion()
 704          * @see ContactChangeInfo
 705          *
 706          * The following example demonstrates how to use the %GetChangedContactsAfterN() method.
 707          * @code
 708          * void
 709          * MyApplication::PrintChangedContacts(void)
 710          * {
 711          *    IList* pChangedContacts = __pAddressbookManager->GetChangedContactsAfterN(__version, __version);
 712          *
 713          *    IEnumerator* pEnum = pChangedContacts->GetEnumeratorN();
 714          *    while (pEnum->MoveNext() == E_SUCCESS)
 715          *    {
 716          *      ContactChangeInfo* pInfo = static_cast<ContactChangeInfo*>(pEnum->GetCurrent());
 717          *
 718          *      AppLog("Contact changed: type(%d), id(%d), version(%d)", pInfo->GetChangeType(), pInfo->GetContctId(), pInfo->GetVersion());
 719          *    }
 720          *    delete pEnum;
 721          *    pChangedContacts->RemoveAll(true);
 722          *    delete pChangedContacts;
 723          * }
 724          * @endcode
 725          */
 726         Tizen::Base::Collection::IList* GetChangedContactsAfterN(int version, int& latestVersion) const;
 727
 728         /**
 729          * Gets the change information of the categories that have been changed after the specified change version.
 730          *
 731          * @brief <i> [Deprecated] </i>
 732          * @deprecated This method is deprecated.
 733          *
 734          * @since       2.0
 735          * @privlevel   public
 736          * @privilege   %http://tizen.org/privilege/contact.read
 737          *
 738          * @return              The list of category change information, @n
 739          *                              else an empty list if there is no changed category, or @c null if an exception occurs (@ref CategoryChangeInfo list)
 740          * @param[in]   version                         The change version
 741          * @param[out]  latestVersion           The latest change version among the changed categories
 742          * @exception   E_SUCCESS                       The method is successful.
 743          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 744          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 745          * @exception   E_INVALID_ARG           The specified @c version is invalid.
 746          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 747          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 748          * @see GetLatestVersion()
 749          * @see CategoryChangeInfo
 750          *
 751          * The following example demonstrates how to use the %GetChangedCategoriesAfterN() method.
 752          * @code
 753          * void
 754          * MyApplication::PrintChangedCategories(void)
 755          * {
 756          *    IList* pChangedCategories = __pAddressbookManager->GetChangedCategoriesAfterN(__version, __version);
 757          *
 758          *    IEnumerator* pEnum = pChangedCategories->GetEnumeratorN();
 759          *    while (pEnum->MoveNext() == E_SUCCESS)
 760          *    {
 761          *      CategoryChangeInfo* pInfo = static_cast<CategoryChangeInfo*>(pEnum->GetCurrent());
 762          *
 763          *      AppLog("Category changed: type(%d), id(%d), version(%d)", pInfo->GetChangeType(), pInfo->GetCategoryId(), pInfo->GetVersion());
 764          *    }
 765          *    delete pEnum;
 766          *    pChangedCategories->RemoveAll(true);
 767          *    delete pChangedCategories;
 768          * }
 769          * @endcode
 770          */
 771         Tizen::Base::Collection::IList* GetChangedCategoriesAfterN(int version, int& latestVersion) const;
 772
 773         /**
 774          * Gets the person with the specified person ID.
 775          *
 776          * @since       2.0
 777          * @privlevel   public
 778          * @privilege   %http://tizen.org/privilege/contact.read
 779          *
 780          * @return      The matched person, @n
 781          *                              else @c null if an exception occurs
 782          * @param[in]   personId                The person ID
 783          * @exception   E_SUCCESS               The method is successful.
 784          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 785          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 786          * @exception   E_INVALID_ARG           The specified @c personId is invalid.
 787          * @exception   E_OBJ_NOT_FOUND         The specified @c personId is not found.
 788          * @exception   E_SYSTEM      The method cannot proceed due to a severe system error.
 789          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 790          */
 791         Person* GetPersonN(PersonId personId) const;
 792
 793         /**
 794          * Removes a person. @n
 795          * All the contacts linked to the person are removed, too.
 796          *
 797          * @since       2.0
 798          * @privlevel   public
 799          * @privilege   %http://tizen.org/privilege/contact.write
 800          *
 801          * @return      An error code
 802          * @param[in]   personId                The person ID
 803          * @exception   E_SUCCESS               The method is successful.
 804          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 805          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 806          * @exception   E_INVALID_ARG           The specified @c personId is invalid.
 807          * @exception   E_OBJ_NOT_FOUND         The specified person does not exist.
 808          * @exception   E_SYSTEM      The method cannot be proceed due to a severe system error.
 809          */
 810         result RemovePerson(PersonId personId);
 811
 812         /**
 813          * Gets all persons on the device. @n
 814          * The persons are ordered by display name.
 815          *
 816          * @since       2.0
 817          * @privlevel   public
 818          * @privilege   %http://tizen.org/privilege/contact.read
 819          *
 820          * @return      The list of all persons on the device, @n
 821          *              else an empty list if there is no person, or @c null if an exception occurs (@ref Person list)
 822          * @exception   E_SUCCESS              The method is successful.
 823          * @exception   E_PRIVILEGE_DENIED     The application does not have the privilege to call this method.
 824          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 825          * @exception   E_SYSTEM      The method cannot be 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.
 829          *              If possible, check whether the exception is @c E_OUT_OF_MEMORY or not. @n
 830          *              For more information on how to handle the out-of-memory exception, refer
 831          *              <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
 832          */
 833         Tizen::Base::Collection::IList* GetAllPersonsN(void) const;
 834
 835         /**
 836          * Gets the persons that are members of the specified category where a person is a member of a category if a contact linked to it is a member of the category. @n
 837          * If the specified @c categoryId is ::INVALID_RECORD_ID, this method returns the persons that are not members of any category. @n
 838          * The persons are ordered by display name.
 839          *
 840          * @since       2.0
 841          * @privlevel   public
 842          * @privilege   %http://tizen.org/privilege/contact.read
 843          *
 844          * @return      The list of persons that are members of the specified category, @n
 845          *              else an empty list if there is no person, or @c null if an exception occurs (@ref Person list)
 846          * @param[in]   categoryId              The category ID
 847          * @exception   E_SUCCESS               The method is successful.
 848          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 849          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 850          * @exception   E_INVALID_ARG           The specified @c categoryId is invalid.
 851          * @exception   E_OBJ_NOT_FOUND         The specified category does not exist.
 852          * @exception   E_SYSTEM      The method cannot proceed due to a severe system error.
 853          * @remarks
 854          *              - The specific error code can be accessed using the GetLastResult() method.
 855          *              - There is a high probability for an occurrence of an out-of-memory exception.
 856          *              If possible, check whether the exception is @c E_OUT_OF_MEMORY or not. @n
 857          *              For more information on how to handle the out-of-memory exception, refer
 858          *              <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
 859          */
 860         Tizen::Base::Collection::IList* GetPersonsByCategoryN(RecordId categoryId) const;
 861
 862         /**
 863          * Gets the list of favorite persons. @n
 864          * The persons are ordered by display name.
 865          *
 866          * @since       2.0
 867          * @privlevel   public
 868          * @privilege   %http://tizen.org/privilege/contact.read
 869          *
 870          * @return      The list of favorite persons, @n
 871          *              else an empty list if there is no favorite person, or @c null if an exception occurs (@ref Person list)
 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 has blocked the application from calling this method. @b Since: @b 2.1
 875          * @exception   E_SYSTEM      The method cannot proceed due to a severe system error.
 876          * @remarks
 877          *              - The specific error code can be accessed using the GetLastResult() method.
 878          *              - There is a high probability for an occurrence of an out-of-memory exception.
 879          *              If possible, check whether the exception is @c 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          * @see SetPersonAsFavorite()
 883          */
 884         Tizen::Base::Collection::IList* GetFavoritePersonsN(void) const;
 885
 886         /**
 887          * Searches the persons that contain the specified @c keyword string in its properties. @n
 888          * The search operation is performed with a case insensitive key (param: @c keyword). @n
 889          * The persons are ordered by display name.
 890          *
 891          * @since       2.0
 892          * @privlevel   public
 893          * @privilege   %http://tizen.org/privilege/contact.read
 894          *
 895          * @return      The list of all matched persons, @n
 896          *              else an empty list if there is no matched person, or @c null if an exception occurs (@ref Person list)
 897          * @param[in]   keyword                 The key to search
 898          * @exception   E_SUCCESS               The method is successful.
 899          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 900          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 901          * @exception   E_INVALID_ARG           The specified @c keyword is an empty string.
 902          * @exception   E_SYSTEM      The method cannot proceed due to a severe system error.
 903          * @remarks
 904          *              - The specific error code can be accessed using the GetLastResult() method.
 905          *              - There is a high probability for an occurrence of an out-of-memory exception.
 906          *              If possible, check whether the exception is @c E_OUT_OF_MEMORY or not. @n
 907          *              For more information on how to handle the out-of-memory exception, refer
 908          *              <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
 909          */
 910         Tizen::Base::Collection::IList* SearchPersonsN(const Tizen::Base::String& keyword) const;
 911
 912         /**
 913          * Sets whether the specified person is a favorite or not.
 914          *
 915          * @since       2.0
 916          * @privlevel   public
 917          * @privilege   %http://tizen.org/privilege/contact.write
 918          *
 919          * @return      An error code
 920          * @param[in]   personId                        The person ID
 921          * @param[in]   isFavorite                      Set to @c true to set the specified person as a favorite, @n
 922          *                                              else @c false to set the specified person as a non-favorite
 923          * @exception   E_SUCCESS               The method is successful.
 924          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 925          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 926          * @exception   E_INVALID_ARG           The specified @c personId is invalid.
 927          * @exception   E_OBJ_NOT_FOUND         The specified person does not exist.
 928          * @exception   E_SYSTEM      The method cannot proceed due to a severe system error.
 929          * @see GetFavoritePersonsN()
 930          * @see Person::IsFavorite()
 931          */
 932         result SetPersonAsFavorite(PersonId personId, bool isFavorite = true);
 933
 934         /**
 935          * Merges the source person with the target person. @n
 936          * The following are done during merging:
 937          *      - Unlinks the contacts linked to the source person.
 938          *      - Links the unlinked contacts to the target person.
 939          *      - Removes the source person.
 940          *      - Updates information of the target person.
 941          *
 942          * The %MergePersons() method does nothing if the source or target person does not exist.
 943          *
 944          * @since       2.0
 945          * @privlevel   public
 946          * @privilege   %http://tizen.org/privilege/contact.write
 947          *
 948          * @return      An error code
 949          * @param[in]   sourcePersonId          The source person ID
 950          * @param[in]   targetPersonId          The target person ID
 951          * @exception   E_SUCCESS               The method is successful.
 952          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 953          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 954          * @exception   E_INVALID_ARG           The specified @c sourcePersonId or @c targetPersonId is invalid.
 955          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 956          */
 957         result MergePersons(PersonId sourcePersonId, PersonId targetPersonId);
 958
 959         /**
 960          * Unlinks the specified contact from the specified person. @n
 961          * The following are done during unlinking:
 962          *      - Unlinks the contact specified by @c contactId.
 963          *      - Creates a new person.
 964          *      - Links the unlinked contact to the new person.
 965          *      - Updates information of a person.
 966          *
 967          * It is not allowed to unlink a contact if it is the only one contact linked to a person.
 968          * The %UnlinkContact() method does nothing if the contact has not been linked to the person or does not exist.
 969          *
 970          * @since       2.0
 971          * @privlevel   public
 972          * @privilege   %http://tizen.org/privilege/contact.write
 973          *
 974          * @return      An error code
 975          * @param[in]   personId                The ID of the person that the contact is unlinked from
 976          * @param[in]   contactId               The contact to unlink
 977          * @param[out]  newPersonId             The ID of the new person
 978          * @exception   E_SUCCESS               The method is successful.
 979          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 980          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 981          * @exception   E_INVALID_ARG           The specified @c personId or @c contactId is invalid.
 982          * @exception   E_SYSTEM      The method cannot proceed due to a severe system error.
 983          */
 984         result UnlinkContact(PersonId personId, RecordId contactId, PersonId& newPersonId);
 985
 986         /**
 987          * Searches items of the addressbook with the filter. @n
 988          * The filter specifies the item type and condition for searching.
 989          * The searched results are ordered by the @c propertyToSort and @c sortOrder.
 990          * If the @c offset is M and the @c maxCount are N, then the first M items are omitted from the result set returned by the searching operation and the next N items are returned.
 991          *
 992          * @since       2.0
 993          * @privlevel   public
 994          * @privilege    %http://tizen.org/privilege/contact.read
 995          *
 996          * @return       The list of searched results (The list of Addressbook, Person, Contact, Category, PhoneNumberContact, EmailContact), @n
 997          *                 else an empty list if there is no searched result, or @c null if an exception occurs
 998          * @param[in]    filter                 The filter that specifies the search condition @n If the filter is empty, all items that are specified by the type of this filter are searched.
 999          * @param[in]    propertyToSort         The property for sorting @n The searched results are ordered by the values of this property.
1000          * @param[in]    sortOrder              The order for sorting
1001          * @param[in]    offset                 The offset of the searched results @n If this value is @c 0, it is ignored.
1002          * @param[in]    maxCount               The maximum count of the searched results @n If this value is @c 0, it is ignored.
1003          * @exception    E_SUCCESS              The method is successful.
1004          * @exception    E_PRIVILEGE_DENIED     The application does not have the privilege to call this method.
1005          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
1006          * @exception    E_INVALID_ARG          Either of the following conditions has occurred:
1007          *                                                      - The specified @c offset or @c maxCount is less than @c 0.
1008          *                                                      - The specified @c propertyToSort is not an element of the enumerator that corresponds to the type of the @c filter.
1009          * @exception    E_SYSTEM                The method cannot proceed due to a severe system error.
1010          * @remarks
1011          *              - The specific error code can be accessed using the GetLastResult() method.
1012          *              - There is a high probability for an occurrence of an out-of-memory exception.
1013          *              If possible, check whether the exception is @c E_OUT_OF_MEMORY or not. @n
1014          *              For more information on how to handle the out-of-memory exception, refer
1015          *              <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
1016          * @see AddressbookFilterProperty
1017          * @see PersonFilterProperty
1018          * @see ContactFilterProperty
1019          * @see CategoryFilterProperty
1020          * @see PhoneContactFilterProperty
1021          * @see EmailContactFilterProperty
1022          */
1023         Tizen::Base::Collection::IList* SearchN(const AddressbookFilter& filter,
1024                         unsigned long propertyToSort = 0, Tizen::Base::SortOrder sortOrder = Tizen::Base::SORT_ORDER_NONE, int offset = 0, int maxCount = 0);
1025
1026         /**
1027          * Gets the matched item count of the search results with the filter. @n
1028          * The filter specifies the item type and condition for searching.
1029          *
1030          * @since       2.0
1031          * @privlevel   public
1032          * @privilege    %http://tizen.org/privilege/contact.read
1033          *
1034          * @return       The count of the searched results
1035          * @param[in]    filter                  The filter that specifies the search condition @n If the filter is empty, all items that are specified by the type of this filter are searched.
1036          * @exception    E_SUCCESS               The method is successful.
1037          * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
1038          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
1039          * @exception    E_SYSTEM                The method cannot proceed due to a severe system error.
1040          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1041          * @see AddressbookFilterProperty
1042          * @see PersonFilterProperty
1043          * @see ContactFilterProperty
1044          * @see CategoryFilterProperty
1045          * @see PhoneContactFilterProperty
1046          * @see EmailContactFilterProperty
1047          */
1048         int GetMatchedItemCount(const AddressbookFilter& filter);
1049
1050         /**
1051          * Parses contacts from the specified vCard file. @n
1052          * The %ParseContactsFromVcardN() method supports vCard formation 2.1 and 3.0.
1053          *
1054          * @since       2.0
1055          *
1056          * @return      The list of contacts, @n
1057          *              else an empty list if there is no contact, or @c null if an exception occurs (@ref Contact list)
1058          * @param[in]   vcardPath               The file path of a vCard file
1059          * @exception   E_SUCCESS               The method is successful.
1060          * @exception   E_INVALID_ARG           The specified @c vcardPath is invalid.
1061          * @exception   E_ILLEGAL_ACCESS        The access is denied due to insufficient permission.
1062          * @exception   E_FILE_NOT_FOUND        The specified file cannot be found.
1063          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
1064          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1065          */
1066         Tizen::Base::Collection::IList* ParseContactsFromVcardN(const Tizen::Base::String& vcardPath);
1067
1068         /**
1069          * Exports a person to the specified vCard 3.0 file.
1070          *
1071          * @since       2.0
1072          * @privlevel   public
1073          * @privilege   %http://tizen.org/privilege/contact.read
1074          *
1075          * @return      An error code
1076          * @param[in]   person                  The person to export
1077          * @param[in]   vcardPath               The file path of a vCard file
1078          * @exception   E_SUCCESS               The method is successful.
1079          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
1080          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
1081          * @exception   E_INVALID_ARG           The specified @c person is invalid.
1082          * @exception   E_ILLEGAL_ACCESS        The access is denied due to insufficient permission.
1083          * @exception   E_FILE_ALREADY_EXIST    The specified file already exists.
1084          * @exception   E_STORAGE_FULL                  The storage is insufficient.
1085          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
1086          */
1087         result ExportPersonToVcard(const Person& person, const Tizen::Base::String& vcardPath);
1088
1089         /**
1090          * Exports a person list to the specified vCard 3.0 file.
1091          *
1092          * @since       2.0
1093          * @privlevel   public
1094          * @privilege   %http://tizen.org/privilege/contact.read
1095          *
1096          * @return      An error code
1097          * @param[in]   personList              The person list to export @n The list should contain the Person instances.
1098          * @param[in]   vcardPath               The file path of a vCard file
1099          * @exception   E_SUCCESS               The method is successful.
1100          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
1101          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
1102          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
1103          *                                                      - The specified @c personList is invalid.
1104          *                                                      - The specified @c vcardPath is invalid.
1105          * @exception   E_ILLEGAL_ACCESS        The access is denied due to insufficient permission.
1106          * @exception   E_FILE_ALREADY_EXIST    The specified file already exists.
1107          * @exception   E_STORAGE_FULL                  The storage is insufficient.
1108          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
1109          */
1110         result ExportPersonsToVcard(const Tizen::Base::Collection::IList& personList, const Tizen::Base::String& vcardPath);
1111
1112         /**
1113          * Exports a contact to the specified vCard 3.0 file.
1114          *
1115          * @since       2.0
1116          *
1117          * @return      An error code
1118          * @param[in]   contact                 The contact to export
1119          * @param[in]   vcardPath               The file path of a vCard file
1120          * @exception   E_SUCCESS               The method is successful.
1121          * @exception   E_INVALID_ARG           The specified @c contact is invalid.
1122          * @exception   E_ILLEGAL_ACCESS        The access is denied due to insufficient permission.
1123          * @exception   E_FILE_ALREADY_EXIST    The specified file already exists.
1124          * @exception   E_STORAGE_FULL                  The storage is insufficient.
1125          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
1126          */
1127         result ExportContactToVcard(const Contact& contact, const Tizen::Base::String& vcardPath);
1128
1129         /**
1130          * Exports a contact list to the specified vCard 3.0 file.
1131          *
1132          * @since       2.0
1133          *
1134          * @return      An error code
1135          * @param[in]   contactList             The contact list to export @n The list should contain Contact instances.
1136          * @param[in]   vcardPath               The file path of a vCard file
1137          * @exception   E_SUCCESS               The method is successful.
1138          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
1139          *                                                      - The specified @c contactList is invalid.
1140          *                                                      - The specified @c vcardPath is invalid.
1141          * @exception   E_ILLEGAL_ACCESS        The access is denied due to insufficient permission.
1142          * @exception   E_FILE_ALREADY_EXIST    The specified file already exists.
1143          * @exception   E_STORAGE_FULL                  The storage is insufficient.
1144          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
1145          */
1146         result ExportContactsToVcard(const Tizen::Base::Collection::IList& contactList, const Tizen::Base::String& vcardPath);
1147
1148         /**
1149         * Exports a contact to a vCard format stream.
1150         *
1151         * @since        2.1
1152         *
1153         * @return               The exported vcard stream, @n
1154         *                               else @c null if an exception occurs
1155         * @param[in]    contact                 The contact to export
1156         * @exception    E_SUCCESS               The method is successful.
1157         * @exception    E_INVALID_ARG           The specified @c contact is invalid.
1158         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
1159         * @remarks              The specific error code can be accessed using the GetLastResult() method.
1160         * @see ExportContactToVcard()
1161         */
1162         Tizen::Base::ByteBuffer*  ExportContactToVcardStreamN(const Contact& contact);
1163
1164         /**
1165         * Exports a contact list to a vCard format stream.
1166         *
1167         * @since        2.1
1168         *
1169         * @return               The exported vcard stream, @n
1170         *                               else @c null if an exception occurs
1171         * @param[in]    contactList             The contact list to export @n The list should contain the Contact instances
1172         * @exception    E_SUCCESS               The method is successful.
1173         * @exception    E_INVALID_ARG           The specified @c contactList contains an invalid contact.
1174         * @exception    E_SYSTEM      The method cannot proceed due to a severe system error.
1175         * @remarks              The specific error code can be accessed using the GetLastResult() method.
1176         * @see ExportContactsToVcard()
1177         */
1178         Tizen::Base::ByteBuffer* ExportContactsToVcardStreamN(const Tizen::Base::Collection::IList& contactList);
1179
1180         /**
1181         * Exports a person to a vCard format stream.
1182         *
1183         * @since        2.1
1184         * @privlevel    public
1185         * @privilege    %http://tizen.org/privilege/contact.read
1186         *
1187         * @return               The exported vcard stream, @n
1188         *                               else @c null if an exception occurs
1189         * @param[in]    person                  The person to export
1190         * @exception    E_SUCCESS               The method is successful.
1191         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
1192         * @exception    E_USER_NOT_CONSENTED    The user has blocked the application from calling this method.
1193         * @exception    E_INVALID_ARG           The specified @c person is invalid.
1194         * @exception    E_SYSTEM      The method cannot proceed due to a severe system error.
1195         * @remarks              The specific error code can be accessed using the GetLastResult() method.
1196         * @see ExportPersonToVcard()
1197         */
1198         Tizen::Base::ByteBuffer* ExportPersonToVcardStreamN(const Person& person);
1199
1200         /**
1201         * Exports a person list to a vCard format stream.
1202         *
1203         * @since        2.1
1204         * @privlevel    public
1205         * @privilege    %http://tizen.org/privilege/contact.read
1206         *
1207         * @return               The exported vcard stream, @n
1208         *                               else @c null if an exception occurs
1209         * @param[in]    personList              The person list to export @n The list should contain the Person instances.
1210         * @exception    E_SUCCESS               The method is successful.
1211         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
1212         * @exception    E_USER_NOT_CONSENTED    The user has blocked the application from calling this method.
1213         * @exception    E_INVALID_ARG           The specified @c personList contains invalid person.
1214         * @exception    E_SYSTEM      The method cannot proceed due to a severe system error.
1215         * @remarks              The specific error code can be accessed using the GetLastResult() method.
1216         * @see ExportPersonsToVcard()
1217         */
1218         Tizen::Base::ByteBuffer* ExportPersonsToVcardStreamN(const Tizen::Base::Collection::IList& personList);
1219
1220         /**
1221         * Parses contacts from the specified vCard stream. @n
1222         * The %ParseVcardStreamN() method supports vCard formation 2.1 and 3.0.
1223         *
1224         * @since        2.1
1225         *
1226         * @return               The list of contacts, @n
1227         *                               else an empty list if there is no contact, or @c null if an exception occurs (@ref Contact list)
1228         * @param[in]    vcardStream             The vCard stream
1229         * @exception    E_SUCCESS               The method is successful.
1230         * @exception    E_INVALID_ARG           The specified @c vcardStream is invalid.
1231         * @exception    E_SYSTEM      The method cannot proceed due to a severe system error.
1232         * @remarks              The specific error code can be accessed using the GetLastResult() method.
1233         * @see ParseContactsFromVcardN()
1234         */
1235         Tizen::Base::Collection::IList* ParseVcardStreamN(const Tizen::Base::ByteBuffer& vcardStream);
1236
1237         /**
1238          * Exports a user profile to a vCard format stream.
1239          *
1240          * @since       2.1
1241          *
1242          * @return      The exported vCard stream, @n
1243          *               else @c null if an exception occurs
1244          * @param[in]   userProfile             The user profile to export
1245          * @exception   E_SUCCESS               The method is successful.
1246          * @exception   E_INVALID_ARG           The specified @c userProfile is invalid.
1247          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
1248          * @remarks     The specific error code can be accessed using the GetLastResult() method.
1249          */
1250         Tizen::Base::ByteBuffer* ExportUserProfileToVcardStreamN(const UserProfile& userProfile);
1251
1252         /**
1253          * Exports a user profile list to a vCard format stream.
1254          *
1255          * @since       2.1
1256          *
1257          * @return      The exported vCard stream, @n
1258          *              else @c null if an exception occurs
1259          * @param[in]   userProfileList         The user profile list to export @n The list should contain the UserProfile instances
1260          * @exception   E_SUCCESS               The method is successful.
1261          * @exception   E_INVALID_ARG           The specified @c userProfile is invalid.
1262          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
1263          * @remarks     The specific error code can be accessed using the GetLastResult() method.
1264          */
1265         Tizen::Base::ByteBuffer* ExportUserProfilesToVcardStreamN(const Tizen::Base::Collection::IList& userProfileList);
1266
1267         /**
1268          * Exports a user profile to the specified vCard 3.0 file.
1269          *
1270          * @since       2.1
1271          *
1272          * @return      An error code
1273          * @param[in]   userProfile              The user profile to export
1274          * @param[in]   vcardPath               The file path of a vCard file
1275          * @exception   E_SUCCESS               The method is successful.
1276          * @exception   E_INVALID_ARG           The specified @c userProfile is invalid.
1277          * @exception   E_ILLEGAL_ACCESS        The access is denied due to insufficient permission.
1278          * @exception   E_FILE_ALREADY_EXIST    The specified file already exists.
1279          * @exception   E_STORAGE_FULL                  The storage is insufficient.
1280          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
1281          */
1282         result ExportUserProfileToVcard(const UserProfile& userProfile, const Tizen::Base::String& vcardPath);
1283
1284         /**
1285          * Exports a user profile list to the specified vCard 3.0 file.
1286          *
1287          * @since       2.1
1288          *
1289          * @return      An error code
1290          * @param[in]   userProfileList          The user profile list to export @n The list should contain the UserProfile instances
1291          * @param[in]   vcardPath               The file path of a vCard file
1292          * @exception   E_SUCCESS               The method is successful.
1293          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
1294          *                                                      - The specified @c userProfileList is invalid.
1295          *                                                      - The specified @c vcardPath is invalid.
1296          * @exception   E_ILLEGAL_ACCESS        The access is denied due to insufficient permission.
1297          * @exception   E_FILE_ALREADY_EXIST    The specified file already exists.
1298          * @exception   E_STORAGE_FULL                  The storage is insufficient.
1299          * @exception   E_SYSTEM                The method cannot proceed due to a severe system error.
1300          */
1301         result ExportUserProfilesToVcard(const Tizen::Base::Collection::IList& userProfileList, const Tizen::Base::String& vcardPath);
1302
1303         /**
1304          * Gets all the user profiles on the device.
1305          *
1306          * @since       2.1
1307          * @privlevel   public
1308          * @privilege   %http://tizen.org/privilege/userprofile.read
1309          *
1310          * @return      The list of all the user profiles on the device, @n
1311          *              else an empty list if there is no user profile, or @c null if an exception occurs (@ref UserProfile list)
1312          * @exception   E_SUCCESS              The method is successful.
1313          * @exception   E_PRIVILEGE_DENIED     The application does not have the privilege to call this method.
1314          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method.
1315          * @exception   E_SYSTEM      The method cannot be proceed due to a severe system error.
1316          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1317          */
1318         Tizen::Base::Collection::IList* GetAllUserProfilesN(void) const;
1319
1320         /**
1321          * Gets a user profile of the address book specified by the address book ID.
1322          *
1323          * @since       2.1
1324          * @privlevel   public
1325          * @privilege   %http://tizen.org/privilege/userprofile.read
1326          *
1327          * @return      The matched user profile, @n
1328          *              else @c null if an exception occurs
1329          * @param[in]   addressbookId           The addressbook ID
1330          * @exception   E_SUCCESS               The method is successful.
1331          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
1332          * @exception   E_USER_NOT_CONSENTED    The user has blocked the application from calling this method.
1333          * @exception   E_INVALID_ARG           The specified @c addressbookId is invalid.
1334          * @exception   E_OBJ_NOT_FOUND         The specified addressbook is not found.
1335          * @exception   E_SYSTEM      The method cannot proceed due to a severe system error.
1336          * @remarks     The specific error code can be accessed using the GetLastResult() method.
1337          */
1338         UserProfile* GetUserProfileN(AddressbookId addressbookId) const;
1339
1340         /**
1341          * Gets an %AddressbookManager instance.
1342          *
1343          * @since       2.0
1344          *
1345          * @return              A pointer to the %AddressbookManager instance, @n
1346          *                              else @c null if it fails
1347          * @exception   E_SUCCESS                       The method is successful.
1348          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
1349          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1350          */
1351         static AddressbookManager* GetInstance(void);
1352
1353 private:
1354         //
1355         // This default constructor is intentionally declared as private to implement the Singleton semantic.
1356         //
1357         // @since       2.0
1358         //
1359         AddressbookManager(void);
1360
1361         //
1362         // This destructor is intentionally declared as private to implement the Singleton semantic.
1363         //
1364         // @since       2.0
1365         //
1366         virtual ~AddressbookManager(void);
1367
1368         //
1369         // This function is only for internal usage.
1370         //
1371         // @since       2.0
1372         //
1373         // @return      An error code
1374         //
1375         result Construct(void);
1376
1377         //
1378         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
1379         //
1380         // @since       2.0
1381         //
1382         AddressbookManager(const AddressbookManager& rhs);
1383
1384         //
1385         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
1386         //
1387         // @since       2.0
1388         //
1389         AddressbookManager& operator =(const AddressbookManager& rhs);
1390
1391         static void InitAddressbookManager(void);
1392         static void DestroyAddressbookManager(void);
1393
1394 private:
1395         static AddressbookManager* __pInstance;
1396         friend struct std::default_delete< AddressbookManager >;
1397
1398         friend class _AddressbookManagerImpl;
1399         class _AddressbookManagerImpl* __pAddressbookManagerImpl;
1400 }; // AddressbookManager
1401
1402 }} // Tizen::Social
1403
1404 #endif //_FSCL_ADDRESSBOOK_MANAGER_H_