Tizen Native API  3.0

The Sensor API provides sensor types and sensor information.

Required Header

#include <sensor.h>

Overview

This Sensor API provides sensor types and sensor error types to make use of sensors in the device. A variety of hardware/virtual sensors are typically available on mobile devices. This Sensor API also provides functions for sensor information, such as name, vendor.

Related Features

This API is related with the following features:

Functions

int sensor_is_supported (sensor_type_e type, bool *supported)
 Checks whether a given sensor type is supported in the current device.
int sensor_is_wake_up (sensor_h sensor, bool *wakeup)
 Checks whether a given sensor is a wake-up sensor or not.
int sensor_get_default_sensor (sensor_type_e type, sensor_h *sensor)
 Gets the handle for the default sensor of a given type.
int sensor_get_sensor_list (sensor_type_e type, sensor_h **list, int *sensor_count)
 Gets the handle list of the sensors of a given type.
int sensor_get_name (sensor_h sensor, char **name)
 Gets the name of a sensor.
int sensor_get_vendor (sensor_h sensor, char **vendor)
 Gets the vendor of a sensor.
int sensor_get_type (sensor_h sensor, sensor_type_e *type)
 Gets the sensor type of a sensor.
int sensor_get_min_range (sensor_h sensor, float *min_range)
 Gets the lower bound of the sensor reading of a sensor.
int sensor_get_max_range (sensor_h sensor, float *max_range)
 Gets the upper bound of the sensor readings of a sensor.
int sensor_get_resolution (sensor_h sensor, float *resolution)
 Gets the resolution of the sensor readings of a sensor.
int sensor_get_min_interval (sensor_h sensor, int *min_interval)
 Gets the possible shortest update interval of a sensor.
int sensor_get_fifo_count (sensor_h sensor, int *fifo_count)
 Gets the size of the hardware FIFO of a sensor.
int sensor_get_max_batch_count (sensor_h sensor, int *max_batch_count)
 Gets the maximum batch count of a sensor.

Typedefs

typedef void * sensor_h
 Sensor handle.

Typedef Documentation

typedef void* sensor_h

Sensor handle.

The handle for controlling a specific sensor can be retrieved using sensor_get_default_sensor().
The function returns the handle of the default sensor of a given type, and usually, a device has one sensor for one type. However, if the device supports multiple sensors of the same type, sensor_get_sensor_list() function can be used to get the list of all the sensors of the type.

Since :
2.3

Enumeration Type Documentation

Enumeration for errors.

Since :
2.3
Enumerator:
SENSOR_ERROR_NONE 

Successful

SENSOR_ERROR_IO_ERROR 

I/O error

SENSOR_ERROR_INVALID_PARAMETER 

Invalid parameter

SENSOR_ERROR_NOT_SUPPORTED 

Not supported

SENSOR_ERROR_PERMISSION_DENIED 

Permission denied

SENSOR_ERROR_OUT_OF_MEMORY 

Out of memory

SENSOR_ERROR_NO_DATA 

No data available (Since 3.0)

SENSOR_ERROR_NOT_NEED_CALIBRATION 

Sensor doesn't need calibration

SENSOR_ERROR_OPERATION_FAILED 

Operation failed

SENSOR_ERROR_NOT_AVAILABLE 

The sensor is supported, but currently not available (Since 3.0)

Enumeration for pedestrian state.

In its sensor_event_s, SENSOR_HUMAN_PEDOMETER reports the user's pedestrian state as one of the followings.

Since :
3.0
Enumerator:
SENSOR_PEDOMETER_STATE_UNKNOWN 

Uncertain

SENSOR_PEDOMETER_STATE_STOP 

The user is not moving

SENSOR_PEDOMETER_STATE_WALK 

The user is walking

SENSOR_PEDOMETER_STATE_RUN 

The user is running

Enumeration for proximity sensor events.

In its sensor_event_s, SENSOR_PROXIMITY reports the existence of nearby objects in front of the sensor as one of the followings.

Since :
2.3
Enumerator:
SENSOR_PROXIMITY_NEAR 

An object is placed near the proximity sensor

SENSOR_PROXIMITY_FAR 

No object is placed near the proximity sensor

Enumeration for sleep state.

In its sensor_event_s, SENSOR_HUMAN_SLEEP_MONITOR reports the user's sleep state as one of the followings.

Since :
3.0
Enumerator:
SENSOR_SLEEP_STATE_UNKNOWN 

Uncertain

SENSOR_SLEEP_STATE_WAKE 

The user is awake

SENSOR_SLEEP_STATE_SLEEP 

The user is asleep

