The Sensor Listener API provides functions to start/stop sensors and receive sensor events.

Required Header

#include <sensor.h>

Overview

This Sensor API provides functions to make use of sensors in the device. A variety of hardware/virtual sensors are typically available on mobile devices.

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)
	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)
	Unregisters the sensor event 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)
	Reads the current sensor data 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.
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 data)
	Called when a sensor event occurs.
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.1

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.1

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()

typedef void(* sensor_event_cb)(sensor_h sensor, sensor_event_s *event, void *data)

Called when a sensor event occurs.

Since :: 2.3.1

Parameters:

[in]	sensor	The corresponding sensor handle
[in]	event	A sensor event
[in]	data	The 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 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.1

Enumeration Type Documentation

enum sensor_attribute_e

Enumeration for sensor listener behavior attributes.

Since :: 2.3.2

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.

enum sensor_axis_e

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 :: 2.3.2

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

enum sensor_data_accuracy_e

Enumeration for sensor data accuracy.

Since :: 2.3.1

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

enum sensor_option_e

Enumeration for sensor options.

Since :: 2.3.1

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

enum sensor_pause_e

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 :: 2.3.2

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.1

Remarks:: The listener must be released using sensor_destroy_listener().

Parameters:

[in]	sensor	A sensor handle
[out]	listener	A listener handle of `sensor`

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

Precondition:: The handle sensor needs to be initialized using sensor_get_default_sensor() or sensor_get_sensor_list() in advance.

int sensor_destroy_listener ( sensor_listener_h listener )

Releases all the resources allocated for a listener.

Since :: 2.3.1

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] listener A listener handle

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

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: sensor_create_listener()

int sensor_listener_read_data	(	sensor_listener_h	listener,
		sensor_event_s *	event
	)

Reads the current sensor data 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 :: 2.3.1

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 always, thus it would be better to use the asynchronous callback approach.

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:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_OPERATION_FAILED	Operation 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.1

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:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_OPERATION_FAILED	Operation 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 :: 2.3.2

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:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid 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.

Since :: 2.3.1

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:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_OPERATION_FAILED	Operation failed

See also:: sensor_listener_unset_event_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.1

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]	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:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_OPERATION_FAILED	Operation 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 cases of non-batching sensors, this function returns SENSOR_ERROR_NONE, but nothing is affected by the input latency value.

Since :: 2.3.1

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]	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:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter

int sensor_listener_set_option	(	sensor_listener_h	listener,
		sensor_option_e	option
	)

Changes the power-saving behavior of a sensor listener.

Since :: 2.3.1

Remarks:: sensor_listener_set_attribute_int() with SENSOR_ATTRIBUTE_PAUSE_POLICY replaces this function.

Parameters:

[in]	listener	A listener handle
[in]	option	A sensor 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_OPERATION_FAILED	Operation failed

int sensor_listener_start ( sensor_listener_h listener )

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.1

Parameters:

[in] listener A listener 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

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()

int sensor_listener_stop ( sensor_listener_h listener )

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.1

Parameters:

[in] listener A listener 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

See also:: sensor_listener_start()

int sensor_listener_unset_accuracy_cb ( sensor_listener_h listener )

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

Since :: 2.3.1

Parameters:

[in] listener A listener 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

See also:: sensor_listener_set_accuracy_cb()

int sensor_listener_unset_event_cb ( sensor_listener_h listener )

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

Since :: 2.3.1

Parameters:

[in] listener A listener 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

See also:: sensor_listener_set_event_cb()

Required Header

Overview

Functions

Typedefs

Defines

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation