Functions
int	sensor_is_supported (sensor_type_e type, bool *supported)
	Checks whether a given sensor type is available on a device.
int	sensor_get_default_sensor (sensor_type_e type, sensor_h *sensor)
	Gets a specific sensor handle.
int	sensor_get_sensor_list (sensor_type_e type, sensor_h *list, int sensor_count)
	Gets a sensor list.
int	sensor_create_listener (sensor_h sensor, sensor_listener_h *listener)
	Creates a sensor listener.
int	sensor_destroy_listener (sensor_listener_h listener)
	Destroys the sensor handle and releases all its resources.
int	sensor_listener_start (sensor_listener_h listener)
	Starts the sensor server for the given listener.
int	sensor_listener_stop (sensor_listener_h listener)
	Stops the sensor server for the given listener.
int	sensor_listener_set_event_cb (sensor_listener_h listener, unsigned int interval_ms, sensor_event_cb callback, void *data)
	Registers a callback function to be invoked when a sensor event occurs.
int	sensor_listener_unset_event_cb (sensor_listener_h listener)
	Unregisters the sensor callback function.
int	sensor_listener_set_accuracy_cb (sensor_listener_h listener, sensor_accuracy_changed_cb callback, void *data)
	Registers an accuracy callback function to be invoked when the accuracy of a sensor has changed.
int	sensor_listener_unset_accuracy_cb (sensor_listener_h listener)
	Unregisters the sensor accuracy changed callback function.
int	sensor_listener_read_data (sensor_listener_h listener, sensor_event_s *event)
	Gets sensor data.
int	sensor_listener_set_interval (sensor_listener_h listener, unsigned int interval_ms)
	Changes the interval at sensor measurements.
int	sensor_listener_set_max_batch_latency (sensor_listener_h listener, unsigned int max_batch_latency)
	Changes the max batch latency at sensor measurements.
int	sensor_listener_set_option (sensor_listener_h listener, sensor_option_e option)
	Changes the option of the sensor.
Typedefs
typedef void *	sensor_h
	The sensor handle.
typedef struct sensor_listener_s *	sensor_listener_h
	The 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 has changed.

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

Required Header

#include <sensor.h>

Overview

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

Related Features

This API is related with the following features:

It is recommended to design feature related codes in your application for reliability.

You can check if a devrice supports the related features for this API by using System Information, thereby controlling the procedure of your application.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from Feature Element.

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 has changed.

When something is artificially influencing, such as ferrous metal objects or electromagnetic fields (car electrical systems, automobile engines, steel pitons, and so on.), this callback is called. One way of implementing this callback is to instruct a user to make big 8-like gestures with the device.

Since :: 2.3

Parameters:

[in]	sensor	The sensor handle
[in]	timestamp	The time in milliseconds at which the event happened
[in]	accuracy	The accuracy of this data
[in]	user_data	The user data passed from the callback registration function

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

Called when a sensor event occurs.

Since :: 2.3

Parameters:

[in]	sensor	The sensor handle
[in]	event	The event information
[in]	data	The user data passed from the callback registration function

See also:: sensor_create_listener(); sensor_listener_set_event_cb(); sensor_listener_unset_event_cb()

typedef void* sensor_h

The sensor handle.

This handle indicates a specific sensor itself.

Since :: 2.3

typedef struct sensor_listener_s* sensor_listener_h

The listener handle.

This listener is an event listener used to receive sensor data asynchronously.

Since :: 2.3

Enumeration Type Documentation

enum sensor_data_accuracy_e

Enumeration for sensor data accuracy.

Since :: 2.3

Enumerator:

SENSOR_DATA_ACCURACY_UNDEFINED	Undefined accuracy
SENSOR_DATA_ACCURACY_BAD	Bad accuracy
SENSOR_DATA_ACCURACY_NORMAL	Normal accuracy
SENSOR_DATA_ACCURACY_GOOD	Good accuracy
SENSOR_DATA_ACCURACY_VERYGOOD	Very good accuracy

enum sensor_error_e

Enumeration for sensor error.

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	Unsupported sensor in the current device
SENSOR_ERROR_PERMISSION_DENIED	Permission denied
SENSOR_ERROR_OUT_OF_MEMORY	Out of memory
SENSOR_ERROR_NOT_NEED_CALIBRATION	Sensor doesn't need calibration
SENSOR_ERROR_OPERATION_FAILED	Operation failed

enum sensor_option_e

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

enum sensor_proximity_e

Enumeration for proximity sensor.

