Tizen Native API  5.5
Contextual History

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_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 Documentation

#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 :
4.0
#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 :
4.0
#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 :
4.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 :
4.0
#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 :
4.0

Typedef Documentation

typedef struct _context_history_filter_handle_s* context_history_filter_h

Computing statistics and patterns using history filter handle.

Since :
4.0
typedef struct _context_history_handle_s* context_history_h

Retrieving statistics and patterns using context history handle.

Since :
4.0
typedef struct _context_history_list_handle_s* context_history_list_h

One or multiple records contained in history list handle.

Since :
4.0
typedef struct _context_history_record_handle_s* context_history_record_h

One or multiple attributes contained in history list handle.

Since :
4.0

Enumeration Type Documentation

Enumeration for data types of statistics and patterns.

Since :
4.0
Enumerator:
CONTEXT_HISTORY_RECENTLY_USED_APP 

Recently used application
Privilege : http://tizen.org/privilege/apphistory.read

CONTEXT_HISTORY_FREQUENTLY_USED_APP 

Frequently used application
Privilege : http://tizen.org/privilege/apphistory.read

CONTEXT_HISTORY_BATTERY_USAGE 

Per-app battery usage in percentage
Privilege : http://tizen.org/privilege/apphistory.read

CONTEXT_HISTORY_RECENT_BATTERY_USAGE 

Per-app battery usage in percentage since last charge
Privilege : http://tizen.org/privilege/apphistory.read

Enumeration for errors.

Since :
4.0
Enumerator:
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_OUT_OF_MEMORY 

Memory allocation failed

CONTEXT_HISTORY_ERROR_NO_DATA 

No Data

CONTEXT_HISTORY_ERROR_OUT_OF_RANGE 

Out of range

CONTEXT_HISTORY_ERROR_OPERATION_FAILED 

Operation failed

Enumeration for filters of statistics and patterns.

Since :
4.0
Enumerator:
CONTEXT_HISTORY_FILTER_TIME_SPAN 

Time span of data in days

CONTEXT_HISTORY_FILTER_RESULT_SIZE 

Result size of data records

CONTEXT_HISTORY_FILTER_START_TIME 

Start time of data in epoch time

CONTEXT_HISTORY_FILTER_END_TIME 

End time of data in epoch time


Function Documentation

Creates a context history handle.

Since :
4.0
Remarks:
The handle must be released using context_history_destroy().
Parameters:
[out]handleHandle to be initialized
Returns:
0 on success, otherwise a negative error value
Return values:
CONTEXT_HISTORY_ERROR_NONESuccessful
CONTEXT_HISTORY_ERROR_INVALID_PARAMETERInvalid parameter
CONTEXT_HISTORY_ERROR_NOT_SUPPORTEDNot supported
CONTEXT_HISTORY_ERROR_OUT_OF_MEMORYOut of memory
See also:
context_history_destroy()

Releases the resources occupied by a handle.

This releases the memory allocated for the handle.

Since :
4.0
Parameters:
[in]handleHandle to be released
Returns:
0 on success, otherwise a negative error value
Return values:
CONTEXT_HISTORY_ERROR_NONESuccessful
CONTEXT_HISTORY_ERROR_NOT_SUPPORTEDNot supported
CONTEXT_HISTORY_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
context_history_create()

Creates a history filter.

Since :
4.0
Remarks:
The filter must be released using context_history_filter_destroy().
Parameters:
[out]filterFilter handle to be initialized
Returns:
0 on success, otherwise a negative error value
Return values:
CONTEXT_HISTORY_ERROR_NONESuccessful
CONTEXT_HISTORY_ERROR_INVALID_PARAMETERInvalid parameter
CONTEXT_HISTORY_ERROR_NOT_SUPPORTEDNot supported
CONTEXT_HISTORY_ERROR_OUT_OF_MEMORYMemory allocation failed
See also:
context_history_filter_destroy()

Releases the resources occupied by a filter.

This releases the memory allocated for the filter.

Since :
4.0
Parameters:
[in]filterFilter handle to be released
Returns:
0 on success, otherwise a negative error value
Return values:
CONTEXT_HISTORY_ERROR_NONESuccessful
CONTEXT_HISTORY_ERROR_INVALID_PARAMETERInvalid parameter
CONTEXT_HISTORY_ERROR_NOT_SUPPORTEDNot supported
Precondition:
context_history_filter_create()

Sets an integer value to a filter.

This sets the value to a filter.

Since :
4.0
Parameters:
[in]filterThe filter handle
[in]filter_typeThe filter type to set
[in]valueThe value to be set
Returns:
0 on success, otherwise a negative error value
Return values:
CONTEXT_HISTORY_ERROR_NONESuccessful
CONTEXT_HISTORY_ERROR_INVALID_PARAMETERInvalid parameter
CONTEXT_HISTORY_ERROR_NOT_SUPPORTEDNot supported
Precondition:
context_history_filter_create()

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 :
4.0
Remarks:
The list must be released using context_history_list_destroy().
http://tizen.org/privilege/apphistory.read is needed to retrieve data. It depends on context data type context_history_data_e.
Parameters:
[in]handleHandle for controlling the context history data requests
[in]data_typeType of the history data
[in]filterFilter to be used to compute statistics or patterns. This can not be NULL
[out]listHistory data retrieved. This should be freed after use
Returns:
0 on success, otherwise a negative error value
Return values:
CONTEXT_HISTORY_ERROR_NONESuccessful
CONTEXT_HISTORY_ERROR_INVALID_PARAMETERInvalid parameter
CONTEXT_HISTORY_ERROR_PERMISSION_DENIEDPermission denied
CONTEXT_HISTORY_ERROR_NOT_SUPPORTEDNot supported
CONTEXT_HISTORY_ERROR_OPERATION_FAILEDOperation failed
CONTEXT_HISTORY_ERROR_OUT_OF_MEMORYOut of memory
CONTEXT_HISTORY_ERROR_NO_DATARequested 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_typeType of history data
[out]supportedIf supported, true, otherwise false
Returns:
0 on success, otherwise a negative error value
Return values:
CONTEXT_HISTORY_ERROR_NONESuccessful
CONTEXT_HISTORY_ERROR_INVALID_PARAMETERInvalid parameter
CONTEXT_HISTORY_ERROR_NOT_SUPPORTEDNot supported
CONTEXT_HISTORY_ERROR_OPERATION_FAILEDOperation failed

