inc/FSclAddressbookManager.h

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