extern "C" {
#endif
-/**
+/*
* @file gesture.h
* @brief This file contains hand gesture's APIs.
*/
*/
/**
+ * @deprecated Deprecated since 8.0.
* @brief The hand gesture handle.
* @since_tizen @if WEARABLE 6.0 @endif
*/
typedef struct hand_gesture_s *hand_gesture_h;
/**
+ * @deprecated Deprecated since 8.0.
* @brief Called when a gesture is detected.
+ * @details Following error codes can be delivered: \n
+ * #HAND_GESTURE_ERROR_NONE, \n
+ * #HAND_GESTURE_ERROR_NOT_SUPPORTED, \n
+ * #HAND_GESTURE_ERROR_INVALID_PARAMETER, \n
+ * #HAND_GESTURE_ERROR_OPERATION_FAILED
*
* @since_tizen @if WEARABLE 6.0 @endif
+ * @remarks The @a handle is managed by the platform and will be released when hand_gesture_destroy() is called.
*
- * @param[in] gesture Gesture type detected
- * @param[in] data Detailed information of the detected gesture.@n
- * hand_gesture_get_event() or gesture_get_tilt() can be used to extract the information from @c data.
+ * @param[in] handle A gesture handle
+ * @param[in] gesture A gesture type detected
* @param[in] timestamp The time when the gesture is detected. Epoch time in seconds.
- * @param[in] error An error value. It can be one of the following error values:@n
- * #HAND_GESTURE_ERROR_NONE, if the operation succeeded.@n
- * #HAND_GESTURE_ERROR_NOT_SUPPORTED, if the gesture is not supported in the current profile.@n
- * #HAND_GESTURE_ERROR_OPERATION_FAILED, if the operation failed because of a system error.@n
- * #HAND_GESTURE_ERROR_PERMISSION_DENIED, if the application has no permission to use this.
- * @param[in] user_data The user data had passed to hand_gesture_start_recognition()
+ * @param[in] error An error value. It can be one of the following error values: \n
+ * #HAND_GESTURE_ERROR_NONE, if the operation succeeded.\n
+ * #HAND_GESTURE_ERROR_NOT_SUPPORTED, if the gesture is not supported on the device.\n
+ * #HAND_GESTURE_ERROR_INVALID_PARAMETER, if the parameter is invalid. \n
+ * #HAND_GESTURE_ERROR_OPERATION_FAILED, if the operation failed because of a system error.
+ * @param[in] user_data The user data is passed to hand_gesture_start_recognition()
*
- * @pre hand_gesture_start_recognition()
+ * @see hand_gesture_start_recognition()
*/
-typedef void(* hand_gesture_recognition_cb)(hand_gesture_type_e gesture, const hand_gesture_data_h data, double timestamp, hand_gesture_error_e error, void *user_data);
+typedef void(* hand_gesture_recognition_cb)(hand_gesture_h handle, hand_gesture_type_e gesture, double timestamp, hand_gesture_error_e error, void *user_data);
/**
- * @brief Checks whether the gesture is supported or not.
- * @details Check if the given gesture type is supported in the current device.
+ * @deprecated Deprecated since 8.0.
+ * @brief Called when an error is occurred.
+ * @details Following error codes can be delivered: \n
+ * #HAND_GESTURE_ERROR_INVALID_PARAMETER, \n
+ * #HAND_GESTURE_ERROR_INVALID_OPERATION, \n
+ * #HAND_GESTURE_ERROR_OUT_OF_MEMORY, \n
+ * #HAND_GESTURE_ERROR_OPERATION_FAILED
*
* @since_tizen @if WEARABLE 6.0 @endif
+ * @remarks The @a handle is the same object for which the callback was set.
+ * The @a handle is available until hand_gesture_destroy() is called.
+ * The @a msg is managed by the platform and will be released when invoking this callback function is finished.
*
- * @param[in] handle The gesture handle
- * @param[in] gesture Gesture type to be checked
- * @param[out] supported @c true if the gesture is recognizable in the current device,@n
+ * @param[in] handle A gesture handle
+ * @param[in] error An error value. It can be one of the following error values: \n
+ * #HAND_GESTURE_ERROR_INVALID_PARAMETER, \n
+ * #HAND_GESTURE_ERROR_INVALID_OPERATION, \n
+ * #HAND_GESTURE_ERROR_OUT_OF_MEMORY, \n
+ * #HAND_GESTURE_ERROR_OPERATION_FAILED
+ * @param[in] msg An error message from gesture engine service
+ * @param[in] user_data The user data is passed to hand_gesture_set_error_cb()
+ *
+ * @see hand_gesture_set_error_cb()
+ * @see hand_gesture_unset_error_cb()
+ */
+typedef void(* hand_gesture_error_cb)(hand_gesture_h handle, hand_gesture_error_e error, const char* msg, void *user_data);
+
+/**
+ * @deprecated Deprecated since 8.0.
+ * @brief Checks whether a gesture is supported or not.
+ * @details Check if the given gesture type is supported on the device.
+ *
+ * @since_tizen @if WEARABLE 6.0 @endif
+ *
+ * @param[in] handle A gesture handle
+ * @param[in] gesture A gesture type to be checked
+ * @param[out] supported @c true if the gesture is recognizable on the device,\n
* @c false otherwise
*
* @return @c 0 if the @c gesture is supported, otherwise a negative error value
* @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER Invalid parameter used
* @retval #HAND_GESTURE_ERROR_OPERATION_FAILED Operation failed because of a system error
*/
-int hand_gesture_is_supported_type(hand_gesture_h handle, hand_gesture_type_e gesture, bool* supported);
+int hand_gesture_is_supported_type(hand_gesture_h handle, hand_gesture_type_e gesture, bool* supported) TIZEN_DEPRECATED_API;
/**
+ * @deprecated Deprecated since 8.0.
* @brief Creates a gesture handle.
*
* @since_tizen @if WEARABLE 6.0 @endif
* @privilege %http://tizen.org/privilege/appmanager.launch
* @remarks If the function succeeds, @a handle must be released with hand_gesture_destroy().
*
- * @param[out] handle The gesture handle
+ * @param[out] handle A gesture handle
*
* @return 0 on success, otherwise a negative error value
* @retval #HAND_GESTURE_ERROR_NONE Successful
* @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #HAND_GESTURE_ERROR_OUT_OF_MEMORY Out of memory
* @retval #HAND_GESTURE_ERROR_OPERATION_FAILED Operation failed
+ *
* @see hand_gesture_destroy()
*/
-int hand_gesture_create(hand_gesture_h *handle);
+int hand_gesture_create(hand_gesture_h *handle) TIZEN_DEPRECATED_API;
/**
+ * @deprecated Deprecated since 8.0.
* @brief Destroys a gesture handle.
*
* @since_tizen @if WEARABLE 6.0 @endif
*
- * @param[in] handle The gesture handle
+ * @param[in] handle A gesture handle
*
* @return 0 on success, otherwise a negative error value
* @retval #HAND_GESTURE_ERROR_NONE Successful
* @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED Not supported
* @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #HAND_GESTURE_ERROR_OPERATION_FAILED Operation failed
+ *
* @see hand_gesture_create()
*/
-int hand_gesture_destroy(hand_gesture_h handle);
+int hand_gesture_destroy(hand_gesture_h handle) TIZEN_DEPRECATED_API;
/**
- * @brief Sets the option for gesture recognition.
+ * @deprecated Deprecated since 8.0.
+ * @brief Sets an option for gesture recognition.
*
* @since_tizen @if WEARABLE 6.0 @endif
+ * @remarks If you would like to set a gesture option, you should call this function before hand_gesture_start_recognition() is invoked. \n
+ * If you do not call this function, #HAND_GESTURE_OPTION_DEFAULT will be set as the default option.
*
- * @param[in] handle Gesture handle to be used to control the gesture event
- * @param[in] option Detection option
+ * @param[in] handle A gesture handle used to control the gesture event
+ * @param[in] option An option for detecting gestures
*
* @return @c 0 on success, otherwise a negative error value
* @retval #HAND_GESTURE_ERROR_NONE Successful
* @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED Gesture recognition is not supported
* @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER Invalid parameter used
- * @retval #HAND_GESTURE_ERROR_ALREADY_STARTED The @c handle is being used already
* @retval #HAND_GESTURE_ERROR_OPERATION_FAILED Operation failed because of a system error
*
* @see hand_gesture_start_recognition()
*/
-int hand_gesture_set_option(hand_gesture_h handle, hand_gesture_option_e option);
+int hand_gesture_set_option(hand_gesture_h handle, hand_gesture_option_e option) TIZEN_DEPRECATED_API;
/**
+ * @deprecated Deprecated since 8.0.
* @brief Starts to recognize a gesture.
* @details Sets a callback function to be invoked when the gesture is detected, and starts to monitor occurrences of the gesture.
*
* @privlevel public
* @privilege %http://tizen.org/privilege/appmanager.launch
*
- * @param[in] handle Gesture handle to be used to control the gesture event
- * @param[in] gesture Gesture type to be monitored
- * @param[in] callback Callback function to receive gesture events
- * @param[in] user_data User data to be passed to the callback function
+ * @param[in] handle A gesture handle used to control the gesture event
+ * @param[in] gesture A gesture type to be monitored
+ * @param[in] callback A callback function to receive gesture events
+ * @param[in] user_data A user data to be passed to the callback function
*
* @return @c 0 on success, otherwise a negative error value
* @retval #HAND_GESTURE_ERROR_NONE Successful
* @retval #HAND_GESTURE_ERROR_PERMISSION_DENIED Permission denied
* @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER Invalid parameter used
* @retval #HAND_GESTURE_ERROR_ALREADY_STARTED The @c handle is being used already
+ * @retval #HAND_GESTURE_ERROR_OUT_OF_MEMORY Out of memory
* @retval #HAND_GESTURE_ERROR_OPERATION_FAILED Operation failed because of a system error
*
* @pre hand_gesture_create()
* @post hand_gesture_recognition_cb()
* @see hand_gesture_stop_recognition()
*/
-int hand_gesture_start_recognition(hand_gesture_h handle, hand_gesture_type_e gesture, hand_gesture_recognition_cb callback, void *user_data);
+int hand_gesture_start_recognition(hand_gesture_h handle, hand_gesture_type_e gesture, hand_gesture_recognition_cb callback, void *user_data) TIZEN_DEPRECATED_API;
/**
+ * @deprecated Deprecated since 8.0.
* @brief Stops recognizing the gesture registered to the gesture handle.
*
* @since_tizen @if WEARABLE 6.0 @endif
*
- * @param[in] handle Gesture handle to release its callback function registered
+ * @param[in] handle A gesture handle
*
* @return @c 0 on success, otherwise a negative error value
* @retval #HAND_GESTURE_ERROR_NONE Successful
* @retval #HAND_GESTURE_ERROR_NOT_STARTED Nothing is started using the @c handle
* @retval #HAND_GESTURE_ERROR_OPERATION_FAILED Operation failed because of a system error
*/
-int hand_gesture_stop_recognition(hand_gesture_h handle);
+int hand_gesture_stop_recognition(hand_gesture_h handle) TIZEN_DEPRECATED_API;
/**
- * @brief Gets the gesture engine information.
+ * @deprecated Deprecated since 8.0.
+ * @brief Gets a gesture engine information.
*
* @since_tizen @if WEARABLE 6.0 @endif
* @remarks The @a engine_app_id and the @a engine_name should be released using free().
*
- * @param[in] handle Gesture handle to release its callback function registered
- * @param[out] engine_app_id The gesture engine app ID
- * @param[out] engine_name The gesture engine name
+ * @param[in] handle A gesture handle
+ * @param[out] engine_app_id A gesture engine app ID
+ * @param[out] engine_name A gesture engine name
+ *
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #HAND_GESTURE_ERROR_NONE Successful
+ * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED Gesture recognition is not supported
+ * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER Invalid parameter used
+ * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED Operation failed because of a system error
+ */
+int hand_gesture_get_engine_info(hand_gesture_h handle, char** engine_app_id, char** engine_name) TIZEN_DEPRECATED_API;
+
+/**
+ * @deprecated Deprecated since 8.0.
+ * @brief Sets a callback function to be invoked when an error is occurred.
+ *
+ * @since_tizen @if WEARABLE 6.0 @endif
+ *
+ * @param[in] handle A gesture handle
+ * @param[in] callback A callback function invoked when an error is occurred
+ * @param[in] user_data A user data to be passed to the callback function
*
* @return @c 0 on success, otherwise a negative error value
* @retval #HAND_GESTURE_ERROR_NONE Successful
* @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED Gesture recognition is not supported
* @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER Invalid parameter used
- * @retval #HAND_GESTURE_ERROR_NOT_STARTED Nothing is started using the @c handle
* @retval #HAND_GESTURE_ERROR_OPERATION_FAILED Operation failed because of a system error
+ *
+ * @see hand_gesture_error_cb()
+ * @see hand_gesture_unset_error_cb()
*/
-int hand_gesture_get_engine_info(hand_gesture_h handle, char** engine_app_id, char** engine_name);
+int hand_gesture_set_error_cb(hand_gesture_h handle, hand_gesture_error_cb callback, void *user_data) TIZEN_DEPRECATED_API;
+
+/**
+ * @deprecated Deprecated since 8.0.
+ * @brief Unsets a callback function to be invoked when an error is occurred.
+ *
+ * @since_tizen @if WEARABLE 6.0 @endif
+ *
+ * @param[in] handle A gesture handle
+ *
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #HAND_GESTURE_ERROR_NONE Successful
+ * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED Gesture recognition is not supported
+ * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER Invalid parameter used
+ * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED Operation failed because of a system error
+ *
+ * @see hand_gesture_set_error_cb()
+ */
+int hand_gesture_unset_error_cb(hand_gesture_h handle) TIZEN_DEPRECATED_API;
+
/**
* @}