2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @brief This is the header file for the %Person class.
20 * This header file contains the declarations of the %Person class.
22 #ifndef _FSCL_PERSON_H_
23 #define _FSCL_PERSON_H_
25 #include <FBaseObject.h>
26 #include <FBaseString.h>
27 #include <FSclRecord.h>
28 #include <FSclTypes.h>
29 #include <FSclPhoneNumber.h>
30 #include <FSclEmail.h>
32 namespace Tizen { namespace Base
36 template<typename Type>
41 namespace Tizen { namespace Graphics
46 namespace Tizen { namespace Social
51 * @brief This class provides an aggregated contact information.
55 * @final This class is not intended for extension.
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
63 * - Primary phone number
66 * Each information is collected from contacts linked to the person. @n
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.
72 class _OSP_EXPORT_ Person
73 : public Tizen::Base::Object
77 * This destructor overrides Tizen::Base::Object::~Object().
81 virtual ~Person(void);
84 * Checks whether the value of the specified instance is equal to the value of the current instance of Tizen::Base::Object.
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
90 * @param[in] rhs An instance of Tizen::Base::Object to compare
92 virtual bool Equals(const Tizen::Base::Object& rhs) const;
95 * Gets the hash value of the current instance.
99 * @return The hash value of the current instance
101 virtual int GetHashCode(void) const;
104 * Gets the display name.
108 * @return The display name
110 Tizen::Base::String GetDisplayName(void) const;
113 * Checks whether this is a favorite or not.
117 * @return @c true if this is a favorite, @n
119 * @see SetAsFavorite()
121 bool IsFavorite(void) const;
124 * Gets the thumbnail path.
128 * @return The file path of the thumbnail
129 * @remarks If the thumbnail path has not been set, empty string is returned.
131 Tizen::Base::String GetThumbnailPath(void) const;
134 * Gets the ringtone path.
138 * @return The file path of the ringtone
139 * @remarks If the ringtone path has not been set, empty string is returned.
141 Tizen::Base::String GetRingtonePath(void) const;
144 * Checks whether this has phone numbers or not.
148 * @return @c true if this has phone numbers, @n
151 bool HasPhoneNumber(void) const;
154 * Checks whether this has emails or not.
158 * @return @c true if this has emails, @n
161 bool HasEmail(void) const;
164 * Gets the list of account ID of contacts linked to the person.
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.
174 Tizen::Base::Collection::IListT<AccountId>* GetAccountIdsN(void) const;
177 * Gets the ID of this person.
181 * @return The person ID
183 PersonId GetId(void) const;
186 * Sets whether this person is a favorite or not.
190 * @privilege %http://tizen.org/privilege/contact.write
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.
200 * @see AddressbookManager::GetFavoritePersonsN()
202 result SetAsFavorite(bool isFavorite = true);
206 * Sets the specified phone number as the primary phone number of this person.
210 * @privilege %http://tizen.org/privilege/contact.write
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()
221 result SetAsPrimaryPhoneNumber(const PhoneNumber& phoneNumber);
224 * Sets the specified email as the primary email of this person.
228 * @privilege %http://tizen.org/privilege/contact.write
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()
239 result SetAsPrimaryEmail(const Email& email);
242 * Gets the primary phone number of this person.
246 * @privilege %http://tizen.org/privilege/contact.read
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()
256 PhoneNumber GetPrimaryPhoneNumber(void) const;
259 * Gets the primary email of this person.
263 * @privilege %http://tizen.org/privilege/contact.read
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()
273 Email GetPrimaryEmail(void) const;
277 * This constructor is intentionally declared as private so that only the platform can create an instance.
284 * This copy constructor is intentionally declared as private to prohibit copying of objects by users.
288 * @param[in] rhs An instance of %Person
290 Person(const Person& rhs);
293 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
297 * @param[in] rhs An instance of %Person
299 Person& operator =(const Person& rhs);
302 friend class _PersonImpl;
303 class _PersonImpl* __pPersonImpl;
305 friend class _AddressbookManagerImpl;
306 friend class _AddressbookUtil;
311 #endif // _FSCL_PERSON_H_