4 * Copyright (c) 2010 - 2015 Samsung Electronics Co., Ltd. All rights reserved.
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
10 * http://www.apache.org/licenses/LICENSE-2.0
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
19 #ifndef __TIZEN_SOCIAL_CONTACTS_SETTING_H__
20 #define __TIZEN_SOCIAL_CONTACTS_SETTING_H__
29 * @file contacts_setting.h
33 * @ingroup CAPI_SOCIAL_CONTACTS_SVC_MODULE
34 * @defgroup CAPI_SOCIAL_CONTACTS_SVC_SETTING_MODULE Setting
36 * @brief The contacts setting API provides the set of definitions and interfaces that enable application developers to set up contacts features.
38 * @section CAPI_SOCIAL_CONTACTS_SVC_SETTING_MODULE_HEADER Required Header
39 * \#include <contacts.h>
46 * @brief Enumeration for name display order.
48 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
53 CONTACTS_NAME_DISPLAY_ORDER_FIRSTLAST, /**< First name comes at the first */
54 CONTACTS_NAME_DISPLAY_ORDER_LASTFIRST /**< First name comes at the last */
55 } contacts_name_display_order_e;
58 * @brief Gets the contacts name display order.
60 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
62 * @privilege %http://tizen.org/privilege/contact.read
64 * @param[out] name_display_order The name display order
66 * @return @c 0 on success,
67 * otherwise a negative error value
69 * @retval #CONTACTS_ERROR_NONE Successful
70 * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
71 * @retval #CONTACTS_ERROR_PERMISSION_DENIED Permission denied. This application does not have the privilege to call this method.
72 * @retval #CONTACTS_ERROR_IPC Unknown IPC error
73 * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
75 * @pre contacts_connect() should be called to open a connection to the contacts service.
77 * @see contacts_connect()
79 int contacts_setting_get_name_display_order(contacts_name_display_order_e *name_display_order);
82 * @brief Sets the contacts name display order.
84 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
86 * @privilege %http://tizen.org/privilege/contact.write
88 * @param[in] name_display_order The name display order
90 * @return @c 0 on success,
91 * otherwise a negative error value
93 * @retval #CONTACTS_ERROR_NONE Successful
94 * @retval #CONTACTS_ERROR_OUT_OF_MEMORY Out of memory
95 * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
96 * @retval #CONTACTS_ERROR_PERMISSION_DENIED Permission denied. This application does not have the privilege to call this method.
97 * @retval #CONTACTS_ERROR_IPC Unknown IPC error
98 * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
100 * @pre contacts_connect() should be called to open a connection to the contacts service.
101 * @post contacts_setting_name_display_order_changed_cb() callback will be called upon success.
103 * @see contacts_connect()
105 int contacts_setting_set_name_display_order(contacts_name_display_order_e name_display_order);
109 * @brief Enumeration for name sorting order.
111 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
116 CONTACTS_NAME_SORTING_ORDER_FIRSTLAST, /**< Contacts are first sorted based on the first name */
117 CONTACTS_NAME_SORTING_ORDER_LASTFIRST /**< Contacts are first sorted based on the last name */
118 } contacts_name_sorting_order_e;
122 * @brief Gets the contacts name sorting order in which contacts are returned.
124 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
126 * @privilege %http://tizen.org/privilege/contact.read
128 * @param[out] name_sorting_order The name sorting order
130 * @return @c 0 on success,
131 * otherwise a negative error value
133 * @retval #CONTACTS_ERROR_NONE Successful
134 * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
135 * @retval #CONTACTS_ERROR_PERMISSION_DENIED Permission denied. This application does not have the privilege to call this method.
136 * @retval #CONTACTS_ERROR_IPC Unknown IPC error
137 * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
139 * @pre contacts_connect() should be called to open a connection to the contacts service.
141 * @see contacts_connect()
143 int contacts_setting_get_name_sorting_order(contacts_name_sorting_order_e *name_sorting_order);
146 * @brief Sets the contacts name sorting order in which contacts are returned.
148 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
150 * @privilege %http://tizen.org/privilege/contact.write
152 * @param[in] name_sorting_order The name sorting order
154 * @return @c 0 on success,
155 * otherwise a negative error value
157 * @retval #CONTACTS_ERROR_NONE Successful
158 * @retval #CONTACTS_ERROR_OUT_OF_MEMORY Out of memory
159 * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
160 * @retval #CONTACTS_ERROR_PERMISSION_DENIED Permission denied. This application does not have the privilege to call this method.
161 * @retval #CONTACTS_ERROR_IPC Unknown IPC error
162 * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
164 * @pre contacts_connect() should be called to open a connection to the contacts service.
165 * @post contacts_setting_name_sorting_order_changed_cb() callback will be called upon success.
167 * @see contacts_connect()
169 int contacts_setting_set_name_sorting_order(contacts_name_sorting_order_e name_sorting_order);
172 * @brief Called when a designated view changes.
174 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
176 * @param[in] name_display_order The name display order setting value
177 * @param[in] user_data The user data passed from the callback registration function
179 * @pre The callback must be registered using contacts_setting_add_name_display_order_changed_cb().
180 * contacts_setting_set_name_display_order() must be called to invoke this callback.
182 * @see contacts_setting_add_name_display_order_changed_cb()
183 * @see contacts_setting_remove_name_display_order_changed_cb()
185 typedef void (*contacts_setting_name_display_order_changed_cb)(contacts_name_display_order_e name_display_order, void *user_data);
189 * @brief Registers a callback function.
191 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
193 * @privilege %http://tizen.org/privilege/contact.read
195 * @param[in] callback The callback function to register
196 * @param[in] user_data The user data to be passed to the callback function
198 * @return @c 0 on success,
199 * otherwise a negative error value
201 * @retval #CONTACTS_ERROR_NONE Successful
202 * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
203 * @retval #CONTACTS_ERROR_IPC Unknown IPC error
204 * @retval #CONTACTS_ERROR_INTERNAL Implementation Error, Temporary Use
205 * @retval #CONTACTS_ERROR_PERMISSION_DENIED Permission denied. This application does not have the privilege to call this method.
207 * @pre contacts_connect() should be called to open a connection to the contacts service.
208 * @post contacts_setting_name_display_order_changed_cb() will be called under certain conditions, after calling contacts_setting_set_name_display_order().
210 * @see contacts_connect()
211 * @see contacts_setting_remove_name_display_order_changed_cb()
214 int contacts_setting_add_name_display_order_changed_cb(contacts_setting_name_display_order_changed_cb callback, void *user_data);
217 * @brief Unregisters a callback function.
219 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
220 * @param[in] callback The callback function to register
221 * @param[in] user_data The user data to be passed to the callback function
223 * @return @c 0 on success,
224 * otherwise a negative error value
226 * @retval #CONTACTS_ERROR_NONE Successful
227 * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
228 * @retval #CONTACTS_ERROR_INTERNAL Implementation Error, Temporary Use
230 * @pre contacts_connect() should be called to open a connection to the contacts service.
232 * @see contacts_connect()
233 * @see contacts_setting_add_name_display_order_changed_cb()
236 int contacts_setting_remove_name_display_order_changed_cb(contacts_setting_name_display_order_changed_cb callback, void *user_data);
239 * @brief Called when a designated view changes.
241 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
242 * @param[in] name_sorting_order The name sorting order setting value
243 * @param[in] user_data The user data passed from the callback registration function
245 * @pre The callback must be registered using contacts_setting_add_name_sorting_order_changed_cb().
246 * contacts_setting_set_name_sorting_order() must be called to invoke this callback.
248 * @see contacts_setting_add_name_sorting_order_changed_cb()
249 * @see contacts_setting_remove_name_sorting_order_changed_cb()
251 typedef void (*contacts_setting_name_sorting_order_changed_cb)(contacts_name_sorting_order_e name_sorting_order, void *user_data);
255 * @brief Registers a callback function.
257 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
259 * @privilege %http://tizen.org/privilege/contact.read
261 * @param[in] callback The callback function to register
262 * @param[in] user_data The user data to be passed to the callback function
264 * @return @c 0 on success,
265 * otherwise a negative error value
267 * @retval #CONTACTS_ERROR_NONE Successful
268 * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
269 * @retval #CONTACTS_ERROR_IPC Unknown IPC error
270 * @retval #CONTACTS_ERROR_INTERNAL Implementation Error, Temporary Use
271 * @retval #CONTACTS_ERROR_PERMISSION_DENIED Permission denied. This application does not have the privilege to call this method.
273 * @pre contacts_connect() should be called to open a connection to the contacts service.
274 * @post contacts_setting_name_sorting_order_changed_cb() will be called under certain conditions, after calling contacts_setting_set_name_sorting_order().
276 * @see contacts_connect()
277 * @see contacts_setting_remove_name_sorting_order_changed_cb()
280 int contacts_setting_add_name_sorting_order_changed_cb(contacts_setting_name_sorting_order_changed_cb callback, void *user_data);
283 * @brief Unregisters a callback function.
285 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
286 * @param[in] callback The callback function to register
287 * @param[in] user_data The user data to be passed to the callback function
289 * @return @c 0 on success,
290 * otherwise a negative error value
292 * @retval #CONTACTS_ERROR_NONE Successful
293 * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
294 * @retval #CONTACTS_ERROR_INTERNAL Implementation Error, Temporary Use
296 * @pre contacts_connect() should be called to open a connection to the contacts service.
298 * @see contacts_connect()
299 * @see contacts_setting_add_name_sorting_order_changed_cb()
302 int contacts_setting_remove_name_sorting_order_changed_cb(contacts_setting_name_sorting_order_changed_cb callback, void *user_data);
313 #endif /* __TIZEN_SOCIAL_CONTACTS_SETTING_H__ */