Enumeration for sensor types.

Since :
2.3
Enumerator:
SENSOR_ALL 

All sensors. This can be used to retrieve sensor_h for all available sensors.

SENSOR_ACCELEROMETER 

Accelerometer

SENSOR_GRAVITY 

Gravity sensor

SENSOR_LINEAR_ACCELERATION 

Linear acceleration sensor

SENSOR_MAGNETIC 

Magnetic sensor

SENSOR_ROTATION_VECTOR 

Rotation vector sensor

SENSOR_ORIENTATION 

Orientation sensor

SENSOR_GYROSCOPE 

Gyroscope

SENSOR_LIGHT 

Light sensor

SENSOR_PROXIMITY 

Proximity sensor

SENSOR_PRESSURE 

Pressure sensor

SENSOR_ULTRAVIOLET 

Ultraviolet sensor

SENSOR_TEMPERATURE 

Temperature sensor

SENSOR_HUMIDITY 

Humidity sensor

SENSOR_HRM 

Heart-rate monitor (Since 2.3.1)
Privilege : http://tizen.org/privilege/healthinfo

SENSOR_HRM_LED_GREEN 

Green LED sensor of HRM (Since 2.3.1)
Privilege : http://tizen.org/privilege/healthinfo

SENSOR_HRM_LED_IR 

Infra-Red LED sensor of HRM (Since 2.3.1)
Privilege : http://tizen.org/privilege/healthinfo

SENSOR_HRM_LED_RED 

Red LED sensor of HRM (Since 2.3.1)
Privilege : http://tizen.org/privilege/healthinfo

SENSOR_GYROSCOPE_UNCALIBRATED 

Uncalibrated Gyroscope sensor (Since 2.4)

SENSOR_GEOMAGNETIC_UNCALIBRATED 

Uncalibrated Geomagnetic sensor (Since 2.4)

SENSOR_GYROSCOPE_ROTATION_VECTOR 

Gyroscope-based rotation vector sensor (Since 2.4)

SENSOR_GEOMAGNETIC_ROTATION_VECTOR 

Geomagnetic-based rotation vector sensor (Since 2.4)

SENSOR_HUMAN_PEDOMETER 

Pedometer (Since 3.0)
Privilege : http://tizen.org/privilege/healthinfo

SENSOR_HUMAN_SLEEP_MONITOR 

Sleep monitor (Since 3.0)
Privilege : http://tizen.org/privilege/healthinfo

SENSOR_HUMAN_SLEEP_DETECTOR 

Sleep detector (Since 3.0)
Privilege : http://tizen.org/privilege/healthinfo

SENSOR_HUMAN_STRESS_MONITOR 

Stress monitor (Since 3.0)
Privilege : http://tizen.org/privilege/healthinfo

SENSOR_LAST 

End of sensor enum values (Deprecated since 3.0)

SENSOR_CUSTOM 

Custom sensor (Deprecated since 3.0)


Function Documentation

int sensor_get_default_sensor ( sensor_type_e  type,
sensor_h sensor 
)

Gets the handle for the default sensor of a given type.

This function returns the handle for the sensor of a given type. In case that the device has more than one sensors of the type, this returns only the default sensor, which is designated by the device.

Since :
2.3
Remarks:
Some sensor types are privileged. An application should have the privilege http://tizen.org/privilege/healthinfo to get handles for 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 get the handle of its default sensor
[out]sensorThe sensor handle of the default sensor
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 in the current device
SENSOR_ERROR_PERMISSION_DENIEDPermission denied
See also:
sensor_get_sensor_list()
int sensor_get_fifo_count ( sensor_h  sensor,
int *  fifo_count 
)

Gets the size of the hardware FIFO of a sensor.

This function returns the size of the hardware FIFO that may be used by a specific sensor to support batching. However, regarding the underlying hardware configuration, the returned count may not mean the maximum number of sensor data that can be batched. See sensor_get_max_batch_count() for such purpose, finding out the possible maximum number of batched data.

Since :
2.3
Parameters:
[in]sensorA sensor handle
[out]fifo_countThe FIFO count
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_get_max_batch_count ( sensor_h  sensor,
int *  max_batch_count 
)

Gets the maximum batch count of a sensor.

This function returns the maximum number of sensor data events that can be possibly delivered when the batched data are flushed. Therefore, this count can be used to check whether the sensor supports batching or not.
If this returns a positive count, i.e., the sensor supports batching, the count also can be used to guess the possible longest batch latency of the sensor, with respect to the update interval to use.

