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