Tizen Native API  3.0
Sensor Recorder

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]typeSensor type
[in]dataRetrieved data record
[in]remainsNumber of remaining records to be delivered
[in]errorError
[in]user_dataThe 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

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

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

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

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

Creates a recorder option handle.

Since :
2.3.2
Remarks:
The option must be released using sensor_recorder_destroy_option().
Parameters:
[out]optionOption handle
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_OUT_OF_MEMORYOut of memory
SENSOR_ERROR_OPERATION_FAILEDOperation failed

Creates a recorder query handle.

Since :
2.3.2
Remarks:
The query must be released using sensor_recorder_destroy_query().
Parameters:
[out]queryQuery handle
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_OUT_OF_MEMORYOut of memory
SENSOR_ERROR_OPERATION_FAILEDOperation failed

Gets a double value from a record data.

Since :
2.3.2
Parameters:
[in]dataRecord data handle
[in]keyData attribute to retrieve
[out]valueRetrieved value
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_OPERATION_FAILEDOperation failed
SENSOR_ERROR_NO_DATANo data retrieved

Gets an integer value from a record data.

Since :
2.3.2
Parameters:
[in]dataRecord data handle
[in]keyData attribute to retrieve
[out]valueRetrieved value
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_OPERATION_FAILEDOperation failed
SENSOR_ERROR_NO_DATANo 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]dataRecord data handle
[out]start_timeStart time of the time period of the record
[out]end_timeEnd time of the time period of the record
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_OPERATION_FAILEDOperation failed

Destroys a recorder option handle.

Since :
2.3.2
Parameters:
[in]optionOption handle
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_OPERATION_FAILEDOperation failed

Destroys a recorder query handle.

Since :
2.3.2
Parameters:
[in]queryQuery handle
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_OPERATION_FAILEDOperation 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]typeA sensor type to check
[out]supportedIf supported, true; otherwise false
Returns:
SENSOR_ERROR_NONE on success; otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_OPERATION_FAILEDOperation failed

Sets a recording option parameter.

Since :
2.3.2
Parameters:
[in]optionOption handle
[in]paramOption parameter
[in]valueValue
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_OPERATION_FAILEDOperation failed

Sets an integer-type query parameter.

Since :
2.3.2
Parameters:
[in]queryQuery handle
[in]paramQuery parameter
[in]valueValue
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_OPERATION_FAILEDOperation failed

Sets a time-type query parameter.

Since :
2.3.2
Parameters:
[in]queryQuery handle
[in]paramQuery parameter
[in]tTime
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_OPERATION_FAILEDOperation 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]typeSensor type
[in]queryQuery handle
[in]cbCallback function to receive the queried data
[in]user_dataUser data to be passed to the callback function
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_NOT_SUPPORTEDNot supported to record the sensor type
SENSOR_ERROR_PERMISSION_DENIEDPermission denied
SENSOR_ERROR_OPERATION_FAILEDOperation 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]typeSensor type
[in]queryQuery handle
[in]cbCallback function to receive the queried data
[in]user_dataUser data to be passed to the callback function
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_NOT_SUPPORTEDNot supported to record the sensor type
SENSOR_ERROR_PERMISSION_DENIEDPermission denied
SENSOR_ERROR_OPERATION_FAILEDOperation failed
SENSOR_ERROR_NO_DATANo data retrieved
See also:
sensor_recorder_read()

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]typeA sensor type to be recorded
[in]optionOption
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_NOT_SUPPORTEDNot supported to record the sensor type
SENSOR_ERROR_PERMISSION_DENIEDPermission denied
SENSOR_ERROR_OPERATION_FAILEDOperation failed
SENSOR_ERROR_NOT_AVAILABLEThe sensor is already being recorded by the request of the current application
See also:
sensor_recorder_stop()

Stops recording a given sensor type.

Since :
2.3.2
Parameters:
[in]typeA sensor type being recorded
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_NOT_SUPPORTEDThe sensor type is not supported
SENSOR_ERROR_OPERATION_FAILEDOperation failed
See also:
sensor_recorder_start()