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

enum context_history_data_e

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

enum context_history_error_e

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

enum context_history_filter_audio_jack_e

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

enum context_history_filter_communication_type_e

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

enum context_history_filter_day_of_week_e

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

enum context_history_filter_e

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

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

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

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]	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

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.

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

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_OPERATION_FAILED	Operation failed

Precondition:: context_history_get_list()

See also:: context_history_list_move_first(); context_history_list_move_next()

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_OPERATION_FAILED	Operation failed
CONTEXT_HISTORY_ERROR_OUT_OF_MEMORY	Out of memory

Precondition:: context_history_get_list()

Postcondition:: context_history_record_destroy()

int context_history_list_move_first ( context_history_list_h list )

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

Precondition:: context_history_get_list()

See also:: context_history_list_get_count(); context_history_list_move_next()

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_NO_DATA	Requested data does not exist

Precondition:: context_history_get_list()

See also:: context_history_list_get_count(); context_history_list_move_first()

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

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]	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

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]	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

Precondition:: context_history_list_get_current()

See also:: context_history_record_get_int()

Functions

Typedefs

Defines

Required Header

Overview

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation