From d2a63e31e6c273016cdd9b4a49ee244d74567fae Mon Sep 17 00:00:00 2001 From: Mu-Woong Lee Date: Fri, 14 Apr 2017 13:43:23 +0900 Subject: [PATCH] Declare APIs to support application sensors Change-Id: I6151f78af54122aab9621d03f3ba7b0e6c70b18d Signed-off-by: Mu-Woong Lee Signed-off-by: kibak.yoon --- doc/sensor_doc.h | 92 ++++++++- include/sensor.h | 525 +++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 585 insertions(+), 32 deletions(-) diff --git a/doc/sensor_doc.h b/doc/sensor_doc.h index e74c594..f786422 100644 --- a/doc/sensor_doc.h +++ b/doc/sensor_doc.h @@ -21,19 +21,21 @@ /** * @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 * * @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 @@ -72,15 +74,83 @@ /** * @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 * - * @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://\/sensor/\/\/\\". + * where the \"/\\" 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 + * + * @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. * */ diff --git a/include/sensor.h b/include/sensor.h index 26ddd46..99a29af 100644 --- a/include/sensor.h +++ b/include/sensor.h @@ -166,9 +166,34 @@ typedef enum * @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. @@ -191,10 +216,10 @@ int sensor_is_wake_up(sensor_h sensor, bool *wakeup); /** * @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 @@ -212,16 +237,43 @@ int sensor_is_wake_up(sensor_h sensor, bool *wakeup); * @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 * @@ -232,11 +284,11 @@ int sensor_get_default_sensor(sensor_type_e type, sensor_h *sensor); * 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 @@ -247,11 +299,53 @@ int sensor_get_default_sensor(sensor_type_e type, sensor_h *sensor); */ 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 * @@ -266,6 +360,8 @@ int sensor_get_name(sensor_h sensor, char **name); * @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 * @@ -277,7 +373,7 @@ int sensor_get_vendor(sensor_h sensor, char **vendor); /** - * @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 @@ -286,6 +382,7 @@ int sensor_get_vendor(sensor_h sensor, char **vendor); * @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); @@ -416,6 +513,101 @@ int sensor_get_fifo_count(sensor_h sensor, int *fifo_count); */ 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); + /** * @} */ @@ -577,10 +769,10 @@ typedef void (*sensor_accuracy_changed_cb)(sensor_h sensor, unsigned long long t * @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 @@ -588,7 +780,7 @@ typedef void (*sensor_accuracy_changed_cb)(sensor_h sensor, unsigned long long t * @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); @@ -630,8 +822,8 @@ int sensor_destroy_listener(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() */ @@ -665,7 +857,7 @@ int sensor_listener_stop(sensor_listener_h listener); * @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 @@ -702,7 +894,7 @@ int sensor_listener_unset_event_cb(sensor_listener_h listener); * @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 @@ -710,7 +902,7 @@ int sensor_listener_unset_event_cb(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 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); @@ -848,6 +1040,297 @@ int sensor_listener_set_attribute_int(sensor_listener_h listener, sensor_attribu */ int sensor_listener_set_option(sensor_listener_h listener, sensor_option_e option); +/** + * @} + */ + +/** + * @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); + /** * @} */ @@ -894,11 +1377,11 @@ typedef enum /** * @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. @@ -914,7 +1397,7 @@ typedef enum } 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. @@ -958,7 +1441,7 @@ typedef enum } 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 @@ -1116,7 +1599,7 @@ int sensor_recorder_query_set_int(sensor_recorder_query_h query, sensor_recorder 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 -- 2.34.1