From: Boram Bae Date: Thu, 12 Dec 2019 02:16:10 +0000 (+0900) Subject: Change descriptions related to batch events API and Deprecate API related to event X-Git-Tag: submit/tizen_5.5/20191219.060634^2~1 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fchanges%2F36%2F219936%2F8;p=platform%2Fcore%2Fapi%2Fsensor.git Change descriptions related to batch events API and Deprecate API related to event * Change the signature of sensor_events_cb * Add deprecation warning logs Change-Id: Ib350d90906bcd19cc5fd836413708420e8b1b0f8 Signed-off-by: Boram Bae --- diff --git a/include/sensor.h b/include/sensor.h index 0e822e5..d84f721 100644 --- a/include/sensor.h +++ b/include/sensor.h @@ -735,29 +735,37 @@ typedef enum /** + * @deprecated Deprecated since 5.5. Use sensor_events_cb() instead. * @brief Called when a sensor event occurs. * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * - * @param[in] sensor The corresponding sensor handle - * @param[in] event A sensor event - * @param[in] data The user data had passed to sensor_listener_set_event_cb() + * @remarks @a sensor should not be freed, it's managed by platform. + * @remarks @a event should not be freed and can be used only in the callback. To use outside the callback, make a copy. + * + * @param[in] sensor The corresponding sensor handle + * @param[in] event A sensor event + * @param[in] user_data The user data had passed to sensor_listener_set_event_cb() * * @pre The sensor needs to be started regarding a listener handle, using sensor_listener_start(). */ -typedef void (*sensor_event_cb)(sensor_h sensor, sensor_event_s *event, void *data); +typedef void (*sensor_event_cb)(sensor_h sensor, sensor_event_s *event, void *user_data) TIZEN_DEPRECATED_API; /** - * @brief Called when a sensor event occurs. + * @brief Called when sensor events occur. * @since_tizen 5.5 * - * @param[in] sensor The corresponding sensor handle - * @param[in] event A sensor event - * @param[in] data The user data had passed to sensor_listener_set_event_cb() + * @remarks @a sensor should not be freed, it's managed by platform. + * @remarks @a events should not be freed and can be used only in the callback. To use outside the callback, make a copy. + * + * @param[in] sensor The corresponding sensor handle + * @param[in] events The sensor events + * @param[in] events_count The number of events + * @param[in] user_data The user data passed to sensor_listener_set_events_cb() * * @pre The sensor needs to be started regarding a listener handle, using sensor_listener_start(). */ -typedef void (*sensor_events_cb)(sensor_h sensor, sensor_event_s* events[], int events_count, void *data); +typedef void (*sensor_events_cb)(sensor_h sensor, sensor_event_s events[], int events_count, void *user_data); /** * @brief Called when the accuracy of a sensor changes. @@ -859,6 +867,7 @@ int sensor_listener_stop(sensor_listener_h listener); /** + * @deprecated Deprecated since 5.5. Use sensor_listener_set_events_cb() instead. * @brief Registers the callback function to be invoked when sensor events are delivered via a sensor listener. * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * @@ -876,10 +885,11 @@ int sensor_listener_stop(sensor_listener_h listener); * * @see sensor_listener_unset_event_cb() */ -int sensor_listener_set_event_cb(sensor_listener_h listener, unsigned int interval_ms, sensor_event_cb callback, void *data); +int sensor_listener_set_event_cb(sensor_listener_h listener, unsigned int interval_ms, sensor_event_cb callback, void *data) TIZEN_DEPRECATED_API; /** + * @deprecated Deprecated since 5.5. Use sensor_listener_unset_events_cb() instead. * @brief Unregisters the sensor event callback function attached to a given sensor listener. * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * @@ -892,16 +902,16 @@ int sensor_listener_set_event_cb(sensor_listener_h listener, unsigned int interv * * @see sensor_listener_set_event_cb() */ -int sensor_listener_unset_event_cb(sensor_listener_h listener); +int sensor_listener_unset_event_cb(sensor_listener_h listener) TIZEN_DEPRECATED_API; /** - * @brief Registers the callback function to be invoked when sensor events are delivered via a sensor listener. + * @brief Sets the callback function to be invoked when sensor events are delivered via a sensor listener. * @since_tizen 5.5 * * @param[in] listener A 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 + * @param[in] callback A callback function to attach to the @a listener handle + * @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 @@ -910,10 +920,10 @@ int sensor_listener_unset_event_cb(sensor_listener_h listener); * * @see sensor_listener_unset_events_cb() */ -int sensor_listener_set_events_cb(sensor_listener_h listener, sensor_events_cb callback, void *data); +int sensor_listener_set_events_cb(sensor_listener_h listener, sensor_events_cb callback, void *user_data); /** - * @brief Unregisters the sensor events callback function attached to a given sensor listener. + * @brief Unsets the sensor events callback function attached to a given sensor listener. * @since_tizen 5.5 * * @param[in] listener A listener handle @@ -1358,6 +1368,7 @@ int sensor_provider_set_interval_changed_cb(sensor_provider_h provider, /** + * @deprecated Deprecated since 5.5. Use sensor_provider_publish_events() instead. * @brief Publishes a sensor event through the declared sensor. * @details This function publishes a sensor's data to its listeners. * @since_tizen 4.0 @@ -1370,16 +1381,27 @@ int sensor_provider_set_interval_changed_cb(sensor_provider_h provider, * @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); +int sensor_provider_publish(sensor_provider_h provider, sensor_event_s event) TIZEN_DEPRECATED_API; /** - * @brief Publishes a sensor event through the declared sensor. + * @brief Publishes sensor events through the declared sensor. * @details This function publishes a sensor's data to its listeners. * @since_tizen 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 @a events will be delivered. This behavior is not guaranteed, + * it's strongly recommended not to use sensor_provider_publish_events() with sensor_event_cb(). + * * @param[in] provider The sensor provider handle * @param[in] events The sensor events - * @param[in] count The number of event + * @param[in] count The number of events * * @return #SENSOR_ERROR_NONE on success, otherwise a negative error value * @retval #SENSOR_ERROR_NONE Successful diff --git a/src/sensor.cpp b/src/sensor.cpp index fc3e283..2be62af 100644 --- a/src/sensor.cpp +++ b/src/sensor.cpp @@ -107,16 +107,16 @@ static void sensor_callback(sensor_t sensor, unsigned int event_type, sensor_dat return; } -static void sensor_events_callback(sensor_t sensor, unsigned int event_type, sensor_data_t* datas[], int events_count, void *user_data) +static void sensor_events_callback(sensor_t sensor, unsigned int event_type, sensor_data_t datas[], int events_count, void *user_data) { - sensor_event_s **events; + sensor_event_s *events; sensor_listener_h listener; listener = (sensor_listener_h)user_data; if (!sensor || !listener->callback) return; - events = (sensor_event_s **)datas; + events = (sensor_event_s *)datas; ((sensor_events_cb) listener->callback)(sensor, events, events_count, listener->user_data); return; @@ -515,12 +515,14 @@ int sensor_listener_stop(sensor_listener_h listener) int sensor_listener_set_event_cb(sensor_listener_h listener, unsigned int interval, sensor_event_cb callback, void *user_data) { + _W("DEPRECATION WARNING: sensor_listener_set_event_cb() is deprecated and will be removed from next release. Use sensor_listener_set_events_cb() instead."); _D("called sensor_listener_set_event_cb : listener[%p]", listener); return sensor_listener_set_event_cb_impl(listener, interval, (void*) callback, false, user_data); } int sensor_listener_unset_event_cb(sensor_listener_h listener) { + _W("DEPRECATION WARNING: sensor_listener_unset_event_cb() is deprecated and will be removed from next release. Use sensor_listener_unset_events_cb() instead."); _D("called sensor_listener_unset_event_cb : listener[%p]", listener); return sensor_listener_unset_event_cb_impl(listener, false); } diff --git a/src/sensor_provider.cpp b/src/sensor_provider.cpp index a3be72f..1f0dc26 100644 --- a/src/sensor_provider.cpp +++ b/src/sensor_provider.cpp @@ -176,6 +176,7 @@ int sensor_provider_set_interval_changed_cb(sensor_provider_h provider, int sensor_provider_publish(sensor_provider_h provider, sensor_event_s event) { + _W("DEPRECATION WARNING: sensor_provider_publish() is deprecated and will be removed from next release. Use sensor_provider_publish_events() instead."); RETV_IF(!provider, SENSOR_ERROR_INVALID_PARAMETER); int result;