Sensor Listener API

The sensor listener API allows an application to register listeners for sensors and get notified whenever sensor data are read from the sensor devices. An application calls the sensor_register_listener() function to register a listener that specifies the callback function and the types of sensor data to listen for from a sensor device.

When the sensor_read() function defined in the sensor API is called to read the sensor data for the specified sensor types from a sensor, the sensor_read() function calls the listener callback, passing it the sensor data that is read from the sensor.

An application calls the sensor_unregister_listener() function to unregister a listener if it no longer needs notifications when data is read from a sensor.

An application can use listeners in conjunction with the sensor manager poller. An application can configure a polling interval for a sensor and register a listener for the sensor types it wants to listen for from the sensor. When the sensor manager poller reads the sensor data from the sensor at each polling interval, the listener callback is called with the sensor data passed to it.

An application can also use listeners for other purposes. For example, an application that uses the OIC sensor server may want to register listeners. The OIC sensor server handles all the OIC requests for the sensor resources and an application does not know about the OIC requests. An application can install a listener if it wants to know about a request for a sensor resource or use the sensor data that the OIC sensor server reads from the sensor.

Data Structures

The struct sensor_listener data structure represents a listener. You must initialize a listener structure with a bit mask of the sensor types to listen for from a sensor, a callback function that is called when sensor data is read for one of the sensor types, and an opaque argument to pass to the callback before you call the sensor_register_listener() function to register a listener.

struct sensor_listener {
{
    /* The type of sensor data to listen for, this is interpreted as a
     * mask, and this listener is called for all sensor types on this
     * sensor that match the mask.
     */
    sensor_type_t sl_sensor_type;

    /* Sensor data handler function, called when has data */
    sensor_data_func_t sl_func;

    /* Argument for the sensor listener */
    void *sl_arg;

    /* Next item in the sensor listener list.  The head of this list is
     * contained within the sensor object.
     */
    SLIST_ENTRY(sensor_listener) sl_next;
};

API

int sensor_register_listener(struct sensor *sensor, struct sensor_listener *listener)

Register a sensor listener.

This allows a calling application to receive callbacks for data from a given sensor object.

For more information on the type of callbacks available, see the documentation for the sensor listener structure.

Parameters:

• sensor – The sensor to register a listener on

• listener – The listener to register onto the sensor

Returns:

0 on success, non-zero error code on failure.

int sensor_unregister_listener(struct sensor *sensor, struct sensor_listener *listener)

Un-register a sensor listener.

This allows a calling application to clear callbacks for a given sensor object.

Parameters:

• sensor – The sensor object

• listener – The listener to remove from the sensor listener list

Returns:

0 on success, non-zero error code on failure.

int sensor_register_err_func(struct sensor *sensor, sensor_error_func_t err_fn, void *arg)

Register a sensor error callback.

The callback is executed when the sensor manager fails to read from the given sensor.

Parameters:

• sensor – The sensor to register an error callback on.

• err_fn – The function to execute when a read fails.

• arg – Optional argument to pass to the callback.

Returns:

0 on success, non-zero error code on failure.