Tizen Native API
5.5
|
The contextual history API provides functions for reading contextual history data.
This API allows you to query statistics and patterns derived from contextual history data.
Required Header
#include <context_history.h>
Overview
An application can retrieve the user's device usages statistics and patterns via the contextual history API. This API mainly provides three categories of statistical usage patterns, including application usage, peak time of activities, and common setting for activities. See context_history_data_e for all available statistic items. After choosing a statistic item to retrieve, a filter can be set to narrow down to the data you need.
For more details about the available filter keys and the data attributes provided by each item, please refer the programming guide and the tutorial.
Related Features
This API is related with the following features:
- http://tizen.org/feature/app_history
And some of the statistic items in this API are related with one of the following features:
- http://tizen.org/feature/battery
It is recommended to design feature related code in your application for reliability.
For your convenience, context_history_is_supported() is provided. Applications can use this function to check the availability of a necessary statistic item in the current device.
In general, you can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application. To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK. More details on featuring your application can be found from Feature Element.
Functions | |
int | context_history_create (context_history_h *handle) |
Creates a context history handle. | |
int | context_history_destroy (context_history_h handle) |
Releases the resources occupied by a handle. | |
int | context_history_filter_create (context_history_filter_h *filter) |
Creates a history filter. | |
int | context_history_filter_destroy (context_history_filter_h filter) |
Releases the resources occupied by a filter. | |
int | context_history_filter_set_int (context_history_filter_h filter, context_history_filter_e filter_type, int value) |
Sets an integer value to a filter. | |
int | context_history_filter_set_string (context_history_filter_h filter, context_history_filter_e filter_type, const char *value) TIZEN_DEPRECATED_API |
Sets a string to a filter. | |
int | context_history_is_supported (context_history_data_e data_type, bool *supported) |
Checks whether a history data type is supported in the current device. | |
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) |
Reads context statistics or patterns. | |
int | context_history_list_get_count (context_history_list_h list, int *count) |
Retrieves the number of records in a list. | |
int | context_history_list_get_current (context_history_list_h list, context_history_record_h *record) |
Retrieves the current record from the history list. | |
int | context_history_list_move_first (context_history_list_h list) |
Moves a history data list to the first position. | |
int | context_history_list_move_next (context_history_list_h list) |
Moves a history data list to the next position. | |
int | context_history_list_destroy (context_history_list_h list) |
Destroys a history list handle and release all its resources. | |
int | context_history_record_get_int (context_history_record_h record, const char *key, int *value) |
Gets an integer value from a record. | |
int | context_history_record_get_string (context_history_record_h record, const char *key, char **value) |
Gets a string from a record. | |
int | context_history_record_get_double (context_history_record_h record, const char *key, double *value) |
Gets a double-precision value from a record. | |
int | context_history_record_destroy (context_history_record_h record) |
Destroys a record handle and releases all its resources. | |
Typedefs | |
typedef struct _context_history_handle_s * | context_history_h |
Retrieving statistics and patterns using context history handle. | |
typedef struct _context_history_filter_handle_s * | context_history_filter_h |
Computing statistics and patterns using history filter handle. | |
typedef struct _context_history_list_handle_s * | context_history_list_h |
One or multiple records contained in history list handle. | |
typedef struct _context_history_record_handle_s * | context_history_record_h |
One or multiple attributes contained in history list handle. | |
Defines | |
#define | CONTEXT_HISTORY_APP_ID "AppId" |
Definition for the attribute key denoting "application id". | |
#define | CONTEXT_HISTORY_TOTAL_COUNT "TotalCount" |
Definition for the attribute key denoting "total count". | |
#define | CONTEXT_HISTORY_TOTAL_AMOUNT "TotalAmount" |
Definition for the attribute key denoting "total amount". | |
#define | CONTEXT_HISTORY_TOTAL_DURATION "TotalDuration" |
Definition for the attribute key denoting "total duration". | |
#define | CONTEXT_HISTORY_LAST_TIME "LastTime" |
Definition for the attribute key denoting "last time". | |
#define | CONTEXT_HISTORY_HOUR_OF_DAY "HourOfDay" |
Definition for the attribute key denoting "hour of day". | |
#define | CONTEXT_HISTORY_AUDIO_JACK "AudioJack" |
Definition for the attribute key denoting "audio jack status". | |
#define | CONTEXT_HISTORY_SYSTEM_VOLUME "SystemVolume" |
Definition for the attribute key denoting "system volume". | |
#define | CONTEXT_HISTORY_MEDIA_VOLUME "MediaVolume" |
Definition for the attribute key denoting "media volume". | |
#define | CONTEXT_HISTORY_ADDRESS "Address" |
Definition for the attribute key denoting "address". |
Define Documentation
#define CONTEXT_HISTORY_ADDRESS "Address" |
Definition for the attribute key denoting "address".
- Deprecated:
- Deprecated since 4.0.
This can be used as a key of context_history_record_get_string().
- Since :
- 2.4
#define CONTEXT_HISTORY_APP_ID "AppId" |
Definition for the attribute key denoting "application id".
This can be used as a key of context_history_record_get_string().
- Since :
- 2.4
#define CONTEXT_HISTORY_AUDIO_JACK "AudioJack" |
Definition for the attribute key denoting "audio jack status".
- Deprecated:
- Deprecated since 4.0.
This can be used as a key of context_history_record_get_int().
- Since :
- 2.4
#define CONTEXT_HISTORY_HOUR_OF_DAY "HourOfDay" |
Definition for the attribute key denoting "hour of day".
- Deprecated:
- Deprecated since 4.0.
This can be used as a key of context_history_record_get_int().
- Since :
- 2.4
#define CONTEXT_HISTORY_LAST_TIME "LastTime" |
Definition for the attribute key denoting "last time".
This can be used as a key of context_history_record_get_int().
- Since :
- 2.4
#define CONTEXT_HISTORY_MEDIA_VOLUME "MediaVolume" |
Definition for the attribute key denoting "media volume".
- Deprecated:
- Deprecated since 4.0.
This can be used as a key of context_history_record_get_int().
- Since :
- 2.4
#define CONTEXT_HISTORY_SYSTEM_VOLUME "SystemVolume" |
Definition for the attribute key denoting "system volume".
- Deprecated:
- Deprecated since 4.0.
This can be used as a key of context_history_record_get_int().
- Since :
- 2.4
#define CONTEXT_HISTORY_TOTAL_AMOUNT "TotalAmount" |
Definition for the attribute key denoting "total amount".
This can be used as a key of context_history_record_get_double().
- Since :
- 3.0
#define CONTEXT_HISTORY_TOTAL_COUNT "TotalCount" |
Definition for the attribute key denoting "total count".
This can be used as a key of context_history_record_get_int().
- Since :
- 2.4
#define CONTEXT_HISTORY_TOTAL_DURATION "TotalDuration" |
Definition for the attribute key denoting "total duration".
This can be used as a key of context_history_record_get_int().
- Since :
- 2.4
Typedef Documentation
typedef struct _context_history_filter_handle_s* context_history_filter_h |
Computing statistics and patterns using history filter handle.
- Since :
- 2.4
typedef struct _context_history_handle_s* context_history_h |
Retrieving statistics and patterns using context history handle.
- Since :
- 2.4
typedef struct _context_history_list_handle_s* context_history_list_h |
One or multiple records contained in history list handle.
- Since :
- 2.4
typedef struct _context_history_record_handle_s* context_history_record_h |
One or multiple attributes contained in history list handle.
- Since :
- 2.4
Enumeration Type Documentation
Enumeration for data types of statistics and patterns.
- Since :
- 2.4
- Enumerator:
CONTEXT_HISTORY_RECENTLY_USED_APP Recently used application
Privilege : http://tizen.org/privilege/apphistory.readCONTEXT_HISTORY_FREQUENTLY_USED_APP Frequently used application
Privilege : http://tizen.org/privilege/apphistory.readCONTEXT_HISTORY_RARELY_USED_APP Rarely used application (Deprecated since 4.0)
Privilege : http://tizen.org/privilege/apphistory.readCONTEXT_HISTORY_PEAK_TIME_FOR_APP Peak time of application use activity (Deprecated since 4.0)
Privilege : http://tizen.org/privilege/apphistory.readCONTEXT_HISTORY_PEAK_TIME_FOR_MUSIC Peak time of music listening activity (Deprecated since 4.0)
Privilege : http://tizen.org/privilege/mediahistory.readCONTEXT_HISTORY_PEAK_TIME_FOR_VIDEO Peak time of video watching activity (Deprecated since 4.0)
Privilege : http://tizen.org/privilege/mediahistory.readCONTEXT_HISTORY_COMMON_SETTING_FOR_APP Common setting value of application use activity (Deprecated since 4.0)
Privilege : http://tizen.org/privilege/apphistory.readCONTEXT_HISTORY_COMMON_SETTING_FOR_MUSIC Common setting value of music listening activity (Deprecated since 4.0)
Privilege : http://tizen.org/privilege/mediahistory.readCONTEXT_HISTORY_COMMON_SETTING_FOR_VIDEO Common setting value of video watching activity (Deprecated since 4.0)
Privilege : http://tizen.org/privilege/mediahistory.readCONTEXT_HISTORY_FREQUENTLY_COMMUNICATED_ADDRESS Frequently communicated address (Deprecated since 4.0)
Privilege : http://tizen.org/privilege/callhistory.readCONTEXT_HISTORY_BATTERY_USAGE Per-app battery usage in percentage (Since 3.0)
Privilege : http://tizen.org/privilege/apphistory.readCONTEXT_HISTORY_RECENT_BATTERY_USAGE Per-app battery usage in percentage since last charge (Since 3.0)
Privilege : http://tizen.org/privilege/apphistory.read
Enumeration for errors.
- Since :
- 2.4
- Enumerator:
Enumeration for filters of statistics and patterns.
- Since :
- 2.4
- Enumerator:
Function Documentation
int context_history_create | ( | context_history_h * | handle | ) |
Creates a context history handle.
- Since :
- 2.4
- Remarks:
- The
handle
must be released using context_history_destroy().
- Parameters:
-
[out] handle Handle to be initialized
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
CONTEXT_HISTORY_ERROR_NONE Successful CONTEXT_HISTORY_ERROR_INVALID_PARAMETER Invalid parameter CONTEXT_HISTORY_ERROR_NOT_SUPPORTED Not supported CONTEXT_HISTORY_ERROR_OUT_OF_MEMORY Out of memory
- See also:
- context_history_destroy()
int context_history_destroy | ( | context_history_h | handle | ) |
Releases the resources occupied by a handle.
This releases the memory allocated for the handle
.
- Since :
- 2.4
- Parameters:
-
[in] handle Handle to be released
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
CONTEXT_HISTORY_ERROR_NONE Successful CONTEXT_HISTORY_ERROR_NOT_SUPPORTED Not supported CONTEXT_HISTORY_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- context_history_create()
int context_history_filter_create | ( | context_history_filter_h * | filter | ) |
Creates a history filter.
- Since :
- 2.4
- Remarks:
- The
filter
must be released using context_history_filter_destroy().
- Parameters:
-
[out] filter Filter handle to be initialized
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
CONTEXT_HISTORY_ERROR_NONE Successful CONTEXT_HISTORY_ERROR_INVALID_PARAMETER Invalid parameter CONTEXT_HISTORY_ERROR_NOT_SUPPORTED Not supported CONTEXT_HISTORY_ERROR_OUT_OF_MEMORY Memory allocation failed
- See also:
- context_history_filter_destroy()
int context_history_filter_destroy | ( | context_history_filter_h | filter | ) |
Releases the resources occupied by a filter.
This releases the memory allocated for the filter
.
- Since :
- 2.4
- Parameters:
-
[in] filter Filter handle to be released
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
CONTEXT_HISTORY_ERROR_NONE Successful CONTEXT_HISTORY_ERROR_INVALID_PARAMETER Invalid parameter CONTEXT_HISTORY_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- context_history_filter_create()
int context_history_filter_set_int | ( | context_history_filter_h | filter, |
context_history_filter_e | filter_type, | ||
int | value | ||
) |
Sets an integer value to a filter.
This sets the value to a filter.
- Since :
- 2.4
- Parameters:
-
[in] filter The filter handle [in] filter_type The filter type to set [in] value The value to be set
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
CONTEXT_HISTORY_ERROR_NONE Successful CONTEXT_HISTORY_ERROR_INVALID_PARAMETER Invalid parameter CONTEXT_HISTORY_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- context_history_filter_create()
int context_history_filter_set_string | ( | context_history_filter_h | filter, |
context_history_filter_e | filter_type, | ||
const char * | value | ||
) |
Sets a string to a filter.
- Deprecated:
- Deprecated since 4.0.
This sets the value to a filter.
- Since :
- 2.4
- Parameters:
-
[in] filter The filter handle [in] filter_type The filter type to set [in] value The value to be set
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
CONTEXT_HISTORY_ERROR_NONE Successful CONTEXT_HISTORY_ERROR_INVALID_PARAMETER Invalid parameter CONTEXT_HISTORY_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- context_history_filter_create()
- See also:
- context_history_filter_set_int()
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 | ||
) |
Reads context statistics or patterns.
Retrieves a given type of context statistics or patterns list. See the programming guide to find available filter type context_history_filter_e
for each context data type context_history_data_e.
- Since :
- 2.4
- Remarks:
- The
list
must be released using context_history_list_destroy().
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.
- Parameters:
-
[in] handle Handle for controlling the context history data requests [in] data_type Type of the history data [in] filter Filter to be used to compute statistics or patterns. This can not be NULL
[out] list History data retrieved. This should be freed after use
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
CONTEXT_HISTORY_ERROR_NONE Successful CONTEXT_HISTORY_ERROR_INVALID_PARAMETER Invalid parameter CONTEXT_HISTORY_ERROR_PERMISSION_DENIED Permission denied CONTEXT_HISTORY_ERROR_NOT_SUPPORTED Not supported CONTEXT_HISTORY_ERROR_OPERATION_FAILED Operation failed CONTEXT_HISTORY_ERROR_OUT_OF_MEMORY Out of memory CONTEXT_HISTORY_ERROR_NO_DATA Requested data does not exist
- Precondition:
- context_history_create()
- Postcondition:
- context_history_list_destroy()
int context_history_is_supported | ( | context_history_data_e | data_type, |
bool * | supported | ||
) |
Checks whether a history data type is supported in the current device.
- Since :
- 4.0
- Parameters:
-
[in] data_type Type of history data [out] supported If supported, true
, otherwisefalse
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
CONTEXT_HISTORY_ERROR_NONE Successful CONTEXT_HISTORY_ERROR_INVALID_PARAMETER Invalid parameter CONTEXT_HISTORY_ERROR_NOT_SUPPORTED Not supported CONTEXT_HISTORY_ERROR_OPERATION_FAILED Operation failed
int context_history_list_destroy | ( | context_history_list_h | list | ) |
Destroys a history list handle and release all its resources.
- Since :
- 2.4
- Parameters:
-
[in] list The context history data handle
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
CONTEXT_HISTORY_ERROR_NONE Successful CONTEXT_HISTORY_ERROR_INVALID_PARAMETER Invalid parameter CONTEXT_HISTORY_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- context_history_get_list()
int context_history_list_get_count | ( | context_history_list_h | list, |
int * | count | ||
) |
Retrieves the number of records in a list.
- Since :
- 2.4
- Parameters:
-
[in] list The history data list handle [out] count The count of the data list
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
CONTEXT_HISTORY_ERROR_NONE Successful CONTEXT_HISTORY_ERROR_INVALID_PARAMETER Invalid parameter CONTEXT_HISTORY_ERROR_NOT_SUPPORTED Not supported CONTEXT_HISTORY_ERROR_OPERATION_FAILED Operation failed
- Precondition:
- context_history_get_list()
int context_history_list_get_current | ( | context_history_list_h | list, |
context_history_record_h * | record | ||
) |
Retrieves the current record from the history list.
The default current record is the first record.
- Since :
- 2.4
- Remarks:
- The
record
must be released using context_history_record_destroy().
- Parameters:
-
[in] list The context history list handle [out] record History data record retrieved
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
CONTEXT_HISTORY_ERROR_NONE Successful CONTEXT_HISTORY_ERROR_INVALID_PARAMETER Invalid parameter CONTEXT_HISTORY_ERROR_NOT_SUPPORTED Not supported CONTEXT_HISTORY_ERROR_OPERATION_FAILED Operation failed CONTEXT_HISTORY_ERROR_OUT_OF_MEMORY Out of memory
- Precondition:
- context_history_get_list()
- Postcondition:
- context_history_record_destroy()
Moves a history data list to the first position.
- Since :
- 2.4
- Parameters:
-
[in] list The context history list handle
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
CONTEXT_HISTORY_ERROR_NONE Successful CONTEXT_HISTORY_ERROR_INVALID_PARAMETER Invalid parameter CONTEXT_HISTORY_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- context_history_get_list()
int context_history_list_move_next | ( | context_history_list_h | list | ) |
Moves a history data list to the next position.
- Since :
- 2.4
- Parameters:
-
[in] list The context history list handle
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
CONTEXT_HISTORY_ERROR_NONE Successful CONTEXT_HISTORY_ERROR_INVALID_PARAMETER Invalid parameter CONTEXT_HISTORY_ERROR_NOT_SUPPORTED Not supported CONTEXT_HISTORY_ERROR_NO_DATA Requested data does not exist
- Precondition:
- context_history_get_list()
int context_history_record_destroy | ( | context_history_record_h | record | ) |
Destroys a record handle and releases all its resources.
- Since :
- 2.4
- Parameters:
-
[in] record The record handle
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
CONTEXT_HISTORY_ERROR_NONE Successful CONTEXT_HISTORY_ERROR_INVALID_PARAMETER Invalid parameter CONTEXT_HISTORY_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- context_history_list_get_current()
int context_history_record_get_double | ( | context_history_record_h | record, |
const char * | key, | ||
double * | value | ||
) |
Gets a double-precision value from a record.
See the programming guide to find available attribute keys
for each context data context_history_data_e.
- Since :
- 3.0
- Parameters:
-
[in] record The record handle [in] key The key of the attribute to get [out] value The result value
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
CONTEXT_HISTORY_ERROR_NONE Successful CONTEXT_HISTORY_ERROR_INVALID_PARAMETER Invalid parameter CONTEXT_HISTORY_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- context_history_list_get_current()
int context_history_record_get_int | ( | context_history_record_h | record, |
const char * | key, | ||
int * | value | ||
) |
Gets an integer value from a record.
See the programming guide to find available attribute keys
for each context data context_history_data_e.
- Since :
- 2.4
- Parameters:
-
[in] record The record handle [in] key The key of attribute to get [out] value The result value
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
CONTEXT_HISTORY_ERROR_NONE Successful CONTEXT_HISTORY_ERROR_INVALID_PARAMETER Invalid parameter CONTEXT_HISTORY_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- context_history_list_get_current()
int context_history_record_get_string | ( | context_history_record_h | record, |
const char * | key, | ||
char ** | value | ||
) |
Gets a string from a record.
See the programming guide to find available attribute keys
for each context data context_history_data_e.
- Since :
- 2.4
- Remarks:
value
must be released using free().
- Parameters:
-
[in] record The record handle [in] key The key of attribute to get [out] value The result value
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
CONTEXT_HISTORY_ERROR_NONE Successful CONTEXT_HISTORY_ERROR_INVALID_PARAMETER Invalid parameter CONTEXT_HISTORY_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- context_history_list_get_current()