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_OUT_OF_MEMORY The memory is insufficient.
172 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
173 * @remarks The specific error code can be accessed using the GetLastResult() method.
175 Tizen::Base::Collection::IListT<AccountId>* GetAccountIdsN(void) const;
178 * Gets the ID of this person.
182 * @return The person ID
184 PersonId GetId(void) const;
187 * Sets whether this person is a favorite or not.
191 * @privilege %http://tizen.org/privilege/contact.write
193 * @return An error code
194 * @param[in] isFavorite Set to @c true to set this person as a favorite, @n
195 * else @c false to set this person as non-favorite
196 * @exception E_SUCCESS The method is successful.
197 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
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_INVALID_ARG The specified @c phoneNumber is invalid.
217 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
218 * @see GetPrimaryPhoneNumber()
220 result SetAsPrimaryPhoneNumber(const PhoneNumber& phoneNumber);
223 * Sets the specified email as the primary email of this person.
227 * @privilege %http://tizen.org/privilege/contact.write
229 * @return An error code
230 * @param[in] email The email
231 * @exception E_SUCCESS The method is successful.
232 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
233 * @exception E_INVALID_ARG The specified @c phoneNumber is invalid.
234 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
235 * @see GetPrimaryEmail()
237 result SetAsPrimaryEmail(const Email& email);
240 * Gets the primary phone number of this person.
244 * @privilege %http://tizen.org/privilege/contact.read
246 * @return The primary phone number @n If this instance does not have the primary email, an empty PhoneNumber instance is returned.
247 * @exception E_SUCCESS The method is successful.
248 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
249 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
250 * @remarks The specific error code can be accessed using the GetLastResult() method.
251 * @see SetAsPrimaryPhoneNumber()
253 PhoneNumber GetPrimaryPhoneNumber(void) const;
256 * Gets the primary email of this person.
260 * @privilege %http://tizen.org/privilege/contact.read
262 * @return The primary email @n If this instance does not have the primary email, an empty Email instance is returned.
263 * @exception E_SUCCESS The method is successful.
264 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
265 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
266 * @remarks The specific error code can be accessed using the GetLastResult() method.
267 * @see SetAsPrimaryEmail()
269 Email GetPrimaryEmail(void) const;
273 * This constructor is intentionally declared as private so that only the platform can create an instance.
280 * This copy constructor is intentionally declared as private to prohibit copying of objects by users.
284 * @param[in] rhs An instance of %Person
286 Person(const Person& rhs);
289 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
293 * @param[in] rhs An instance of %Person
295 Person& operator =(const Person& rhs);
298 friend class _PersonImpl;
299 class _PersonImpl* __pPersonImpl;
301 friend class _AddressbookManagerImpl;
302 friend class _AddressbookUtil;
307 #endif // _FSCL_PERSON_H_