include/vce.h

   1 /*
   2 * Copyright (c) 2011-2017 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
  18 #ifndef __VCE_H__
  19 #define __VCE_H__
  20
  21 #include <tizen.h>
  22
  23 /**
  24 * @addtogroup CAPI_UIX_VCE_MODULE
  25 * @{
  26 */
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /**
  33 * @brief Enumerations of error codes.
  34 * @since_tizen 5.0
  35 */
  36 typedef enum {
  37         VCE_ERROR_NONE                  = TIZEN_ERROR_NONE,             /**< Successful */
  38         VCE_ERROR_OUT_OF_MEMORY         = TIZEN_ERROR_OUT_OF_MEMORY,    /**< Out of Memory */
  39         VCE_ERROR_IO_ERROR              = TIZEN_ERROR_IO_ERROR,         /**< I/O error */
  40         VCE_ERROR_INVALID_PARAMETER     = TIZEN_ERROR_INVALID_PARAMETER,/**< Invalid parameter */
  41         VCE_ERROR_OUT_OF_NETWORK        = TIZEN_ERROR_NETWORK_DOWN,     /**< Out of network */
  42     VCE_ERROR_RECORDER_BUSY     = TIZEN_ERROR_RESOURCE_BUSY,/**< Busy resource */
  43         VCE_ERROR_INVALID_STATE         = TIZEN_ERROR_VOICE_CONTROL | 0x011, /**< Invalid state */
  44         VCE_ERROR_INVALID_LANGUAGE      = TIZEN_ERROR_VOICE_CONTROL | 0x012, /**< Invalid language */
  45         VCE_ERROR_OPERATION_FAILED      = TIZEN_ERROR_VOICE_CONTROL | 0x014, /**< Operation failed */
  46     VCE_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,        /**< Permission denied */
  47         VCE_ERROR_NOT_SUPPORTED_FEATURE = TIZEN_ERROR_VOICE_CONTROL | 0x022 /**< Not supported feature of current engine */
  48 } vce_error_e;
  49
  50 /**
  51 * @brief Enumerations of audio type.
  52 * @since_tizen 5.0
  53 */
  54 typedef enum {
  55         VCE_AUDIO_TYPE_PCM_S16_LE = 0,  /**< Signed 16bit audio type, Little endian */
  56         VCE_AUDIO_TYPE_PCM_U8           /**< Unsigned 8bit audio type */
  57 } vce_audio_type_e;
  58
  59 /**
  60 * @brief Enumerations of callback event.
  61 * @since_tizen 5.0
  62 */
  63 typedef enum {
  64         VCE_RESULT_EVENT_SUCCESS = 0,           /**< Event when the recognition full result is ready  */
  65         VCE_RESULT_EVENT_REJECTED,              /**< Event when the recognition result is rejected */
  66         VCE_RESULT_EVENT_ERROR                  /**< Event when the recognition has failed */
  67 } vce_result_event_e;
  68
  69 /**
  70 * @brief Enumerations of command type.
  71 * @since_tizen 5.0
  72 */
  73 typedef enum {
  74         VCE_COMMAND_FORMAT_FIXED = 0,                   /**< Fixed command */
  75         VCE_COMMAND_FORMAT_FIXED_AND_VFIXED,    /**< Fixed command + variable-fixed command */
  76         VCE_COMMAND_FORMAT_VFIXED_AND_FIXED,    /**< variable-fixed command + Fixed command */
  77         VCE_COMMAND_FORMAT_FIXED_AND_NONFIXED,  /**< Fixed command + Non-fixed command */
  78         VCE_COMMAND_FORMAT_NONFIXED_AND_FIXED,  /**< Non-fixed command + Fixed command */
  79     VCE_COMMAND_FORMAT_ACTION,              /**< Action command */
  80     VCE_COMMAND_FORMAT_PARTIAL              /**< Partial matched command */
  81 } vce_command_format_e;
  82
  83 /**
  84 * @brief Enumerations of speech detect.
  85 * @since_tizen 5.0
  86 */
  87 typedef enum {
  88     VCE_SPEECH_DETECT_NONE = 0, /**< No event */
  89     VCE_SPEECH_DETECT_BEGIN,    /**< Begin of speech detected */
  90     VCE_SPEECH_DETECT_END,              /**< End of speech detected */
  91 } vce_speech_detect_e;
  92
  93 /**
  94 * @brief Enumerations of ASR result events.
  95 * @since_tizen 5.0
  96 */
  97 typedef enum {
  98     VCE_ASR_RESULT_EVENT_FINAL_RESULT = 0, /**< Event when the ASR result is last data or ASR result is only one result */
  99     VCE_ASR_RESULT_EVENT_PARTIAL_RESULT,   /**< Event when the ASR result exist, not first and not last */
 100     VCE_ASR_RESULT_EVENT_ERROR             /**< Event when the ASR result is failed */
 101 } vce_asr_result_event_e;
 102
 103 /**
 104 * @brief A structure of handle for VC command.
 105 * @since_tizen 5.0
 106 */
 107 typedef int vce_cmd_h;
 108
 109 /**
 110 * @brief Definition for foreground command type.
 111 * @since_tizen 5.0
 112 */
 113 #define VCE_COMMAND_TYPE_FOREGROUND     1
 114
 115 /**
 116 * @brief Definition for background command type.
 117 * @since_tizen 5.0
 118 */
 119 #define VCE_COMMAND_TYPE_BACKGROUND     2
 120
 121 /**
 122 * @brief Definition for widget command type.
 123 * @since_tizen 5.0
 124 */
 125 #define VCE_COMMAND_TYPE_WIDGET         3
 126
 127 /**
 128 * @brief Definition for system command type.
 129 * @since_tizen 5.0
 130 */
 131 #define VCE_COMMAND_TYPE_SYSTEM         4
 132
 133 /**
 134 * @brief Definition for system background command type.
 135 * @since_tizen 5.0
 136 */
 137 #define VCE_COMMAND_TYPE_SYSTEM_BACKGROUND      5
 138
 139 /**
 140 * @brief Definitions for exclusive command type.
 141 * @since_tizen 5.0
 142 */
 143 #define VCE_COMMAND_TYPE_EXCLUSIVE      6
 144
 145 /**
 146 * @brief Definition of bluetooth audio id.
 147 * @since_tizen 5.0
 148 */
 149 #define VCE_AUDIO_ID_BLUETOOTH          "VC_AUDIO_ID_BLUETOOTH"         /**< Bluetooth audio id */
 150
 151 /**
 152 * @brief Definition of Wi-Fi audio id.
 153 * @since_tizen 5.0
 154 */
 155 #define VCE_AUDIO_ID_WIFI               "VC_AUDIO_ID_WIFI"              /**< Wi-Fi audio id */
 156
 157 /**
 158 * @brief Definition for none message.
 159 * @since_tizen 5.0
 160 */
 161 #define VC_RESULT_MESSAGE_NONE                  "vc.result.message.none"
 162
 163 /**
 164 * @brief Definition for failed recognition because the speech is too loud to listen.
 165 * @since_tizen 5.0
 166 */
 167 #define VC_RESULT_MESSAGE_ERROR_TOO_LOUD        "vc.result.message.error.too.loud"
 168
 169 /**
 170 * @brief Called when VC engine informs the engine service user about whole supported languages.
 171 * @details This callback function is implemented by the engine service user. Therefore, the engine developer does NOT have to implement this callback function.
 172 * @since_tizen 5.0
 173 * @remarks This callback function is called by vce_foreach_supported_languages_cb() to retrieve the whole supported language list.
 174 *               @a user_data must be transferred from vce_foreach_supported_languages_cb().
 175 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code
 176 *               followed by ISO 639-1 for the two-letter language code \n
 177 *               For example, "ko_KR" for Korean, "en_US" for American English
 178 * @param[in] user_data The user data passed from the foreach function
 179 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
 180 * @pre vce_foreach_supported_languages() will invoke this callback.
 181 * @see vce_foreach_supported_languages()
 182 */
 183 typedef bool (*vce_supported_language_cb)(const char* language, void* user_data);
 184
 185 /**
 186 * @brief Called when the engine service user initializes VC engine.
 187 * @since_tizen 5.0
 188 * @remarks This callback function is mandatory and must be registered using vce_main().
 189 * @return 0 on success, otherwise a negative error value
 190 * @retval #VCE_ERROR_NONE Successful
 191 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 192 * @retval #VCE_ERROR_INVALID_STATE Already initialized
 193 * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
 194 * @see vce_deinitialize_cb()
 195 */
 196 typedef int (*vce_initialize_cb)(void);
 197
 198 /**
 199 * @brief Called when the engine service user deinitializes VC engine.
 200 * @since_tizen 5.0
 201 * @remarks This callback function is mandatory and must be registered using vce_main().
 202 * @return 0 on success, otherwise a negative error value
 203 * @retval #VCE_ERROR_NONE Successful
 204 * @retval #VCE_ERROR_INVALID_STATE Not initialized
 205 * @see vce_initialize_cb()
 206 */
 207 typedef int (*vce_deinitialize_cb)(void);
 208
 209 /**
 210 * @brief Called when the engine service user requests the recording format of VC engine.
 211 * @since_tizen 5.0
 212 * @remarks This callback function is mandatory and must be registered using vce_main().
 213 * @param[out] audio_id The audio device id. (e.g. #VCE_AUDIO_ID_BLUETOOTH or VCE_AUDIO_ID_WIFI)
 214 * @param[out] types The format used by the recorder.
 215 * @param[out] rate The sample rate used by the recorder.
 216 * @param[out] channels The number of channels used by the recorder.
 217 * @return 0 on success, otherwise a negative error value
 218 * @retval #VCE_ERROR_NONE Successful
 219 * @retval #VCE_ERROR_INVALID_PARAMETER Not initialized
 220 */
 221 typedef int (*vce_get_recording_format_cb)(const char* audio_id, const vce_audio_type_e* types, const int* rate, const int* channels);
 222
 223 /**
 224 * @brief Called when the engine service user retrieves all supported languages of VC engine.
 225 * @since_tizen 5.0
 226 * @remarks This callback function is mandatory and must be registered using vce_main().
 227 * @param[in] callback a callback function
 228 * @param[in] user_data The user data to be passed to the callback function
 229 * @return 0 on success, otherwise a negative error value
 230 * @retval #VCE_ERROR_NONE Successful
 231 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 232 * @retval #VCE_ERROR_INVALID_STATE Not initialized
 233 * @post This function invokes vce_supported_language_cb() repeatedly for getting supported languages.
 234 *
 235 * @see vce_supported_language_cb()
 236 */
 237 typedef int (*vce_foreach_supported_languages_cb)(vce_supported_language_cb callback, void* user_data);
 238
 239 /**
 240 * @brief Called when the engine service user checks whether a language is supported or not.
 241 * @since_tizen 5.0
 242 * @remarks This callback function is mandatory and must be registered using vce_main().
 243 * @param[out] language A language
 244 * @return @c true = supported, \n @c false = not supported.
 245 */
 246 typedef bool (*vce_is_language_supported_cb)(const char* language);
 247
 248 /**
 249 * @brief Called when the engine service user sets language.
 250 * @since_tizen 5.0
 251 * @param[in] language A language.
 252 * @return 0 on success, otherwise a negative error value
 253 * @retval #VCE_ERROR_NONE Successful
 254 * @retval #VCE_ERROR_INVALID_LANGUAGE Invalid language
 255 * @retval #VCE_ERROR_INVALID_STATE Not initialized
 256 */
 257 typedef int (*vce_set_language_cb)(const char* language);
 258
 259 /**
 260 * @brief Called when the engine service user sets command list before recognition.
 261 * @since_tizen 5.0
 262 * @remarks This function should set commands via vcd_foreach_command().
 263 * @param[in] vc_command command handle.
 264 * @return 0 on success, otherwise a negative error value
 265 * @retval #VCE_ERROR_NONE Successful
 266 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 267 * @retval #VCE_ERROR_INVALID_STATE Invalid state
 268 * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
 269 * @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported command type
 270 * @post vce_start() is called after this function is successful.
 271 * @see vce_start()
 272 * @see vcd_foreach_command()
 273 * @see vce_unset_commands()
 274 * @see vce_get_command_count()
 275 */
 276 typedef int (*vce_set_commands_cb)(vce_cmd_h vc_command);
 277
 278 /**
 279 * @brief Called when the engine service user unsets command list for reset.
 280 * @since_tizen 5.0
 281 * @return 0 on success, otherwise a negative error value
 282 * @retval #VCE_ERROR_NONE Successful
 283 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 284 * @retval #VCE_ERROR_INVALID_STATE Invalid state
 285 * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
 286 * @see vce_set_commands_cb()
 287 */
 288 typedef int (*vce_unset_commands_cb)(void);
 289
 290 /**
 291 * @brief Called when the engine service user starts recognition.
 292 * @since_tizen 5.0
 293 * @remarks This callback function is mandatory and must be registered using vce_main().
 294 * @param[in] stop_by_silence Silence detection option.
 295 *                   @c true to detect the silence,
 296 *                   @c false not to detect the silence
 297 * @return 0 on success, otherwise a negative error value
 298 * @retval #VCE_ERROR_NONE Successful
 299 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 300 * @retval #VCE_ERROR_INVALID_STATE Invalid state
 301 * @retval #VCE_ERROR_INVALID_LANGUAGE Invalid language
 302 * @retval #VCE_ERROR_OUT_OF_NETWORK Out of network
 303 * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
 304 * @pre vcd_foreach_command() is successful.
 305 * @see vce_set_recording_data_cb()
 306 * @see vce_stop()
 307 * @see vce_cancel()
 308 */
 309 typedef int (*vce_start_cb)(bool stop_by_silence);
 310
 311 /**
 312 * @brief Called when the engine service user sets recording data for speech recognition from recorder.
 313 * @since_tizen 5.0
 314 * @remarks This function should be returned immediately after recording data copy.
 315 * @param[out] data A recording data
 316 * @param[out] length A length of recording data
 317 * @param[in] speech_detected The status of speech (e.g. VCE_SPEECH_DETECT_BEGIN or VCE_SPEECH_DETECT_END)
 318 * @return 0 on success, otherwise a negative error value
 319 * @retval #VCE_ERROR_NONE Successful
 320 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 321 * @retval #VCE_ERROR_INVALID_STATE Invalid state
 322 * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
 323 * @pre vce_start() is successful.
 324 * @see vce_start()
 325 * @see vce_cancel()
 326 * @see vce_stop()
 327 */
 328 typedef int(*vce_set_recording_data_cb)(const void* data, unsigned int length, vce_speech_detect_e* speech_detected);
 329
 330 /**
 331 * @brief Called when the engine service user stops to get the result of recognition.
 332 * @since_tizen 5.0
 333 * @return 0 on success, otherwise a negative error value
 334 * @retval #VCE_ERROR_NONE Successful
 335 * @retval #VCE_ERROR_INVALID_STATE Invalid state
 336 * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
 337 * @retval #VCE_ERROR_OUT_OF_NETWORK Out of network
 338 * @pre vce_set_recording_data() is successful.
 339 * @see vce_start()
 340 * @see vce_set_recording_data()
 341 * @see vce_result_cb()
 342 * @see vce_cancel()
 343 */
 344 typedef int (*vce_stop_cb)(void);
 345
 346 /**
 347 * @brief Called when the engine service user cancels the recognition process.
 348 * @since_tizen 5.0
 349 * @return 0 on success, otherwise a negative error value.
 350 * @retval #VCE_ERROR_NONE Successful.
 351 * @retval #VCE_ERROR_INVALID_STATE Invalid state.
 352 * @pre vce_start() is successful.
 353 * @see vce_start()
 354 * @see vce_stop()
 355 */
 356 typedef int (*vce_cancel_cb)(void);
 357
 358 /**
 359 * @brief Called when the engine service user sets audio recording type.
 360 * @since_tizen 5.0
 361 * @param[in] audio Available agent or device type
 362 * @return 0 on success, otherwise a negative error value.
 363 * @retval #VCE_ERROR_NONE Successful.
 364 */
 365 typedef int (*vce_set_audio_type_cb)(const char* audio);
 366
 367 /**
 368 * @brief Called when the engine service user sets domain (Agent or device type).
 369 * @since_tizen 5.0
 370 * @param[in] domain Available agent or device type
 371 * @return 0 on success, otherwise a negative error value.
 372 * @retval #VCE_ERROR_NONE Successful.
 373 */
 374 typedef int (*vce_set_domain_cb)(const char* domain);
 375
 376 /**
 377 * @brief Called when the engine service user requests essential value from nlu result.
 378 * @since_tizen 5.0
 379 * @remarks This function is available inside vce_nlu_result_cb()
 380 * @param[in] key NLU base info key
 381 * @param[out] value NLU base info value
 382 * @return 0 on success, otherwise a negative error value.
 383 */
 384 typedef int (*vce_nlu_base_info_requested_cb)(const char* key, char** value);
 385
 386 /**
 387 * @brief Called when the engine service user sets private data between app and engine.
 388 * @since_tizen 5.0
 389 * @param[in] key Private key
 390 * @param[in] data Private data
 391 * @return 0 on success, otherwise a negative error value.
 392 */
 393 typedef int (*vce_private_data_set_cb)(const char* key, const char* data);
 394
 395 /**
 396 * @brief Called when the engine service user requests private data between app and engine.
 397 * @since_tizen 5.0
 398 * @param[in] key Private key
 399 * @param[out] data Private data
 400 * @return 0 on success, otherwise a negative error value.
 401 */
 402 typedef int (*vce_private_data_requested_cb)(const char* key, char** data);
 403
 404 /**
 405 * @brief Called when the engine service user requests process text.
 406 * @since_tizen 5.0
 407 * @param[in] text Requested text
 408 * @return 0 on success, otherwise a negative error value.
 409 */
 410 typedef int (*vce_process_text_cb)(const char* text);
 411
 412 /**
 413 * @brief Called when the engine service user requests list event.
 414 * @since_tizen 5.0
 415 * @param[in] event Requested list event
 416 * @return 0 on success, otherwise a negative error value.
 417 */
 418 typedef int (*vce_process_list_event_cb)(const char* event);
 419
 420 /**
 421 * @brief Called when the engine service user requests haptic event.
 422 * @since_tizen 5.0
 423 * @param[in] event Requested haptic event
 424 * @return 0 on success, otherwise a negative error value.
 425 */
 426 typedef int (*vce_process_haptic_event_cb)(const char* event);
 427
 428 /**
 429 * @brief Called when the engine service user requests the base information of VC engine.
 430 * @since_tizen 5.0
 431 * @remarks This callback function is mandatory and must be registered using vce_main().
 432 *          The allocated @a engine_uuid, @a engine_name, and @a engine_setting will be released internally.
 433 *          In order to upload the engine at Tizen Appstore, both a service app and a ui app are necessary.
 434 *          Therefore, @a engine_setting must be transferred to the engine service user.
 435 * @param[out] engine_uuid The engine id
 436 * @param[out] engine_name The engine name
 437 * @param[out] engine_setting The setting path name
 438 * @param[out] use_network @c true to need network @c false not to need network.
 439 * @return @c 0 on success,
 440 *         otherwise a negative error code on failure
 441 * @retval #VCE_ERROR_NONE Successful
 442 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 443 * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 444 */
 445 typedef int (*vce_get_info_cb)(char** engine_uuid, char** engine_name, char** engine_setting, bool* use_network);
 446
 447 /**
 448 * @brief Called to retrieve the commands.
 449 * @since_tizen 5.0
 450 * @param[in] id command id
 451 * @param[in] type command type
 452 * @param[in] format command format
 453 * @param[in] command command text
 454 * @param[in] param parameter text
 455 * @param[in] domain command domain
 456 * @param[in] user_data The user data passed from the foreach function
 457 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
 458 * @pre vce_get_foreach_command() will invoke this callback.
 459 * @see vce_get_foreach_command()
 460 */
 461 typedef bool (*vce_command_cb)(int id, int type, int format, const char* command, const char* param, int domain, void* user_data);
 462
 463
 464 /**
 465 * @brief A structure for the VC engine functions.
 466 * @details This structure contains essential callback functions for operating VC engine.
 467 * @since_tizen 5.0
 468 * @remarks These functions ar mandatory for operating VC engine. Therefore, all functions MUST be implemented.
 469 */
 470 typedef struct {
 471         int version;                                            /**< Version */
 472
 473         /* Get engine information */
 474         vce_get_info_cb         get_info;               /**< Called when the engine service user requests the basic information of VC engine */
 475         vce_get_recording_format_cb     get_recording_format;   /**< Get recording format */
 476         vce_foreach_supported_languages_cb foreach_langs;               /**< Foreach language list */
 477         vce_is_language_supported_cb    is_lang_supported;      /**< Check language */
 478
 479         vce_initialize_cb                       initialize;             /**< Initialize engine */
 480         vce_deinitialize_cb             deinitialize;           /**< Shutdown engine */
 481
 482         /* Set info */
 483         vce_set_language_cb             set_language;           /**< Set language */
 484         vce_set_commands_cb             set_commands;           /**< Request to set current commands */
 485         vce_unset_commands_cb           unset_commands;         /**< Request to unset current commands */
 486
 487         /* Control recognition */
 488         vce_start_cb                    start;                  /**< Start recognition */
 489         vce_set_recording_data_cb               set_recording;          /**< Set recording data */
 490         vce_stop_cb                     stop;                   /**< Stop recording for getting result */
 491         vce_cancel_cb                   cancel;                 /**< Cancel recording and processing */
 492
 493         vce_set_audio_type_cb           set_audio_type;         /**< Set audio type */
 494
 495         vce_set_domain_cb                       set_domain;             /**< Set domain */
 496         vce_process_text_cb             process_text;           /**< Request to process text */
 497         vce_process_list_event_cb               process_list_event;     /**< Request to process list event */
 498         vce_process_haptic_event_cb     process_haptic_event;   /**< Request to process haptic event */
 499 } vce_request_callback_s;
 500
 501 /**
 502 * @brief Main function for Voice Control (VC) engine.
 503 * @details This function is the main function for operating VC engine.
 504 * @since_tizen 5.0
 505 * @privlevel public
 506 * @privilege %http://tizen.org/privilege/recorder
 507 * @remarks The service_app_main() should be used for working the engine after this function.
 508 * @param[in] argc The argument count(original)
 509 * @param[in] argv The argument(original)
 510 * @param[in] callback The structure of engine request callback function
 511 * @return This function returns @c zero on success,
 512 *         or negative with error code on failure
 513 * @retval #VCE_ERROR_NONE Successful
 514 * @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
 515 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 516 * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
 517 * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
 518 * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
 519 * @pre The vce_get_engine_info() should be successful.
 520 * @post The daemon calls engine functions of vce_funcs_s.
 521 * @see vce_get_engine_info()
 522 * @see vce_unload_engine()
 523 * @see vce_request_callback_s
 524 * @code
 525 #include <vce.h>
 526
 527 // Required callback functions - MUST BE IMPLEMENTED
 528 static int vce_default_initialize();
 529 static int vce_default_deinitialize(void);
 530
 531 static int vce_default_get_info(char** engine_uuid, char** engine_name, char** engine_setting, bool* use_network);
 532 static int vce_default_get_recording_format(const char* audio_id, vce_audio_type_e* types, int* rate, int* channels);
 533 static int vce_default_foreach_langs(vce_supported_language_cb callback, void* user_data);
 534 static bool vce_default_is_lang_supported(const char* lang);
 535
 536 static int vce_default_set_language(const char* language);
 537 static int vce_default_set_commands(vce_cmd_h vc_command);
 538 static int vce_default_unset_commands();
 539
 540 static int vce_default_start(bool stop_by_silence);
 541 static int vce_default_set_recording(const void* data, unsigned int length, vce_speech_detect_e* silence_detected);
 542 static int vce_default_stop();
 543 static int vce_default_cancel(void);
 544
 545 static int vce_default_set_audio_type(const char* audio_type);
 546 static int vce_default_set_domain(const char* domain);
 547 static int vce_default_process_text(const char* text);
 548 static int vce_default_process_list_event(const char* event);
 549 static int vce_default_process_haptic_event(const char* event);
 550
 551 // Optional callback function
 552 static int vce_default_private_data_set_cb(const char* key, const char* data);
 553
 554 int main(int argc, char* argv[])
 555 {
 556         // 1. Create a structure 'vce_request_callback_s'
 557         vce_request_callback_s callback = {0,};
 558
 559         callback.version = 1;
 560
 561         callback.initialize     = vce_default_initialize;
 562         callback.deinitialize   = vce_default_deinitialize;
 563
 564         callback.get_info       = vce_default_get_info;
 565         callback.get_recording_format   = vce_default_get_recording_format;
 566         callback.foreach_langs  = vce_default_foreach_langs;
 567         callback.is_lang_supported      = vce_default_is_lang_supported;
 568
 569         callback.set_language   = vce_default_set_language;
 570         callback.set_commands   = vce_default_set_commands;
 571         callback.unset_commands = vce_default_unset_commands;
 572
 573         callback.start          = vce_default_start;
 574         callback.set_recording  = vce_default_set_recording;
 575         callback.stop           = vce_default_stop;
 576         callback.cancel         = vce_default_cancel;
 577
 578         callback.set_audio_type = vce_default_set_audio_type;
 579         callback.set_domain     = vce_default_set_domain;
 580         callback.process_text   = vce_default_process_text;
 581         callback.process_list_event     = vce_default_process_list_event;
 582         callback.process_haptic_event   = vce_default_process_haptic_event;
 583
 584     // 2. Run 'vce_main()'
 585         if (0 != vce_main(argc, argv, &callback)) {
 586                 SLOG(LOG_ERROR, TAG_VCE, "[ERROR] Fail to vce main");
 587                 return -1;
 588         }
 589
 590         // Optional
 591         vce_set_private_data_set_cb(vce_default_private_data_set_cb);
 592
 593     // 3. Set event callbacks for service app and Run 'service_app_main()'
 594         char ad[50] = {0,};
 595         service_app_lifecycle_callback_s event_callback;
 596         app_event_handler_h handlers[5] = {NULL, };
 597
 598         event_callback.create = service_app_create;
 599         event_callback.terminate = service_app_terminate;
 600         event_callback.app_control = service_app_control;
 601
 602         service_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY, service_app_low_battery, &ad);
 603         service_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY], APP_EVENT_LOW_MEMORY, service_app_low_memory, &ad);
 604         service_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED], APP_EVENT_LANGUAGE_CHANGED, service_app_lang_changed, &ad);
 605         service_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED], APP_EVENT_REGION_FORMAT_CHANGED, service_app_region_changed, &ad);
 606
 607         return service_app_main(argc, argv, &event_callback, ad);
 608 }
 609
 610 * @endcode
 611 */
 612 int vce_main(int argc, char** argv, vce_request_callback_s* callback);
 613
 614 /**
 615 * @brief Sends the results to the engine service user.
 616 * @since_tizen 5.0
 617 * @param[in] event A result event
 618 * @param[in] result_id Result ids
 619 * @param[in] count Result count
 620 * @param[in] all_result All result text
 621 * @param[in] non_fixed_result Non-fixed command result text
 622 * @param[in] nlu_result NLU result text
 623 * @param[in] msg Engine message (e.g. #VC_RESULT_MESSAGE_NONE, #VC_RESULT_MESSAGE_ERROR_TOO_LOUD)
 624 * @param[out] user_info A user info (e.g. If ASR result is consumed, the value is 0x01. If not, the value is 0x00.)
 625 * @param[in] user_data The user data passed from set callback function
 626 * @return @c 0 on success,
 627 *         otherwise a negative error value
 628 * @retval #VCE_ERROR_NONE Successful
 629 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 630 * @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
 631 * @retval #VCE_ERROR_INVALID_STATE Invalid state
 632 * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 633 * @pre The vce_main() function should be invoked before this function is called.
 634 *               vce_stop_cb() will invoke this callback.
 635 * @see vce_stop_cb()
 636 */
 637 int vce_send_result(vce_result_event_e event, int* result_id, int count, const char* all_result, const char* non_fixed_result, const char* nlu_result, const char* msg, int* user_info, void* user_data);
 638
 639 /**
 640 * @brief Sends the ASR result to the engine service user.
 641 * @since_tizen 5.0
 642 * @param[in] event A asr result event
 643 * @param[in] asr_result A asr result text
 644 * @param[in] user_data The user data passed from the start
 645 * @return @c 0 on success,
 646 *         otherwise a negative error value
 647 * @retval #VCE_ERROR_NONE Successful
 648 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 649 * @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
 650 * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 651 * @pre The vce_main() function should be invoked before this function is called.
 652 * @see vce_start_cb()
 653 */
 654 int vce_send_asr_result(vce_asr_result_event_e event, const char* asr_result, void* user_data);
 655
 656 /**
 657 * @brief Sends the nlg(natural language generation) result to the engine service user.
 658 * @since_tizen 5.0
 659 * @param[in] nlg_result A nlg result
 660 * @param[in] user_data The user data passed from the start
 661 * @return @c 0 on success,
 662 *         otherwise a negative error value
 663 * @retval #VCE_ERROR_NONE Successful
 664 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 665 * @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
 666 * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 667 * @pre The vce_main() function should be invoked before this function is called.
 668 * @see vce_start_cb()
 669 */
 670 int vce_send_nlg_result(const char* nlg_result, void* user_data);
 671
 672 /**
 673 * @brief Sends the error to the engine service user.
 674 * @details The following error codes can be delivered.
 675 *               #VCE_ERROR_NONE,
 676 *               #VCE_ERROR_OUT_OF_MEMORY,
 677 *               #VCE_ERROR_IO_ERROR,
 678 *               #VCE_ERROR_INVALID_PARAMETER,
 679 *               #VCE_ERROR_OUT_OF_NETWORK,
 680 *       #VCE_ERROR_RECORDER_BUSY,
 681 *               #VCE_ERROR_INVALID_STATE,
 682 *               #VCE_ERROR_INVALID_LANGUAGE,
 683 *               #VCE_ERROR_OPERATION_FAILED,
 684 *               #VCE_ERROR_PERMISSION_DENIED,
 685 *               #VCE_ERROR_NOT_SUPPORTED_FEATURE.
 686 * @since_tizen 5.0
 687 * @param[in] error Error type
 688 * @param[in] msg Error message
 689 * @param[in] user_data The user data passed from set callback function
 690 * @return @c 0 on success,
 691 *         otherwise a negative error value
 692 * @retval #VCE_ERROR_NONE Successful
 693 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 694 * @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
 695 * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 696 * @pre The vce_main() function should be invoked before this function is called.
 697 */
 698 int vce_send_error(vce_error_e error, const char* msg, void* user_data);
 699
 700 /**
 701 * @brief Sets a callback function for setting the private data to the engine service.
 702 * @since_tizen 5.0
 703 * @privlevel public
 704 * @privilege %http://tizen.org/privilege/recorder
 705 * @remarks The vce_private_data_set_cb() function is called when the engine service user sets the private data to the engine service.
 706 * @param[in] callback_func vce_private_data_set event callback function
 707 * @return @c 0 on success,
 708 *         otherwise a negative error value
 709 * @retval #VCE_ERROR_NONE Successful
 710 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 711 * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
 712 * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
 713 * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 714 * @pre The vce_main() function should be invoked before this function is called.
 715 * @see vce_private_data_set_cb()
 716 */
 717 int vce_set_private_data_set_cb(vce_private_data_set_cb callback_func);
 718
 719 /**
 720 * @brief Sets a callback function for requesting the private data to the engine service.
 721 * @since_tizen 5.0
 722 * @privlevel public
 723 * @privilege %http://tizen.org/privilege/recorder
 724 * @remarks The vce_private_data_requested_cb() function is called when the engine service user requests the private data to the engine service.
 725 * @param[in] callback_func vce_private_data_requested event callback function
 726 * @return @c 0 on success,
 727 *         otherwise a negative error value
 728 * @retval #VCE_ERROR_NONE Successful
 729 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 730 * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
 731 * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
 732 * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 733 * @see vce_private_data_requested_cb()
 734 */
 735 int vce_set_private_data_requested_cb(vce_private_data_requested_cb callback_func);
 736
 737 /**
 738 * @brief Sets a callback function for requesting the NLU base information to the engine service.
 739 * @since_tizen 5.0
 740 * @remarks The vce_nlu_base_info_requested_cb() function is called when the engine service user requests the NLU base information to the engine service.
 741 * @param[in] callback_func vce_nlu_base_info_requested event callback function
 742 * @return @c 0 on success,
 743 *         otherwise a negative error value
 744 * @retval #VCE_ERROR_NONE Successful
 745 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 746 * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 747 * @see vce_nlu_base_info_requested_cb()
 748 */
 749 int vce_set_nlu_base_info_requested_cb(vce_nlu_base_info_requested_cb callback_func);
 750
 751 /**
 752 * @brief Retrieves all commands using callback function.
 753 * @since_tizen 5.0
 754 * @param[in] vce_command The handle to be passed to the vce_set_commands() function
 755 * @param[in] callback The callback function to invoke
 756 * @param[in] user_data The user data to be passed to the callback function
 757 * @return 0 on success, otherwise a negative error value
 758 * @retval #VCE_ERROR_NONE Successful
 759 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 760 * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 761 * @retval #VCE_ERROR_INVALID_STATE Invalid state
 762 * @post This function invokes vce_command_cb() repeatedly for getting commands.
 763 * @see vce_foreach_command_cb()
 764 * @see vce_set_commands()
 765 */
 766 int vce_get_foreach_command(vce_cmd_h vce_command, vce_command_cb callback, void* user_data);
 767
 768 /**
 769 * @brief Gets command length.
 770 * @since_tizen 5.0
 771 * @param[in] vce_command The handle to be passed to the vce_set_commands() function
 772 * @return the value greater than 0 on success
 773 * @see vce_set_commands()
 774 */
 775 int vce_get_command_count(vce_cmd_h vce_command);
 776
 777 /**
 778 * @brief Gets current audio type.
 779 * @since_tizen 5.0
 780 * @remarks audio_type must be released using free() when it is no longer required.
 781 * @param[in] audio_type Current audio type (e.g. #VCE_AUDIO_ID_BLUETOOTH or VCE_AUDIO_ID_WIFI)
 782 * @return the value greater than 0 on success, otherwise a negative error value
 783 * @retval #VCE_ERROR_NONE Successful
 784 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 785 */
 786 int vce_get_audio_type(char** audio_type);
 787
 788 /**
 789 * @brief Sets private data to Manager client.
 790 * @since_tizen 5.0
 791 * @privlevel public
 792 * @privilege %http://tizen.org/privilege/recorder
 793 * @param[in] key Private key
 794 * @param[in] data Private data
 795 * @return 0 on success, otherwise a negative error value.
 796 * @retval #VCE_ERROR_NONE Successful
 797 * @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
 798 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 799 * @retval #VCE_ERROR_INVALID_STATE Invalid state
 800 * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
 801 * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
 802 * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
 803 */
 804 int vce_set_private_data(const char* key, const char* data);
 805
 806 /**
 807 * @brief Gets private data from Manager client.
 808 * @since_tizen 5.0
 809 * @privlevel public
 810 * @privilege %http://tizen.org/privilege/recorder
 811 * @param[in] key Private key
 812 * @param[out] data Private data
 813 * @return 0 on success, otherwise a negative error value.
 814 * @retval #VCE_ERROR_NONE Successful
 815 * @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
 816 * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
 817 * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
 818 * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 819 * @retval #VCE_ERROR_INVALID_STATE Invalid state
 820 * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
 821 */
 822 int vce_get_private_data(const char* key, char** data);
 823
 824 /**
 825 * @brief Request start recording.
 826 * @since_tizen 5.0
 827 * @privlevel public
 828 * @privilege %http://tizen.org/privilege/recorder
 829 * @return 0 on success, otherwise a negative error value.
 830 * @retval #VCE_ERROR_NONE Successful
 831 * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
 832 * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
 833 * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 834 * @retval #VCE_ERROR_RECORDER_BUSY Busy recorder
 835 */
 836 int vce_start_recording(void);
 837
 838 /**
 839 * @brief Request stop recording.
 840 * @since_tizen 5.0
 841 * @privlevel public
 842 * @privilege %http://tizen.org/privilege/recorder
 843 * @return 0 on success, otherwise a negative error value.
 844 * @retval #VCE_ERROR_NONE Successful
 845 * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
 846 * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
 847 * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 848 */
 849 int vce_stop_recording(void);
 850
 851 #ifdef __cplusplus
 852 }
 853 #endif
 854
 855 /**
 856 * @}@}
 857 */
 858
 859 #endif /* __VCE_H__ */
 860
 861