Tizen Native API
Contextual History

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)
 Sets a string to a filter.
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_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
 Context history handle for retrieving statistics and patterns.
typedef struct
_context_history_filter_handle_s * 
context_history_filter_h
 History filter handle to be used to compute statistics and patterns.
typedef struct
_context_history_list_handle_s * 
context_history_list_h
 History list handle. It contains one or multiple records.
typedef struct
_context_history_record_handle_s * 
context_history_record_h
 History record handle. It contains one or multiple attributes.

Defines

#define CONTEXT_HISTORY_APP_ID   "AppId"
 The attribute key denoting "application id".
#define CONTEXT_HISTORY_TOTAL_COUNT   "TotalCount"
 The attribute key denoting "total count".
#define CONTEXT_HISTORY_TOTAL_DURATION   "TotalDuration"
 The attribute key denoting "total duration".
#define CONTEXT_HISTORY_LAST_TIME   "LastTime"
 The attribute key denoting "last time".
#define CONTEXT_HISTORY_HOUR_OF_DAY   "HourOfDay"
 The attribute key denoting "hour of day".
#define CONTEXT_HISTORY_AUDIO_JACK   "AudioJack"
 The attribute key denoting "audio jack status".
#define CONTEXT_HISTORY_SYSTEM_VOLUME   "SystemVolume"
 The attribute key denoting "system volume".
#define CONTEXT_HISTORY_MEDIA_VOLUME   "MediaVolume"
 The attribute key denoting "media volume".
#define CONTEXT_HISTORY_ADDRESS   "Address"
 The attribute key denoting "address".

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.


Define Documentation

#define CONTEXT_HISTORY_ADDRESS   "Address"

The attribute key denoting "address".

Since :
2.4
#define CONTEXT_HISTORY_APP_ID   "AppId"

The attribute key denoting "application id".

Since :
2.4
#define CONTEXT_HISTORY_AUDIO_JACK   "AudioJack"

The attribute key denoting "audio jack status".

Since :
2.4
#define CONTEXT_HISTORY_HOUR_OF_DAY   "HourOfDay"

The attribute key denoting "hour of day".

Since :
2.4
#define CONTEXT_HISTORY_LAST_TIME   "LastTime"

The attribute key denoting "last time".

Since :
2.4
#define CONTEXT_HISTORY_MEDIA_VOLUME   "MediaVolume"

The attribute key denoting "media volume".

Since :
2.4
#define CONTEXT_HISTORY_SYSTEM_VOLUME   "SystemVolume"

The attribute key denoting "system volume".

Since :
2.4
#define CONTEXT_HISTORY_TOTAL_COUNT   "TotalCount"

The attribute key denoting "total count".

Since :
2.4
#define CONTEXT_HISTORY_TOTAL_DURATION   "TotalDuration"

The attribute key denoting "total duration".

Since :
2.4

Typedef Documentation

typedef struct _context_history_filter_handle_s* context_history_filter_h

History filter handle to be used to compute statistics and patterns.

Since :
2.4
typedef struct _context_history_handle_s* context_history_h

Context history handle for retrieving statistics and patterns.

Since :
2.4
typedef struct _context_history_list_handle_s* context_history_list_h

History list handle. It contains one or multiple records.

Since :
2.4
typedef struct _context_history_record_handle_s* context_history_record_h

History record handle. It contains one or multiple attributes.

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.read

CONTEXT_HISTORY_FREQUENTLY_USED_APP 

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

CONTEXT_HISTORY_RARELY_USED_APP 

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

CONTEXT_HISTORY_PEAK_TIME_FOR_APP 

Peak time of application use activity.
Privilege : http://tizen.org/privilege/apphistory.read

CONTEXT_HISTORY_PEAK_TIME_FOR_MUSIC 

Peak time of music listening activity.
Privilege : http://tizen.org/privilege/mediahistory.read

