The Sensor Recorder API provides functions to start/stop recording sensor events and read the recorded data.

Required Header

#include <sensor.h>

Overview

This Sensor API provides functions to record sensors events in the device. Several sensors are typically available on mobile devices.

Functions
int	sensor_recorder_is_supported (sensor_type_e type, bool *supported)
	Checks whether it is supported to record a given sensor type.
int	sensor_recorder_start (sensor_type_e type, sensor_recorder_option_h option)
	Starts to record a given sensor type.
int	sensor_recorder_stop (sensor_type_e type)
	Stops recording a given sensor type.
int	sensor_recorder_create_option (sensor_recorder_option_h *option)
	Creates a recorder option handle.
int	sensor_recorder_destroy_option (sensor_recorder_option_h option)
	Destroys a recorder option handle.
int	sensor_recorder_option_set_int (sensor_recorder_option_h option, sensor_recorder_option_e param, int value)
	Sets a recording option parameter.
int	sensor_recorder_create_query (sensor_recorder_query_h *query)
	Creates a recorder query handle.
int	sensor_recorder_destroy_query (sensor_recorder_query_h query)
	Destroys a recorder query handle.
int	sensor_recorder_query_set_int (sensor_recorder_query_h query, sensor_recorder_query_e param, int value)
	Sets an integer-type query parameter.
int	sensor_recorder_query_set_time (sensor_recorder_query_h query, sensor_recorder_query_e param, time_t t)
	Sets a time-type query parameter.
int	sensor_recorder_read (sensor_type_e type, sensor_recorder_query_h query, sensor_recorder_data_cb cb, void *user_data)
	Queries the recorded data asynchronously.
int	sensor_recorder_read_sync (sensor_type_e type, sensor_recorder_query_h query, sensor_recorder_data_cb cb, void *user_data)
	Queries the recorded data synchronously.
int	sensor_recorder_data_get_time (sensor_recorder_data_h data, time_t start_time, time_t end_time)
	Gets the start and the end time of the time period of a given record data.
int	sensor_recorder_data_get_int (sensor_recorder_data_h data, sensor_recorder_data_e key, int *value)
	Gets an integer value from a record data.
int	sensor_recorder_data_get_double (sensor_recorder_data_h data, sensor_recorder_data_e key, double *value)
	Gets a double value from a record data.
Typedefs
typedef void *	sensor_recorder_option_h
	Option handle to contain recording policies and parameters.
typedef void *	sensor_recorder_query_h
	Query handle to contain filtering and aggregation parameters for recorded data.
typedef void *	sensor_recorder_data_h
	Data handle to contain retrieved sensor records.
typedef bool(*	sensor_recorder_data_cb )(sensor_type_e type, sensor_recorder_data_h data, int remains, sensor_error_e error, void *user_data)
	Called when the query results are retrieved.

Typedef Documentation

typedef bool(* sensor_recorder_data_cb)(sensor_type_e type, sensor_recorder_data_h data, int remains, sensor_error_e error, void *user_data)

Called when the query results are retrieved.

One of the following errors can be delivered.
SENSOR_ERROR_NONE, Successful
SENSOR_ERROR_OPERATION_FAILED, Operation failed
SENSOR_ERROR_NO_DATA, No data retrieved.

Since :: 2.3.2

Parameters:

[in]	type	Sensor type
[in]	data	Retrieved data record
[in]	remains	Number of remaining records to be delivered
[in]	error	Error
[in]	user_data	The user data passed from sensor_recorder_read() or sensor_recorder_read_sync()

Returns:: If true, it continues to iterate to the next record; if false, the iteration stops

typedef void* sensor_recorder_data_h

Data handle to contain retrieved sensor records.

Since :: 2.3.2

typedef void* sensor_recorder_option_h

Option handle to contain recording policies and parameters.

One or more sensor options can be created by using sensor_recorder_create_option().

Since :: 2.3.2

typedef void* sensor_recorder_query_h

Query handle to contain filtering and aggregation parameters for recorded data.

One or more sensor options can be created by using sensor_recorder_create_query().

Since :: 2.3.2

Enumeration Type Documentation