Since :: 2.3

Enumerator:

SENSOR_PROXIMITY_NEAR	The object is near
SENSOR_PROXIMITY_FAR	The object is far

enum sensor_type_e

Enumeration for sensor types.

Since :: 2.3

Enumerator:

SENSOR_ALL	All 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
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 sensor (Since Tizen 2.3.1)
SENSOR_HRM_LED_GREEN	HRM (LED Green) sensor (Since Tizen 2.3.1)
SENSOR_HRM_LED_IR	HRM (LED IR) sensor (Since Tizen 2.3.1)
SENSOR_HRM_LED_RED	HRM (LED RED) sensor (Since Tizen 2.3.1)
SENSOR_GYROSCOPE_UNCALIBRATED	Uncalibrated Gyroscope sensor (Since Tizen 2.4)
SENSOR_GEOMAGNETIC_UNCALIBRATED	Uncalibrated Geomagnetic sensor (Since Tizen 2.4)
SENSOR_GYROSCOPE_ROTATION_VECTOR	Gyroscope-based rotation vector sensor (Since Tizen 2.4)
SENSOR_GEOMAGNETIC_ROTATION_VECTOR	Geomagnetic-based rotation vector sensor (Since Tizen 2.4)
SENSOR_LAST	End of sensor enum values
SENSOR_CUSTOM	Custom sensor

Function Documentation

int sensor_create_listener	(	sensor_h	sensor,
		sensor_listener_h *	listener
	)

Creates a sensor listener.

Since :: 2.3

Remarks:: You must release listener using sensor_destroy_listener().

Parameters:

[in]	sensor	The sensor handle
[out]	listener	A new listener handle

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

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device
SENSOR_ERROR_OUT_OF_MEMORY	Out of memory

See also:: sensor_listener_set_event_cb(); sensor_listener_set_interval(); sensor_listener_set_max_batch_latency(); sensor_listener_set_option(); sensor_destroy_listener()

int sensor_destroy_listener ( sensor_listener_h listener )

Destroys the sensor handle and releases all its resources.

Since :: 2.3

Remarks:: After this function is called, the attached sensor is detached and the corresponding sensor connection is released.

Parameters:

[in] listener The listener handle

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

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device

See also:: sensor_create_listener()

int sensor_get_default_sensor	(	sensor_type_e	type,
		sensor_h *	sensor
	)

Gets a specific sensor handle.

Since :: 2.3

Remarks:: For getting a handle of HRM Sensor(including HRM_LED_GREEN, HRM_LED_IR and HRM_LED_RED) the privilege should be set to, http://tizen.org/privilege/healthinfo.

Parameters:

[in]	type	The sensor type
[out]	sensor	The sensor handle

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

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device
SENSOR_ERROR_PERMISSION_DENIED	Permission denied

int sensor_get_sensor_list	(	sensor_type_e	type,
		sensor_h **	list,
		int *	sensor_count
	)

Gets a sensor list.

Since :: 2.3

Remarks:: If you want to get a handle list of all sensors, use SENSOR_ALL type in sensor_type_e.; The caller should explicitly free this list.

Parameters:

[in]	type	The sensor type
[out]	list	The sensor list
[out]	sensor_count	The count of sensors

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

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device
SENSOR_ERROR_PERMISSION_DENIED	Permission denied

int sensor_is_supported	(	sensor_type_e	type,
		bool *	supported
	)

Checks whether a given sensor type is available on a device.

Availability of a sensor should be checked first because this sensor may not be supported on the device.

Since :: 2.3

Parameters:

[in]	type	The sensor type to check
[out]	supported	If `true` this sensor type is supported, otherwise `false`

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

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter

int sensor_listener_read_data	(	sensor_listener_h	listener,
		sensor_event_s *	event
	)

Gets sensor data.

This function may fail (return SENSOR_ERROR_OPERATION_FAILED) if it is called before the sensor is ready. In case of interval-driven sensors, it is recommended to call the function after at least one sensor event is delivered. Otherwise, applications can retry to call this function to be sure that the sensor is ready.

Since :: 2.3

Parameters:

[in]	listener	The listener handle
[out]	event	The event information

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

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device
SENSOR_ERROR_IO_ERROR	I/O error
SENSOR_ERROR_OPERATION_FAILED	Operation failed

Precondition:: In order to read sensor data, an application should call sensor_listener_start().

int sensor_listener_set_accuracy_cb	(	sensor_listener_h	listener,
		sensor_accuracy_changed_cb	callback,
		void *	data
	)

