/**
* @ingroup CAPI_SYSTEM_FRAMEWORK
* @defgroup CAPI_SYSTEM_SENSOR_MODULE Sensor
- * @brief The @ref CAPI_SYSTEM_SENSOR_MODULE API provides sensor types and sensor information
+ * @brief The @ref CAPI_SYSTEM_SENSOR_MODULE API provides functions to make use of sensors in the device.
*
* @section CAPI_SYSTEM_SENSOR_MODULE_HEADER Required Header
* \#include <sensor.h>
*
* @section CAPI_SYSTEM_SENSOR_MODULE_OVERVIEW Overview
- * This Sensor API provides sensor types and sensor error types to make use of sensors in the
- * device. A variety of hardware/virtual sensors are typically available on
- * mobile devices.
- * This Sensor API also provides functions for sensor information, such as name, vendor.
+ * This @ref CAPI_SYSTEM_SENSOR_MODULE API provides functions to make use of sensors in the device,
+ * define new sensor instances from applications, request to record sensor events,
+ * and acquire the recorded events.
+ * It also provides functions for getting information of a sensor, for example,
+ * the vendor and the resolution of its data.
*
* @section CAPI_SYSTEM_SENSOR_MODULE_FEATURE Related Features
- * This API is related with the following features:\n
+ * A variety of sensors are typically available on mobile and wearable devices.
+ * Regarding the types of sensors, this API is related with the following features:\n
* - http://tizen.org/feature/sensor.accelerometer\n
* - http://tizen.org/feature/sensor.barometer\n
* - http://tizen.org/feature/sensor.gyroscope\n
/**
* @ingroup CAPI_SYSTEM_SENSOR_MODULE
* @defgroup CAPI_SYSTEM_SENSOR_LISTENER_MODULE Sensor Listener
- * @brief The @ref CAPI_SYSTEM_SENSOR_LISTENER_MODULE API provides functions to start/stop sensors and receive sensor events.
+ * @brief The @ref CAPI_SYSTEM_SENSOR_LISTENER_MODULE API provides functions to observe data from sensors in the device.
*
* @section CAPI_SYSTEM_SENSOR_LISTENER_MODULE_HEADER Required Header
* \#include <sensor.h>
*
- * @section CAPI_SYSTEM_SENSOR_MODULE_OVERVIEW 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.
+ * @section CAPI_SYSTEM_SENSOR_LISTENER_MODULE_OVERVIEW Overview
+ * This @ref CAPI_SYSTEM_SENSOR_LISTENER_MODULE 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.\n
+ * 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.\n
+ * 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.\n
+ * 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,
+ * \a 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 \ref CAPI_SYSTEM_SENSOR_PROVIDER_MODULE API
+ * also can be accessed using this URI-based method.
+ *
+ * @section CAPI_SYSTEM_SENSOR_LISTENER_MODULE_URI 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:\n
+ * - %http://tizen.org/sensor/general/accelerometer (#SENSOR_ACCELEROMETER) \n
+ * - %http://tizen.org/sensor/general/gravity (#SENSOR_GRAVITY) \n
+ * - %http://tizen.org/sensor/general/linear_acceleration (#SENSOR_LINEAR_ACCELERATION) \n
+ * - %http://tizen.org/sensor/general/magnetic (#SENSOR_MAGNETIC) \n
+ * - %http://tizen.org/sensor/general/rotation_vector (#SENSOR_ROTATION_VECTOR) \n
+ * - %http://tizen.org/sensor/general/orientation (#SENSOR_ORIENTATION) \n
+ * - %http://tizen.org/sensor/general/gyroscope (#SENSOR_GYROSCOPE) \n
+ * - %http://tizen.org/sensor/general/light (#SENSOR_LIGHT) \n
+ * - %http://tizen.org/sensor/general/proximity (#SENSOR_PROXIMITY) \n
+ * - %http://tizen.org/sensor/general/pressure (#SENSOR_PRESSURE) \n
+ * - %http://tizen.org/sensor/general/ultraviolet (#SENSOR_ULTRAVIOLET) \n
+ * - %http://tizen.org/sensor/general/temperature (#SENSOR_TEMPERATURE) \n
+ * - %http://tizen.org/sensor/general/humidity (#SENSOR_HUMIDITY) \n
+ * - %http://tizen.org/sensor/healthinfo/heart_rate_monitor (#SENSOR_HRM) \n
+ * - %http://tizen.org/sensor/healthinfo/heart_rate_monitor.led_green (#SENSOR_HRM_LED_GREEN) \n
+ * - %http://tizen.org/sensor/healthinfo/heart_rate_monitor.led_ir (#SENSOR_HRM_LED_IR) \n
+ * - %http://tizen.org/sensor/healthinfo/heart_rate_monitor.led_red (#SENSOR_HRM_LED_RED) \n
+ * - %http://tizen.org/sensor/general/gyroscope.uncalibrated (#SENSOR_GYROSCOPE_UNCALIBRATED) \n
+ * - %http://tizen.org/sensor/general/geomagnetic.uncalibrated (#SENSOR_GEOMAGNETIC_UNCALIBRATED) \n
+ * - %http://tizen.org/sensor/general/gyroscope_rotation_vector (#SENSOR_GYROSCOPE_ROTATION_VECTOR) \n
+ * - %http://tizen.org/sensor/general/geomagnetic_rotation_vector (#SENSOR_GEOMAGNETIC_ROTATION_VECTOR) \n
+ * - %http://tizen.org/sensor/healthinfo/human_pedometer (#SENSOR_HUMAN_PEDOMETER) \n
+ * - %http://tizen.org/sensor/healthinfo/human_sleep_monitor (#SENSOR_HUMAN_SLEEP_MONITOR) \n
+ * - %http://tizen.org/sensor/healthinfo/human_sleep_detector (#SENSOR_HUMAN_SLEEP_DETECTOR) \n
+ * - %http://tizen.org/sensor/healthinfo/human_stress_monitor (#SENSOR_HUMAN_STRESS_MONITOR) \n
+ */
+
+ /**
+ * @ingroup CAPI_SYSTEM_SENSOR_MODULE
+ * @defgroup CAPI_SYSTEM_SENSOR_PROVIDER_MODULE Sensor Provider
+ * @brief The @ref CAPI_SYSTEM_SENSOR_PROVIDER_MODULE API provides functions
+ * to define a new sensor instance and provide its data.
+ *
+ * @section CAPI_SYSTEM_SENSOR_PROVIDER_MODULE_HEADER Required Header
+ * \#include <sensor.h>
+ *
+ * @section CAPI_SYSTEM_SENSOR_PROVIDER_MODULE_OVERVIEW 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.
*
*/
* @return #SENSOR_ERROR_NONE on success; Otherwise a negative error value
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ *
+ * @see sensor_is_supported_by_uri()
*/
int sensor_is_supported(sensor_type_e type, bool *supported);
+/**
+ * @brief Checks whether a sensor corresponding to a given URI is supported in the current device.
+ * @details To correctly check the availability of a sensor, a valid URI should be provided.
+ * The valid form of URIs is explained in \ref CAPI_SYSTEM_SENSOR_LISTENER_MODULE_URI.\n
+ * If a URI with the sensor's name is given, for example, %http://tizen.org/sensor/general/light/front,
+ * the availability of the \"front\" light sensor is checked.
+ * Otherwise, if a URI without the name, %http://tizen.org/sensor/general/light, is given,
+ * this function checks the availability of any light sensor in the device.\n
+ * It is recommended to check the availability of the sensors corresponding to the URI
+ * before actually acquiring #sensor_h.
+ * @since_tizen 4.0
+ *
+ * @param[in] uri A sensor or a sensor type URI to check
+ * @param[out] supported If supported, @c true, otherwise @c false
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ *
+ * @see sensor_is_supported()
+ */
+int sensor_is_supported_by_uri(const char *uri, bool *supported);
+
/**
* @brief Checks whether a given sensor is a wake-up sensor or not.
/**
* @brief Gets the handle for the default sensor of a given type.
- * @details This function returns the handle for the sensor of a given type,
- * if the device has one sensor of the given type.
- * In case that the device has more than one sensors of the type,
- * this returns only the default sensor, which is designated by the device.@n
+ * @details This function returns the handle for the sensor of a given type.
+ * If the device has more than one sensor of the given type,
+ * this function returns the default sensor of the given type,
+ * which is designated by the device.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @remarks Some sensor types are privileged. An application should have the privilege
* @retval #SENSOR_ERROR_NOT_SUPPORTED The sensor type is not supported in the current device
* @retval #SENSOR_ERROR_PERMISSION_DENIED Permission denied
*
+ * @see sensor_get_default_sensor_by_uri()
* @see sensor_get_sensor_list()
*/
int sensor_get_default_sensor(sensor_type_e type, sensor_h *sensor);
+/**
+ * @brief Gets the handle for the default sensor of a given sensor URI.
+ * @details This function returns the handle for the sensor of a given URI.
+ * If the device has more than one sensor of the given URI,
+ * this function returns the default sensor of the URI, which is designated by the device.\n
+ * See \ref CAPI_SYSTEM_SENSOR_LISTENER_MODULE_URI for more details about the URI format.
+ * @since_tizen 4.0
+ *
+ * @remarks Some sensor types are privileged. An application should have the privilege
+ * http://tizen.org/privilege/healthinfo to get handles for the sensor URIs of \"healthinfo\" category.
+ * See \ref CAPI_SYSTEM_SENSOR_LISTENER_MODULE_URI to find the \"healthinfo\" category sensor URIs.
+ *
+ * @param[in] uri A sensor or a sensor type URI to get the handle of its default sensor
+ * @param[out] sensor The default sensor handle
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_NOT_SUPPORTED The URI is not supported in the current device
+ * @retval #SENSOR_ERROR_PERMISSION_DENIED Permission denied
+ *
+ * @see sensor_get_default_sensor()
+ * @see sensor_get_sensor_list_by_uri()
+ */
+int sensor_get_default_sensor_by_uri(const char *uri, sensor_h *sensor);
+
/**
* @brief Gets the handle list of the sensors of a given type.
* @details A device may have more than one sensors of the given type.
* In such case, this function can be used to get the handles of all sensors of the type.@n
- * The first element of the @c list denotes the default sensor,
+ * The first element of the @a list denotes the default sensor,
* which can be retrieved by sensor_get_default_sensor().
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* and #SENSOR_HUMAN_STRESS_MONITOR.@n
* Instead of specifying a sensor type, by using #SENSOR_ALL,
* applications can get the list of handles for all available sensors.@n
- * The @c list must be released using @c free(), if not being used anymore.@n
+ * The @a list must be released using free(), if not being used anymore.@n
*
* @param[in] type A sensor type to get the list of sensor handles
* @param[out] list An array of the sensor handles
- * @param[out] sensor_count The number of handles contained in @c list
+ * @param[out] sensor_count The number of handles contained in @a list
*
* @return #SENSOR_ERROR_NONE on success; Otherwise a negative error value
* @retval #SENSOR_ERROR_NONE Successful
*/
int sensor_get_sensor_list(sensor_type_e type, sensor_h **list, int *sensor_count);
+/**
+ * @brief Gets the handle list of the sensors of a given URI.
+ * @details A device may have more than one sensor of the given URI.
+ * In such case, this function can be used to get the handles of all sensors of the given URI.\n
+ * See \ref CAPI_SYSTEM_SENSOR_LISTENER_MODULE_URI for more details about the URI format.
+ * @since_tizen 4.0
+ *
+ * @remarks Some sensors require one or more privileges. An application should have the corresponding privilege
+ * to get handles for such sensors.
+ * See sensor_get_default_sensor_by_uri() for more details.@n
+ * The @a list must be released using free(), if not being used anymore.
+ *
+ * @param[in] uri A sensor or a sensor type URI to get the list of sensor handles
+ * @param[out] list An array of the sensor handles
+ * @param[out] sensor_count The number of handles contained in @a list
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_NOT_SUPPORTED The URI is not supported in the current device
+ * @retval #SENSOR_ERROR_PERMISSION_DENIED Permission denied
+ * @retval #SENSOR_ERROR_OUT_OF_MEMORY Out of memory
+ */
+int sensor_get_sensor_list_by_uri(const char *uri, sensor_h **list, int *sensor_count);
+
+
+/**
+ * @brief Gets the URI of a sensor.
+ * @since_tizen 4.0
+ *
+ * @remarks The @a uri must be released using free(), if not being used anymore.
+ *
+ * @param[in] sensor A sensor handle
+ * @param[out] uri The URI of the sensor
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ */
+int sensor_get_uri(sensor_h sensor, char **uri);
/**
* @brief Gets the name of a sensor.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
+ * @remarks The @a name must be released using free(), if not being used anymore.
+ *
* @param[in] sensor A sensor handle
* @param[out] name The name of the sensor
*
* @brief Gets the vendor of a sensor.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
+ * @remarks The @a vendor must be released using free(), if not being used anymore.
+ *
* @param[in] sensor A sensor handle
* @param[out] vendor The vendor of the sensor
*
/**
- * @brief Gets the sensor type of a sensor.
+ * @brief Gets the type of a sensor, if it belongs to the known types defined in #sensor_type_e.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @param[in] sensor A sensor handle
* @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_NO_DATA No known sensor type for the given sensor
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*/
int sensor_get_type(sensor_h sensor, sensor_type_e *type);
*/
int sensor_get_max_batch_count(sensor_h sensor, int *max_batch_count);
+
+/**
+ * @brief Called when a new sensor is added.
+ * @since_tizen 4.0
+ *
+ * @remarks @a uri should not be freed and can be used only in the callback.
+ * To use outside the callback, make a copy.
+ *
+ * @param[in] uri The URI of the newly added sensor
+ * @param[in] user_data The user data had passed to sensor_add_sensor_added_cb().
+ *
+ * @pre A callback function needs to be set using sensor_add_sensor_added_cb().
+ * @see sensor_add_sensor_added_cb()
+ * @see sensor_remove_sensor_added_cb()
+ */
+typedef void (*sensor_added_cb)(const char *uri, void *user_data);
+
+/**
+ * @brief Adds a callback function to be invoked when a new sensor is added.
+ * @since_tizen 4.0
+ *
+ * @param[in] callback A callback function to be added
+ * @param[in] user_data A user data to be passed to the callback function
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ *
+ * @see sensor_remove_sensor_added_cb()
+ */
+int sensor_add_sensor_added_cb(sensor_added_cb callback, void *user_data);
+
+/**
+ * @brief Removes a callback function added using sensor_add_sensor_added_cb().
+ * @since_tizen 4.0
+ *
+ * @param[in] callback A callback function to be removed
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ *
+ * @see sensor_add_sensor_added_cb()
+ */
+int sensor_remove_sensor_added_cb(sensor_added_cb callback);
+
+/**
+ * @brief Called when a sensor is removed.
+ * @since_tizen 4.0
+ *
+ * @remarks @a uri should not be freed and can be used only in the callback.
+ * To use outside the callback, make a copy.
+ *
+ * @param[in] uri The URI of the removed sensor
+ * @param[in] user_data The user data had passed to sensor_add_sensor_removed_cb()
+ *
+ * @pre A callback function needs to be set using sensor_add_sensor_removed_cb().
+ * @see sensor_add_sensor_removed_cb()
+ * @see sensor_remove_sensor_removed_cb()
+ */
+typedef void (*sensor_removed_cb)(const char *uri, void *user_data);
+
+/**
+ * @brief Adds a callback function to be invoked when a sensor is removed.
+ * @since_tizen 4.0
+ *
+ * @param[in] callback A callback function to be removed
+ * @param[in] user_data A user data to be passed to the callback function
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ *
+ * @see sensor_remove_sensor_removed_cb()
+ */
+int sensor_add_sensor_removed_cb(sensor_removed_cb callback, void *user_data);
+
+/**
+ * @brief Removes a callback function added using sensor_add_sensor_removed_cb().
+ * @since_tizen 4.0
+ *
+ * @param[in] callback A callback function to be removed
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ *
+ * @see sensor_add_sensor_removed_cb()
+ */
+int sensor_remove_sensor_removed_cb(sensor_removed_cb callback);
+
/**
* @}
*/
* @brief Creates a sensor listener.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
- * @remarks The @c listener must be released using sensor_destroy_listener().
+ * @remarks The @a listener must be released using sensor_destroy_listener().
*
* @param[in] sensor A sensor handle
- * @param[out] listener A listener handle of @c sensor
+ * @param[out] listener A listener handle of @a sensor
*
* @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
* @retval #SENSOR_ERROR_NONE Successful
* @retval #SENSOR_ERROR_OUT_OF_MEMORY Out of memory
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
- * @pre The handle @c sensor needs to be initialized using
+ * @pre The handle @a sensor needs to be initialized using
* sensor_get_default_sensor() or sensor_get_sensor_list() in advance.
*/
int sensor_create_listener(sensor_h sensor, sensor_listener_h *listener);
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
- * @pre The @c listener needs to be created in advance, by using sensor_create_listener().
- * Then the callback function needs to be attached to the @c listener, by using
+ * @pre The @a listener needs to be created in advance, by using sensor_create_listener().
+ * Then the callback function needs to be attached to the @a listener, by using
* sensor_listener_set_event_cb().
* @see sensor_listener_stop()
*/
* @param[in] interval_ms A desired update interval between sensor events in milliseconds.@n
* If 0, it will be automatically set to the default interval of the corresponding sensor.@n
* See sensor_listener_set_interval() for more details.
- * @param[in] callback A callback function to attach with the @c listener handle
+ * @param[in] callback A callback function to attach with the @a listener handle
* @param[in] data A user data to be passed to the callback function
*
* @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*
* @param[in] listener A listener handle
- * @param[in] callback A callback function to attach with the @c listener handle
+ * @param[in] callback A callback function to attach with the @a listener handle
* @param[in] data A user data to be passed to the callback function
*
* @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
* @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
*
- * @pre The @c listener needs to be started to get the change callbacks.
+ * @pre The @a listener needs to be started to get the change callbacks.
* @see sensor_listener_unset_accuracy_cb()
*/
int sensor_listener_set_accuracy_cb(sensor_listener_h listener, sensor_accuracy_changed_cb callback, void *data);
*/
/**
+ * @addtogroup CAPI_SYSTEM_SENSOR_PROVIDER_MODULE
+ * @{
+ */
+
+/**
+ * @brief Sensor provider handle.
+ * @details 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_tizen 4.0
+ *
+ * @see sensor_create_provider()
+ * @see sensor_destroy_provider()
+ */
+typedef struct _sensor_provider_s *sensor_provider_h;
+
+/**
+ * @brief Creates a sensor provider.
+ * @details This function creates a sensor provider handle with a given URI.
+ * The URI should be in the valid form described in \ref CAPI_SYSTEM_SENSOR_LISTENER_MODULE_URI.
+ * 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.\n
+ * @since_tizen 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.
+ *
+ * @remarks The @a provider must be released using sensor_destroy_provider().
+ *
+ * @param[in] uri The URI of sensor to be created
+ * @param[out] provider The sensor provider handle
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ *
+ * @see sensor_destroy_provider()
+ */
+int sensor_create_provider(const char *uri, sensor_provider_h *provider);
+
+/**
+ * @brief Registers the sensor provider.
+ * @details 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_tizen 4.0
+ *
+ * @param[in] provider The sensor provider handle
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_PERMISSION_DENIED Permission denied
+ * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ *
+ * @see sensor_remove_provider()
+ */
+int sensor_add_provider(sensor_provider_h provider);
+
+/**
+ * @brief Unregisters the sensor provider.
+ * @since_tizen 4.0
+ *
+ * @param[in] provider The sensor provider handle
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ *
+ * @see sensor_add_provider()
+ */
+int sensor_remove_provider(sensor_provider_h provider);
+
+/**
+ * @brief Releases all the resources allocated for the sensor provider.
+ * @since_tizen 4.0
+ *
+ * @remarks If this function is called before sensor_remove_provider() is called,
+ * then the sensor provider will be implicitly unregistered.
+ *
+ * @param[in] provider The sensor provider handle
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ *
+ * @see sensor_create_provider()
+ */
+int sensor_destroy_provider(sensor_provider_h provider);
+
+/**
+ * @brief Sets the name to the sensor provider.
+ * @since_tizen 4.0
+ *
+ * @param[in] provider The sensor provider handle
+ * @param[in] name The name of the sensor
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ *
+ * @pre sensor_create_provider()
+ * @see sensor_provider_set_vendor()
+ * sensor_provider_set_range()
+ * sensor_provider_set_resolution()
+ */
+int sensor_provider_set_name(sensor_provider_h provider, const char *name);
+
+/**
+ * @brief Sets the vendor to the sensor provider.
+ * @since_tizen 4.0
+ *
+ * @param[in] provider The sensor provider handle
+ * @param[in] vendor The vendor of the sensor
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ *
+ * @pre sensor_create_provider()
+ * @see sensor_provider_set_name()
+ * sensor_provider_set_range()
+ * sensor_provider_set_resolution()
+ */
+int sensor_provider_set_vendor(sensor_provider_h provider, const char *vendor);
+
+/**
+ * @brief Sets the range of possible sensor values to the sensor provider.
+ * @since_tizen 4.0
+ *
+ * @remarks If the application does not set the range, the default values are 0 and 1.
+ *
+ * @param[in] provider The sensor provider handle
+ * @param[in] min_range The lower bound
+ * @param[in] max_range The upper bound
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ *
+ * @pre sensor_create_provider()
+ * @see sensor_provider_set_name()
+ * sensor_provider_set_vendor()
+ * sensor_provider_set_resolution()
+ */
+int sensor_provider_set_range(sensor_provider_h provider, float min_range, float max_range);
+
+/**
+ * @brief Sets the resolution of sensor values to the sensor provider.
+ * @since_tizen 4.0
+ *
+ * @remarks If the application does not set the resolution, the default value is 1.
+ *
+ * @param[in] provider The sensor provider handle
+ * @param[in] resolution The resolution
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ *
+ * @pre sensor_create_provider()
+ * @see sensor_provider_set_name()
+ * sensor_provider_set_vendor()
+ * sensor_provider_set_range()
+ */
+int sensor_provider_set_resolution(sensor_provider_h provider, float resolution);
+
+
+/**
+ * @brief Called when a sensor listener starts the sensor provider.
+ * @since_tizen 4.0
+ *
+ * @remarks @a provider is the object created with sensor_create_provider()
+ * and is the object for which the callback was triggered.
+ *
+ * @param[in] provider The sensor provider handle
+ * @param[in] user_data The user data to be passed to the callback function
+ *
+ * @pre A callback function needs to be set using sensor_provider_set_start_cb().
+ * @see sensor_provider_set_start_cb()
+ */
+typedef void (*sensor_provider_start_cb)(sensor_provider_h provider, void *user_data);
+
+/**
+ * @brief Registers the callback function to be invoked when a listener starts the sensor provider.
+ * @since_tizen 4.0
+ *
+ * @param[in] provider The provider handle
+ * @param[in] callback The callback function to attach to the @a provider handle
+ * @param[in] user_data The user data to be passed to the callback function
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ *
+ */
+int sensor_provider_set_start_cb(sensor_provider_h provider,
+ sensor_provider_start_cb callback, void *user_data);
+
+
+/**
+ * @brief Called when a sensor listener stops the sensor provider.
+ * @since_tizen 4.0
+ *
+ * @remarks @a provider is the object created with sensor_create_provider()
+ * and is the object for which the callback was triggered.
+ *
+ * @param[in] provider The sensor provider handle
+ * @param[in] user_data The user data to be passed to the callback function
+ *
+ * @pre A callback function needs to be set using sensor_provider_set_stop_cb().
+ * @see sensor_provider_set_stop_cb()
+ */
+typedef void (*sensor_provider_stop_cb)(sensor_provider_h provider, void *user_data);
+
+/**
+ * @brief Registers the callback function to be invoked when a sensor listener stops the sensor provider.
+ * @since_tizen 4.0
+ *
+ * @param[in] provider The sensor provider handle
+ * @param[in] callback The callback function to attach to the @a provider handle
+ * @param[in] user_data The user data to be passed to the callback function
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ */
+int sensor_provider_set_stop_cb(sensor_provider_h provider,
+ sensor_provider_stop_cb callback, void *user_data);
+
+
+/**
+ * @brief Called when the interval of the sensor provider is changed.
+ * @since_tizen 4.0
+ *
+ * @remarks @a provider is the object created with sensor_create_provider()
+ * and is the object for which the callback was triggered.
+ *
+ * @param[in] provider The sensor provider handle
+ * @param[in] interval_ms The interval
+ * @param[in] user_data The user data to be passed to the callback function
+ *
+ * @pre A callback function needs to be set using sensor_provider_set_interval_changed_cb().
+ * @see sensor_provider_set_interval_changed_cb()
+ */
+typedef void (*sensor_provider_interval_changed_cb)(sensor_provider_h provider,
+ unsigned int interval_ms, void *user_data);
+
+/**
+ * @brief Registers the callback function to be invoked when the interval is changed.
+ * @since_tizen 4.0
+ *
+ * @param[in] provider The sensor provider handle
+ * @param[in] callback The callback function to attach to the @a provider handle
+ * @param[in] user_data The user data to be passed to the callback function
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ */
+int sensor_provider_set_interval_changed_cb(sensor_provider_h provider,
+ sensor_provider_interval_changed_cb callback, void *user_data);
+
+
+/**
+ * @brief Publishes a sensor event through the declared sensor.
+ * @details This function publishes a sensor's data to its listeners.
+ * @since_tizen 4.0
+ *
+ * @param[in] provider The sensor provider handle
+ * @param[out] event The sensor event
+ *
+ * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value
+ * @retval #SENSOR_ERROR_NONE Successful
+ * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed
+ */
+int sensor_provider_publish(sensor_provider_h provider, sensor_event_s event);
+
+/**
+ * @}
+ */
+
+/**
* @addtogroup CAPI_SYSTEM_SENSOR_RECORDER_MODULE
* @{
*/
/**
* @brief Enumeration for intervals between data records.
* @details Some sensor types including #SENSOR_HRM may not fit to continuous monitoring and recording.
- * To reduce the battery use for recoridng such sensors, recording interval between each
+ * To reduce the battery use for recording such sensors, recording interval between each
* sensor data is chosen. For example, an application set the interval of 1 hour,
* the platform tries to retrieve the sensor data only once per hour, thus it will be more
* battery efficient than to listen the sensor data continuously.@n
- * If the application does not set the interval explicitely, the default value is chosen.
+ * If the application does not set the interval explicitly, the default value is chosen.
* The default values are differ from sensor to sensor.
* @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
* @remarks If more than one applications set different intervals, the shortest value is chosen.
} sensor_recorder_interval_e;
/**
- * @brief Enumeration for filtering and aggregation parameters for queyring sensor records.
+ * @brief Enumeration for filtering and aggregation parameters for querying sensor records.
* @details None, one, or more query parameters can be set to #sensor_recorder_query_h,
* to specify the data to be retrieved via sensor_recorder_read().
* If a necessary parameter is not set, the default value is chosen.
} sensor_recorder_data_e;
/**
- * @brief Checks whether it is suppored to record a given sensor type.
+ * @brief Checks whether it is supported to record a given sensor type.
* @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
*
* @param[in] type A sensor type to check
int sensor_recorder_query_set_time(sensor_recorder_query_h query, sensor_recorder_query_e param, time_t t);
/**
- * @brief Called when the query results are retieved.
+ * @brief Called when the query results are retrieved.
* @details One of the following errors can be delivered.\n
* #SENSOR_ERROR_NONE, Successful\n
* #SENSOR_ERROR_OPERATION_FAILED, Operation failed\n
--- /dev/null
+/*
+ * Copyright (c) 2017 Samsung Electronics Co., Ltd All Rights Reserved
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <sensor.h>
+#include <sensor_private.h>
+#include <sensor_internal.h>
+#include <new>
+#include <map>
+
+#include "include/sensor_log.h"
+
+#define RETV_IF(expr, val) \
+ do { if (expr) { return (val); } } while (0)
+
+typedef struct _sensor_provider_s {
+ sensord_provider_h sensor;
+ sensor_provider_start_cb start_cb;
+ sensor_provider_stop_cb stop_cb;
+ sensor_provider_interval_changed_cb interval_cb;
+ void *start_user_data;
+ void *stop_user_data;
+ void *interval_user_data;
+} sensor_provider_handle;
+
+int sensor_create_provider(const char *uri, sensor_provider_h *provider)
+{
+ RETV_IF(!provider, SENSOR_ERROR_INVALID_PARAMETER);
+
+ *provider = new(std::nothrow) sensor_provider_handle();
+ RETV_IF(!*provider, SENSOR_ERROR_OUT_OF_MEMORY);
+
+ (*provider)->sensor = NULL;
+ (*provider)->stop_cb = NULL;
+ (*provider)->interval_cb = NULL;
+ (*provider)->start_cb = NULL;
+ (*provider)->start_user_data = NULL;
+ (*provider)->stop_user_data = NULL;
+ (*provider)->interval_user_data = NULL;
+
+ return sensord_create_provider(uri, &(*provider)->sensor);
+}
+
+int sensor_add_provider(sensor_provider_h provider)
+{
+ RETV_IF(!provider, SENSOR_ERROR_INVALID_PARAMETER);
+
+ int result;
+ result = sensord_add_provider(provider->sensor);
+ RETV_IF(result == -EINVAL, SENSOR_ERROR_INVALID_PARAMETER);
+ RETV_IF(result == -EACCES, SENSOR_ERROR_PERMISSION_DENIED);
+ RETV_IF(result < 0, SENSOR_ERROR_OPERATION_FAILED);
+
+ return SENSOR_ERROR_NONE;
+}
+
+int sensor_remove_provider(sensor_provider_h provider)
+{
+ RETV_IF(!provider, SENSOR_ERROR_INVALID_PARAMETER);
+
+ int result;
+ result = sensord_remove_provider(provider->sensor);
+ RETV_IF(result == -EINVAL, SENSOR_ERROR_INVALID_PARAMETER);
+ RETV_IF(result < 0, SENSOR_ERROR_OPERATION_FAILED);
+
+ return SENSOR_ERROR_NONE;
+}
+
+int sensor_destroy_provider(sensor_provider_h provider)
+{
+ RETV_IF(!provider, SENSOR_ERROR_INVALID_PARAMETER);
+
+ int result;
+ result = sensord_destroy_provider(provider->sensor);
+
+ if (result == SENSOR_ERROR_NONE)
+ delete provider;
+
+ return result;
+}
+
+int sensor_provider_set_name(sensor_provider_h provider, const char *name)
+{
+ RETV_IF(!provider, SENSOR_ERROR_INVALID_PARAMETER);
+ return sensord_provider_set_name(provider->sensor, name);
+}
+
+int sensor_provider_set_vendor(sensor_provider_h provider, const char *vendor)
+{
+ RETV_IF(!provider, SENSOR_ERROR_INVALID_PARAMETER);
+ return sensord_provider_set_vendor(provider->sensor, vendor);
+}
+
+int sensor_provider_set_range(sensor_provider_h provider, float min_range, float max_range)
+{
+ RETV_IF(!provider, SENSOR_ERROR_INVALID_PARAMETER);
+ return sensord_provider_set_range(provider->sensor, min_range, max_range);
+}
+
+int sensor_provider_set_resolution(sensor_provider_h provider, float resolution)
+{
+ RETV_IF(!provider, SENSOR_ERROR_INVALID_PARAMETER);
+ return sensord_provider_set_resolution(provider->sensor, resolution);
+}
+
+static void sensor_start_callback(sensord_provider_h provider, void *user_data)
+{
+ sensor_provider_h p = (sensor_provider_h)user_data;
+ if (p->start_cb)
+ p->start_cb(p, p->start_user_data);
+}
+
+int sensor_provider_set_start_cb(sensor_provider_h provider,
+ sensor_provider_start_cb callback, void *user_data)
+{
+ RETV_IF(!provider, SENSOR_ERROR_INVALID_PARAMETER);
+ RETV_IF(!callback, SENSOR_ERROR_INVALID_PARAMETER);
+
+ provider->start_cb = callback;
+ provider->start_user_data = user_data;
+
+ return sensord_provider_set_start_cb(provider->sensor, sensor_start_callback, provider);
+}
+
+static void sensor_stop_callback(sensord_provider_h provider, void *user_data)
+{
+ sensor_provider_h p = (sensor_provider_h)user_data;
+ if (p->stop_cb)
+ p->stop_cb(p, p->stop_user_data);
+}
+
+int sensor_provider_set_stop_cb(sensor_provider_h provider,
+ sensor_provider_stop_cb callback, void *user_data)
+{
+ RETV_IF(!provider, SENSOR_ERROR_INVALID_PARAMETER);
+ RETV_IF(!callback, SENSOR_ERROR_INVALID_PARAMETER);
+
+ provider->stop_cb = callback;
+ provider->stop_user_data = user_data;
+
+ return sensord_provider_set_stop_cb(provider->sensor, sensor_stop_callback, provider);
+}
+
+static void sensor_interval_changed_callback(sensord_provider_h provider,
+ unsigned int interval_ms, void *user_data)
+{
+ sensor_provider_h p = (sensor_provider_h)user_data;
+ if (p->interval_cb)
+ p->interval_cb(p, interval_ms, p->interval_user_data);
+}
+
+int sensor_provider_set_interval_changed_cb(sensor_provider_h provider,
+ sensor_provider_interval_changed_cb callback, void *user_data)
+{
+ RETV_IF(!provider, SENSOR_ERROR_INVALID_PARAMETER);
+ RETV_IF(!callback, SENSOR_ERROR_INVALID_PARAMETER);
+
+ provider->interval_cb = callback;
+ provider->interval_user_data = user_data;
+
+ return sensord_provider_set_interval_changed_cb(provider->sensor,
+ sensor_interval_changed_callback, provider);
+}
+
+int sensor_provider_publish(sensor_provider_h provider, sensor_event_s event)
+{
+ RETV_IF(!provider, SENSOR_ERROR_INVALID_PARAMETER);
+
+ int result;
+ sensor_data_t data;
+ memcpy(&data, &event, sizeof(data));
+
+ result = sensord_provider_publish(provider->sensor, data);
+ RETV_IF(result == -EINVAL, SENSOR_ERROR_INVALID_PARAMETER);
+ RETV_IF(result < 0, SENSOR_ERROR_OPERATION_FAILED);
+
+ return SENSOR_ERROR_NONE;
+}
projects / platform / core / api / sensor.git / commitdiff