enum sensor_recorder_data_e

Enumeration for data attributes can be contained in sensor_recorder_data_h.

Since :: 2.3.2

See also:: sensor_recorder_data_get_int(); sensor_recorder_data_get_double()

Enumerator:

SENSOR_RECORDER_DATA_STEPS	Count of both walking and running steps; int (Since 3.0)
SENSOR_RECORDER_DATA_WALK_STEPS	Count of walking steps; int (Since 3.0)
SENSOR_RECORDER_DATA_RUN_STEPS	Count of running steps; int (Since 3.0)
SENSOR_RECORDER_DATA_DISTANCE	Distance walked or ran (m); double (Since 3.0)
SENSOR_RECORDER_DATA_CALORIE	Calorie burned (kcal); double (Since 3.0)
SENSOR_RECORDER_DATA_HEART_RATE	Heart Rate (BPM); int (Since 3.0)
SENSOR_RECORDER_DATA_SLEEP_STATE	Sleep state; int; One of sensor_sleep_state_e (Since 3.0)
SENSOR_RECORDER_DATA_PRESSURE	Pressure; double
SENSOR_RECORDER_DATA_MAX_PRESSURE	Max pressure; double
SENSOR_RECORDER_DATA_MIN_PRESSURE	Min pressure; double
SENSOR_RECORDER_DATA_AVERAGE_PRESSURE	Average pressure; double

enum sensor_recorder_interval_e

Enumeration for intervals between data records.

Some sensor types including SENSOR_HRM may not fit to continuous monitoring and recording. To reduce the battery use for recording such sensors, recording interval between each sensor data is chosen. For example, an application sets the interval of 1 hour, the platform tries to retrieve the sensor data only once per hour, thus it will be more battery efficient than to listen the sensor data continuously.
If the application does not set the interval explicitly, the default value is chosen. The default values differ from sensor to sensor.

Since :: 2.3.2

Remarks:: If more than one application set different intervals, the shortest value is chosen.

Enumerator:

SENSOR_RECORDER_INTERVAL_10_MINUTES	10 Minutes
SENSOR_RECORDER_INTERVAL_1_HOUR	1 Hour
SENSOR_RECORDER_INTERVAL_3_HOURS	3 Hours
SENSOR_RECORDER_INTERVAL_6_HOURS	6 Hours
SENSOR_RECORDER_INTERVAL_12_HOURS	12 Hours
SENSOR_RECORDER_INTERVAL_1_DAY	1 Day

enum sensor_recorder_option_e

Enumeration for option parameters for sensor recording.

None, one, or more option parameters can be set to sensor_recorder_option_h, then applications can request to record a specific sensor with the parameters via sensor_recorder_start(). If a parameter is not supported for the specified sensor type, it will be ignored.

Since :: 2.3.2

Enumerator:

SENSOR_RECORDER_OPTION_RETENTION_PERIOD	Desired retention period for the recorded sensor data (hours); int;
SENSOR_RECORDER_OPTION_INTERVAL	Desired interval between data records (minutes); int; see sensor_recorder_interval_e

enum sensor_recorder_query_e

Enumeration for filtering and aggregation parameters for querying sensor records.

None, one, or more query parameters can be set to sensor_recorder_query_h, to specify the data to be retrieved via sensor_recorder_read(). If a necessary parameter is not set, the default value is chosen.

Since :: 2.3.2

Enumerator:

SENSOR_RECORDER_QUERY_START_TIME	Start time of the data to be queried (Epoch); time_t; If unspecified, 1 day ago
SENSOR_RECORDER_QUERY_END_TIME	End time of the data to be queried (Epoch); time_t; If unspecified, the current time
SENSOR_RECORDER_QUERY_ANCHOR_TIME	The anchor time to slice the querying duration of time (Epoch); time_t; It needs to be set with SENSOR_RECORDER_QUERY_TIME_INTERVAL, otherwise, it is ignored
SENSOR_RECORDER_QUERY_TIME_INTERVAL	The interval of each sliced querying duration (minutes); int

Function Documentation

int sensor_recorder_create_option ( sensor_recorder_option_h * option )

Creates a recorder option handle.

