include/gesture.h

   1 /*
   2  * Copyright (c) 2020 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __TIZEN_UIX_GESTURE_H__
  18 #define __TIZEN_UIX_GESTURE_H__
  19
  20 #include <gesture_common.h>
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 /*
  27  * @file gesture.h
  28  * @brief This file contains hand gesture's APIs.
  29  */
  30
  31 /**
  32  * @addtogroup CAPI_UIX_GESTURE_MODULE
  33  * @{
  34  */
  35
  36 /**
  37  * @deprecated Deprecated since 8.0.
  38  * @brief The hand gesture handle.
  39  * @since_tizen @if WEARABLE 6.0 @endif
  40  */
  41 typedef struct hand_gesture_s *hand_gesture_h;
  42
  43 /**
  44  * @deprecated Deprecated since 8.0.
  45  * @brief Called when a gesture is detected.
  46  * @details Following error codes can be delivered: \n
  47  *          #HAND_GESTURE_ERROR_NONE, \n
  48  *          #HAND_GESTURE_ERROR_NOT_SUPPORTED, \n
  49  *          #HAND_GESTURE_ERROR_INVALID_PARAMETER, \n
  50  *          #HAND_GESTURE_ERROR_OPERATION_FAILED
  51  *
  52  * @since_tizen @if WEARABLE 6.0 @endif
  53  * @remarks The @a handle is managed by the platform and will be released when hand_gesture_destroy() is called.
  54  *
  55  * @param[in] handle     A gesture handle
  56  * @param[in] gesture    A gesture type detected
  57  * @param[in] timestamp  The time when the gesture is detected. Epoch time in seconds.
  58  * @param[in] error      An error value. It can be one of the following error values: \n
  59  *                       #HAND_GESTURE_ERROR_NONE, if the operation succeeded.\n
  60  *                       #HAND_GESTURE_ERROR_NOT_SUPPORTED, if the gesture is not supported on the device.\n
  61  *                       #HAND_GESTURE_ERROR_INVALID_PARAMETER, if the parameter is invalid. \n
  62  *                       #HAND_GESTURE_ERROR_OPERATION_FAILED, if the operation failed because of a system error.
  63  * @param[in] user_data  The user data is passed to hand_gesture_start_recognition()
  64  *
  65  * @see hand_gesture_start_recognition()
  66  */
  67 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);
  68
  69 /**
  70  * @deprecated Deprecated since 8.0.
  71  * @brief Called when an error is occurred.
  72  * @details Following error codes can be delivered: \n
  73  *          #HAND_GESTURE_ERROR_INVALID_PARAMETER, \n
  74  *          #HAND_GESTURE_ERROR_INVALID_OPERATION, \n
  75  *          #HAND_GESTURE_ERROR_OUT_OF_MEMORY, \n
  76  *          #HAND_GESTURE_ERROR_OPERATION_FAILED
  77  *
  78  * @since_tizen @if WEARABLE 6.0 @endif
  79  * @remarks The @a handle is the same object for which the callback was set.
  80  *          The @a handle is available until hand_gesture_destroy() is called.
  81  *          The @a msg is managed by the platform and will be released when invoking this callback function is finished.
  82  *
  83  * @param[in] handle     A gesture handle
  84  * @param[in] error      An error value. It can be one of the following error values: \n
  85  *                       #HAND_GESTURE_ERROR_INVALID_PARAMETER, \n
  86  *                       #HAND_GESTURE_ERROR_INVALID_OPERATION, \n
  87  *                       #HAND_GESTURE_ERROR_OUT_OF_MEMORY, \n
  88  *                       #HAND_GESTURE_ERROR_OPERATION_FAILED
  89  * @param[in] msg        An error message from gesture engine service
  90  * @param[in] user_data  The user data is passed to hand_gesture_set_error_cb()
  91  *
  92  * @see hand_gesture_set_error_cb()
  93  * @see hand_gesture_unset_error_cb()
  94  */
  95 typedef void(* hand_gesture_error_cb)(hand_gesture_h handle, hand_gesture_error_e error, const char* msg, void *user_data);
  96
  97 /**
  98  * @deprecated Deprecated since 8.0.
  99  * @brief Checks whether a gesture is supported or not.
 100  * @details Check if the given gesture type is supported on the device.
 101  *
 102  * @since_tizen @if WEARABLE 6.0 @endif
 103  *
 104  * @param[in] handle      A gesture handle
 105  * @param[in] gesture     A gesture type to be checked
 106  * @param[out] supported  @c true if the gesture is recognizable on the device,\n
 107  *                        @c false otherwise
 108  *
 109  * @return @c 0 if the @c gesture is supported, otherwise a negative error value
 110  * @retval #HAND_GESTURE_ERROR_NONE               Supported
 111  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      The @c gesture is not supported
 112  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter used
 113  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed because of a system error
 114  */
 115 int hand_gesture_is_supported_type(hand_gesture_h handle, hand_gesture_type_e gesture, bool* supported) TIZEN_DEPRECATED_API;
 116
 117 /**
 118  * @deprecated Deprecated since 8.0.
 119  * @brief Creates a gesture handle.
 120  *
 121  * @since_tizen @if WEARABLE 6.0 @endif
 122  * @privlevel public
 123  * @privilege %http://tizen.org/privilege/appmanager.launch
 124  * @remarks If the function succeeds, @a handle must be released with hand_gesture_destroy().
 125  *
 126  * @param[out] handle  A gesture handle
 127  *
 128  * @return 0 on success, otherwise a negative error value
 129  * @retval #HAND_GESTURE_ERROR_NONE               Successful
 130  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      Not supported
 131  * @retval #HAND_GESTURE_ERROR_PERMISSION_DENIED  Permission denied
 132  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter
 133  * @retval #HAND_GESTURE_ERROR_OUT_OF_MEMORY      Out of memory
 134  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed
 135  *
 136  * @see hand_gesture_destroy()
 137  */
 138 int hand_gesture_create(hand_gesture_h *handle) TIZEN_DEPRECATED_API;
 139
 140 /**
 141  * @deprecated Deprecated since 8.0.
 142  * @brief Destroys a gesture handle.
 143  *
 144  * @since_tizen @if WEARABLE 6.0 @endif
 145  *
 146  * @param[in] handle A gesture handle
 147  *
 148  * @return 0 on success, otherwise a negative error value
 149  * @retval #HAND_GESTURE_ERROR_NONE               Successful
 150  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      Not supported
 151  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter
 152  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed
 153  *
 154  * @see hand_gesture_create()
 155  */
 156 int hand_gesture_destroy(hand_gesture_h handle) TIZEN_DEPRECATED_API;
 157
 158 /**
 159  * @deprecated Deprecated since 8.0.
 160  * @brief Sets an option for gesture recognition.
 161  *
 162  * @since_tizen @if WEARABLE 6.0 @endif
 163  * @remarks If you would like to set a gesture option, you should call this function before hand_gesture_start_recognition() is invoked. \n
 164  *          If you do not call this function, #HAND_GESTURE_OPTION_DEFAULT will be set as the default option.
 165  *
 166  * @param[in] handle  A gesture handle used to control the gesture event
 167  * @param[in] option  An option for detecting gestures
 168  *
 169  * @return @c 0 on success, otherwise a negative error value
 170  * @retval #HAND_GESTURE_ERROR_NONE               Successful
 171  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      Gesture recognition is not supported
 172  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter used
 173  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed because of a system error
 174  *
 175  * @see hand_gesture_start_recognition()
 176  */
 177 int hand_gesture_set_option(hand_gesture_h handle, hand_gesture_option_e option) TIZEN_DEPRECATED_API;
 178
 179 /**
 180  * @deprecated Deprecated since 8.0.
 181  * @brief Starts to recognize a gesture.
 182  * @details Sets a callback function to be invoked when the gesture is detected, and starts to monitor occurrences of the gesture.
 183  *
 184  * @since_tizen @if WEARABLE 6.0 @endif
 185  * @privlevel public
 186  * @privilege %http://tizen.org/privilege/appmanager.launch
 187  *
 188  * @param[in] handle     A gesture handle used to control the gesture event
 189  * @param[in] gesture    A gesture type to be monitored
 190  * @param[in] callback   A callback function to receive gesture events
 191  * @param[in] user_data  A user data to be passed to the callback function
 192  *
 193  * @return @c 0 on success, otherwise a negative error value
 194  * @retval #HAND_GESTURE_ERROR_NONE               Successful
 195  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      Gesture recognition is not supported
 196  * @retval #HAND_GESTURE_ERROR_PERMISSION_DENIED  Permission denied
 197  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter used
 198  * @retval #HAND_GESTURE_ERROR_ALREADY_STARTED    The @c handle is being used already
 199  * @retval #HAND_GESTURE_ERROR_OUT_OF_MEMORY      Out of memory
 200  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed because of a system error
 201  *
 202  * @pre hand_gesture_create()
 203  * @pre hand_gesture_set_option()
 204  * @post hand_gesture_recognition_cb()
 205  * @see hand_gesture_stop_recognition()
 206  */
 207 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;
 208
 209 /**
 210  * @deprecated Deprecated since 8.0.
 211  * @brief Stops recognizing the gesture registered to the gesture handle.
 212  *
 213  * @since_tizen @if WEARABLE 6.0 @endif
 214  *
 215  * @param[in] handle  A gesture handle
 216  *
 217  * @return @c 0 on success, otherwise a negative error value
 218  * @retval #HAND_GESTURE_ERROR_NONE               Successful
 219  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      Gesture recognition is not supported
 220  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter used
 221  * @retval #HAND_GESTURE_ERROR_NOT_STARTED        Nothing is started using the @c handle
 222  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed because of a system error
 223  */
 224 int hand_gesture_stop_recognition(hand_gesture_h handle) TIZEN_DEPRECATED_API;
 225
 226 /**
 227  * @deprecated Deprecated since 8.0.
 228  * @brief Gets a gesture engine information.
 229  *
 230  * @since_tizen @if WEARABLE 6.0 @endif
 231  * @remarks The @a engine_app_id and the @a engine_name should be released using free().
 232  *
 233  * @param[in] handle          A gesture handle
 234  * @param[out] engine_app_id  A gesture engine app ID
 235  * @param[out] engine_name    A gesture engine name
 236  *
 237  * @return @c 0 on success, otherwise a negative error value
 238  * @retval #HAND_GESTURE_ERROR_NONE               Successful
 239  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      Gesture recognition is not supported
 240  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter used
 241  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed because of a system error
 242  */
 243 int hand_gesture_get_engine_info(hand_gesture_h handle, char** engine_app_id, char** engine_name) TIZEN_DEPRECATED_API;
 244
 245 /**
 246  * @deprecated Deprecated since 8.0.
 247  * @brief Sets a callback function to be invoked when an error is occurred.
 248  *
 249  * @since_tizen @if WEARABLE 6.0 @endif
 250  *
 251  * @param[in] handle     A gesture handle
 252  * @param[in] callback   A callback function invoked when an error is occurred
 253  * @param[in] user_data  A user data to be passed to the callback function
 254  *
 255  * @return @c 0 on success, otherwise a negative error value
 256  * @retval #HAND_GESTURE_ERROR_NONE               Successful
 257  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      Gesture recognition is not supported
 258  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter used
 259  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed because of a system error
 260  *
 261  * @see hand_gesture_error_cb()
 262  * @see hand_gesture_unset_error_cb()
 263  */
 264 int hand_gesture_set_error_cb(hand_gesture_h handle, hand_gesture_error_cb callback, void *user_data) TIZEN_DEPRECATED_API;
 265
 266 /**
 267  * @deprecated Deprecated since 8.0.
 268  * @brief Unsets a callback function to be invoked when an error is occurred.
 269  *
 270  * @since_tizen @if WEARABLE 6.0 @endif
 271  *
 272  * @param[in] handle     A gesture handle
 273  *
 274  * @return @c 0 on success, otherwise a negative error value
 275  * @retval #HAND_GESTURE_ERROR_NONE               Successful
 276  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      Gesture recognition is not supported
 277  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter used
 278  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed because of a system error
 279  *
 280  * @see hand_gesture_set_error_cb()
 281  */
 282 int hand_gesture_unset_error_cb(hand_gesture_h handle) TIZEN_DEPRECATED_API;
 283
 284
 285 /**
 286  * @}
 287  */
 288
 289 #ifdef __cplusplus
 290 }
 291 #endif
 292
 293 #endif /* __TIZEN_UIX_GESTURE_H__ */