2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
9 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 * @brief This is the header file for the %Person class.
21 * This header file contains the declarations of the %Person class.
23 #ifndef _FSCL_PERSON_H_
24 #define _FSCL_PERSON_H_
26 #include <FBaseObject.h>
27 #include <FBaseString.h>
28 #include <FSclRecord.h>
29 #include <FSclTypes.h>
30 #include <FSclPhoneNumber.h>
31 #include <FSclEmail.h>
33 namespace Tizen { namespace Base
37 template<typename Type>
42 namespace Tizen { namespace Graphics
47 namespace Tizen { namespace Social
52 * @brief This class provides an aggregated contact information.
56 * @final This class is not intended for extension.
58 * The %Person class provides an aggregated contact information of a person. @n
59 * There can be more than one contact of the same person because contacts can be synchronized from multiple service providers. @n
60 * %Person has the following information of an individual. @n
64 * - Primary phone number
67 * Each information is collected from contacts linked to the person. @n
69 * 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.
70 * It is possible to merge two persons into one or unlink a contact from a person.
73 class _OSP_EXPORT_ Person
74 : public Tizen::Base::Object
78 * This destructor overrides Tizen::Base::Object::~Object().
82 virtual ~Person(void);
85 * Checks whether the value of the specified instance is equal to the value of the current instance of Tizen::Base::Object.
89 * @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
91 * @param[in] rhs An instance of Tizen::Base::Object to compare
93 virtual bool Equals(const Tizen::Base::Object& rhs) const;
96 * Gets the hash value of the current instance.
100 * @return The hash value of the current instance
102 virtual int GetHashCode(void) const;
105 * Gets the display name.
109 * @return The display name
111 Tizen::Base::String GetDisplayName(void) const;
114 * Checks whether this is a favorite or not.
118 * @return @c true if this is a favorite, @n
120 * @see SetAsFavorite()
122 bool IsFavorite(void) const;
125 * Gets the thumbnail path.
129 * @return The file path of the thumbnail
130 * @remarks If the thumbnail path has not been set, empty string is returned.
132 Tizen::Base::String GetThumbnailPath(void) const;
135 * Gets the ringtone path.
139 * @return The file path of the ringtone
140 * @remarks If the ringtone path has not been set, empty string is returned.
142 Tizen::Base::String GetRingtonePath(void) const;
145 * Checks whether this has phone numbers or not.
149 * @return @c true if this has phone numbers, @n
152 bool HasPhoneNumber(void) const;
155 * Checks whether this has emails or not.
159 * @return @c true if this has emails, @n
162 bool HasEmail(void) const;
165 * Gets the list of account ID of contacts linked to the person.
169 * @return The account ID list
170 * @exception E_SUCCESS The method is successful.
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.
189 * @privilege %http://tizen.org/privilege/contact.write
191 * @return An error code
192 * @param[in] isFavorite Set to @c true to set this person as a favorite, @n
193 * else @c false to set this person as non-favorite
194 * @exception E_SUCCESS The method is successful.
195 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
196 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
198 * @see AddressbookManager::GetFavoritePersonsN()
200 result SetAsFavorite(bool isFavorite = true);
204 * Sets the specified phone number as the primary phone number of this person.
205 * The phone number must be one of the instances returned by calling Contact::GetValuesN(CONTACT_MPROPERTY_ID_PHONE_NUMBERS) on the instance of the contacts of this person.@n
208 * @privilege %http://tizen.org/privilege/contact.write
210 * @return An error code
211 * @param[in] phoneNumber The phone number
212 * @exception E_SUCCESS The method is successful.
213 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
214 * @exception E_INVALID_ARG The specified @c phoneNumber is invalid.
215 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
216 * @see GetPrimaryPhoneNumber()
218 * The following example demonstractes how to use %SetAsPrimaryPhoneNumber() method
221 * MyApplication::SetPrimaryPhoneNumber(void)
223 * IList* pContacts = pAddressbookManager->GetContactsByPersonN(pPerson->GetId());
224 * Contact* pContact = static_cast<Contact*>(pContacts->GetAt(0));
225 * IList* pPhoneNumbers = pContact->GetValuesN(CONTACT_MPROPERTY_ID_PHONE_NUMBERS);
227 * PhoneNumber* pPhoneNumber = static_cast<PhoneNumber*>(pPhoneNumbers->GetAt(0));
229 * // Set the first phone number of the first contact of the person as the primary phone number
230 * pPerson->SetAsPrimaryPhoneNumber(*pPhoneNumber);
232 * pPhoneNumbers->RemoveAll(true);
233 * delete pPhoneNumbers;
235 * pContacts->RemoveAll(true);
240 result SetAsPrimaryPhoneNumber(const PhoneNumber& phoneNumber);
243 * Sets the specified email as the primary email of this person.
244 * The email must be one of the instances returned by calling Contact::GetValuesN(CONTACT_MPROPERTY_ID_EMAILS) on the instance of the contacts of this person.@n
247 * @privilege %http://tizen.org/privilege/contact.write
249 * @return An error code
250 * @param[in] email The email
251 * @exception E_SUCCESS The method is successful.
252 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
253 * @exception E_INVALID_ARG The specified @c phoneNumber is invalid.
254 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
255 * @see GetPrimaryEmail()
256 * The following example demonstractes how to use %SetAsPrimaryEmail() method
259 * MyApplication::SetPrimaryEmail(void)
261 * IList* pContacts = pAddressbookManager->GetContactsByPersonN(pPerson->GetId());
262 * Contact* pContact = static_cast<Contact*>(pContacts->GetAt(0));
263 * IList* pEmails = pContact->GetValuesN(CONTACT_MPROPERTY_ID_EMAILS);
265 * Email* pEmail = static_cast<Email*>(pEmails->GetAt(0));
267 * // Set the first email of the first contact of the person as the primary email
268 * pPerson->SetAsPrimaryEmail(*pEmail);
270 * pEmails->RemoveAll(true);
273 * pContacts->RemoveAll(true);
279 result SetAsPrimaryEmail(const Email& email);
282 * Gets the primary phone number of this person.
285 * @privilege %http://tizen.org/privilege/contact.read
287 * @return The primary phone number @n If this instance does not have the primary email, an empty PhoneNumber instance is returned.
288 * @exception E_SUCCESS The method is successful.
289 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
290 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
291 * @remarks The specific error code can be accessed using the GetLastResult() method.
292 * @see SetAsPrimaryPhoneNumber()
294 PhoneNumber GetPrimaryPhoneNumber(void) const;
297 * Gets the primary email of this person.
300 * @privilege %http://tizen.org/privilege/contact.read
302 * @return The primary email @n If this instance does not have the primary email, an empty Email instance is returned.
303 * @exception E_SUCCESS The method is successful.
304 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
305 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
306 * @remarks The specific error code can be accessed using the GetLastResult() method.
307 * @see SetAsPrimaryEmail()
309 Email GetPrimaryEmail(void) const;
313 * This constructor is intentionally declared as private so that only the platform can create an instance.
320 * This copy constructor is intentionally declared as private to prohibit copying of objects by users.
324 * @param[in] rhs An instance of %Person
326 Person(const Person& rhs);
329 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
333 * @param[in] rhs An instance of %Person
335 Person& operator =(const Person& rhs);
338 friend class _PersonImpl;
339 class _PersonImpl* __pPersonImpl;
341 friend class _AddressbookManagerImpl;
342 friend class _AddressbookUtil;
347 #endif // _FSCL_PERSON_H_