Since :: 2.3.2

Remarks:: The option must be released using sensor_recorder_destroy_option().

Parameters:

[out] option Option handle

Returns:: SENSOR_ERROR_NONE on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_OUT_OF_MEMORY	Out of memory
SENSOR_ERROR_OPERATION_FAILED	Operation failed

int sensor_recorder_create_query ( sensor_recorder_query_h * query )

Creates a recorder query handle.

Since :: 2.3.2

Remarks:: The query must be released using sensor_recorder_destroy_query().

Parameters:

[out] query Query handle

Returns:: SENSOR_ERROR_NONE on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_OUT_OF_MEMORY	Out of memory
SENSOR_ERROR_OPERATION_FAILED	Operation failed

int sensor_recorder_data_get_double	(	sensor_recorder_data_h	data,
		sensor_recorder_data_e	key,
		double *	value
	)

Gets a double value from a record data.

Since :: 2.3.2

Parameters:

[in]	data	Record data handle
[in]	key	Data attribute to retrieve
[out]	value	Retrieved value

Returns:: SENSOR_ERROR_NONE on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_OPERATION_FAILED	Operation failed
SENSOR_ERROR_NO_DATA	No data retrieved

int sensor_recorder_data_get_int	(	sensor_recorder_data_h	data,
		sensor_recorder_data_e	key,
		int *	value
	)

Gets an integer value from a record data.

Since :: 2.3.2

Parameters:

[in]	data	Record data handle
[in]	key	Data attribute to retrieve
[out]	value	Retrieved value

Returns:: SENSOR_ERROR_NONE on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_OPERATION_FAILED	Operation failed
SENSOR_ERROR_NO_DATA	No data retrieved

int sensor_recorder_data_get_time	(	sensor_recorder_data_h	data,
		time_t *	start_time,
		time_t *	end_time
	)

Gets the start and the end time of the time period of a given record data.

Since :: 2.3.2

Parameters:

[in]	data	Record data handle
[out]	start_time	Start time of the time period of the record
[out]	end_time	End time of the time period of the record

Returns:: SENSOR_ERROR_NONE on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_OPERATION_FAILED	Operation failed

int sensor_recorder_destroy_option ( sensor_recorder_option_h option )

Destroys a recorder option handle.

Since :: 2.3.2

Parameters:

[in] option Option handle

Returns:: SENSOR_ERROR_NONE on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_OPERATION_FAILED	Operation failed

int sensor_recorder_destroy_query ( sensor_recorder_query_h query )

Destroys a recorder query handle.

Since :: 2.3.2

Parameters:

[in] query Query handle

Returns:: SENSOR_ERROR_NONE on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_OPERATION_FAILED	Operation failed

int sensor_recorder_is_supported	(	sensor_type_e	type,
		bool *	supported
	)

Checks whether it is supported to record a given sensor type.

Since :: 2.3.2

Parameters:

[in]	type	A sensor type to check
[out]	supported	If supported, `true`; otherwise `false`

Returns:: SENSOR_ERROR_NONE on success; otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_OPERATION_FAILED	Operation failed

int sensor_recorder_option_set_int	(	sensor_recorder_option_h	option,
		sensor_recorder_option_e	param,
		int	value
	)

Sets a recording option parameter.

Since :: 2.3.2

Parameters:

[in]	option	Option handle
[in]	param	Option parameter
[in]	value	Value

Returns:: SENSOR_ERROR_NONE on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_OPERATION_FAILED	Operation failed

int sensor_recorder_query_set_int	(	sensor_recorder_query_h	query,
		sensor_recorder_query_e	param,
		int	value
	)

Sets an integer-type query parameter.

Since :: 2.3.2

Parameters:

[in]	query	Query handle
[in]	param	Query parameter
[in]	value	Value

Returns:: SENSOR_ERROR_NONE on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_OPERATION_FAILED	Operation failed

int sensor_recorder_query_set_time	(	sensor_recorder_query_h	query,
		sensor_recorder_query_e	param,
		time_t	t
	)

Sets a time-type query parameter.

Since :: 2.3.2

Parameters:

