include/calllog.h

   1 /*
   2  * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef __TIZEN_CALLLOG_H__
  19 #define __TIZEN_CALLLOG_H__
  20
  21 #include <calllog_types.h>
  22
  23 #ifdef __cplusplus
  24 extern "C"
  25 {
  26 #endif
  27 /**
  28  * @addtogroup CAPI_SOCIAL_CALLLOG_MODULE
  29  * @{
  30  */
  31
  32 /**
  33  * @brief       Opens a connection to call log service.
  34  *
  35  * @details    Opening connection is necessary to access call log database.
  36  * All operations like inserting, updating, and deleting call log require opened connection.
  37
  38  * @remarks  If the call log connection has been already established, this function will return #CALLLOG_ERROR_NONE.
  39  *
  40  * @return  0 on success, otherwise a negative error value.
  41  * @retval  #CALLLOG_ERROR_NONE        Successful
  42  * @retval  #CALLLOG_ERROR_DB_FAILED        Failed to connect
  43  *
  44  * @see calllog_disconnect()
  45  *
  46  */
  47
  48 int calllog_connect(void);
  49
  50 /**
  51  * @brief       Closes the connection to call log service.
  52  *
  53  * @return  0 on success, otherwise a negative error value.
  54  * @retval  #CALLLOG_ERROR_NONE            Successful
  55  * @retval  #CALLLOG_ERROR_DB_FAILED           Database failed
  56  *
  57  * @see calllog_connect()
  58  */
  59 int calllog_disconnect(void);
  60
  61 /**
  62  * @brief       Registers a callback function to be invoked when the call log changes.
  63  *
  64  * @param[in]   callback        The callback function to register
  65  * @param[in]   user_data       The user data to be passed to the callback function
  66  *
  67  * @return  0 on success, otherwise a negative error value.
  68  * @retval      #CALLLOG_ERROR_NONE                Successful
  69  * @retval      #CALLLOG_ERROR_INVALID_PARAMETER   Invalid parameter
  70  *
  71  * @pre     This function requires an open connection to the call log service by calllog_connect().
  72  * @post calllog_db_changed_cb() will be invoked when the call log changes.
  73  *
  74  * @see calllog_connect()
  75  * @see calllog_db_changed_cb()
  76  * @see calllog_insert_to_db()
  77  * @see calllog_update_missed_unchecked_to_checked_to_db()
  78  * @see calllog_delete_from_db()
  79  */
  80 int calllog_add_calllog_db_changed_cb(calllog_db_changed_cb callback, void *user_data);
  81
  82 /**
  83  * @brief       Unregisters the callback function.
  84  *
  85  * @param[in]   callback            The callback function to unregister
  86  *
  87  * @return  0 on success, otherwise a negative error value.
  88  * @retval  #CALLLOG_ERROR_NONE                Successful
  89  * @retval  #CALLLOG_ERROR_INVALID_PARAMETER   Invalid parameter
  90  *
  91  * @see calllog_db_changed_cb()
  92  * @see calllog_add_calllog_db_changed_cb()
  93  */
  94 int calllog_remove_calllog_db_changed_cb(calllog_db_changed_cb callback);
  95
  96 /**
  97  * @brief       Creates a new call log handle.
  98  * @remarks The call log handle must be released with calllog_destroy() by you.
  99  * @remarks    The created handle is not added to call log database until calllog_insert_to_db() is called.
 100  *
 101  * @param[out]  log    A new call log handle
 102  *
 103  * @return  0 on success, otherwise a negative error value.
 104  * @retval  #CALLLOG_ERROR_NONE                Successful
 105  * @retval  #CALLLOG_ERROR_OUT_OF_MEMORY       Out of memory
 106  * @retval  #CALLLOG_ERROR_INVALID_PARAMETER   Invalid parameter
 107  *
 108  * @see calllog_destroy()
 109  *
 110  */
 111 int calllog_create(calllog_h *log);
 112
 113 /**
 114  * @brief       Destroys the call log handle.
 115  *
 116  *
 117  * @param[in]   log     The call log handle
 118  *
 119  * @return  0 on success, otherwise a negative error value.
 120  * @retval  #CALLLOG_ERROR_NONE                Successful
 121  * @retval  #CALLLOG_ERROR_INVALID_PARAMETER   Invalid parameter
 122  *
 123  * @see calllog_create()
 124  */
 125 int calllog_destroy(calllog_h log);
 126
 127 /**
 128  * @brief       Inserts a new call log entry to the call log database.
 129  *
 130  *
 131  *
 132  * @param[in]   log         The call log handle
 133  *
 134  * @return  0 on success, otherwise a negative error value.
 135  * @retval  #CALLLOG_ERROR_NONE            Successful
 136  * @retval  #CALLLOG_ERROR_INVALID_PARAMETER        Invalid parameter
 137  * @retval  #CALLLOG_ERROR_DB_FAILED           Database failed
 138  *
 139  * @pre     This function requires an open connection to call log service by calllog_connect().
 140  *
 141  * @see calllog_connect()
 142  * @see calllog_disconnect()
 143  * @see calllog_delete_from_db()
 144  * @see calllog_delete_all_from_db()
 145  *
 146  */
 147 int calllog_insert_to_db(calllog_h log);
 148
 149 /**
 150  * @brief       Deletes the call log with given ID from the database.
 151  *
 152  * @param[in]   calllog_db_id      The database identifier of call log to delete
 153  *
 154  * @return  0 on success, otherwise a negative error value
 155  * @retval  #CALLLOG_ERROR_NONE                Successful
 156  * @retval  #CALLLOG_ERROR_INVALID_PARAMETER   Invalid parameter
 157  * @retval  #CALLLOG_ERROR_DB_FAILED           Database failed
 158  *
 159  * @pre     This function requires an open connection to call log service by calllog_connect().
 160  *
 161  * @see calllog_connect()
 162  * @see calllog_disconnect()
 163  * @see calllog_insert_to_db()
 164  * @see calllog_delete_all_from_db()
 165  */
 166 int calllog_delete_from_db(int calllog_db_id);
 167
 168 /**
 169  * @brief       Deletes all the call log from the database.
 170  *
 171  * @return  0 on success, otherwise a negative error value
 172  * @retval  #CALLLOG_ERROR_NONE                Successful
 173  * @retval  #CALLLOG_ERROR_OUT_OF_MEMORY       Out of memory
 174  * @retval  #CALLLOG_ERROR_INVALID_PARAMETER   Invalid parameter
 175  * @retval  #CALLLOG_ERROR_DB_FAILED           Database failed
 176  *
 177  * @pre     This function requires an open connection to call log service by calllog_connect().
 178  *
 179  * @see calllog_connect()
 180  * @see calllog_disconnect()
 181  * @see calllog_insert_to_db()
 182  * @see calllog_delete_from_db()
 183  */
 184 int calllog_delete_all_from_db(void);
 185
 186 /**
 187  * @brief       Updates the call log status of missed call from unchecked to checked.
 188  *
 189  * @param[in]   calllog_db_id      The database ID of call log to update \n
 190  * The type of call log must be #CALLLOG_TYPE_VOICE_MISSED_UNCHECKED or #CALLLOG_TYPE_VIDEO_MISSED_UNCHECKED (If not, #CALLLOG_ERROR_INVALID_PARAMETER occurred)
 191  *
 192  * @return  0 on success, otherwise a negative error value
 193  * @retval  #CALLLOG_ERROR_NONE                Successful
 194  * @retval  #CALLLOG_ERROR_INVALID_PARAMETER   Call log doesn't exist
 195  * @retval  #CALLLOG_ERROR_DB_FAILED           Database failed
 196  *
 197  * @see  calllog_query_calllog_by_number()
 198  * @see calllog_set_type()
 199  * @see calllog_get_type()
 200  */
 201 int calllog_update_missed_unchecked_to_checked_to_db(int calllog_db_id);
 202
 203 /**
 204  * @brief       Gets the time from the call log handle.
 205  *
 206  *
 207  * @param[in]   log         The call log handle
 208  * @param[out]  log_time   The log time in UNIX-time format
 209  *
 210  * @return 0 on success, otherwise a negative error value.
 211  * @retval  #CALLLOG_ERROR_NONE                Successful
 212  * @retval  #CALLLOG_ERROR_INVALID_PARAMETER   Invalid parameter
 213  *
 214  * @see calllog_set_time()
 215  */
 216 int calllog_get_time(calllog_h log, time_t *log_time);
 217
 218 /**
 219  * @brief       Sets a log time to the call log handle.
 220  *
 221  *
 222  * @param[in]   log         The call log handle
 223  * @param[in]   log_time    The log time in UNIX-time format
 224  *
 225  * @return 0 on success, otherwise a negative error value.
 226  * @retval  #CALLLOG_ERROR_NONE                Successful
 227  * @retval  #CALLLOG_ERROR_INVALID_PARAMETER   Invalid parameter
 228  *
 229  * @see calllog_get_time()
 230  */
 231 int calllog_set_time(calllog_h log, time_t log_time);
 232
 233 /**
 234  * @brief       Gets the log type from the call log handle.
 235  *
 236  *
 237  * @param[in]   log         The call log handle
 238  * @param[out]  type       The log type
 239  *
 240  * @return 0 on success, otherwise a negative error value.
 241  * @retval  #CALLLOG_ERROR_NONE                Successful
 242  * @retval  #CALLLOG_ERROR_INVALID_PARAMETER   Invalid parameter
 243  *
 244  * @see calllog_set_type()
 245  */
 246 int calllog_get_type(calllog_h log, calllog_type_e *type);
 247
 248 /**
 249  * @brief       Sets a log type to the call log handle.
 250  *
 251  *
 252  * @param[in]   log        The call log handle
 253  * @param[in]   type       The log type
 254  *
 255  * @return 0 on success, otherwise a negative error value.
 256  * @retval  #CALLLOG_ERROR_NONE                Successful
 257  * @retval  #CALLLOG_ERROR_INVALID_PARAMETER   Invalid parameter
 258  *
 259  * @see calllog_get_type()
 260  */
 261 int calllog_set_type(calllog_h log, calllog_type_e type);
 262
 263 /**
 264  * @brief       Gets the call duration from the call log handle.
 265  *
 266  *
 267  * @param[in]   log         The call log handle
 268  * @param[out]  duration_sec   The call duration (seconds)
 269  *
 270  * @return 0 on success, otherwise a negative error value.
 271  * @retval  #CALLLOG_ERROR_NONE                Successful
 272  * @retval  #CALLLOG_ERROR_INVALID_PARAMETER   Invalid parameter
 273  *
 274  * @see  calllog_set_duration()
 275  */
 276 int calllog_get_duration(calllog_h log, int *duration_sec);
 277
 278 /**
 279  * @brief       Sets the call duration to the call log handle.
 280  *
 281  * @param[in]   log         The call log handle
 282  * @param[in]   duration_sec   The call duration (seconds)
 283  *
 284  * @return 0 on success, otherwise a negative error value.
 285  * @retval  #CALLLOG_ERROR_NONE                Successful
 286  * @retval  #CALLLOG_ERROR_INVALID_PARAMETER   Invalid parameter
 287  *
 288  * @see calllog_get_duration()
 289  */
 290 int calllog_set_duration(calllog_h log, int duration_sec);
 291
 292 /**
 293  * @brief       Gets the phone number from the call log handle.
 294  *
 295  * @remarks     @a number must be released with free() by you.
 296  *
 297  * @param[in]   log         The call log handle
 298  * @param[out]  number      The phone number \n If the number does not exist, it is NULL
 299  *
 300  * @return 0 on success, otherwise a negative error value.
 301  * @retval  #CALLLOG_ERROR_NONE                Successful
 302  * @retval  #CALLLOG_ERROR_INVALID_PARAMETER   Invalid parameter
 303  *
 304  * @see calllog_set_number()
 305  */
 306 int calllog_get_number(calllog_h log, char **number);
 307
 308 /**
 309  * @brief       Sets the phone number to the call log handle.
 310  *
 311  *
 312  * @param[in]   log         The call log handle
 313  * @param[in]   number      The phone number
 314  *
 315  * @return 0 on success, otherwise a negative error value.
 316  * @retval  #CALLLOG_ERROR_NONE                Successful
 317  * @retval  #CALLLOG_ERROR_INVALID_PARAMETER   Invalid parameter
 318  *
 319  * @see calllog_get_number()
 320  *
 321  */
 322 int calllog_set_number(calllog_h log, const char *number);
 323
 324 /**
 325  * @brief       Retrieves all call logs by invoking the given callback function iteratively.
 326  *
 327  * @param[in]   callback        The callback function
 328  * @param[in]   user_data       The user data to be passed to the callback function
 329  *
 330  * @return  0 on success, otherwise a negative error value.
 331  * @retval  #CALLLOG_ERROR_NONE                Successful
 332  * @retval  #CALLLOG_ERROR_INVALID_PARAMETER   Invalid parameter
 333  * @retval  #CALLLOG_ERROR_DB_FAILED           Database failed
 334  *
 335  * @pre     This function requires an open connection to call log service by calllog_connect().
 336  *
 337  * @post        This function invokes calllog_foreach_cb().
 338  *
 339  * @see calllog_connect()
 340  * @see calllog_foreach_cb()
 341  * @see calllog_query_calllog_by_number()
 342  */
 343 int calllog_foreach_calllog_from_db(calllog_foreach_cb callback, void *user_data);
 344
 345 /**
 346  * @brief        Retrieves all call logs with the given number.
 347  *
 348  * @param[in]   callback            The callback function to invoke
 349  * @param[in]   number_to_find  The number to filter
 350  * @param[in]   user_data       The user data to be passed to the callback function
 351  *
 352  * @return  0 on success, otherwise a negative error value.
 353  * @retval  #CALLLOG_ERROR_NONE                Successful
 354  * @retval  #CALLLOG_ERROR_INVALID_PARAMETER   Invalid parameter
 355  * @retval  #CALLLOG_ERROR_DB_FAILED           Database failed
 356  *
 357  * @pre     This function requires an open connection to call log service by calllog_connect().
 358  *
 359  * @post        This function invokes calllog_foreach_cb().
 360  *
 361  * @see calllog_connect()
 362  * @see calllog_foreach_cb()
 363  * @see calllog_foreach_calllog_from_db()
 364  */
 365 int calllog_query_calllog_by_number(calllog_foreach_cb callback, const char *number_to_find, void *user_data);
 366
 367 /**
 368  * @}
 369  */
 370
 371 #ifdef __cplusplus
 372 }
 373 #endif
 374
 375 #endif /* __TIZEN_CALLLOG_H__ */
 376