Destroys a history list handle and release all its resources.

Since :
4.0
Parameters:
[in]listThe context history data handle
Returns:
0 on success, otherwise a negative error value
Return values:
CONTEXT_HISTORY_ERROR_NONESuccessful
CONTEXT_HISTORY_ERROR_INVALID_PARAMETERInvalid parameter
CONTEXT_HISTORY_ERROR_NOT_SUPPORTEDNot 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 :
4.0
Parameters:
[in]listThe history data list handle
[out]countThe count of the data list
Returns:
0 on success, otherwise a negative error value
Return values:
CONTEXT_HISTORY_ERROR_NONESuccessful
CONTEXT_HISTORY_ERROR_INVALID_PARAMETERInvalid parameter
CONTEXT_HISTORY_ERROR_NOT_SUPPORTEDNot supported
CONTEXT_HISTORY_ERROR_OPERATION_FAILEDOperation failed
Precondition:
context_history_get_list()
See also:
context_history_list_move_first()
context_history_list_move_next()

Retrieves the current record from the history list.

The default current record is the first record.

Since :
4.0
Remarks:
The record must be released using context_history_record_destroy().
Parameters:
[in]listThe context history list handle
[out]recordHistory data record retrieved
Returns:
0 on success, otherwise a negative error value
Return values:
CONTEXT_HISTORY_ERROR_NONESuccessful
CONTEXT_HISTORY_ERROR_INVALID_PARAMETERInvalid parameter
CONTEXT_HISTORY_ERROR_NOT_SUPPORTEDNot supported
CONTEXT_HISTORY_ERROR_OPERATION_FAILEDOperation failed
CONTEXT_HISTORY_ERROR_OUT_OF_MEMORYOut of memory
Precondition:
context_history_get_list()
Postcondition:
context_history_record_destroy()

Moves a history data list to the first position.

Since :
4.0
Parameters:
[in]listThe context history list handle
Returns:
0 on success, otherwise a negative error value
Return values:
CONTEXT_HISTORY_ERROR_NONESuccessful
CONTEXT_HISTORY_ERROR_INVALID_PARAMETERInvalid parameter
CONTEXT_HISTORY_ERROR_NOT_SUPPORTEDNot supported
Precondition:
context_history_get_list()
See also:
context_history_list_get_count()
context_history_list_move_next()

Moves a history data list to the next position.

Since :
4.0
Parameters:
[in]listThe context history list handle
Returns:
0 on success, otherwise a negative error value
Return values:
CONTEXT_HISTORY_ERROR_NONESuccessful
CONTEXT_HISTORY_ERROR_INVALID_PARAMETERInvalid parameter
CONTEXT_HISTORY_ERROR_NOT_SUPPORTEDNot supported
CONTEXT_HISTORY_ERROR_NO_DATARequested data does not exist
Precondition:
context_history_get_list()
See also:
context_history_list_get_count()
context_history_list_move_first()

Destroys a record handle and releases all its resources.

Since :
4.0
Parameters:
[in]recordThe record handle
Returns:
0 on success, otherwise a negative error value
Return values:
CONTEXT_HISTORY_ERROR_NONESuccessful
CONTEXT_HISTORY_ERROR_INVALID_PARAMETERInvalid parameter
CONTEXT_HISTORY_ERROR_NOT_SUPPORTEDNot 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 :
4.0
Parameters:
[in]recordThe record handle
[in]keyThe key of the attribute to get
[out]valueThe result value
Returns:
0 on success, otherwise a negative error value
Return values:
CONTEXT_HISTORY_ERROR_NONESuccessful
CONTEXT_HISTORY_ERROR_INVALID_PARAMETERInvalid parameter
CONTEXT_HISTORY_ERROR_NOT_SUPPORTEDNot supported
Precondition:
context_history_list_get_current()
See also:
context_history_record_get_int()
context_history_record_get_string()
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 :
4.0
Parameters:
[in]recordThe record handle
[in]keyThe key of attribute to get
[out]valueThe result value
Returns:
0 on success, otherwise a negative error value
Return values:
CONTEXT_HISTORY_ERROR_NONESuccessful
CONTEXT_HISTORY_ERROR_INVALID_PARAMETERInvalid parameter
CONTEXT_HISTORY_ERROR_NOT_SUPPORTEDNot supported
Precondition:
context_history_list_get_current()
See also:
context_history_record_get_double()
context_history_record_get_string()
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 :
4.0
Remarks:
value must be released using free().
Parameters:
[in]recordThe record handle
[in]keyThe key of attribute to get
[out]valueThe result value
Returns:
0 on success, otherwise a negative error value
Return values:
CONTEXT_HISTORY_ERROR_NONESuccessful
CONTEXT_HISTORY_ERROR_INVALID_PARAMETERInvalid parameter
CONTEXT_HISTORY_ERROR_NOT_SUPPORTEDNot supported
Precondition:
context_history_list_get_current()
See also:
context_history_record_get_int()
context_history_record_get_double()