[in]	query	Query handle
[in]	param	Query parameter
[in]	t	Time

Returns:: SENSOR_ERROR_NONE on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_OPERATION_FAILED	Operation failed

int sensor_recorder_read	(	sensor_type_e	type,
		sensor_recorder_query_h	query,
		sensor_recorder_data_cb	cb,
		void *	user_data
	)

Queries the recorded data asynchronously.

Since :: 2.3.2

Remarks:: Some sensor types are privileged. An application should have the privilege http://tizen.org/privilege/healthinfo to get access to the following sensors: SENSOR_HRM, SENSOR_HRM_LED_GREEN, SENSOR_HRM_LED_IR, SENSOR_HRM_LED_RED, SENSOR_HUMAN_PEDOMETER, SENSOR_HUMAN_SLEEP_MONITOR, SENSOR_HUMAN_SLEEP_DETECTOR, and SENSOR_HUMAN_STRESS_MONITOR.

Parameters:

[in]	type	Sensor type
[in]	query	Query handle
[in]	cb	Callback function to receive the queried data
[in]	user_data	User data to be passed to the callback function

Returns:: SENSOR_ERROR_NONE on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	Not supported to record the sensor type
SENSOR_ERROR_PERMISSION_DENIED	Permission denied
SENSOR_ERROR_OPERATION_FAILED	Operation failed

See also:: sensor_recorder_read_sync()

int sensor_recorder_read_sync	(	sensor_type_e	type,
		sensor_recorder_query_h	query,
		sensor_recorder_data_cb	cb,
		void *	user_data
	)

Queries the recorded data synchronously.

Since :: 2.3.2

Remarks:: Some sensor types are privileged. An application should have the privilege http://tizen.org/privilege/healthinfo to get access to the following sensors: SENSOR_HRM, SENSOR_HRM_LED_GREEN, SENSOR_HRM_LED_IR, SENSOR_HRM_LED_RED, SENSOR_HUMAN_PEDOMETER, SENSOR_HUMAN_SLEEP_MONITOR, SENSOR_HUMAN_SLEEP_DETECTOR, and SENSOR_HUMAN_STRESS_MONITOR.

Parameters:

[in]	type	Sensor type
[in]	query	Query handle
[in]	cb	Callback function to receive the queried data
[in]	user_data	User data to be passed to the callback function

Returns:: SENSOR_ERROR_NONE on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	Not supported to record the sensor type
SENSOR_ERROR_PERMISSION_DENIED	Permission denied
SENSOR_ERROR_OPERATION_FAILED	Operation failed
SENSOR_ERROR_NO_DATA	No data retrieved

See also:: sensor_recorder_read()

int sensor_recorder_start	(	sensor_type_e	type,
		sensor_recorder_option_h	option
	)

Starts to record a given sensor type.

Since :: 2.3.2

Remarks:: Some sensor types are privileged. An application should have the privilege http://tizen.org/privilege/healthinfo to get access to the following sensors: SENSOR_HRM, SENSOR_HRM_LED_GREEN, SENSOR_HRM_LED_IR, SENSOR_HRM_LED_RED, SENSOR_HUMAN_PEDOMETER, SENSOR_HUMAN_SLEEP_MONITOR, SENSOR_HUMAN_SLEEP_DETECTOR, and SENSOR_HUMAN_STRESS_MONITOR.

Parameters:

[in]	type	A sensor type to be recorded
[in]	option	Option

Returns:: SENSOR_ERROR_NONE on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	Not supported to record the sensor type
SENSOR_ERROR_PERMISSION_DENIED	Permission denied
SENSOR_ERROR_OPERATION_FAILED	Operation failed
SENSOR_ERROR_NOT_AVAILABLE	The sensor is already being recorded by the request of the current application

See also:: sensor_recorder_stop()

int sensor_recorder_stop ( sensor_type_e type )

Stops recording a given sensor type.

Since :: 2.3.2

Parameters:

[in] type A sensor type being recorded

Returns:: SENSOR_ERROR_NONE on success, otherwise a negative error value

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported
SENSOR_ERROR_OPERATION_FAILED	Operation failed

See also:: sensor_recorder_start()

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation