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

enum context_history_data_e

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

enum context_history_error_e

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

enum context_history_filter_e

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

int context_history_create ( context_history_h * handle )

Creates a context history handle.

Since :: 4.0

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 :: 4.0

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 :: 4.0

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 :: 4.0

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 :: 4.0

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_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 :: 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]	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`, otherwise `false`

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 :: 4.0

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 :: 4.0

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()

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 :: 4.0

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()

int context_history_list_move_first ( context_history_list_h list )

Moves a history data list to the first position.

Since :: 4.0

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()

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 :: 4.0

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()

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 :: 4.0

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 :: 4.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()

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

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

See also:: context_history_record_get_int(); context_history_record_get_double()

Required Header

Overview

Related Features

Functions

Typedefs

Defines

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation