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 #ifndef __TIZEN_SOCIAL_CONTACTS_SETTING_H__
  20 #define __TIZEN_SOCIAL_CONTACTS_SETTING_H__
  21
  22
  23 #ifdef __cplusplus
  24 extern "C"
  25 {
  26 #endif
  27
  28 /**
  29  * @file contacts_setting.h
  30  */
  31
  32 /**
  33  * @ingroup CAPI_SOCIAL_CONTACTS_SVC_MODULE
  34  * @defgroup CAPI_SOCIAL_CONTACTS_SVC_SETTING_MODULE Setting
  35  *
  36  * @brief The contacts setting API provides the set of definitions and interfaces that enable application developers to set up contacts features.
  37  *
  38  * @section CAPI_SOCIAL_CONTACTS_SVC_SETTING_MODULE_HEADER Required Header
  39  *  \#include <contacts.h>
  40  *
  41  * <BR>
  42  * @{
  43  */
  44
  45 /**
  46  * @brief Enumeration for name display order.
  47  *
  48  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
  49  *
  50  */
  51 typedef enum
  52 {
  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;
  56
  57 /**
  58  * @brief Gets the contacts name display order.
  59  *
  60  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
  61  * @privlevel public
  62  * @privilege %http://tizen.org/privilege/contact.read
  63  *
  64  * @param[out]  name_display_order    The name display order
  65  *
  66  * @return  @c 0 on success,
  67  *          otherwise a negative error value
  68  *
  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
  74  *
  75  * @pre     contacts_connect() should be called to open a connection to the contacts service.
  76  *
  77  * @see contacts_connect()
  78  */
  79 int contacts_setting_get_name_display_order(contacts_name_display_order_e *name_display_order);
  80
  81 /**
  82  * @brief Sets the contacts name display order.
  83  *
  84  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
  85  * @privlevel public
  86  * @privilege %http://tizen.org/privilege/contact.write
  87  *
  88  * @param[in]  name_display_order    The name display order
  89  *
  90  * @return  @c 0 on success,
  91  *          otherwise a negative error value
  92  *
  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
  99  *
 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.
 102  *
 103  * @see contacts_connect()
 104  */
 105 int contacts_setting_set_name_display_order(contacts_name_display_order_e name_display_order);
 106
 107
 108 /**
 109  * @brief Enumeration for name sorting order.
 110  *
 111  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
 112  *
 113  */
 114 typedef enum
 115 {
 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;
 119
 120
 121 /**
 122  * @brief Gets the contacts name sorting order in which contacts are returned.
 123  *
 124  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
 125  * @privlevel public
 126  * @privilege %http://tizen.org/privilege/contact.read
 127  *
 128  * @param[out]  name_sorting_order    The name sorting order
 129  *
 130  * @return  @c 0 on success,
 131  *          otherwise a negative error value
 132  *
 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
 138  *
 139  * @pre     contacts_connect() should be called to open a connection to the contacts service.
 140  *
 141  * @see contacts_connect()
 142  */
 143 int contacts_setting_get_name_sorting_order(contacts_name_sorting_order_e *name_sorting_order);
 144
 145 /**
 146  * @brief Sets the contacts name sorting order in which contacts are returned.
 147  *
 148  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
 149  * @privlevel public
 150  * @privilege %http://tizen.org/privilege/contact.write
 151  *
 152  * @param[in]  name_sorting_order    The name sorting order
 153  *
 154  * @return  @c 0 on success,
 155  *          otherwise a negative error value
 156  *
 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
 163  *
 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.
 166  *
 167  * @see contacts_connect()
 168  */
 169 int contacts_setting_set_name_sorting_order(contacts_name_sorting_order_e name_sorting_order);
 170
 171 /**
 172  * @brief Called when a designated view changes.
 173  *
 174  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
 175  *
 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
 178  *
 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.
 181  *
 182  * @see contacts_setting_add_name_display_order_changed_cb()
 183  * @see contacts_setting_remove_name_display_order_changed_cb()
 184  */
 185 typedef void (*contacts_setting_name_display_order_changed_cb)(contacts_name_display_order_e name_display_order, void *user_data);
 186
 187
 188 /**
 189  * @brief Registers a callback function.
 190  *
 191  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
 192  * @privlevel public
 193  * @privilege %http://tizen.org/privilege/contact.read
 194  *
 195  * @param[in]   callback    The callback function to register
 196  * @param[in]   user_data   The user data to be passed to the callback function
 197  *
 198  * @return  @c 0 on success,
 199  *          otherwise a negative error value
 200  *
 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.
 206  *
 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().
 209  *
 210  * @see contacts_connect()
 211  * @see contacts_setting_remove_name_display_order_changed_cb()
 212  */
 213
 214 int contacts_setting_add_name_display_order_changed_cb(contacts_setting_name_display_order_changed_cb callback, void *user_data);
 215
 216 /**
 217  * @brief Unregisters a callback function.
 218  *
 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
 222  *
 223  * @return  @c 0 on success,
 224  *          otherwise a negative error value
 225  *
 226  * @retval  #CONTACTS_ERROR_NONE                Successful
 227  * @retval  #CONTACTS_ERROR_INVALID_PARAMETER   Invalid parameter
 228  * @retval  #CONTACTS_ERROR_INTERNAL            Implementation Error, Temporary Use
 229  *
 230  * @pre contacts_connect() should be called to open a connection to the contacts service.
 231  *
 232  * @see contacts_connect()
 233  * @see contacts_setting_add_name_display_order_changed_cb()
 234  */
 235
 236 int contacts_setting_remove_name_display_order_changed_cb(contacts_setting_name_display_order_changed_cb callback, void *user_data);
 237
 238 /**
 239  * @brief Called when a designated view changes.
 240  *
 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
 244  *
 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.
 247  *
 248  * @see contacts_setting_add_name_sorting_order_changed_cb()
 249  * @see contacts_setting_remove_name_sorting_order_changed_cb()
 250  */
 251 typedef void (*contacts_setting_name_sorting_order_changed_cb)(contacts_name_sorting_order_e name_sorting_order, void *user_data);
 252
 253
 254 /**
 255  * @brief Registers a callback function.
 256  *
 257  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.4 @endif
 258  * @privlevel public
 259  * @privilege %http://tizen.org/privilege/contact.read
 260  *
 261  * @param[in]   callback    The callback function to register
 262  * @param[in]   user_data   The user data to be passed to the callback function
 263  *
 264  * @return  @c 0 on success,
 265  *          otherwise a negative error value
 266  *
 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.
 272  *
 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().
 275  *
 276  * @see contacts_connect()
 277  * @see contacts_setting_remove_name_sorting_order_changed_cb()
 278  */
 279
 280 int contacts_setting_add_name_sorting_order_changed_cb(contacts_setting_name_sorting_order_changed_cb callback, void *user_data);
 281
 282 /**
 283  * @brief Unregisters a callback function.
 284  *
 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
 288  *
 289  * @return  @c 0 on success,
 290  *          otherwise a negative error value
 291  *
 292  * @retval  #CONTACTS_ERROR_NONE                Successful
 293  * @retval  #CONTACTS_ERROR_INVALID_PARAMETER   Invalid parameter
 294  * @retval  #CONTACTS_ERROR_INTERNAL            Implementation Error, Temporary Use
 295  *
 296  * @pre contacts_connect() should be called to open a connection to the contacts service.
 297  *
 298  * @see contacts_connect()
 299  * @see contacts_setting_add_name_sorting_order_changed_cb()
 300  */
 301
 302 int contacts_setting_remove_name_sorting_order_changed_cb(contacts_setting_name_sorting_order_changed_cb callback, void *user_data);
 303
 304 /**
 305  * @}
 306  */
 307
 308 #ifdef __cplusplus
 309 }
 310 #endif
 311
 312
 313 #endif /* __TIZEN_SOCIAL_CONTACTS_SETTING_H__ */