Registers an accuracy callback function to be invoked when the accuracy of a sensor has changed.

Since :: 2.3

Parameters:

[in]	listener	The listener handle
[in]	callback	The callback function to register
[in]	data	The user data to be passed to the callback function

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

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device
SENSOR_ERROR_IO_ERROR	I/O error
SENSOR_ERROR_OPERATION_FAILED	Operation failed

See also:: sensor_accuracy_changed_cb(); sensor_listener_unset_accuracy_cb()

int sensor_listener_set_event_cb	(	sensor_listener_h	listener,
		unsigned int	interval_ms,
		sensor_event_cb	callback,
		void *	data
	)

Registers a callback function to be invoked when a sensor event occurs.

Since :: 2.3

Parameters:

[in]	listener	The listener handle
[in]	interval_ms	The interval at which sensor events are delivered (in milliseconds) If rate is zero, it uses the default value(100ms) Min value is 10ms, Max value is 1000ms(10ms ~ 1000ms)
[in]	callback	The callback function to register
[in]	data	The user data to be passed to the callback function

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

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device
SENSOR_ERROR_IO_ERROR	I/O error
SENSOR_ERROR_OPERATION_FAILED	Operation failed

See also:: sensor_event_cb(); sensor_listener_unset_event_cb()

int sensor_listener_set_interval	(	sensor_listener_h	listener,
		unsigned int	interval_ms
	)

Changes the interval at sensor measurements.

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	The listener handle
[in]	interval_ms	The interval at which sensor events are delivered (in milliseconds) If rate is zero, it uses the default value(100ms) Min value is 10ms, Max value is 1000ms(10ms ~ 1000ms)

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

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device
SENSOR_ERROR_IO_ERROR	I/O error
SENSOR_ERROR_OPERATION_FAILED	Operation failed

int sensor_listener_set_max_batch_latency	(	sensor_listener_h	listener,
		unsigned int	max_batch_latency
	)

Changes the max batch latency at sensor measurements.

Since :: 2.3

Parameters:

[in]	listener	The listener handle
[in]	max_batch_latency	The latency at which sensor events are delivered (in milliseconds)

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

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device
SENSOR_ERROR_IO_ERROR	I/O error
SENSOR_ERROR_OPERATION_FAILED	Operation failed

int sensor_listener_set_option	(	sensor_listener_h	listener,
		sensor_option_e	option
	)

Changes the option of the sensor.

If it is default, sensor data cannot be received when the LCD is off and in the power save mode.

Since :: 2.3

Parameters:

[in]	listener	The listener handle
[in]	option	The sensor option

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

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device
SENSOR_ERROR_IO_ERROR	I/O error
SENSOR_ERROR_OPERATION_FAILED	Operation failed

int sensor_listener_start ( sensor_listener_h listener )

Starts the sensor server for the given listener.

After this function is called, sensor events will occur and the specific sensor type related callback function will be called. An application can read sensor data.

Since :: 2.3

Parameters:

[in] listener The listener handle

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

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device
SENSOR_ERROR_IO_ERROR	I/O error
SENSOR_ERROR_OPERATION_FAILED	Operation failed

Precondition:: Call sensor_create_listener() before using this function.

See also:: sensor_listener_stop()

int sensor_listener_stop ( sensor_listener_h listener )

Stops the sensor server for the given listener.

The given type event will not occur any more and the callback functions also won't be called.

Since :: 2.3

Parameters:

[in] listener The listener handle

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

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device
SENSOR_ERROR_IO_ERROR	I/O error

See also:: sensor_listener_start()

int sensor_listener_unset_accuracy_cb ( sensor_listener_h listener )

Unregisters the sensor accuracy changed callback function.

Since :: 2.3

Parameters:

[in] listener The listener handle

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

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device
SENSOR_ERROR_IO_ERROR	I/O error
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 callback function.

Since :: 2.3

Parameters:

[in] listener The listener handle

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

Return values:

SENSOR_ERROR_NONE	Successful
SENSOR_ERROR_INVALID_PARAMETER	Invalid parameter
SENSOR_ERROR_NOT_SUPPORTED	The sensor type is not supported in the current device
SENSOR_ERROR_IO_ERROR	I/O error
SENSOR_ERROR_OPERATION_FAILED	Operation failed

See also:: sensor_listener_set_event_cb()

Functions

Typedefs

Required Header

Overview

Related Features

Typedef Documentation

Enumeration Type Documentation

Function Documentation