Tizen Native API  6.5
Sensor Listener

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

#define MAX_VALUE_SIZE   16

The upper bound of sensor_event_s::value_count.

Since :
2.3

Typedef Documentation

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.

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]sensorA sensor handle
[in]timestampThe time in milliseconds when the accuracy changed
[in]accuracyThe current accuracy of the sensor
[in]dataThe user data had passed to sensor_listener_set_accuracy_cb()
typedef void(* sensor_event_cb)(sensor_h sensor, sensor_event_s *event, void *user_data) TIZEN_DEPRECATED_API

Called when a sensor event occurs.

Deprecated:
Deprecated since 5.5. Use sensor_events_cb() instead.
Since :
2.3
Remarks:
sensor should not be freed, it's managed by platform.
event should not be freed and can be used only in the callback. To use outside the callback, make a copy.
Parameters:
[in]sensorThe corresponding sensor handle
[in]eventA sensor event
[in]user_dataThe user data had passed to sensor_listener_set_event_cb()
Precondition:
The sensor needs to be started regarding a listener handle, using sensor_listener_start().
typedef void(* sensor_events_cb)(sensor_h sensor, sensor_event_s events[], int events_count, void *user_data)

Called when sensor events occur.

Since :
5.5
Remarks:
sensor should not be freed, it's managed by platform.
events should not be freed and can be used only in the callback. To use outside the callback, make a copy.
Parameters:
[in]sensorThe corresponding sensor handle
[in]eventsThe sensor events
[in]events_countThe number of events
[in]user_dataThe user data passed to sensor_listener_set_events_cb()
Precondition:
The sensor needs to be started regarding a listener handle, using sensor_listener_start().
typedef struct sensor_listener_s* sensor_listener_h

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

int sensor_create_listener ( sensor_h  sensor,
sensor_listener_h listener 
)

Creates a sensor listener.

Since :
2.3
Remarks:
The listener must be released using sensor_destroy_listener().
Parameters:
[in]sensorA sensor handle
[out]listenerA listener handle of sensor
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
Precondition:
The handle sensor needs to be initialized using sensor_get_default_sensor() or sensor_get_sensor_list() in advance.

Releases all the resources allocated for a listener.

Since :
2.3
Remarks:
If this function is called while the sensor is still running, that is, sensor_listener_start() was called but sensor_listener_stop() was not, then it is implicitly stopped.
Parameters:
[in]listenerA listener handle
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
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]listenerA listener 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

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
Remarks:
As a sensor usually works in an event-driven manner, it may not be able to read its data on demand. Then this function tries to return the last known values.
To be able to read the current values or the last known values, the sensor needs to be enabled in advance. As an application cannot be sure that the sensor is already enabled by other applications, it is recommended to start the sensor explicitly by using sensor_listener_start().
But note that even if the sensor is started, on-demand reading can fail anyway, thus it would be better to use the asynchronous callback approach.
Parameters:
[in]listenerA listener handle
[out]eventThe retrieved sensor data
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_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.

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
Remarks:
As a sensor usually works in an event-driven manner, it may not be able to read its data on demand. In such cases this function tries to return the last known values.
When there are last known values that are caused by multi-event publishing, the count is greater than or equal to 1.
To be able to read the current values or the last known values, the sensor needs to be enabled in advance. As an application cannot be sure that the sensor is already enabled by other applications, it is recommended to start the sensor explicitly by using sensor_listener_start().
But note that even if the sensor is started, on-demand reading can fail anyway, thus it would be better to use the asynchronous callback approach. The events must be released using free(), if not being used anymore.
Parameters:
[in]listenerA listener handle
[out]eventsThe retrieved sensor data list
[out]countThe number of event contained in events
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_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.

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]listenerA listener handle
[in]callbackA callback function to attach with the listener handle
[in]dataA user 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_OPERATION_FAILEDOperation failed
Precondition:
The listener needs to be started to get the change callbacks.
See also:
sensor_listener_unset_accuracy_cb()
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.

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]listenerA listener handle
[in]attributeAn attribute to change
[in]valueAn attribute value
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
int sensor_listener_set_event_cb ( sensor_listener_h  listener,
unsigned int  interval_ms,
sensor_event_cb  callback,
void *  data 
)

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]listenerA listener handle
[in]interval_msA 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]callbackA callback function to attach with the listener handle
[in]dataA user 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_OPERATION_FAILEDOperation failed
See also:
sensor_listener_unset_event_cb()
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.

Since :
5.5
Parameters:
[in]listenerA listener handle
[in]callbackA callback function to attach to the listener handle
[in]user_dataA user 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_OPERATION_FAILEDOperation failed
See also:
sensor_listener_unset_events_cb()
int sensor_listener_set_interval ( sensor_listener_h  listener,
unsigned int  interval_ms 
)

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
Remarks:
Normally, a sensor's default update interval is 100 ms, and you can use the default interval by setting the interval to 0. However, please note that, the default interval varies with the sensor and the device.
In addition, a sensor has the lower and the upper bound of its update interval, usually 10 and 1000 ms respectively. These lower and upper bounds also can vary with the sensor and the device, any invalid input values exceeding the bounds will be implicitly adjusted into the valid range.
Parameters:
[in]listenerA listener handle
[in]interval_msA 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:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_OPERATION_FAILEDOperation failed
See also:
sensor_get_min_interval()
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.

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
Remarks:
Even if you set a batch latency, the sensor may not work as you intended, as one sensor can be used by more than one listeners. In addition, some batch sensors may already have fixed batching latency or batching queue size, which cannot be altered by applications.
Parameters:
[in]listenerA listener handle
[in]max_batch_latencyA desired batch latency in milliseconds
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter

Changes the power-saving behavior of a sensor listener.

Since :
2.3
Remarks:
sensor_listener_set_attribute_int() with SENSOR_ATTRIBUTE_PAUSE_POLICY replaces this function.
Parameters:
[in]listenerA listener handle
[in]optionA sensor option
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

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]listenerA listener 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
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]listenerA listener 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
See also:
sensor_listener_start()

Unregisters the sensor accuracy change callback function attached to a given sensor listener.

Since :
2.3
Parameters:
[in]listenerA listener 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
See also:
sensor_listener_set_accuracy_cb()

Unregisters the sensor event callback function attached to a given sensor listener.

Deprecated:
Deprecated since 5.5. Use sensor_listener_unset_events_cb() instead.
Since :
2.3
Parameters:
[in]listenerA listener 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
See also:
sensor_listener_set_event_cb()

Unsets the sensor events callback function attached to a given sensor listener.

Since :
5.5
Parameters:
[in]listenerA listener 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
See also:
sensor_listener_set_events_cb()