include/context_history.h

   1 /*
   2  * Copyright (c) 2015 Samsung Electronics Co., Ltd.
   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 #ifndef __TIZEN_CONTEXT_HISTORY_H__
  18 #define __TIZEN_CONTEXT_HISTORY_H__
  19
  20
  21 #include <tizen_error.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif /* __cplusplus */
  26
  27 /**
  28  * @addtogroup CAPI_CONTEXT_HISTORY_MODULE
  29  * @{
  30  */
  31
  32 /**
  33  * @brief       The attribute key denoting "application id"
  34  * @since_tizen 2.4
  35  */
  36 #define CONTEXT_HISTORY_APP_ID "AppId"
  37
  38 /**
  39  * @brief       The attribute key denoting "total count"
  40  * @since_tizen 2.4
  41  */
  42 #define CONTEXT_HISTORY_TOTAL_COUNT "TotalCount"
  43
  44 /**
  45  * @brief       The attribute key denoting "total duration"
  46  * @since_tizen 2.4
  47  */
  48 #define CONTEXT_HISTORY_TOTAL_DURATION "TotalDuration"
  49
  50 /**
  51  * @brief       The attribute key denoting "last time"
  52  * @since_tizen 2.4
  53  */
  54 #define CONTEXT_HISTORY_LAST_TIME "LastTime"
  55
  56 /**
  57  * @brief       The attribute key denoting "hour of day"
  58  * @since_tizen 2.4
  59  */
  60 #define CONTEXT_HISTORY_HOUR_OF_DAY "HourOfDay"
  61
  62 /**
  63  * @brief       The attribute key denoting "audio jack status"
  64  * @since_tizen 2.4
  65  */
  66 #define CONTEXT_HISTORY_AUDIO_JACK "AudioJack"
  67
  68 /**
  69  * @brief       The attribute key denoting "system volume"
  70  * @since_tizen 2.4
  71  */
  72 #define CONTEXT_HISTORY_SYSTEM_VOLUME "SystemVolume"
  73
  74 /**
  75  * @brief       The attribute key denoting "media volume"
  76  * @since_tizen 2.4
  77  */
  78 #define CONTEXT_HISTORY_MEDIA_VOLUME "MediaVolume"
  79
  80 /**
  81  * @brief       The attribute key denoting "address"
  82  * @since_tizen 2.4
  83  */
  84 #define CONTEXT_HISTORY_ADDRESS "Address"
  85
  86 /**
  87  * @brief               Enumeration for errors.
  88  * @since_tizen 2.4
  89  */
  90 typedef enum {
  91         CONTEXT_HISTORY_ERROR_NONE = TIZEN_ERROR_NONE,                                                  /**< Successful */
  92         CONTEXT_HISTORY_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,        /**< Invalid parameter */
  93         CONTEXT_HISTORY_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,        /**< Permission denied */
  94         CONTEXT_HISTORY_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED,                        /**< Not supported */
  95         CONTEXT_HISTORY_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,                        /**< Memory allocation failed */
  96         CONTEXT_HISTORY_ERROR_NO_DATA = TIZEN_ERROR_NO_DATA,                                            /**< No Data */
  97         CONTEXT_HISTORY_ERROR_OUT_OF_RANGE = (TIZEN_ERROR_CONTEXT | 0x03),              /**< Out of range */
  98         CONTEXT_HISTORY_ERROR_OPERATION_FAILED = (TIZEN_ERROR_CONTEXT | 0x04),  /**< Operation failed */
  99 } context_history_error_e;
 100
 101 /**
 102  * @brief               Enumeration for data types of statistics and patterns.
 103  * @since_tizen 2.4
 104  */
 105 typedef enum {
 106         CONTEXT_HISTORY_RECENTLY_USED_APP = 1,  /**< Recently used application.@n Privilege : http://tizen.org/privilege/apphistory.read*/
 107         CONTEXT_HISTORY_FREQUENTLY_USED_APP,    /**< Frequently used application.@n Privilege : http://tizen.org/privilege/apphistory.read*/
 108         CONTEXT_HISTORY_RARELY_USED_APP,                /**< Rarely used application.@n Privilege : http://tizen.org/privilege/apphistory.read*/
 109         CONTEXT_HISTORY_PEAK_TIME_FOR_APP,              /**< Peak time of application use activity.@n Privilege : http://tizen.org/privilege/apphistory.read*/
 110         CONTEXT_HISTORY_PEAK_TIME_FOR_MUSIC,            /**< Peak time of music listening activity.@n Privilege : http://tizen.org/privilege/mediahistory.read*/
 111         CONTEXT_HISTORY_PEAK_TIME_FOR_VIDEO,            /**< Peak time of video watching activity.@n Privilege : http://tizen.org/privilege/mediahistory.read*/
 112         CONTEXT_HISTORY_COMMON_SETTING_FOR_APP,         /**< Common setting value of application use activity.@n Privilege : http://tizen.org/privilege/apphistory.read*/
 113         CONTEXT_HISTORY_COMMON_SETTING_FOR_MUSIC,               /**< Common setting value of music listening activity.@n Privilege : http://tizen.org/privilege/mediahistory.read*/
 114         CONTEXT_HISTORY_COMMON_SETTING_FOR_VIDEO,               /**< Common setting value of video watching activity.@n Privilege : http://tizen.org/privilege/mediahistory.read*/
 115         CONTEXT_HISTORY_FREQUENTLY_COMMUNICATED_ADDRESS         /**< Frequently communicated address.@n Privilege : http://tizen.org/privilege/callhistory.read*/
 116 } context_history_data_e;
 117
 118 /**
 119  * @brief               Enumeration for filters of statistics and patterns.
 120  * @since_tizen 2.4
 121  */
 122 typedef enum {
 123         CONTEXT_HISTORY_FILTER_TIME_SPAN = 1,           /**< Time span of data in days*/
 124         CONTEXT_HISTORY_FILTER_RESULT_SIZE,                     /**< Result size of data records*/
 125         CONTEXT_HISTORY_FILTER_APP_ID,                  /**< Application id*/
 126         CONTEXT_HISTORY_FILTER_DAY_OF_WEEK,                     /**<  Weekdays, weekends*/
 127         CONTEXT_HISTORY_FILTER_START_TIME,                      /**< Start time of data in epoch time*/
 128         CONTEXT_HISTORY_FILTER_END_TIME,                        /**< End time of data in epoch time*/
 129         CONTEXT_HISTORY_FILTER_WIFI_BSSID,                      /**< Wi-Fi BSSID value*/
 130         CONTEXT_HISTORY_FILTER_AUDIO_JACK,                      /**< Audio jack status value*/
 131         CONTEXT_HISTORY_FILTER_COMMUNICATION_TYPE                       /**< Type of phone log*/
 132 } context_history_filter_e;
 133
 134 /**
 135  * @brief               Enumeration for day of week filter.
 136  * @since_tizen 2.4
 137  */
 138 typedef enum {
 139         CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_WEEKDAYS = 1,                /**< Includes only weekdays*/
 140         CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_WEEKENDS,            /**< Includes only weekends*/
 141         CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_ALL                  /**< Includes all days*/
 142 } context_history_filter_day_of_week_e;
 143
 144 /**
 145  * @brief               Enumeration for audio jack filter.
 146  * @since_tizen 2.4
 147  */
 148 typedef enum {
 149         CONTEXT_HISTORY_FILTER_AUDIO_JACK_NOT_CONNECTED = 0,            /**< Audio jack is not connected*/
 150         CONTEXT_HISTORY_FILTER_AUDIO_JACK_CONNECTED                     /**< Audio jack is connected*/
 151 } context_history_filter_audio_jack_e;
 152
 153 /**
 154  * @brief               Enumeration for log type filter.
 155  * @since_tizen 2.4
 156  */
 157 typedef enum {
 158         CONTEXT_HISTORY_FILTER_COMMUNICATION_TYPE_CALL = 1,             /**< Includes only call logs*/
 159         CONTEXT_HISTORY_FILTER_COMMUNICATION_TYPE_MESSAGE,              /**< Includes only message logs*/
 160         CONTEXT_HISTORY_FILTER_COMMUNICATION_TYPE_ALL                   /**< Includes all logs*/
 161 } context_history_filter_communication_type_e;
 162
 163 /**
 164  * @brief               Context history handle for retrieving statistics and patterns.
 165  * @since_tizen 2.4
 166  */
 167 typedef struct _context_history_handle_s* context_history_h;
 168
 169 /**
 170  * @brief               History filter handle to be used to compute statistics and patterns.
 171  * @since_tizen 2.4
 172  */
 173 typedef struct _context_history_filter_handle_s* context_history_filter_h;
 174
 175 /**
 176  * @brief               History list handle. It contains one or multiple records.
 177  * @since_tizen 2.4
 178  */
 179 typedef struct _context_history_list_handle_s* context_history_list_h;
 180
 181 /**
 182  * @brief               History record handle. It contains one or multiple attributes.
 183  * @since_tizen 2.4
 184  */
 185 typedef struct _context_history_record_handle_s* context_history_record_h;
 186
 187 /**
 188  * @brief               Creates a context history handle.
 189  * @since_tizen 2.4
 190  * @remarks             The @c handle must be released using context_history_destroy().
 191  *
 192  * @param[out] handle    Handle to be initialized
 193  *
 194  * @return              0 on success, otherwise a negative error value
 195  * @retval              #CONTEXT_HISTORY_ERROR_NONE                                     Successful
 196  * @retval              #CONTEXT_HISTORY_ERROR_INVALID_PARAMETER                Invalid parameter
 197  * @retval              #CONTEXT_HISTORY_ERROR_OUT_OF_MEMORY                    Out of memory
 198  *
 199  * @see context_history_destroy()
 200  */
 201 int context_history_create(context_history_h* handle);
 202
 203 /**
 204  * @brief               Releases the resources occupied by a handle.
 205  * @details             This releases the memory allocated for the @c handle.
 206  *
 207  * @since_tizen 2.4
 208  *
 209  * @param[in]  handle   Handle to be released
 210  *
 211  * @return              0 on success, otherwise a negative error value
 212  * @retval              #CONTEXT_HISTORY_ERROR_NONE                                     Successful
 213  * @retval              #CONTEXT_HISTORY_ERROR_INVALID_PARAMETER                Invalid parameter
 214  *
 215  * @pre context_history_create()
 216  */
 217 int context_history_destroy(context_history_h handle);
 218
 219 /**
 220  * @brief               Creates a history filter.
 221  * @since_tizen 2.4
 222  * @remarks             The @c filter must be released using context_history_filter_destroy().
 223  *
 224  * @param[out]  filter          Filter handle to be initialized
 225  *
 226  * @return              0 on success, otherwise a negative error value
 227  * @retval              #CONTEXT_HISTORY_ERROR_NONE                                     Successful
 228  * @retval              #CONTEXT_HISTORY_ERROR_INVALID_PARAMETER        Invalid parameter
 229  * @retval              #CONTEXT_HISTORY_ERROR_OUT_OF_MEMORY            Memory allocation failed
 230  *
 231  * @see         context_history_filter_destroy()
 232  */
 233 int context_history_filter_create(context_history_filter_h* filter);
 234
 235 /**
 236  * @brief               Releases the resources occupied by a filter.
 237  * @details             This releases the memory allocated for the @c filter.
 238  * @since_tizen 2.4
 239  *
 240  * @param[in]   filter          Filter handle to be released
 241  *
 242  * @return              0 on success, otherwise a negative error value
 243  * @retval              #CONTEXT_HISTORY_ERROR_NONE                                     Successful
 244  * @retval              #CONTEXT_HISTORY_ERROR_INVALID_PARAMETER        Invalid parameter
 245  *
 246  * @pre         context_history_filter_create()
 247  */
 248 int context_history_filter_destroy(context_history_filter_h filter);
 249
 250 /**
 251  * @brief               Sets an integer value to a filter.
 252  * @details             This sets the value to a filter.
 253  * @since_tizen 2.4
 254  *
 255  * @param[in]   filter          The filter handle
 256  * @param[in]   filter_type     The filter type to set
 257  * @param[in]   value           The value to be set
 258  *
 259  * @return              0 on success, otherwise a negative error value
 260  * @retval              #CONTEXT_HISTORY_ERROR_NONE                                     Successful
 261  * @retval              #CONTEXT_HISTORY_ERROR_INVALID_PARAMETER        Invalid parameter
 262  *
 263  * @pre         context_history_filter_create()
 264  * @see         context_history_filter_set_string()
 265   */
 266 int context_history_filter_set_int(context_history_filter_h filter, context_history_filter_e filter_type, int value);
 267
 268 /**
 269  * @brief               Sets a string to a filter.
 270  * @details             This sets the value to a filter.
 271  * @since_tizen 2.4
 272  *
 273  * @param[in]   filter          The filter handle
 274  * @param[in]   filter_type     The filter type to set
 275  * @param[in]   value           The value to be set
 276  *
 277  * @return              0 on success, otherwise a negative error value
 278  * @retval              #CONTEXT_HISTORY_ERROR_NONE                                     Successful
 279  * @retval              #CONTEXT_HISTORY_ERROR_INVALID_PARAMETER        Invalid parameter
 280  *
 281  * @pre         context_history_filter_create()
 282  * @see         context_history_filter_set_int()
 283   */
 284 int context_history_filter_set_string(context_history_filter_h filter, context_history_filter_e filter_type, const char* value);
 285
 286 /**
 287  * @brief               Reads context statistics or patterns.
 288  * @details             Retrieves a given type of context statistics or patterns list.
 289  * @since_tizen 2.4
 290  *
 291  * @privlevel public
 292  * @privilege   %http://tizen.org/privilege/apphistory.read
 293  * @privilege   %http://tizen.org/privilege/mediahistory.read
 294  *
 295  * @remarks             The @c list must be released using context_history_list_destroy(). \n
 296  *              %http://tizen.org/privilege/apphistory.read or %http://tizen.org/privilege/mediahistory.read is needed to retrieve data. It depends on context data type #context_history_data_e.
 297  *
 298  * @param[in]   handle      Handle for controlling the context history data requests
 299  * @param[in]   data_type       Type of the history data
 300  * @param[in]   filter          Filter to be used to compute statistics or patterns. This can not be @c NULL
 301  * @param[out]  list   History data retrieved. This should be freed after use
 302  *
 303  * @return              0 on success, otherwise a negative error value
 304  * @retval              #CONTEXT_HISTORY_ERROR_NONE                                     Successful
 305  * @retval              #CONTEXT_HISTORY_ERROR_INVALID_PARAMETER                Invalid parameter
 306  * @retval              #CONTEXT_HISTORY_ERROR_OPERATION_FAILED         Operation failed
 307  * @retval              #CONTEXT_HISTORY_ERROR_OUT_OF_MEMORY                    Out of memory
 308  * @retval              #CONTEXT_HISTORY_ERROR_NO_DATA                  Requested data does not exist
 309  *
 310  * @pre context_history_create()
 311  * @post context_history_list_destroy()
 312  */
 313 int context_history_get_list(context_history_h handle, context_history_data_e data_type, context_history_filter_h filter, context_history_list_h* list);
 314
 315 /**
 316  * @brief               Retrieves the number of records in a list.
 317  * @since_tizen 2.4
 318  *
 319  * @param[in]   list    The history data list handle
 320  * @param[out]  count   The count of the data list
 321  *
 322  * @return              0 on success, otherwise a negative error value
 323  * @retval              #CONTEXT_HISTORY_ERROR_NONE                                     Successful
 324  * @retval              #CONTEXT_HISTORY_ERROR_INVALID_PARAMETER                Invalid parameter
 325  * @retval              #CONTEXT_HISTORY_ERROR_OPERATION_FAILED         Operation failed
 326  *
 327  * @pre context_history_get_list()
 328  * @see context_history_list_move_first()
 329  * @see context_history_list_move_next()
 330  */
 331 int context_history_list_get_count(context_history_list_h list, int* count);
 332
 333 /**
 334  * @brief               Retrieves the current record from the history list.
 335  * @details             The default current record is the first record.
 336  * @since_tizen 2.4
 337  * @remarks             The @c record must be released using context_history_record_destroy().
 338  *
 339  * @param[in]   list      The context history list handle
 340  * @param[out]  record   History data record retrieved
 341  *
 342  * @return              0 on success, otherwise a negative error value
 343  * @retval              #CONTEXT_HISTORY_ERROR_NONE                                     Successful
 344  * @retval              #CONTEXT_HISTORY_ERROR_INVALID_PARAMETER                Invalid parameter
 345  * @retval              #CONTEXT_HISTORY_ERROR_OPERATION_FAILED         Operation failed
 346  * @retval              #CONTEXT_HISTORY_ERROR_OUT_OF_MEMORY                    Out of memory
 347  *
 348  * @pre context_history_get_list()
 349  * @post context_history_record_destroy()
 350  */
 351 int context_history_list_get_current(context_history_list_h list, context_history_record_h* record);
 352
 353 /**
 354  * @brief               Moves a history data list to the first position.
 355  * @since_tizen 2.4
 356  *
 357  * @param[in]   list    The context history list handle
 358  *
 359  * @return              0 on success, otherwise a negative error value
 360  * @retval              #CONTEXT_HISTORY_ERROR_NONE                                     Successful
 361  * @retval              #CONTEXT_HISTORY_ERROR_INVALID_PARAMETER                Invalid parameter
 362  *
 363  * @pre context_history_get_list()
 364  * @see context_history_list_get_count()
 365  * @see context_history_list_move_next()
 366  */
 367 int context_history_list_move_first(context_history_list_h list);
 368
 369 /**
 370  * @brief               Moves a history data list to the next position.
 371  * @since_tizen 2.4
 372  *
 373  * @param[in]   list    The context history list handle
 374  *
 375  * @return              0 on success, otherwise a negative error value
 376  * @retval              #CONTEXT_HISTORY_ERROR_NONE                                     Successful
 377  * @retval              #CONTEXT_HISTORY_ERROR_INVALID_PARAMETER                Invalid parameter
 378  * @retval              #CONTEXT_HISTORY_ERROR_NO_DATA                  Requested data does not exist
 379  *
 380  * @pre context_history_get_list()
 381  * @see context_history_list_get_count()
 382  * @see context_history_list_move_first()
 383  */
 384 int context_history_list_move_next(context_history_list_h list);
 385
 386 /**
 387  * @brief               Destroys a history list handle and release all its resources.
 388  * @since_tizen 2.4
 389  *
 390  * @param[in]   list    The context history data handle
 391  *
 392  * @return              0 on success, otherwise a negative error value
 393  * @retval              #CONTEXT_HISTORY_ERROR_NONE                                     Successful
 394  * @retval              #CONTEXT_HISTORY_ERROR_INVALID_PARAMETER                Invalid parameter
 395  *
 396  * @pre context_history_get_list()
 397  */
 398 int context_history_list_destroy(context_history_list_h list);
 399
 400 /**
 401  * @brief               Gets an integer value from a record.
 402  * @since_tizen 2.4
 403  *
 404  * @param[in]   record          The record handle
 405  * @param[in]   key                     The key of attribute to get
 406  * @param[out]  value           The result value
 407  *
 408  * @return              0 on success, otherwise a negative error value
 409  * @retval              #CONTEXT_HISTORY_ERROR_NONE                                     Successful
 410  * @retval              #CONTEXT_HISTORY_ERROR_INVALID_PARAMETER        Invalid parameter
 411  *
 412  * @pre         context_history_list_get_current()
 413  * @see         context_history_record_get_string()
 414  */
 415 int context_history_record_get_int(context_history_record_h record,  const char* key, int* value);
 416
 417 /**
 418  * @brief               Gets a string from a record.
 419  * @since_tizen 2.4
 420  * @remarks             @c value must be released using free().
 421  *
 422  * @param[in]   record          The record handle
 423  * @param[in]   key                     The key of attribute to get
 424  * @param[out]  value           The result value
 425  *
 426  * @return              0 on success, otherwise a negative error value
 427  * @retval              #CONTEXT_HISTORY_ERROR_NONE                                     Successful
 428  * @retval              #CONTEXT_HISTORY_ERROR_INVALID_PARAMETER        Invalid parameter
 429  *
 430  * @pre         context_history_list_get_current()
 431  * @see         context_history_record_get_int()
 432  */
 433 int context_history_record_get_string(context_history_record_h record, const char* key, char** value);
 434
 435 /**
 436  * @brief               Destroys a record handle and releases all its resources.
 437  * @since_tizen 2.4
 438  *
 439  * @param[in]   record          The record handle
 440  *
 441  * @return              0 on success, otherwise a negative error value
 442  * @retval              #CONTEXT_HISTORY_ERROR_NONE                                     Successful
 443  * @retval              #CONTEXT_HISTORY_ERROR_INVALID_PARAMETER        Invalid parameter
 444  *
 445  * @pre         context_history_list_get_current()
 446  */
 447 int context_history_record_destroy(context_history_record_h record);
 448
 449 #ifdef __cplusplus
 450 }
 451 #endif /* __cplusplus */
 452
 453 /**
 454 * @}
 455 */
 456
 457 #endif /* __TIZEN_CONTEXT_HISTORY_H__ */