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  * @brief The hand gesture handle.
  38  * @since_tizen @if WEARABLE 6.0 @endif
  39  */
  40 typedef struct hand_gesture_s *hand_gesture_h;
  41
  42 /**
  43  * @brief Called when a gesture is detected.
  44  * @details Following error codes can be delivered: \n
  45  *          #HAND_GESTURE_ERROR_NONE, \n
  46  *          #HAND_GESTURE_ERROR_NOT_SUPPORTED, \n
  47  *          #HAND_GESTURE_ERROR_INVALID_PARAMETER, \n
  48  *          #HAND_GESTURE_ERROR_OPERATION_FAILED
  49  *
  50  * @since_tizen @if WEARABLE 6.0 @endif
  51  * @remarks The @a handle is managed by the platform and will be released when hand_gesture_destroy() is called.
  52  *
  53  * @param[in] handle     A gesture handle
  54  * @param[in] gesture    A gesture type detected
  55  * @param[in] timestamp  The time when the gesture is detected. Epoch time in seconds.
  56  * @param[in] error      An error value. It can be one of the following error values: \n
  57  *                       #HAND_GESTURE_ERROR_NONE, if the operation succeeded.\n
  58  *                       #HAND_GESTURE_ERROR_NOT_SUPPORTED, if the gesture is not supported on the device.\n
  59  *                       #HAND_GESTURE_ERROR_INVALID_PARAMETER, if the parameter is invalid. \n
  60  *                       #HAND_GESTURE_ERROR_OPERATION_FAILED, if the operation failed because of a system error.
  61  * @param[in] user_data  The user data is passed to hand_gesture_start_recognition()
  62  *
  63  * @see hand_gesture_start_recognition()
  64  */
  65 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);
  66
  67 /**
  68  * @brief Called when an error is occurred.
  69  * @details Following error codes can be delivered: \n
  70  *          #HAND_GESTURE_ERROR_INVALID_PARAMETER, \n
  71  *          #HAND_GESTURE_ERROR_INVALID_OPERATION, \n
  72  *          #HAND_GESTURE_ERROR_OUT_OF_MEMORY, \n
  73  *          #HAND_GESTURE_ERROR_OPERATION_FAILED
  74  *
  75  * @since_tizen @if WEARABLE 6.0 @endif
  76  * @remarks The @a handle is the same object for which the callback was set.
  77  *          The @a handle is available until hand_gesture_destroy() is called.
  78  *          The @a msg is managed by the platform and will be released when invoking this callback function is finished.
  79  *
  80  * @param[in] handle     A gesture handle
  81  * @param[in] error      An error value. It can be one of the following error values: \n
  82  *                       #HAND_GESTURE_ERROR_INVALID_PARAMETER, \n
  83  *                       #HAND_GESTURE_ERROR_INVALID_OPERATION, \n
  84  *                       #HAND_GESTURE_ERROR_OUT_OF_MEMORY, \n
  85  *                       #HAND_GESTURE_ERROR_OPERATION_FAILED
  86  * @param[in] msg        An error message from gesture engine service
  87  * @param[in] user_data  The user data is passed to hand_gesture_set_error_cb()
  88  *
  89  * @see hand_gesture_set_error_cb()
  90  * @see hand_gesture_unset_error_cb()
  91  */
  92 typedef void(* hand_gesture_error_cb)(hand_gesture_h handle, hand_gesture_error_e error, const char* msg, void *user_data);
  93
  94 /**
  95  * @brief Checks whether a gesture is supported or not.
  96  * @details Check if the given gesture type is supported on the device.
  97  *
  98  * @since_tizen @if WEARABLE 6.0 @endif
  99  *
 100  * @param[in] handle      A gesture handle
 101  * @param[in] gesture     A gesture type to be checked
 102  * @param[out] supported  @c true if the gesture is recognizable on the device,\n
 103  *                        @c false otherwise
 104  *
 105  * @return @c 0 if the @c gesture is supported, otherwise a negative error value
 106  * @retval #HAND_GESTURE_ERROR_NONE               Supported
 107  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      The @c gesture is not supported
 108  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter used
 109  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed because of a system error
 110  */
 111 int hand_gesture_is_supported_type(hand_gesture_h handle, hand_gesture_type_e gesture, bool* supported);
 112
 113 /**
 114  * @brief Creates a gesture handle.
 115  *
 116  * @since_tizen @if WEARABLE 6.0 @endif
 117  * @privlevel public
 118  * @privilege %http://tizen.org/privilege/appmanager.launch
 119  * @remarks If the function succeeds, @a handle must be released with hand_gesture_destroy().
 120  *
 121  * @param[out] handle  A gesture handle
 122  *
 123  * @return 0 on success, otherwise a negative error value
 124  * @retval #HAND_GESTURE_ERROR_NONE               Successful
 125  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      Not supported
 126  * @retval #HAND_GESTURE_ERROR_PERMISSION_DENIED  Permission denied
 127  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter
 128  * @retval #HAND_GESTURE_ERROR_OUT_OF_MEMORY      Out of memory
 129  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed
 130  *
 131  * @see hand_gesture_destroy()
 132  */
 133 int hand_gesture_create(hand_gesture_h *handle);
 134
 135 /**
 136  * @brief Destroys a gesture handle.
 137  *
 138  * @since_tizen @if WEARABLE 6.0 @endif
 139  *
 140  * @param[in] handle A gesture handle
 141  *
 142  * @return 0 on success, otherwise a negative error value
 143  * @retval #HAND_GESTURE_ERROR_NONE               Successful
 144  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      Not supported
 145  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter
 146  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed
 147  *
 148  * @see hand_gesture_create()
 149  */
 150 int hand_gesture_destroy(hand_gesture_h handle);
 151
 152 /**
 153  * @brief Sets an option for gesture recognition.
 154  *
 155  * @since_tizen @if WEARABLE 6.0 @endif
 156  * @remarks If you would like to set a gesture option, you should call this function before hand_gesture_start_recognition() is invoked. \n
 157  *          If you do not call this function, #HAND_GESTURE_OPTION_DEFAULT will be set as the default option.
 158  *
 159  * @param[in] handle  A gesture handle used to control the gesture event
 160  * @param[in] option  An option for detecting gestures
 161  *
 162  * @return @c 0 on success, otherwise a negative error value
 163  * @retval #HAND_GESTURE_ERROR_NONE               Successful
 164  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      Gesture recognition is not supported
 165  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter used
 166  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed because of a system error
 167  *
 168  * @see hand_gesture_start_recognition()
 169  */
 170 int hand_gesture_set_option(hand_gesture_h handle, hand_gesture_option_e option);
 171
 172 /**
 173  * @brief Starts to recognize a gesture.
 174  * @details Sets a callback function to be invoked when the gesture is detected, and starts to monitor occurrences of the gesture.
 175  *
 176  * @since_tizen @if WEARABLE 6.0 @endif
 177  * @privlevel public
 178  * @privilege %http://tizen.org/privilege/appmanager.launch
 179  *
 180  * @param[in] handle     A gesture handle used to control the gesture event
 181  * @param[in] gesture    A gesture type to be monitored
 182  * @param[in] callback   A callback function to receive gesture events
 183  * @param[in] user_data  A user data to be passed to the callback function
 184  *
 185  * @return @c 0 on success, otherwise a negative error value
 186  * @retval #HAND_GESTURE_ERROR_NONE               Successful
 187  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      Gesture recognition is not supported
 188  * @retval #HAND_GESTURE_ERROR_PERMISSION_DENIED  Permission denied
 189  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter used
 190  * @retval #HAND_GESTURE_ERROR_ALREADY_STARTED    The @c handle is being used already
 191  * @retval #HAND_GESTURE_ERROR_OUT_OF_MEMORY      Out of memory
 192  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed because of a system error
 193  *
 194  * @pre hand_gesture_create()
 195  * @pre hand_gesture_set_option()
 196  * @post hand_gesture_recognition_cb()
 197  * @see hand_gesture_stop_recognition()
 198  */
 199 int hand_gesture_start_recognition(hand_gesture_h handle, hand_gesture_type_e gesture, hand_gesture_recognition_cb callback, void *user_data);
 200
 201 /**
 202  * @brief Stops recognizing the gesture registered to the gesture handle.
 203  *
 204  * @since_tizen @if WEARABLE 6.0 @endif
 205  *
 206  * @param[in] handle  A gesture handle
 207  *
 208  * @return @c 0 on success, otherwise a negative error value
 209  * @retval #HAND_GESTURE_ERROR_NONE               Successful
 210  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      Gesture recognition is not supported
 211  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter used
 212  * @retval #HAND_GESTURE_ERROR_NOT_STARTED        Nothing is started using the @c handle
 213  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed because of a system error
 214  */
 215 int hand_gesture_stop_recognition(hand_gesture_h handle);
 216
 217 /**
 218  * @brief Gets a gesture engine information.
 219  *
 220  * @since_tizen @if WEARABLE 6.0 @endif
 221  * @remarks The @a engine_app_id and the @a engine_name should be released using free().
 222  *
 223  * @param[in] handle          A gesture handle
 224  * @param[out] engine_app_id  A gesture engine app ID
 225  * @param[out] engine_name    A gesture engine name
 226  *
 227  * @return @c 0 on success, otherwise a negative error value
 228  * @retval #HAND_GESTURE_ERROR_NONE               Successful
 229  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      Gesture recognition is not supported
 230  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter used
 231  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed because of a system error
 232  */
 233 int hand_gesture_get_engine_info(hand_gesture_h handle, char** engine_app_id, char** engine_name);
 234
 235 /**
 236  * @brief Sets a callback function to be invoked when an error is occurred.
 237  *
 238  * @since_tizen @if WEARABLE 6.0 @endif
 239  *
 240  * @param[in] handle     A gesture handle
 241  * @param[in] callback   A callback function invoked when an error is occurred
 242  * @param[in] user_data  A user data to be passed to the callback function
 243  *
 244  * @return @c 0 on success, otherwise a negative error value
 245  * @retval #HAND_GESTURE_ERROR_NONE               Successful
 246  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      Gesture recognition is not supported
 247  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter used
 248  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed because of a system error
 249  *
 250  * @see hand_gesture_error_cb()
 251  * @see hand_gesture_unset_error_cb()
 252  */
 253 int hand_gesture_set_error_cb(hand_gesture_h handle, hand_gesture_error_cb callback, void *user_data);
 254
 255 /**
 256  * @brief Unsets a callback function to be invoked when an error is occurred.
 257  *
 258  * @since_tizen @if WEARABLE 6.0 @endif
 259  *
 260  * @param[in] handle     A gesture handle
 261  *
 262  * @return @c 0 on success, otherwise a negative error value
 263  * @retval #HAND_GESTURE_ERROR_NONE               Successful
 264  * @retval #HAND_GESTURE_ERROR_NOT_SUPPORTED      Gesture recognition is not supported
 265  * @retval #HAND_GESTURE_ERROR_INVALID_PARAMETER  Invalid parameter used
 266  * @retval #HAND_GESTURE_ERROR_OPERATION_FAILED   Operation failed because of a system error
 267  *
 268  * @see hand_gesture_set_error_cb()
 269  */
 270 int hand_gesture_unset_error_cb(hand_gesture_h handle);
 271
 272
 273 /**
 274  * @}
 275  */
 276
 277 #ifdef __cplusplus
 278 }
 279 #endif
 280
 281 #endif /* __TIZEN_UIX_GESTURE_H__ */