CONTEXT_HISTORY_PEAK_TIME_FOR_VIDEO 

Peak time of video watching activity.
Privilege : http://tizen.org/privilege/mediahistory.read

CONTEXT_HISTORY_COMMON_SETTING_FOR_APP 

Common setting value of application use activity.
Privilege : http://tizen.org/privilege/apphistory.read

CONTEXT_HISTORY_COMMON_SETTING_FOR_MUSIC 

Common setting value of music listening activity.
Privilege : http://tizen.org/privilege/mediahistory.read

CONTEXT_HISTORY_COMMON_SETTING_FOR_VIDEO 

Common setting value of video watching activity.
Privilege : http://tizen.org/privilege/mediahistory.read

CONTEXT_HISTORY_FREQUENTLY_COMMUNICATED_ADDRESS 

Frequently communicated address.
Privilege : http://tizen.org/privilege/callhistory.read

Enumeration for errors.

Since :
2.4
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 audio jack filter.

Since :
2.4
Enumerator:
CONTEXT_HISTORY_FILTER_AUDIO_JACK_NOT_CONNECTED 

Audio jack is not connected

CONTEXT_HISTORY_FILTER_AUDIO_JACK_CONNECTED 

Audio jack is connected

Enumeration for log type filter.

Since :
2.4
Enumerator:
CONTEXT_HISTORY_FILTER_COMMUNICATION_TYPE_CALL 

Includes only call logs

CONTEXT_HISTORY_FILTER_COMMUNICATION_TYPE_MESSAGE 

Includes only message logs

CONTEXT_HISTORY_FILTER_COMMUNICATION_TYPE_ALL 

Includes all logs

Enumeration for day of week filter.

Since :
2.4
Enumerator:
CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_WEEKDAYS 

Includes only weekdays

CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_WEEKENDS 

Includes only weekends

CONTEXT_HISTORY_FILTER_DAY_OF_WEEK_ALL 

Includes all days

Enumeration for filters of statistics and patterns.

Since :
2.4
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_APP_ID 

Application id

CONTEXT_HISTORY_FILTER_DAY_OF_WEEK 

Weekdays, weekends

CONTEXT_HISTORY_FILTER_START_TIME 

Start time of data in epoch time

CONTEXT_HISTORY_FILTER_END_TIME 

End time of data in epoch time

CONTEXT_HISTORY_FILTER_WIFI_BSSID 

Wi-Fi BSSID value

CONTEXT_HISTORY_FILTER_AUDIO_JACK 

Audio jack status value

CONTEXT_HISTORY_FILTER_COMMUNICATION_TYPE 

Type of phone log


Function Documentation

Creates a context history handle.

Since :
2.4
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_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 :
2.4
Parameters:
[in]handleHandle to be released
Returns:
0 on success, otherwise a negative error value
Return values:
CONTEXT_HISTORY_ERROR_NONESuccessful
CONTEXT_HISTORY_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
context_history_create()

Creates a history filter.

Since :
2.4
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_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 :
2.4
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
Precondition:
context_history_filter_create()

Sets an integer value to a filter.

This sets the value to a filter.

Since :
2.4
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
Precondition:
context_history_filter_create()
See also:
context_history_filter_set_string()
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.

This sets the value to a filter.

Since :
2.4
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
Precondition:
context_history_filter_create()
See also:
context_history_filter_set_int()

Reads context statistics or patterns.

Retrieves a given type of context statistics or patterns list.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/apphistory.read
Privilege:
http://tizen.org/privilege/mediahistory.read
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]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_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()

Destroys a history list handle and release all its resources.

Since :
2.4
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
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]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_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 :
2.4
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_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 :
2.4
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
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 :
2.4
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_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 :
2.4
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
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.

Since :
2.4
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
Precondition:
context_history_list_get_current()
See also:
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.

Since :
2.4
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
Precondition:
context_history_list_get_current()
See also:
context_history_record_get_int()