The Sensor Listener API provides functions to observe data from sensors in the device.
Required Header
#include <sensor.h>
Overview
This Sensor Listener API provides functions to make use of sensors in the device. It allows applications to turn on or turn off sensors, change the parameters of sensors, and observe the changes of sensor data.
To control or listen a sensor, its corresponding sensor handle sensor_h needs to be acquired first, and this API provides two different ways to get the handle.
The conventional way is to get the sensor handles corresponding to the types of sensors, sensor_type_e, using sensor_get_sensor_list() or sensor_get_default_sensor(). You can access to the platform-defined sensors in this way.
Another way is to get the handles with with sensor URIs, using sensor_get_sensor_list_by_uri() or sensor_get_default_sensor_by_uri(). This method allows to get the handles for non-platform-defined sensors, i.e., sensors not listed in sensor_type_e. For example, a healthcare device may provide a galvanic skin response sensor. In addition, application-defined sensors registered via Sensor Provider API also can be accessed using this URI-based method.
Sensor URIs
A sensor URI is in the form of "http://<vendor>/sensor/<category>/<sensor-type>/<sensor-name>". where the "/<sensor-name>" can be omitted. In cases of platform-defined sensors, the vendor should be "tizen.org". The category can be one of "general" and "healthinfo", and "healthinfo" means that an application should have the privilege http://tizen.org/privilege/healthinfo to get the corresponding sensor handles. If the name is omitted, the URI denotes the sensors of the given type, it thus may correspond to more than one sensor. Otherwise, it corresponds to a specific sensor in the device. For example, the URI http://tizen.org/sensor/general/light denotes all the light sensors in the device, while http://tizen.org/sensor/general/light/front only denotes the light sensor named as "front".
Here are the platform-defined sensor URIs corresponding to the sensor types defined in sensor_type_e:
Functions |
int | sensor_create_listener (sensor_h sensor, sensor_listener_h *listener) |
| Creates a sensor listener.
|
int | sensor_destroy_listener (sensor_listener_h listener) |
| Releases all the resources allocated for a listener.
|
int | sensor_listener_start (sensor_listener_h listener) |
| Starts observing the sensor events regarding a given sensor listener.
|
int | sensor_listener_stop (sensor_listener_h listener) |
| Stops observing the sensor events regarding a given sensor listener.
|
int | sensor_listener_set_event_cb (sensor_listener_h listener, unsigned int interval_ms, sensor_event_cb callback, void *data) TIZEN_DEPRECATED_API |
| Registers the callback function to be invoked when sensor events are delivered via a sensor listener.
|
int | sensor_listener_unset_event_cb (sensor_listener_h listener) TIZEN_DEPRECATED_API |
| Unregisters the sensor event callback function attached to a given sensor listener.
|
int | sensor_listener_set_events_cb (sensor_listener_h listener, sensor_events_cb callback, void *user_data) |
| Sets the callback function to be invoked when sensor events are delivered via a sensor listener.
|
int | sensor_listener_unset_events_cb (sensor_listener_h listener) |
| Unsets the sensor events callback function attached to a given sensor listener.
|
int | sensor_listener_set_accuracy_cb (sensor_listener_h listener, sensor_accuracy_changed_cb callback, void *data) |
| Registers the callback function to be invoked when the accuracy of a sensor changes.
|
int | sensor_listener_unset_accuracy_cb (sensor_listener_h listener) |
| Unregisters the sensor accuracy change callback function attached to a given sensor listener.
|
int | sensor_listener_read_data (sensor_listener_h listener, sensor_event_s *event) TIZEN_DEPRECATED_API |
| Reads the current sensor data via a given sensor listener.
|
int | sensor_listener_read_data_list (sensor_listener_h listener, sensor_event_s **events, int *count) |
| Reads the current sensor data list via a given sensor listener.
|
int | sensor_listener_set_interval (sensor_listener_h listener, unsigned int interval_ms) |
| Changes the update interval of a sensor.
|
int | sensor_listener_set_max_batch_latency (sensor_listener_h listener, unsigned int max_batch_latency) |
| Sets the desired max batch latency of a sensor.
|
int | sensor_listener_set_attribute_int (sensor_listener_h listener, sensor_attribute_e attribute, int value) |
| Sets an attribute to control the behavior of a sensor listener.
|
int | sensor_listener_set_option (sensor_listener_h listener, sensor_option_e option) |
| Changes the power-saving behavior of a sensor listener.
|
int | sensor_listener_flush (sensor_listener_h listener) |
| Flushes stored data of a sensor.
|
Typedefs |
typedef struct sensor_listener_s * | sensor_listener_h |
| Sensor listener handle.
|
typedef void(* | sensor_event_cb )(sensor_h sensor, sensor_event_s *event, void *user_data) TIZEN_DEPRECATED_API |
| Called when a sensor event occurs.
|
typedef void(* | sensor_events_cb )(sensor_h sensor, sensor_event_s events[], int events_count, void *user_data) |
| Called when sensor events occur.
|
typedef void(* | sensor_accuracy_changed_cb )(sensor_h sensor, unsigned long long timestamp, sensor_data_accuracy_e accuracy, void *data) |
| Called when the accuracy of a sensor changes.
|
Defines |
#define | MAX_VALUE_SIZE 16 |
| The upper bound of sensor_event_s::value_count.
|
Define Documentation
Typedef Documentation
Called when the accuracy of a sensor changes.
Sensors can be affected by the environment. For example, SENSOR_MAGNETIC is sensitive to any surrounding objects that can influence electromagnetic fields. This function is called if the accuracy of the corresponding sensor is changed.
- Since :
- 2.3
- Parameters:
-
[in] | sensor | A sensor handle |
[in] | timestamp | The time in milliseconds when the accuracy changed |
[in] | accuracy | The current accuracy of the sensor |
[in] | data | The user data had passed to sensor_listener_set_accuracy_cb() |
Called when sensor events occur.
- Since :
- 5.5
- Parameters:
-
[in] | sensor | The corresponding sensor handle |
[in] | events | The sensor events |
[in] | events_count | The number of events |
[in] | user_data | The user data passed to sensor_listener_set_events_cb() |
- Precondition:
- The sensor needs to be started regarding a listener handle, using sensor_listener_start().
Sensor listener handle.
For each sensor_h, one or more sensor listeners can be created by using sensor_create_listener(). Then the sensor's data can observed asynchronously, can be read synchronously if available, via the listener. Applications are also able to control the behavior of each sensor, for example, update interval of sensor readings.
- Since :
- 2.3
Enumeration Type Documentation
Enumeration for sensor listener behavior attributes.
- Since :
- 3.0
- Enumerator:
SENSOR_ATTRIBUTE_AXIS_ORIENTATION |
Reference orientation of sensor data to be reported.
See sensor_axis_e for available attribute values.
|
SENSOR_ATTRIBUTE_PAUSE_POLICY |
Pause-and-resume policy of sensors.
See sensor_pause_e for available attribute values.
|
Enumeration for reference orientations of sensor data.
The sensor's physical orientation may differ from what applications are aware of, in cases that the device has a rotated screen, physically or logically. For example, a watch device may have right hand mode, which logically rotates the display 180 degrees. Applications may not be aware of such situations, thus they may receives sensor data inverted in X and Y directions. With SENSOR_AXIS_DISPLAY_ORIENTED option, applications can get data that are properly aligned with the orientation of which they are aware.
By default, SENSOR_AXIS_DISPLAY_ORIENTED is used. If you need to use the data that are not affected by display orientations, SENSOR_AXIS_DEVICE_ORIENTED needs to be set.
- Since :
- 3.0
- Enumerator:
SENSOR_AXIS_DEVICE_ORIENTED |
Using the device orientation as the reference coordinate system
|
SENSOR_AXIS_DISPLAY_ORIENTED |
Using the display orientation as the reference coordinate system
|
Enumeration for sensor data accuracy.
- Since :
- 2.3
- Enumerator:
SENSOR_DATA_ACCURACY_UNDEFINED |
Undefined
|
SENSOR_DATA_ACCURACY_BAD |
Not accurate
|
SENSOR_DATA_ACCURACY_NORMAL |
Moderately accurate
|
SENSOR_DATA_ACCURACY_GOOD |
Highly accurate
|
SENSOR_DATA_ACCURACY_VERYGOOD |
Very highly accurate
|
Enumeration for sensor options.
- Since :
- 2.3
- Enumerator:
SENSOR_OPTION_DEFAULT |
Does not receive data when the LCD is off and in the power save mode
|
SENSOR_OPTION_ON_IN_SCREEN_OFF |
Receives data when the LCD is off
|
SENSOR_OPTION_ON_IN_POWERSAVE_MODE |
Receives data in the power save mode
|
SENSOR_OPTION_ALWAYS_ON |
Receives data when the LCD is off and in the power save mode
|
Enumeration for pause policies of sensor listeners.
To be power-efficient, you can set the policy of how to pause and resume a sensor listener regarding the system status. By default, SENSOR_PAUSE_ALL is used to obtain the maximum power efficiency.
- Since :
- 3.0
- Enumerator:
SENSOR_PAUSE_NONE |
The sensor will not pause, unless the system goes into sleep mode
|
SENSOR_PAUSE_ON_DISPLAY_OFF |
The sensor pauses while the display is off
|
SENSOR_PAUSE_ON_POWERSAVE_MODE |
The sensor pauses while the power-save mode is enabled
|
SENSOR_PAUSE_ALL |
The sensor pauses in all the above cases
|
Function Documentation
Releases all the resources allocated for a listener.
- Since :
- 2.3
- Parameters:
-
[in] | listener | A listener handle |
- Returns:
- SENSOR_ERROR_NONE on success, otherwise a negative error value
- Return values:
-
- See also:
- sensor_create_listener()
Flushes stored data of a sensor.
Flushes all data of a sensor as if the max batch latency has expired. Data is delivered in the usual way through the event callback function.
In case of non-batching sensors, this function does nothing and returns SENSOR_ERROR_NONE.
- Since :
- 5.5
- Parameters:
-
[in] | listener | A listener handle |
- Returns:
- SENSOR_ERROR_NONE on success, otherwise a negative error value
- Return values:
-
Reads the current sensor data via a given sensor listener.
- Deprecated:
- Deprecated since 5.5. Use sensor_listener_read_data_list() instead.
This function synchronously reads the sensor reading of the corresponding sensor, if available. Otherwise, if the sensor is not ready to report its values, this function fails and returns SENSOR_ERROR_OPERATION_FAILED.
- Since :
- 2.3
- Parameters:
-
[in] | listener | A listener handle |
[out] | event | The retrieved sensor data |
- Returns:
- SENSOR_ERROR_NONE on success, otherwise a negative error value
- Return values:
-
Reads the current sensor data list via a given sensor listener.
This function synchronously reads the sensor reading of the corresponding sensor, if available. Otherwise, if the sensor is not ready to report its values, this function fails and returns SENSOR_ERROR_OPERATION_FAILED.
- Since :
- 5.5
- Parameters:
-
[in] | listener | A listener handle |
[out] | events | The retrieved sensor data list |
[out] | count | The number of event contained in events |
- Returns:
- SENSOR_ERROR_NONE on success, otherwise a negative error value
- Return values:
-
Registers the callback function to be invoked when the accuracy of a sensor changes.
In addition to sensor_event_cb(), sensor_accuracy_changed_cb() also can be attached to sensor listeners. With this accuracy callback function, applications can be notified the changes of the corresponding sensors separately.
- Since :
- 2.3
- Parameters:
-
[in] | listener | A listener handle |
[in] | callback | A callback function to attach with the listener handle |
[in] | data | A user data to be passed to the callback function |
- Returns:
- SENSOR_ERROR_NONE on success, otherwise a negative error value
- Return values:
-
- Precondition:
- The listener needs to be started to get the change callbacks.
- See also:
- sensor_listener_unset_accuracy_cb()
Sets an attribute to control the behavior of a sensor listener.
Applications can change the behavior of a sensor listener, for example, what is the reference coordinate of the sensor values, and when the system is allowed to turn off the sensor implicitly to reduce the power consumption. See sensor_attribute_e for more details about the available control parameters.
- Since :
- 3.0
- Parameters:
-
[in] | listener | A listener handle |
[in] | attribute | An attribute to change |
[in] | value | An attribute value |
- Returns:
- SENSOR_ERROR_NONE on success, otherwise a negative error value
- Return values:
-
Registers the callback function to be invoked when sensor events are delivered via a sensor listener.
- Deprecated:
- Deprecated since 5.5. Use sensor_listener_set_events_cb() instead.
- Since :
- 2.3
- Parameters:
-
[in] | listener | A listener handle |
[in] | interval_ms | A desired update interval between sensor events in milliseconds.
If 0, it will be automatically set to the default interval of the corresponding sensor.
See sensor_listener_set_interval() for more details. |
[in] | callback | A callback function to attach with the listener handle |
[in] | data | A user data to be passed to the callback function |
- Returns:
- SENSOR_ERROR_NONE on success, otherwise a negative error value
- Return values:
-
- See also:
- sensor_listener_unset_event_cb()
Sets the callback function to be invoked when sensor events are delivered via a sensor listener.
- Since :
- 5.5
- Parameters:
-
[in] | listener | A listener handle |
[in] | callback | A callback function to attach to the listener handle |
[in] | user_data | A user data to be passed to the callback function |
- Returns:
- SENSOR_ERROR_NONE on success, otherwise a negative error value
- Return values:
-
- See also:
- sensor_listener_unset_events_cb()
Changes the update interval of a sensor.
The specified interval is only a suggested interval between sensor measurements. You will get at least one sensor measurement within the interval you specify, but the actual interval between sensor measurements can be affected by other applications and the system. To reduce the system overhead, it is recommended to set the longest interval that you can, because the system usually chooses the shortest interval among all intervals specified.
- Since :
- 2.3
- Parameters:
-
[in] | listener | A listener handle |
[in] | interval_ms | A desired update interval between sensor events in milliseconds. If 0, it will be automatically set to the default interval of the corresponding sensor. |
- Returns:
- SENSOR_ERROR_NONE on success, otherwise a negative error value
- Return values:
-
- See also:
- sensor_get_min_interval()
Sets the desired max batch latency of a sensor.
Sensors that support batching may allow applications to change their maximum batch latencies. For example, if you set the latency as 10,000 ms, the sensor may store its data up to 10,000 ms, before delivering the data through the HAL.
In case of non-batching sensors, this function returns SENSOR_ERROR_NONE, but nothing is affected by the input latency value.
- Since :
- 2.3
- Parameters:
-
[in] | listener | A listener handle |
[in] | max_batch_latency | A desired batch latency in milliseconds |
- Returns:
- SENSOR_ERROR_NONE on success, otherwise a negative error value
- Return values:
-
Changes the power-saving behavior of a sensor listener.
- Since :
- 2.3
- Parameters:
-
[in] | listener | A listener handle |
[in] | option | A sensor option |
- Returns:
- SENSOR_ERROR_NONE on success, otherwise a negative error value
- Return values:
-
Starts observing the sensor events regarding a given sensor listener.
If a sensor listener is started, its event callback function starts to be called whenever the corresponding sensor events occur.
For example, SENSOR_ACCELEROMETER reports its sensor readings repeatedly, with a specific update interval. Note that, unlike the accelerometer, sensors like SENSOR_PROXIMITY emit events only if their states change.
- Since :
- 2.3
- Parameters:
-
[in] | listener | A listener handle |
- Returns:
- SENSOR_ERROR_NONE on success, otherwise a negative error value
- Return values:
-
- Precondition:
- The listener needs to be created in advance, by using sensor_create_listener(). Then the callback function needs to be attached to the listener, by using sensor_listener_set_event_cb().
- See also:
- sensor_listener_stop()
Stops observing the sensor events regarding a given sensor listener.
The listener's event callback function stops being called. But the sensor itself may not be stopped if there are other listeners that are using the same sensor.
- Since :
- 2.3
- Parameters:
-
[in] | listener | A listener handle |
- Returns:
- SENSOR_ERROR_NONE on success, otherwise a negative error value
- Return values:
-
- See also:
- sensor_listener_start()
Unregisters the sensor accuracy change callback function attached to a given sensor listener.
- Since :
- 2.3
- Parameters:
-
[in] | listener | A listener handle |
- Returns:
- SENSOR_ERROR_NONE on success, otherwise a negative error value
- Return values:
-
- See also:
- sensor_listener_set_accuracy_cb()
Unsets the sensor events callback function attached to a given sensor listener.
- Since :
- 5.5
- Parameters:
-
[in] | listener | A listener handle |
- Returns:
- SENSOR_ERROR_NONE on success, otherwise a negative error value
- Return values:
-
- See also:
- sensor_listener_set_events_cb()