inc/FSclPerson.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                FSclPerson.h
  18  * @brief               This is the header file for the %Person class.
  19  *
  20  * This header file contains the declarations of the %Person class.
  21  */
  22 #ifndef _FSCL_PERSON_H_
  23 #define _FSCL_PERSON_H_
  24
  25 #include <FBaseObject.h>
  26 #include <FBaseString.h>
  27 #include <FSclRecord.h>
  28 #include <FSclTypes.h>
  29 #include <FSclPhoneNumber.h>
  30 #include <FSclEmail.h>
  31
  32 namespace Tizen { namespace Base
  33 {
  34 namespace Collection
  35 {
  36 template<typename Type>
  37 class IListT;
  38 }
  39 } }
  40
  41 namespace Tizen { namespace Graphics
  42 {
  43 class Bitmap;
  44 } }
  45
  46 namespace Tizen { namespace Social
  47 {
  48
  49 /**
  50  * @class      Person
  51  * @brief      This class provides an aggregated contact information.
  52  *
  53  * @since       2.0
  54  *
  55  * @final      This class is not intended for extension.
  56  *
  57  * The %Person class provides an aggregated contact information of a person. @n
  58  * There can be more than one contact of the same person because contacts can be synchronized from multiple service providers. @n
  59  * %Person has the following information of an individual. @n
  60  * - Display name
  61  * - Thumbnail
  62  * - Ringtone
  63  * - Primary phone number
  64  * - Primary email
  65  *
  66  * Each information is collected from contacts linked to the person. @n
  67  *
  68  * There is no explicit way to create a person. When a contact is added, the system creates a new person and links the contact to the person.
  69  * It is possible to merge two persons into one or unlink a contact from a person.
  70  */
  71
  72 class _OSP_EXPORT_ Person
  73         : public Tizen::Base::Object
  74 {
  75 public:
  76         /**
  77          * This destructor overrides Tizen::Base::Object::~Object().
  78          *
  79          * @since       2.0
  80          */
  81         virtual ~Person(void);
  82
  83         /**
  84          * Checks whether the value of the specified instance is equal to the value of the current instance of Tizen::Base::Object.
  85          *
  86          * @since       2.0
  87          *
  88          * @return     @c true if the value of the specified instance of Tizen::Base::Object is equal to the value of the current instance of %Tizen::Base::Object, @n
  89          *                     else @c false
  90          * @param[in]  rhs            An instance of Tizen::Base::Object to compare
  91          */
  92         virtual bool Equals(const Tizen::Base::Object& rhs) const;
  93
  94         /**
  95          * Gets the hash value of the current instance.
  96          *
  97          * @since       2.0
  98          *
  99          * @return     The hash value of the current instance
 100          */
 101         virtual int GetHashCode(void) const;
 102
 103         /**
 104          * Gets the display name.
 105          *
 106          * @since       2.0
 107          *
 108          * @return     The display name
 109          */
 110         Tizen::Base::String GetDisplayName(void) const;
 111
 112         /**
 113          * Checks whether this is a favorite or not.
 114          *
 115          * @since       2.0
 116          *
 117          * @return     @c true if this is a favorite, @n
 118          *              else @c false
 119          * @see SetAsFavorite()
 120          */
 121         bool IsFavorite(void) const;
 122
 123         /**
 124          * Gets the thumbnail path.
 125          *
 126          * @since       2.0
 127          *
 128          * @return     The file path of the thumbnail
 129          * @remarks    If the thumbnail path has not been set, empty string is returned.
 130          */
 131         Tizen::Base::String GetThumbnailPath(void) const;
 132
 133         /**
 134          * Gets the ringtone path.
 135          *
 136          * @since       2.0
 137          *
 138          * @return     The file path of the ringtone
 139          * @remarks    If the ringtone path has not been set, empty string is returned.
 140          */
 141         Tizen::Base::String GetRingtonePath(void) const;
 142
 143         /**
 144          * Checks whether this has phone numbers or not.
 145          *
 146          * @since       2.0
 147          *
 148          * @return     @c true if this has phone numbers, @n
 149          *              else @c false
 150          */
 151         bool HasPhoneNumber(void) const;
 152
 153         /**
 154          * Checks whether this has emails or not.
 155          *
 156          * @since       2.0
 157          *
 158          * @return     @c true if this has emails, @n
 159          *              else @c false
 160          */
 161         bool HasEmail(void) const;
 162
 163         /**
 164          * Gets the list of account ID of contacts linked to the person.
 165          *
 166          * @since       2.0
 167          *
 168          * @return     The account ID list
 169          * @exception  E_SUCCESS              The method is successful.
 170          * @exception  E_OUT_OF_MEMORY        The memory is insufficient.
 171          * @exception  E_SYSTEM         The method cannot proceed due to a severe system error.
 172          * @remarks    The specific error code can be accessed using the GetLastResult() method.
 173          */
 174         Tizen::Base::Collection::IListT<AccountId>* GetAccountIdsN(void) const;
 175
 176         /**
 177          * Gets the ID of this person.
 178          *
 179          * @since       2.0
 180          *
 181          * @return      The person ID
 182          */
 183         PersonId GetId(void) const;
 184
 185         /**
 186          * Sets whether this person is a favorite or not.
 187          *
 188          * @since       2.0
 189          * @privlevel   public
 190          * @privilege   %http://tizen.org/privilege/contact.write
 191          *
 192          * @return      An error code
 193          * @param[in]   isFavorite    Set to @c true to set this person as a favorite, @n
 194          *                            else @c false to set this person as non-favorite
 195          * @exception   E_SUCCESS               The method is successful.
 196          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 197          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 198          * @exception   E_SYSTEM      The method cannot proceed due to a severe system error.
 199          * @see IsFavorite()
 200          * @see AddressbookManager::GetFavoritePersonsN()
 201          */
 202         result SetAsFavorite(bool isFavorite = true);
 203
 204
 205         /**
 206          * Sets the specified phone number as the primary phone number of this person.
 207          *
 208          * @since       2.0
 209          * @privlevel   public
 210          * @privilege   %http://tizen.org/privilege/contact.write
 211          *
 212          * @return     An error code
 213          * @param[in]  phoneNumber    The phone number
 214          * @exception  E_SUCCESS      The method is successful.
 215          * @exception  E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 216          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 217          * @exception  E_INVALID_ARG          The specified @c phoneNumber is invalid.
 218          * @exception  E_SYSTEM     The method cannot proceed due to a severe system error.
 219          * @see GetPrimaryPhoneNumber()
 220          */
 221         result SetAsPrimaryPhoneNumber(const PhoneNumber& phoneNumber);
 222
 223         /**
 224          * Sets the specified email as the primary email of this person.
 225          *
 226          * @since       2.0
 227          * @privlevel   public
 228          * @privilege   %http://tizen.org/privilege/contact.write
 229          *
 230          * @return     An error code
 231          * @param[in]  email          The email
 232          * @exception  E_SUCCESS      The method is successful.
 233          * @exception  E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 234          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 235          * @exception  E_INVALID_ARG          The specified @c phoneNumber is invalid.
 236          * @exception  E_SYSTEM     The method cannot proceed due to a severe system error.
 237          * @see GetPrimaryEmail()
 238          */
 239         result SetAsPrimaryEmail(const Email& email);
 240
 241         /**
 242          * Gets the primary phone number of this person.
 243          *
 244          * @since       2.0
 245          * @privlevel   public
 246          * @privilege   %http://tizen.org/privilege/contact.read
 247          *
 248          * @return      The primary phone number @n If this instance does not have the primary email, an empty PhoneNumber instance is returned.
 249          * @exception  E_SUCCESS                The method is successful.
 250          * @exception  E_PRIVILEGE_DENIED       The application does not have the privilege to call this method.
 251          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 252          * @exception  E_SYSTEM     The method cannot proceed due to a severe system error.
 253          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 254          * @see SetAsPrimaryPhoneNumber()
 255          */
 256         PhoneNumber GetPrimaryPhoneNumber(void) const;
 257
 258         /**
 259          * Gets the primary email of this person.
 260          *
 261          * @since       2.0
 262          * @privlevel   public
 263          * @privilege   %http://tizen.org/privilege/contact.read
 264          *
 265          * @return      The primary email @n If this instance does not have the primary email, an empty Email instance is returned.
 266          * @exception  E_SUCCESS                The method is successful.
 267          * @exception  E_PRIVILEGE_DENIED       The application does not have the privilege to call this method.
 268          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 269          * @exception  E_SYSTEM     The method cannot proceed due to a severe system error.
 270          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 271          * @see SetAsPrimaryEmail()
 272          */
 273         Email GetPrimaryEmail(void) const;
 274
 275 private:
 276         /**
 277          * This constructor is intentionally declared as private so that only the platform can create an instance.
 278          *
 279          * @since       2.0
 280          */
 281         Person(void);
 282
 283         /**
 284          * This copy constructor is intentionally declared as private to prohibit copying of objects by users.
 285          *
 286          * @since       2.0
 287          *
 288          * @param[in]  rhs            An instance of %Person
 289          */
 290         Person(const Person& rhs);
 291
 292         /**
 293          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 294          *
 295          * @since       2.0
 296          *
 297          * @param[in]  rhs            An instance of %Person
 298          */
 299         Person& operator =(const Person& rhs);
 300
 301 private:
 302         friend class _PersonImpl;
 303         class _PersonImpl* __pPersonImpl;
 304
 305         friend class _AddressbookManagerImpl;
 306         friend class _AddressbookUtil;
 307 };      // Person
 308
 309 }}      // Tizen::Social
 310
 311 #endif // _FSCL_PERSON_H_