/*
 * Copyright (c) 2020 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.
 */

#ifndef __TIZEN_UIX_GESTURE_H__
#define __TIZEN_UIX_GESTURE_H__

#include <gesture_common.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 * @file gesture.h
 * @brief This file contains hand gesture's APIs.
 */

/**
 * @addtogroup CAPI_UIX_GESTURE_MODULE
 * @{
 */

/**
 * @brief The hand gesture handle.
 * @since_tizen @if WEARABLE 6.0 @endif
 */
typedef struct hand_gesture_s *hand_gesture_h;

/**
 * @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] 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 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()
 *
 * @see hand_gesture_start_recognition()
 */
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 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     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);

/**
 * @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_NONE               Supported
 * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      The @c gesture 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_is_supported_type(hand_gesture_h handle, hand_gesture_type_e gesture, bool* supported);

/**
 * @brief Creates a gesture handle.
 *
 * @since_tizen @if WEARABLE 6.0 @endif
 * @privlevel public
 * @privilege %http://tizen.org/privilege/appmanager.launch
 * @remarks If the function succeeds, @a handle must be released with hand_gesture_destroy().
 *
 * @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_NOT_SUPPORTED      Not supported
 * @retval #HAND_GESTURE_ERROR_PERMISSION_DENIED  Permission denied
 * @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);

/**
 * @brief Destroys a gesture handle.
 *
 * @since_tizen @if WEARABLE 6.0 @endif
 *
 * @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);

/**
 * @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  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_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);

/**
 * @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.
 *
 * @since_tizen @if WEARABLE 6.0 @endif
 * @privlevel public
 * @privilege %http://tizen.org/privilege/appmanager.launch
 *
 * @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_NOT_SUPPORTED      Gesture recognition is not supported
 * @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()
 * @pre hand_gesture_set_option()
 * @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);

/**
 * @brief Stops recognizing the gesture registered to the gesture handle.
 *
 * @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_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);

/**
 * @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          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);

/**
 * @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_OPERATION_FAILED   Operation failed because of a system error
 *
 * @see hand_gesture_error_cb()
 * @see hand_gesture_unset_error_cb()
 */
int hand_gesture_set_error_cb(hand_gesture_h handle, hand_gesture_error_cb callback, void *user_data);

/**
 * @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);


/**
 * @}
 */

#ifdef __cplusplus
}
#endif

#endif /* __TIZEN_UIX_GESTURE_H__ */
