include/gesture_engine.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_ENGINE_H__
  18 #define __TIZEN_UIX_GESTURE_ENGINE_H__
  19
  20 #include <gesture_common.h>
  21 #include <gesture_common_internal.h>
  22
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /**
  29  * @brief Enumerations for gesture server error.
  30  */
  31 typedef enum {
  32         GESTURE_ENGINE_ERROR_NONE = 0,
  33         GESTURE_ENGINE_ERROR_INVALID_PARAMETER,
  34         GESTURE_ENGINE_ERROR_INVALID_OPERATION,
  35         GESTURE_ENGINE_ERROR_OUT_OF_MEMORY,
  36         GESTURE_ENGINE_ERROR_PERMISSION_DENIED,
  37         GESTURE_ENGINE_ERROR_NOT_SUPPORTED,
  38         GESTURE_ENGINE_ERROR_IO_ERROR,
  39         GESTURE_ENGINE_ERROR_SERVICE_NOT_READY,
  40         GESTURE_ENGINE_ERROR_OPERATION_FAILED,
  41 } gesture_engine_error_e;
  42
  43 /**
  44  * @file gesture_engine.h
  45  * @brief This file contains gesture engine's APIs.
  46  */
  47
  48 /**
  49  * @brief The gesture engine handle.
  50  * @since_tizen @if WEARABLE 6.0 @endif
  51  */
  52 typedef struct gesture_engine_s *gesture_engine_h;
  53
  54
  55 /**
  56 * @brief Enumeration for callback event.
  57 * @since_tizen 6.0
  58 */
  59 typedef enum {
  60         GESTURE_ENGINE_RESULT_EVENT_FINAL_RESULT = 0, /**< Event when either the full matched or the final result is delivered */
  61         GESTURE_ENGINE_RESULT_EVENT_PARTIAL_RESULT, /**< Event when the partial matched result is delivered */
  62         GESTURE_ENGINE_RESULT_EVENT_ERROR /**< Event when the recognition has failed */
  63 } gesture_engine_result_event_e;
  64
  65
  66 /**
  67 * @brief Enumeration for result time callback event.
  68 * @since_tizen 6.0
  69 */
  70 typedef enum {
  71         GESTURE_ENGINE_RESULT_TIME_EVENT_BEGINNING = 0, /**< Event when the token is beginning type */
  72         GESTURE_ENGINE_RESULT_TIME_EVENT_MIDDLE, /**< Event when the token is middle type */
  73         GESTURE_ENGINE_RESULT_TIME_EVENT_END /**< Event when the token is end type */
  74 } gesture_engine_result_time_event_e;
  75
  76
  77 /**
  78 * @brief Enumeration for motion status.
  79 * @since_tizen 6.0
  80 */
  81 typedef enum {
  82         GESTURE_ENGINE_MOTION_STATUS_START_POINT_DETECTED = 0, /**< Beginning point of motion is detected */
  83         GESTURE_ENGINE_MOTION_STATUS_END_POINT_DETECTED /**< End point of motion is detected */
  84 } gesture_engine_motion_status_e;
  85
  86
  87 typedef void(* gesture_engine_recognition_cb)(hand_gesture_type_e gesture, const hand_gesture_data_h data, double timestamp, gesture_engine_error_e error, void *user_data);
  88
  89
  90 /**
  91 * @brief Called when GESTURE engine provides the time stamp of result to the engine service user.
  92 * @details This callback function is implemented by the engine service user. Therefore, the engine developer does NOT have to implement this callback function.
  93 * @since_tizen 6.0
  94 * @remarks This callback function is called in gesture_engine_foreach_result_time_cb() for adding time information.
  95 *          @a user_data must be transferred from gesture_engine_foreach_result_time_cb().
  96 * @param[in] index The result index
  97 * @param[in] event The token event
  98 * @param[in] start_time The time started detecting the hand motion
  99 * @param[in] end_time The time finished detecting the hand motion
 100 * @param[in] user_data The user data passed from gesture_engine_foreach_result_time_cb()
 101 * @return @c true to continue with the next iteration of the loop
 102 *         @c false to break out of the loop
 103 * @pre gesture_engine_send_result() should be called.
 104 * @see gesture_engine_send_result()
 105 * @see gesture_engine_foreach_result_time_cb()
 106 */
 107 typedef bool (*gesture_engine_result_time_cb)(int index, gesture_engine_result_time_event_e event,
 108                                 long start_time, long end_time, void* user_data);
 109
 110
 111 /**
 112 * @brief Called when GESTURE engine informs the engine service user about whole supported gesture types.
 113 * @details This callback function is implemented by the engine service user. Therefore, the engine developer does NOT have to implement this callback function.
 114 * @since_tizen 6.0
 115 * @remarks This callback function is called in gesture_engine_foreach_supported_type_cb() to inform the whole supported gesture types.
 116 *          @a user_data must be transferred from gesture_engine_foreach_supported_type_cb().
 117 * @param[in] gesture_type The type is specified as hand_gesture_type_e
 118 *                     For example, "GESTURE_WRIST_UP", "GESTURE_LEFT_HAND_MOVE"
 119 * @param[in] user_data The user data passed from gesture_engine_foreach_supported_type_cb()
 120 * @return @c true to continue with the next iteration of the loop
 121 *         @c false to break out of the loop
 122 * @pre gesture_engine_foreach_supported_type_cb() will invoke this callback function.
 123 * @see gesture_engine_foreach_supported_type_cb()
 124 */
 125 typedef bool (*gesture_engine_supported_type_cb)(const char* gesture_type, void* user_data);
 126
 127
 128 /**
 129 * @brief Called when the engine service user initializes GESTURE engine.
 130 * @details This callback function is called by the engine service user to request for GESTURE engine to be started.
 131 * @since_tizen 6.0
 132 * @remarks This callback function is mandatory and must be registered using gesture_engine_main().
 133 * @return @c 0 on success,
 134 *         otherwise a negative error value
 135 * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 136 * @retval #GESTURE_ENGINE_ERROR_INVALID_PARAMETER Invalid parameter
 137 * @retval #GESTURE_ENGINE_ERROR_OPERATION_FAILED Operation failure
 138 * @see gesture_engine_deinitialize_cb()
 139 */
 140 typedef int (*gesture_engine_initialize_cb)(void);
 141
 142
 143 /**
 144 * @brief Called when the engine service user deinitializes GESTURE engine
 145 * @details This callback function is called by the engine service user to request for GESTURE engine to be deinitialized.
 146 * @since_tizen 6.0
 147 * @remarks This callback function is mandatory and must be registered using gesture_engine_main().
 148 *          NOTE that the engine may be terminated automatically.
 149 *          When this callback function is invoked, the release of resources is necessary.
 150 * @return @c 0 on success,
 151 *         otherwise a negative error value
 152 * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 153 * @see gesture_engine_initialize_cb()
 154 */
 155 typedef int (*gesture_engine_deinitialize_cb)(void);
 156
 157
 158 /**
 159 * @brief Called when the engine service user gets the whole supported gesture types.
 160 * @since_tizen 6.0
 161 * @remarks This callback function is mandatory and must be registered using gesture_engine_main().
 162 *          In this function, the engine service user's callback function 'gesture_engine_supported_type_cb()' is invoked repeatedly for getting all supported gesture types, and @a user_data must be transferred to 'gesture_engine_supported_type_cb()'.
 163 *          If 'gesture_engine_supported_type_cb()' returns @c false, it should be stopped to call 'gesture_engine_supported_type_cb()'.
 164 * @param[in] callback The callback function
 165 * @param[in] user_data The user data which must be passed to the callback function 'gesture_engine_supported_type_cb()'
 166 * @return @c 0 on success,
 167 *         otherwise a negative error value
 168 * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 169 * @retval #GESTURE_ENGINE_ERROR_INVALID_PARAMETER Invalid parameter
 170 * @post This callback function invokes gesture_engine_supported_type_cb() repeatedly for getting supported gesture types.
 171 * @see gesture_engine_supported_type_cb()
 172 */
 173 typedef int (*gesture_engine_foreach_supported_type_cb)(gesture_engine_supported_type_cb callback, void* user_data);
 174
 175 /**
 176 * @brief Called when the engine service user checks whether GESTURE engine supports the corresponding recognition type.
 177 * @since_tizen 6.0
 178 * @remarks This callback function is mandatory and must be registered using gesture_engine_main().
 179 * @param[in] type The type for recognition (e.g. #GESTURE_WRIST_UP)
 180 * @param[out] is_supported A variable for checking whether GESTURE engine supports the corresponding recognition type.
 181 *                          @c true to support recognition type,
 182 *                          @c false not to support recognition type
 183 * @return @c 0 on success,
 184 *         otherwise a negative error value
 185 * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 186 * @retval #GESTURE_ENGINE_ERROR_INVALID_PARAMETER Invalid parameter
 187 *
 188 */
 189 typedef int (*gesture_engine_is_support_gesture_type_cb)(const hand_gesture_type_e type, bool* is_supported);
 190
 191
 192 /**
 193 * @brief Called when the engine service user gets the result time information(stamp).
 194 * @since_tizen 6.0
 195 * @remarks This callback function is mandatory and must be registered using gesture_engine_main().
 196 *          In this function, the engine service user's callback function 'gesture_engine_result_time_cb()' is invoked repeatedly for sending the time information to the engine service user, and @a user_data must be transferred to 'gesture_engine_result_time_cb()'.
 197 *          If 'gesture_engine_result_time_cb()' returns @c false, it should be stopped to call 'gesture_engine_result_time_cb()'.
 198 *          @a time_info is transferred from gesture_engine_send_result(). The type of @a time_info is up to the GESTURE engine developer.
 199 * @param[in] time_info The time information
 200 * @param[in] callback The callback function
 201 * @param[in] user_data The user data which must be passed to the callback function 'gesture_engine_result_time_cb()'
 202 * @return @c 0 on success,
 203 *         otherwise a negative error value
 204 * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 205 * @retval #GESTURE_ENGINE_ERROR_INVALID_PARAMETER Invalid parameter
 206 * @pre gesture_engine_send_result() will invoke this function.
 207 * @post This function invokes gesture_engine_result_time_cb() repeatedly for getting result time information.
 208 * @see gesture_engine_result_time_cb()
 209 */
 210 typedef int (*gesture_engine_foreach_result_time_cb)(void* time_info, gesture_engine_result_time_cb callback, void* user_data);
 211
 212
 213 /**
 214 * @brief Called when the engine service user starts to detecting gesture motion
 215 * @since_tizen 6.0
 216 * @remarks This callback function is mandatory and must be registered using gesture_engine_main().
 217 *          In this callback function, GESTURE engine must transfer the recognition result and @a user_data to the engine service user using gesture_engine_send_result().
 218 * @param[in] gesture_type The gesture type. (e.g. #GESTURE_WRIST_UP)
 219 * @param[in] hand_type Hand type using for gesture (right or left)
 220 * @param[in] work_mode Determining whether to move the hand in one direction or back
 221 * @param[in] option     Detection option
 222 * @param[in] sensitivity Set sensitivity for recognizing gesture
 223 * @param[in] callback The result data to be passed to the callback function
 224 * @param[in] user_data The user data to be passed to the callback function
 225 * @return @c 0 on success,
 226 *         otherwise a negative error value
 227 * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 228 * @retval #GESTURE_ENGINE_ERROR_INVALID_PARAMETER Invalid parameter
 229 * @retval #GESTURE_ENGINE_ERROR_OPERATION_FAILED Operation failure
 230 * @pre The engine is not in recognition processing.
 231 * @see gesture_engine_stop_cb()
 232 */
 233 typedef int (*gesture_engine_start_cb)(const hand_gesture_type_e gesture_type, hand_gesture_handtype_e hand_type, hand_gesture_workmode_e work_mode, hand_gesture_option_e option, int sensitivity, gesture_engine_recognition_cb callback, void *user_data);
 234
 235
 236 /**
 237 * @brief Called when the engine service user stops to detecting gesture motion.
 238 * @details This callback function is called by the engine service user to stop detecting and to get the recognition result.
 239 * @since_tizen 6.0
 240 * @remarks This callback function is mandatory and must be registered using gesture_engine_main().
 241 * @return @c 0 on success,
 242 *         otherwise a negative error value
 243 * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 244 * @retval #GESTURE_ENGINE_ERROR_OPERATION_FAILED Operation failure
 245 * @pre gesture_engine_start_cb() should succeed.
 246 * @post After processing of the engine, gesture_engine_send_result() must be called.
 247 * @see gesture_engine_start_cb()
 248 * @see gesture_engine_send_result()
 249 */
 250 typedef int (*gesture_engine_stop_cb)(void);
 251
 252
 253 /**
 254 * @brief Called when the engine service user requests the basic information of GESTURE engine.
 255 * @since_tizen 6.0
 256 * @remarks This callback function is mandatory and must be registered using gesture_engine_main().
 257 *          The allocated @a engine_app_id, @a engine_name, and @a engine_setting will be released internally.
 258 * @param[out] engine_app_id The app id of engine
 259 * @param[out] engine_name The name of engine
 260 * @return @c 0 on success,
 261 *         otherwise a negative error code on failure
 262 * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 263 * @retval #GESTURE_ENGINE_ERROR_INVALID_PARAMETER Invalid parameter
 264 * @retval #GESTURE_ENGINE_ERROR_OPERATION_FAILED Operation failure
 265 */
 266 typedef int (*gesture_engine_get_info_cb)(char** engine_app_id, char** engine_name);
 267
 268
 269 /**
 270 * @brief Called when GESTURE engine receives the private data from the engine service user.
 271 * @details This callback function is called when the engine service user sends the private data to GESTURE engine.
 272 * @since_tizen 6.0
 273 * @remarks This callback function is optional and is registered using gesture_engine_set_private_data_set_cb().
 274 * @param[in] key The key field of private data
 275 * @param[in] data The data field of private data
 276 * @return @c 0 on success,
 277 *         otherwise a negative error value
 278 * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 279 * @retval #GESTURE_ENGINE_ERROR_INVALID_PARAMETER Invalid parameter
 280 * @retval #GESTURE_ENGINE_ERROR_OPERATION_FAILED Operation failure
 281 * @see gesture_engine_private_data_requested_cb()
 282 * @see gesture_engine_set_private_data_set_cb()
 283 */
 284 typedef int (*gesture_engine_private_data_set_cb)(const char* key, const char* data);
 285
 286
 287 /**
 288 * @brief Called when GESTURE engine provides the engine service user with the private data.
 289 * @details This callback function is called when the engine service user gets the private data from GESTURE engine.
 290 * @since_tizen 6.0
 291 * @remarks This callback function is optional and is registered using gesture_engine_set_private_data_requested_cb().
 292 * @param[out] key The key field of private data
 293 * @param[out] data The data field of private data
 294 * @return @c 0 on success,
 295 *         otherwise a negative error value
 296 * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 297 * @retval #GESTURE_ENGINE_ERROR_INVALID_PARAMETER Invalid parameter
 298 * @retval #GESTURE_ENGINE_ERROR_OPERATION_FAILED Operation failure
 299 * @see gesture_engine_private_data_set_cb()
 300 * @see gesture_engine_set_private_data_requested_cb()
 301 */
 302 typedef int (*gesture_engine_private_data_requested_cb)(const char* key, char** data);
 303
 304 /**
 305 * @brief A structure for the GESTURE engine functions.
 306 * @details This structure contains essential callback functions for operating GESTURE engine.
 307 * @since_tizen 6.0
 308 * @remarks These functions are mandatory for operating GESTURE engine. Therefore, all functions MUST be implemented.
 309 */
 310 typedef struct {
 311         int version; /**< The version of the structure 'gesture_engine_request_callback_s' */
 312         gesture_engine_get_info_cb                      get_info; /**< Called when the engine service user requests the basic information of GESTURE engine */
 313
 314         gesture_engine_initialize_cb                    initialize; /**< Called when the engine service user initializes GESTURE engine */
 315         gesture_engine_deinitialize_cb                  deinitialize; /**< Called when the engine service user deinitializes GESTURE engine */
 316
 317         gesture_engine_foreach_supported_type_cb        foreach_types; /**< Called when the engine service user gets the whole supported gesture types */
 318         gesture_engine_is_support_gesture_type_cb       is_support_gesture_type; /**< Called when the engine service user checks whether GESTURE engine supports the corresponding recognition type */
 319         gesture_engine_foreach_result_time_cb           foreach_result_time; /**< Called when the engine service user gets the result time information(stamp) */
 320
 321         gesture_engine_start_cb                         start; /**< Called when the engine service user starts to detect gesture motion */
 322         gesture_engine_stop_cb                          stop; /**< Called when the engine service user stops to detect gesture motion */
 323
 324 } gesture_engine_request_callback_s;
 325
 326
 327 /**
 328 * @brief Main function for GESTURE engine.
 329 * @details This function is the main function for operating GESTURE engine.
 330 * @since_tizen 6.0
 331 * @privlevel public
 332 * @remarks The service_app_main() should be used for working the engine after this function.
 333 * @param[in] argc The argument count(original)
 334 * @param[in] argv The argument(original)
 335 * @param[in] callback The structure of engine request callback function
 336 * @return This function returns @c zero on success,
 337 *         or negative with error code on failure
 338 * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 339 * @retval #GESTURE_ENGINE_ERROR_INVALID_PARAMETER Invalid parameter
 340 * @retval #GESTURE_ENGINE_ERROR_PERMISSION_DENIED       Permission denied
 341 * @retval #GESTURE_ENGINE_ERROR_NOT_SUPPORTED Not supported
 342 * @retval #GESTURE_ENGINE_ERROR_OPERATION_FAILED Operation failure
 343 * @see gesture_engine_request_callback_s
 344 * @code
 345 #include <gesture_engine.h>
 346
 347 // Required callback functions - MUST BE IMPLEMENTED
 348 static int gesture_engine_get_info_cb(char** engine_app_id, char** engine_name);
 349 static int gesture_engine_initialize_cb(void);
 350 static int gesture_engine_deinitialize_cb(void);
 351 static int gesture_engine_foreach_supported_type_cb(gesture_engine_supported_type_cb callback, void* user_data);
 352 static int gesture_engine_is_support_gesture_type_cb(const hand_gesture_type_e type, bool* is_supported);
 353 static int gesture_engine_foreach_result_time_cb(void* time_info, gesture_engine_result_time_cb callback, void* user_data);
 354 static int gesture_engine_start_cb(const hand_gesture_type_e gesture_type, hand_gesture_handtype_e hand_type, hand_gesture_workmode_e work_mode, hand_gesture_option_e option, int sensitivity, void *user_data);
 355 static int gesture_engine_stop_cb(void);
 356
 357 // Optional callback function
 358 static int gesture_engine_private_data_set_cb(const char* key, const char* data);
 359
 360 // Engine handle
 361 static gesture_engine_h engineHandle = NULL;
 362
 363 int main(int argc, char* argv[])
 364 {
 365         // 0. Connect with server and get engine handle
 366         gesture_engine_connect(&engineHandle);
 367
 368         // 1. Create a structure 'gesture_engine_request_callback_s'
 369         gesture_engine_request_callback_s engine_callback = { 0, };
 370
 371         engine_callback.size = sizeof(gesture_engine_request_callback_s);
 372         engine_callback.version = 1;
 373         engine_callback.get_info = gesture_engine_get_info_cb;
 374
 375         engine_callback.initialize = gesture_engine_initialize_cb;
 376         engine_callback.deinitialize = gesture_engine_deinitialize_cb;
 377
 378         engine_callback.foreach_types = gesture_engine_foreach_supported_type_cb;
 379         engine_callback.is_support_gesture_type = gesture_engine_is_support_gesture_type_cb;
 380
 381         engine_callback.foreach_result_time = gesture_engine_foreach_result_time_cb;
 382
 383         engine_callback.start = gesture_engine_start_cb;
 384         engine_callback.stop = gesture_engine_stop_cb;
 385
 386         // 2. Run 'gesture_engine_main()'
 387         if (0 != gesture_engine_main(argc, argv, engine_handle, &engine_callback)) {
 388                 return -1;
 389         }
 390
 391         // Optional
 392         gesture_engine_set_private_data_set_cb(gesture_engine_private_data_set_cb);
 393
 394         // 3. Set event callbacks for service app and Run 'service_app_main()'
 395         char ad[50] = { 0, };
 396
 397         service_app_lifecycle_callback_s event_callback;
 398         app_event_handler_h handlers[5] = { NULL, };
 399
 400         event_callback.create = service_app_create;
 401         event_callback.terminate = service_app_terminate;
 402         event_callback.app_control = service_app_control;
 403
 404         service_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY, service_app_low_battery, &ad);
 405         service_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY], APP_EVENT_LOW_MEMORY, service_app_low_memory, &ad);
 406         service_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED], APP_EVENT_LANGUAGE_CHANGED, service_app_lang_changed, &ad);
 407         service_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED], APP_EVENT_REGION_FORMAT_CHANGED, service_app_region_changed, &ad);
 408
 409         return service_app_main(argc, argv, &event_callback, ad);
 410 }
 411
 412 * @endcode
 413 */
 414 int gesture_engine_main(int argc, char** argv, gesture_engine_h engine_handle, gesture_engine_request_callback_s *callback);
 415
 416
 417 /**
 418  * @brief Connect gesture engine with Server and get handle.
 419  * @since_tizen @if WEARABLE 6.0 @endif
 420  * @remarks If the function succeeds, @a engine_handle must be released with gesture_engine_disconnect().
 421  * @param[out] engine_handle The gesture handle
 422  * @return 0 on success, otherwise a negative error value
 423  * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 424  * @retval #GESTURE_ENGINE_ERROR_NOT_SUPPORTED Not supported
 425  * @retval #GESTURE_ENGINE_ERROR_PERMISSION_DENIED Permission denied
 426  * @retval #GESTURE_ENGINE_ERROR_INVALID_PARAMETER Invalid parameter
 427  * @retval #GESTURE_ENGINE_ERROR_OUT_OF_MEMORY Out of memory
 428  * @retval #GESTURE_ENGINE_ERROR_OPERATION_FAILED Operation failed
 429  * @see gesture_engine_disconnect()
 430  */
 431 int gesture_engine_connect(gesture_engine_h *engine_handle);
 432
 433
 434 /**
 435  * @brief Disconnect with server and destroy gesture handle.
 436  * @since_tizen @if WEARABLE 6.0 @endif
 437  * @param[in] engine_handle The gesture handle
 438  * @return 0 on success, otherwise a negative error value
 439  * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 440  * @retval #GESTURE_ENGINE_ERROR_NOT_SUPPORTED Not supported
 441  * @retval #GESTURE_ENGINE_ERROR_INVALID_PARAMETER Invalid parameter
 442  * @retval #GESTURE_ENGINE_ERROR_OPERATION_FAILED Operation failed
 443  * @see gesture_engine_connect()
 444  */
 445 int gesture_engine_disconnect(gesture_engine_h engine_handle);
 446
 447
 448 /**
 449 * @brief Sends the recognition result to the engine service user.
 450 * @since_tizen 6.0
 451 * @remarks This API is used in gesture_engine_stop_cb(), when GESTURE engine sends the recognition result to the engine service user.
 452 *          This function is called in the following situations; 1) after gesture_engine_stop_cb() is called, 2) the end point of motion is detected from gesture, or 3) partial result is occurred.
 453 *          The recognition result and @a user_data must be transferred to the engine service user through this function.
 454 *          Also, @a time_info must be transferred to gesture_engine_foreach_result_time_cb(). The type of @a time_info is up to the GESTURE engine developer.
 455 * @param[in] engine_handle The gesture handle
 456 * @param[in] event The result event
 457 * @param[in] gesture_type The gesture type (e.g. #GESTURE_WRIST_UP, #GESTURE_LEFT_HAND_MOVE)
 458 * @param[in] result The gesture_data_s (gesture_type, event, detected_Count)
 459 * @param[in] time_info The time information
 460 * @param[in] user_data The user data passed from gesture_engine_start_cb()
 461 * @return @c 0 on success,
 462 *         otherwise a negative error value
 463 * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 464 * @retval #GESTURE_ENGINE_ERROR_INVALID_PARAMETER Invalid parameter
 465 * @retval #GESTURE_ENGINE_ERROR_PERMISSION_DENIED Permission denied
 466 * @retval #GESTURE_ENGINE_ERROR_NOT_SUPPORTED Not supported
 467 * @retval #GESTURE_ENGINE_ERROR_OPERATION_FAILED Operation failure
 468 * @pre The gesture_engine_main() function should be invoked before this function is called.
 469 *      gesture_engine_stop_cb() will invoke this function.
 470 * @post This function invokes gesture_engine_foreach_result_time_cb().
 471 * @see gesture_engine_start_cb()
 472 * @see gesture_engine_stop_cb()
 473 * @see gesture_engine_foreach_result_time_cb()
 474 */
 475 int gesture_engine_send_result(gesture_engine_h engine_handle, gesture_engine_result_event_e event, hand_gesture_type_e gesture_type, hand_gesture_data_h result,
 476                                 void* time_info, void* user_data);
 477
 478
 479 /**
 480 * @brief Sends the error to the engine service user.
 481 * @details The following error codes can be delivered.
 482 *          #GESTURE_ENGINE_ERROR_NONE,
 483 *          #GESTURE_ENGINE_ERROR_IO_ERROR,
 484 *          #GESTURE_ENGINE_ERROR_INVALID_PARAMETER,
 485 *          #GESTURE_ENGINE_ERROR_PERMISSION_DENIED,
 486 *          #GESTURE_ENGINE_ERROR_OUT_OF_MEMORY,
 487 *          #GESTURE_ENGINE_ERROR_SERVICE_NOT_READY,
 488 *          #GESTURE_ENGINE_ERROR_OPERATION_FAILED,
 489 *          #GESTURE_ENGINE_ERROR_NOT_SUPPORTED.
 490 * @since_tizen 6.0
 491 * @param[in] engine_handle The gesture handle
 492 * @param[in] error The error reason
 493 * @param[in] msg The error message
 494 * @return @c 0 on success,
 495 *         otherwise a negative error value
 496 * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 497 * @retval #GESTURE_ENGINE_ERROR_INVALID_PARAMETER Invalid parameter
 498 * @retval #GESTURE_ENGINE_ERROR_PERMISSION_DENIED Permission denied
 499 * @retval #GESTURE_ENGINE_ERROR_NOT_SUPPORTED Not supported
 500 * @retval #GESTURE_ENGINE_ERROR_OPERATION_FAILED Operation failure
 501 * @pre The gesture_engine_main() function should be invoked before this function is called.
 502 */
 503 int gesture_engine_send_error(gesture_engine_h engine_handle, gesture_engine_error_e error, const char* msg);
 504
 505
 506 /**
 507 * @brief Sends the gesture status to the engine service user when GESTURE engine notifies the change of the motion status.
 508 * @since_tizen 6.0
 509 * @remarks This API is invoked when GESTURE engine wants to notify the change of the motion status anytime.
 510 *          NOTE that this API can be invoked for recognizing the motion.
 511 * @param[in] engine_handle The gesture handle
 512 * @param[in] status The status of motion (e.g. GESTURE_ENGINE_MOTION_STATUS_START_POINT_DETECTED or GESTURE_ENGINE_MOTION_STATUS_END_POINT_DETECTED)
 513 * @param[in] user_data The user data passed from the start function.
 514 * @return @c 0 on success,
 515 *         otherwise a negative error value
 516 * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 517 * @retval #GESTURE_ENGINE_ERROR_INVALID_PARAMETER Invalid parameter
 518 * @retval #GESTURE_ENGINE_ERROR_PERMISSION_DENIED Permission denied
 519 * @retval #GESTURE_ENGINE_ERROR_NOT_SUPPORTED Not supported
 520 * @retval #GESTURE_ENGINE_ERROR_OPERATION_FAILED Operation failure
 521 * @pre The gesture_engine_main() function should be invoked before this function is called.
 522 *      gesture_engine_start_cb() will invoke this function.
 523 * @see gesture_engine_start_cb()
 524 */
 525 int gesture_engine_send_motion_status(gesture_engine_h engine_handle, gesture_engine_motion_status_e status, void* user_data);
 526
 527
 528 /**
 529 * @brief Sets a callback function for setting the private data.
 530 * @since_tizen 6.0
 531 * @privlevel public
 532 * @remarks The gesture_engine_private_data_set_cb() function is called when the engine service user sends the private data.
 533 * @param[in] engine_handle The gesture handle
 534 * @param[in] callback_func The gesture_engine_private_data_set event callback function
 535 * @return @c 0 on success,
 536 *         otherwise a negative error value
 537 * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 538 * @retval #GESTURE_ENGINE_ERROR_INVALID_PARAMETER Invalid parameter
 539 * @retval #GESTURE_ENGINE_ERROR_PERMISSION_DENIED Permission denied
 540 * @retval #GESTURE_ENGINE_ERROR_NOT_SUPPORTED Not supported
 541 * @retval #GESTURE_ENGINE_ERROR_OPERATION_FAILED Operation failure
 542 * @pre The gesture_engine_main() function should be invoked before this function is called.
 543 * @see gesture_engine_private_data_set_cb()
 544 */
 545 int gesture_engine_set_private_data_set_cb(gesture_engine_h engine_handle, gesture_engine_private_data_set_cb callback_func);
 546
 547
 548 /**
 549 * @brief Sets a callback function for requesting the private data.
 550 * @since_tizen 6.0
 551 * @privlevel public
 552 * @remarks The gesture_engine_private_data_requested_cb() function is called when the engine service user gets the private data from GESTURE engine.
 553 * @param[in] engine_handle The gesture handle
 554 * @param[in] callback_func The gesture_engine_private_data_requested event callback function
 555 * @return @c 0 on success,
 556 *         otherwise a negative error value
 557 * @retval #GESTURE_ENGINE_ERROR_NONE Successful
 558 * @retval #GESTURE_ENGINE_ERROR_INVALID_PARAMETER Invalid parameter
 559 * @retval #GESTURE_ENGINE_ERROR_PERMISSION_DENIED Permission denied
 560 * @retval #GESTURE_ENGINE_ERROR_NOT_SUPPORTED Not supported
 561 * @retval #GESTURE_ENGINE_ERROR_OPERATION_FAILED Operation failure
 562 * @pre The gesture_engine_main() function should be invoked before this function is called.
 563 * @see gesture_engine_private_data_requested_cb()
 564 */
 565 int gesture_engine_set_private_data_requested_cb(gesture_engine_h engine_handle, gesture_engine_private_data_requested_cb callback_func);
 566
 567 int gesture_engine_send_engine_get_info(gesture_engine_h engine_handle, char* engine_app_id, char* engine_name);
 568
 569 #ifdef __cplusplus
 570 }
 571 #endif
 572
 573 #endif /* __TIZEN_UIX_GESTURE_ENGINE_H__ */