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 <boram21.bae@samsung.com>

diff --git a/include/sensor.h b/include/sensor.h
index 0e822e5..d84f721 100644 (file)
--- 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 (file)
--- 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 (file)
--- 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;