Tizen(Headed) Native API  6.5
Sensor Provider

The Sensor Provider API provides functions to define a new sensor instance and provide its data.

Required Header

#include <sensor.h>

Overview

This Sensor API provides functions to define a new sensor instance from an application. Other applications are able to be notified whenever a new sensor instance is registered and listen to the new sensor.

Functions

int sensor_create_provider (const char *uri, sensor_provider_h *provider)
 Creates a sensor provider.
int sensor_add_provider (sensor_provider_h provider)
 Registers the sensor provider.
int sensor_remove_provider (sensor_provider_h provider)
 Unregisters the sensor provider.
int sensor_destroy_provider (sensor_provider_h provider)
 Releases all the resources allocated for the sensor provider.
int sensor_provider_set_name (sensor_provider_h provider, const char *name)
 Sets the name to the sensor provider.
int sensor_provider_set_vendor (sensor_provider_h provider, const char *vendor)
 Sets the vendor to the sensor provider.
int sensor_provider_set_range (sensor_provider_h provider, float min_range, float max_range)
 Sets the range of possible sensor values to the sensor provider.
int sensor_provider_set_resolution (sensor_provider_h provider, float resolution)
 Sets the resolution of sensor values to the sensor provider.
int sensor_provider_set_start_cb (sensor_provider_h provider, sensor_provider_start_cb callback, void *user_data)
 Registers the callback function to be invoked when a listener starts the sensor provider.
int sensor_provider_set_stop_cb (sensor_provider_h provider, sensor_provider_stop_cb callback, void *user_data)
 Registers the callback function to be invoked when a sensor listener stops the sensor provider.
int sensor_provider_set_interval_changed_cb (sensor_provider_h provider, sensor_provider_interval_changed_cb callback, void *user_data)
 Registers the callback function to be invoked when the interval is changed.
int sensor_provider_publish (sensor_provider_h provider, sensor_event_s event) TIZEN_DEPRECATED_API
 Publishes a sensor event through the declared sensor.
int sensor_provider_publish_events (sensor_provider_h provider, sensor_event_s events[], int count)
 Publishes sensor events through the declared sensor.

Typedefs

typedef struct _sensor_provider_s * sensor_provider_h
 Sensor provider handle.
typedef void(* sensor_provider_start_cb )(sensor_provider_h provider, void *user_data)
 Called when a sensor listener starts the sensor provider.
typedef void(* sensor_provider_stop_cb )(sensor_provider_h provider, void *user_data)
 Called when a sensor listener stops the sensor provider.
typedef void(* sensor_provider_interval_changed_cb )(sensor_provider_h provider, unsigned int interval_ms, void *user_data)
 Called when the interval of the sensor provider is changed.

Typedef Documentation

typedef struct _sensor_provider_s* sensor_provider_h

Sensor provider handle.

One or more sensor providers can be created by using sensor_create_provider(). The sensor's data can be published to listeners, via the provider.

Since :
4.0
See also:
sensor_create_provider()
sensor_destroy_provider()
typedef void(* sensor_provider_interval_changed_cb)(sensor_provider_h provider, unsigned int interval_ms, void *user_data)

Called when the interval of the sensor provider is changed.

Since :
4.0
Remarks:
provider is the object created with sensor_create_provider() and is the object for which the callback was triggered.
Parameters:
[in]providerThe sensor provider handle
[in]interval_msThe interval
[in]user_dataThe user data to be passed to the callback function
Precondition:
A callback function needs to be set using sensor_provider_set_interval_changed_cb().
See also:
sensor_provider_set_interval_changed_cb()
typedef void(* sensor_provider_start_cb)(sensor_provider_h provider, void *user_data)

Called when a sensor listener starts the sensor provider.

Since :
4.0
Remarks:
provider is the object created with sensor_create_provider() and is the object for which the callback was triggered.
Parameters:
[in]providerThe sensor provider handle
[in]user_dataThe user data to be passed to the callback function
Precondition:
A callback function needs to be set using sensor_provider_set_start_cb().
See also:
sensor_provider_set_start_cb()
typedef void(* sensor_provider_stop_cb)(sensor_provider_h provider, void *user_data)

Called when a sensor listener stops the sensor provider.

Since :
4.0
Remarks:
provider is the object created with sensor_create_provider() and is the object for which the callback was triggered.
Parameters:
[in]providerThe sensor provider handle
[in]user_dataThe user data to be passed to the callback function
Precondition:
A callback function needs to be set using sensor_provider_set_stop_cb().
See also:
sensor_provider_set_stop_cb()

Function Documentation

Registers the sensor provider.

A sensor provider is created via sensor_create_provider(), and the three callback functions sensor_provider_start_cb(), sensor_provider_stop_cb(), and sensor_provider_set_interval_changed_cb() should be set in advance.

Since :
4.0
Parameters:
[in]providerThe sensor provider handle
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
SENSOR_ERROR_PERMISSION_DENIEDPermission denied
SENSOR_ERROR_OPERATION_FAILEDOperation failed
See also:
sensor_remove_provider()
int sensor_create_provider ( const char *  uri,
sensor_provider_h provider 
)

