include/contacts_setting.h

   1 /*
   2  * Contacts Service
   3  *
   4  * Copyright (c) 2010 - 2015 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   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
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  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.
  17  *
  18  */
  19
  20
  21 #ifndef __TIZEN_SOCIAL_CONTACTS_SETTING_H__
  22 #define __TIZEN_SOCIAL_CONTACTS_SETTING_H__
  23
  24
  25 #ifdef __cplusplus
  26 extern "C"
  27 {
  28 #endif
  29
  30
  31 /**
  32  * @file contacts_setting.h
  33  */
  34
  35
  36 /**
  37  * @ingroup CAPI_SOCIAL_CONTACTS_SVC_MODULE
  38  * @defgroup CAPI_SOCIAL_CONTACTS_SVC_SETTING_MODULE Setting
  39  * @brief The contacts setting API provides the set of definitions and interfaces that enable application developers to set up contacts features.
  40  * @section CAPI_SOCIAL_CONTACTS_SVC_SETTING_MODULE_HEADER Required Header
  41  *          \#include <contacts.h>
  42  * <BR>
  43  * @{
  44  */
  45
  46
  47 /**
  48  * @brief Enumeration for name display order.
  49  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  50  */
  51 typedef enum {
  52         CONTACTS_NAME_DISPLAY_ORDER_FIRSTLAST, /**< First name comes at the first */
  53         CONTACTS_NAME_DISPLAY_ORDER_LASTFIRST /**< First name comes at the last */
  54 } contacts_name_display_order_e;
  55
  56
  57 /**
  58  * @brief Gets the contacts name display order.
  59  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  60  * @privlevel public
  61  * @privilege %http://tizen.org/privilege/contact.read
  62  * @param[out] name_display_order The name display order
  63  * @return @c 0 on success,
  64  *         otherwise a negative error value
  65  * @retval #CONTACTS_ERROR_NONE Successful
  66  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
  67  * @retval #CONTACTS_ERROR_PERMISSION_DENIED Permission denied. This application does not have the privilege to call this method
  68  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
  69  * @retval #CONTACTS_ERROR_IPC Unknown IPC error
  70  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
  71  * @pre contacts_connect() should be called to open a connection to the contacts service.
  72  * @see contacts_connect()
  73  */
  74 int contacts_setting_get_name_display_order(contacts_name_display_order_e *name_display_order);
  75
  76
  77 /**
  78  * @brief Sets the contacts name display order.
  79  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  80  * @privlevel public
  81  * @privilege %http://tizen.org/privilege/contact.write
  82  * @param[in] name_display_order The name display order
  83  * @return @c 0 on success,
  84  *         otherwise a negative error value
  85  * @retval #CONTACTS_ERROR_NONE Successful
  86  * @retval #CONTACTS_ERROR_OUT_OF_MEMORY Out of memory
  87  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
  88  * @retval #CONTACTS_ERROR_PERMISSION_DENIED Permission denied. This application does not have the privilege to call this method
  89  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
  90  * @retval #CONTACTS_ERROR_IPC Unknown IPC error
  91  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
  92  * @pre contacts_connect() should be called to open a connection to the contacts service.
  93  * @post contacts_setting_name_display_order_changed_cb() callback will be called upon success.
  94  * @see contacts_connect()
  95  */
  96 int contacts_setting_set_name_display_order(contacts_name_display_order_e name_display_order);
  97
  98
  99 /**
 100  * @brief Enumeration for name sorting order.
 101  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 102  */
 103 typedef enum {
 104         CONTACTS_NAME_SORTING_ORDER_FIRSTLAST, /**< Contacts are first sorted based on the first name */
 105         CONTACTS_NAME_SORTING_ORDER_LASTFIRST /**< Contacts are first sorted based on the last name */
 106 } contacts_name_sorting_order_e;
 107
 108
 109 /**
 110  * @brief Gets the contacts name sorting order in which contacts are returned.
 111  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 112  * @privlevel public
 113  * @privilege %http://tizen.org/privilege/contact.read
 114  * @param[out] name_sorting_order The name sorting order
 115  * @return @c 0 on success,
 116  *         otherwise a negative error value
 117  * @retval #CONTACTS_ERROR_NONE Successful
 118  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 119  * @retval #CONTACTS_ERROR_PERMISSION_DENIED Permission denied. This application does not have the privilege to call this method.
 120  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 121  * @retval #CONTACTS_ERROR_IPC Unknown IPC error
 122  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 123  * @pre contacts_connect() should be called to open a connection to the contacts service.
 124  * @see contacts_connect()
 125  */
 126 int contacts_setting_get_name_sorting_order(contacts_name_sorting_order_e *name_sorting_order);
 127
 128
 129 /**
 130  * @brief Sets the contacts name sorting order in which contacts are returned.
 131  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 132  * @privlevel public
 133  * @privilege %http://tizen.org/privilege/contact.write
 134  * @param[in] name_sorting_order The name sorting order
 135  * @return @c 0 on success,
 136  *         otherwise a negative error value
 137  * @retval #CONTACTS_ERROR_NONE Successful
 138  * @retval #CONTACTS_ERROR_OUT_OF_MEMORY Out of memory
 139  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 140  * @retval #CONTACTS_ERROR_PERMISSION_DENIED Permission denied. This application does not have the privilege to call this method
 141  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 142  * @retval #CONTACTS_ERROR_IPC Unknown IPC error
 143  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 144  * @pre contacts_connect() should be called to open a connection to the contacts service.
 145  * @post contacts_setting_name_sorting_order_changed_cb() callback will be called upon success.
 146  * @see contacts_connect()
 147  */
 148 int contacts_setting_set_name_sorting_order(contacts_name_sorting_order_e name_sorting_order);
 149
 150
 151 /**
 152  * @brief Called when a designated view changes.
 153  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 154  * @param[in] name_display_order The name display order setting value
 155  * @param[in] user_data The user data passed from the callback registration function
 156  * @pre The callback must be registered using contacts_setting_add_name_display_order_changed_cb().
 157  *      contacts_setting_set_name_display_order() must be called to invoke this callback.
 158  * @see contacts_setting_add_name_display_order_changed_cb()
 159  * @see contacts_setting_remove_name_display_order_changed_cb()
 160  */
 161 typedef void (*contacts_setting_name_display_order_changed_cb)(contacts_name_display_order_e name_display_order, void *user_data);
 162
 163
 164 /**
 165  * @brief Registers a callback function.
 166  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 167  * @privlevel public
 168  * @privilege %http://tizen.org/privilege/contact.read
 169  * @param[in] callback The callback function to register
 170  * @param[in] user_data The user data to be passed to the callback function
 171  * @return @c 0 on success,
 172  *         otherwise a negative error value
 173  * @retval #CONTACTS_ERROR_NONE Successful
 174  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 175  * @retval #CONTACTS_ERROR_IPC Unknown IPC error
 176  * @retval #CONTACTS_ERROR_INTERNAL Implementation Error, Temporary Use
 177  * @retval #CONTACTS_ERROR_PERMISSION_DENIED Permission denied. This application does not have the privilege to call this method
 178  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 179  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 180  * @pre contacts_connect() should be called to open a connection to the contacts service.
 181  * @post contacts_setting_name_display_order_changed_cb() will be called under certain conditions, after calling contacts_setting_set_name_display_order().
 182  * @see contacts_connect()
 183  * @see contacts_setting_remove_name_display_order_changed_cb()
 184  */
 185 int contacts_setting_add_name_display_order_changed_cb(contacts_setting_name_display_order_changed_cb callback, void *user_data);
 186
 187
 188 /**
 189  * @brief Unregisters a callback function.
 190  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 191  * @param[in] callback The callback function to register
 192  * @param[in] user_data The user data to be passed to the callback function
 193  * @return @c 0 on success,
 194  *         otherwise a negative error value
 195  * @retval #CONTACTS_ERROR_NONE Successful
 196  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 197  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 198  * @retval #CONTACTS_ERROR_INTERNAL Implementation Error, Temporary Use
 199  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 200  * @pre contacts_connect() should be called to open a connection to the contacts service.
 201  * @see contacts_connect()
 202  * @see contacts_setting_add_name_display_order_changed_cb()
 203  */
 204 int contacts_setting_remove_name_display_order_changed_cb(contacts_setting_name_display_order_changed_cb callback, void *user_data);
 205
 206
 207 /**
 208  * @brief Called when a designated view changes.
 209  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 210  * @param[in] name_sorting_order The name sorting order setting value
 211  * @param[in] user_data The user data passed from the callback registration function
 212  * @pre The callback must be registered using contacts_setting_add_name_sorting_order_changed_cb().
 213  *      contacts_setting_set_name_sorting_order() must be called to invoke this callback.
 214  * @see contacts_setting_add_name_sorting_order_changed_cb()
 215  * @see contacts_setting_remove_name_sorting_order_changed_cb()
 216  */
 217 typedef void (*contacts_setting_name_sorting_order_changed_cb)(contacts_name_sorting_order_e name_sorting_order, void *user_data);
 218
 219
 220 /**
 221  * @brief Registers a callback function.
 222  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 223  * @privlevel public
 224  * @privilege %http://tizen.org/privilege/contact.read
 225  * @param[in] callback The callback function to register
 226  * @param[in] user_data The user data to be passed to the callback function
 227  * @return @c 0 on success,
 228  *         otherwise a negative error value
 229  * @retval #CONTACTS_ERROR_NONE Successful
 230  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 231  * @retval #CONTACTS_ERROR_PERMISSION_DENIED Permission denied. This application does not have the privilege to call this method
 232  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 233  * @retval #CONTACTS_ERROR_IPC Unknown IPC error
 234  * @retval #CONTACTS_ERROR_INTERNAL Implementation Error, Temporary Use
 235  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 236  * @pre contacts_connect() should be called to open a connection to the contacts service.
 237  * @post contacts_setting_name_sorting_order_changed_cb() will be called under certain conditions, after calling contacts_setting_set_name_sorting_order().
 238  * @see contacts_connect()
 239  * @see contacts_setting_remove_name_sorting_order_changed_cb()
 240  */
 241 int contacts_setting_add_name_sorting_order_changed_cb(contacts_setting_name_sorting_order_changed_cb callback, void *user_data);
 242
 243
 244 /**
 245  * @brief Unregisters a callback function.
 246  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 247  * @param[in] callback The callback function to register
 248  * @param[in] user_data The user data to be passed to the callback function
 249  * @return @c 0 on success,
 250  *         otherwise a negative error value
 251  * @retval #CONTACTS_ERROR_NONE Successful
 252  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 253  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 254  * @retval #CONTACTS_ERROR_INTERNAL Implementation Error, Temporary Use
 255  * @retval #CONTACTS_ERROR_SYSTEM Internal system module error
 256  * @pre contacts_connect() should be called to open a connection to the contacts service.
 257  * @see contacts_connect()
 258  * @see contacts_setting_add_name_sorting_order_changed_cb()
 259  */
 260 int contacts_setting_remove_name_sorting_order_changed_cb(contacts_setting_name_sorting_order_changed_cb callback, void *user_data);
 261
 262
 263 /**
 264  * @}
 265  */
 266
 267
 268 #ifdef __cplusplus
 269 }
 270 #endif
 271
 272
 273 #endif /* __TIZEN_SOCIAL_CONTACTS_SETTING_H__ */
 274