Since :
2.3
Parameters:
[in]sensorA sensor handle
[out]max_batch_countIf the sensor does not support batching, 0; otherwise a positive integer.
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
See also:
sensor_listener_set_max_batch_latency()
int sensor_get_max_range ( sensor_h  sensor,
float *  max_range 
)

Gets the upper bound of the sensor readings of a sensor.

This function returns the upper bound of the range of possible sensor values, which are generated by the corresponding sensor denoted by a sensor handle.
If all sensor values are in the same unit, e.g., $\mbox{m/s}^2$ or degrees, the upper bound of all sensor values is returned. Otherwise, the upper bound of the representative sensor value, e.g., the step count of SENSOR_HUMAN_PEDOMETER, is returned.

Since :
2.3
Parameters:
[in]sensorA sensor handle
[out]max_rangeThe upper bound
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
See also:
sensor_get_min_range()
int sensor_get_min_interval ( sensor_h  sensor,
int *  min_interval 
)

Gets the possible shortest update interval of a sensor.

Since :
2.3
Parameters:
[in]sensorA sensor handle
[out]min_intervalThe shortest interval in milliseconds
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_get_min_range ( sensor_h  sensor,
float *  min_range 
)

Gets the lower bound of the sensor reading of a sensor.

This function returns the lower bound of the range of possible sensor values, which are generated by the corresponding sensor denoted by a sensor handle.
If all sensor values are in the same unit, e.g., $\mbox{m/s}^2$ or degrees, the lower bound of all sensor values is returned. Otherwise, the lower bound of the representative sensor value, e.g., the step count of SENSOR_HUMAN_PEDOMETER, is returned.

Since :
2.3
Parameters:
[in]sensorA sensor handle
[out]min_rangeThe lower bound
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
See also:
sensor_get_max_range()
int sensor_get_name ( sensor_h  sensor,
char **  name 
)

Gets the name of a sensor.

Since :
2.3
Parameters:
[in]sensorA sensor handle
[out]nameThe name of the sensor
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
int sensor_get_resolution ( sensor_h  sensor,
float *  resolution 
)

Gets the resolution of the sensor readings of a sensor.

This function returns the resolution of the sensor readings. The resolution denotes the smallest difference between sensor readings, each of which is in the range that can be verified by sensor_get_min_range() and sensor_get_max_range().

Since :
2.3
Parameters:
[in]sensorA sensor handle
[out]resolutionThe resolution
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_get_sensor_list ( sensor_type_e  type,
sensor_h **  list,
int *  sensor_count 
)

Gets the handle list of the sensors of a given type.

A device may have more than one sensors of the given type. In such case, this function can be used to get the handles of all sensors of the type.
The first element of the list denotes the default sensor, which can be retrieved by sensor_get_default_sensor().

Since :
2.3
Remarks:
Some sensor types are privileged. An application should have the privilege http://tizen.org/privilege/healthinfo to get handles for 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.
Instead of specifying a sensor type, it is able to get the handles for all available sensors by using SENSOR_ALL.
The list must be released using free(), if not being used anymore.
Parameters:
[in]typeA sensor type to get the list of sensor handles
[out]listAn array of the sensor handles
[out]sensor_countThe number of handles contained in list
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 in the current device
SENSOR_ERROR_PERMISSION_DENIEDPermission denied
SENSOR_ERROR_OUT_OF_MEMORYOut of memory
int sensor_get_type ( sensor_h  sensor,
sensor_type_e type 
)

Gets the sensor type of a sensor.

Since :
2.3
Parameters:
[in]sensorA sensor handle
[out]typeThe type of the sensor
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_get_vendor ( sensor_h  sensor,
char **  vendor 
)

Gets the vendor of a sensor.

Since :
2.3
Parameters:
[in]sensorA sensor handle
[out]vendorThe vendor of the sensor
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
int sensor_is_supported ( sensor_type_e  type,
bool *  supported 
)

Checks whether a given sensor type is supported in the current device.

If the given sensor type is not supported, sensor_get_default_sensor() will return an error. It is thus recommended to check the availability of the sensor before actually acquiring sensor_h.

Since :
2.3
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
int sensor_is_wake_up ( sensor_h  sensor,
bool *  wakeup 
)

Checks whether a given sensor is a wake-up sensor or not.

If a sensor is a wake-up sensor, the sensor is able to wake-up the system to report its sensor data even if the system is in sleep mode.

Since :
3.0
Parameters:
[in]sensorA sensor handle to check
[out]wakeupIf the sensor is a wake-up sensor, true; otherwise false
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
The handle sensor needs to be initialized using sensor_get_default_sensor() or sensor_get_sensor_list() in advance.