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