Creates a sensor provider.

This function creates a sensor provider handle with a given URI. The URI should be in the valid form described in Sensor URIs. In addition, it is not allowed to set the vendor in the URI to "tizen.org", as it is pre-assigned to the platform-defined sensors.

Since :
4.0
Remarks:
If your application needs to publish health-related sensor data, the URI category should be "healthinfo". Then the applications without the privilege http://tizen.org/privilege/healthinfo are not allowed to listen your application's health-related sensor.
The provider must be released using sensor_destroy_provider().
Parameters:
[in]uriThe URI of sensor to be created
[out]providerThe sensor provider handle
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
See also:
sensor_destroy_provider()

Releases all the resources allocated for the sensor provider.

Since :
4.0
Remarks:
If this function is called before sensor_remove_provider() is called, then the sensor provider will be implicitly unregistered.
Parameters:
[in]providerThe sensor provider 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_provider()

Publishes a sensor event through the declared sensor.

Deprecated:
Deprecated since 5.5. Use sensor_provider_publish_events() instead.

This function publishes a sensor's data to its listeners.

Since :
4.0
Parameters:
[in]providerThe sensor provider handle
[in]eventThe sensor event
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_provider_publish_events ( sensor_provider_h  provider,
sensor_event_s  events[],
int  count 
)

Publishes sensor events through the declared sensor.

This function publishes a sensor's data to its listeners.

Since :
5.5
Remarks:
Both callbacks sensor_event_cb() (set with sensor_listener_set_event_cb()) and sensor_events_cb() (set with sensor_listener_set_events_cb()) are available. Only one of the callbacks can be used at any given time. A call to sensor_listener_set_event_cb() or sensor_listener_set_events_cb() sets the new callback in place of the callback previously set by any of the callback setters. If sensor_events_cb() is set and a single event is published with sensor_provider_publish(), then the event will be delivered through this callback with events_count set to 1. If sensor_event_cb() is set and multiple events are published with sensor_provider_publish_events(), then only the first element of events will be delivered. This behavior is not guaranteed, it's strongly recommended not to use sensor_provider_publish_events() with sensor_event_cb().
Parameters:
[in]providerThe sensor provider handle
[in]eventsThe sensor events
[in]countThe number of 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

Registers the callback function to be invoked when the interval is changed.

Since :
4.0
Parameters:
[in]providerThe sensor provider handle
[in]callbackThe callback function to attach to the provider handle
[in]user_dataThe 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
int sensor_provider_set_name ( sensor_provider_h  provider,
const char *  name 
)

Sets the name to the sensor provider.

Since :
4.0
Parameters:
[in]providerThe sensor provider handle
[in]nameThe name of the sensor
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
sensor_create_provider()
See also:
sensor_provider_set_vendor() sensor_provider_set_range() sensor_provider_set_resolution()
int sensor_provider_set_range ( sensor_provider_h  provider,
float  min_range,
float  max_range 
)

Sets the range of possible sensor values to the sensor provider.

Since :
4.0
Remarks:
If the application does not set the range, the default values are 0 and 1.
Parameters:
[in]providerThe sensor provider handle
[in]min_rangeThe lower bound
[in]max_rangeThe upper bound
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
sensor_create_provider()
See also:
sensor_provider_set_name() sensor_provider_set_vendor() sensor_provider_set_resolution()
int sensor_provider_set_resolution ( sensor_provider_h  provider,
float  resolution 
)

Sets the resolution of sensor values to the sensor provider.

Since :
4.0
Remarks:
If the application does not set the resolution, the default value is 1.
Parameters:
[in]providerThe sensor provider handle
[in]resolutionThe resolution
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
sensor_create_provider()
See also:
sensor_provider_set_name() sensor_provider_set_vendor() sensor_provider_set_range()
int sensor_provider_set_start_cb ( sensor_provider_h  provider,
sensor_provider_start_cb  callback,
void *  user_data 
)

Registers the callback function to be invoked when a listener starts the sensor provider.

Since :
4.0
Parameters:
[in]providerThe provider handle
[in]callbackThe callback function to attach to the provider handle
[in]user_dataThe 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
int sensor_provider_set_stop_cb ( sensor_provider_h  provider,
sensor_provider_stop_cb  callback,
void *  user_data 
)

Registers the callback function to be invoked when a sensor listener stops the sensor provider.

Since :
4.0
Parameters:
[in]providerThe sensor provider handle
[in]callbackThe callback function to attach to the provider handle
[in]user_dataThe 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
int sensor_provider_set_vendor ( sensor_provider_h  provider,
const char *  vendor 
)

Sets the vendor to the sensor provider.

Since :
4.0
Parameters:
[in]providerThe sensor provider handle
[in]vendorThe vendor of the sensor
Returns:
SENSOR_ERROR_NONE on success, otherwise a negative error value
Return values:
SENSOR_ERROR_NONESuccessful
SENSOR_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
sensor_create_provider()
See also:
sensor_provider_set_name() sensor_provider_set_range() sensor_provider_set_resolution()

Unregisters the sensor provider.

Since :
4.0
Parameters:
[in]providerThe sensor provider 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_add_provider()