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 @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
  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_TTS_FAILED = TIZEN_ERROR_VOICE_CONTROL | 0x024 /**< TTS operation failed (Since 7.0) */
  50 } vce_error_e;
  51
  52 /**
  53  * @brief Enumerations of audio type.
  54  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
  55  */
  56 typedef enum {
  57         VCE_AUDIO_TYPE_PCM_S16_LE = 0, /**< Signed 16bit audio type, Little endian */
  58         VCE_AUDIO_TYPE_PCM_U8 /**< Unsigned 8bit audio type */
  59 } vce_audio_type_e;
  60
  61 /**
  62  * @brief Enumerations of callback event.
  63  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
  64  */
  65 typedef enum {
  66         VCE_RESULT_EVENT_SUCCESS = 0, /**< Event when the recognition full result is ready  */
  67         VCE_RESULT_EVENT_REJECTED, /**< Event when the recognition result is rejected */
  68         VCE_RESULT_EVENT_ERROR /**< Event when the recognition has failed */
  69 } vce_result_event_e;
  70
  71 /**
  72  * @brief Enumerations of command type.
  73  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
  74  */
  75 typedef enum {
  76         VCE_COMMAND_FORMAT_FIXED = 0, /**< Fixed command */
  77         VCE_COMMAND_FORMAT_FIXED_AND_VFIXED, /**< Fixed command + variable-fixed command */
  78         VCE_COMMAND_FORMAT_VFIXED_AND_FIXED, /**< variable-fixed command + Fixed command */
  79         VCE_COMMAND_FORMAT_FIXED_AND_NONFIXED, /**< Fixed command + Non-fixed command */
  80         VCE_COMMAND_FORMAT_NONFIXED_AND_FIXED, /**< Non-fixed command + Fixed command */
  81         VCE_COMMAND_FORMAT_ACTION, /**< Action command */
  82         VCE_COMMAND_FORMAT_PARTIAL /**< Partial matched command */
  83 } vce_command_format_e;
  84
  85 /**
  86  * @brief Enumerations of speech detect.
  87  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
  88  */
  89 typedef enum {
  90         VCE_SPEECH_DETECT_NONE = 0, /**< No event */
  91         VCE_SPEECH_DETECT_BEGIN, /**< Begin of speech detected */
  92         VCE_SPEECH_DETECT_END, /**< End of speech detected */
  93 } vce_speech_detect_e;
  94
  95 /**
  96  * @brief Enumerations of ASR result events.
  97  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
  98  */
  99 typedef enum {
 100         VCE_ASR_RESULT_EVENT_FINAL_RESULT = 0, /**< Event when the ASR result is last data or ASR result is only one result */
 101         VCE_ASR_RESULT_EVENT_PARTIAL_RESULT, /**< Event when the ASR result exist, not first and not last */
 102         VCE_ASR_RESULT_EVENT_ERROR /**< Event when the ASR result is failed */
 103 } vce_asr_result_event_e;
 104
 105 /**
 106  * @brief Enumerations of audio channels.
 107  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 108  */
 109 typedef enum {
 110         VCE_AUDIO_CHANNEL_MONO = 0, /**< 1 channel, mono */
 111         VCE_AUDIO_CHANNEL_STEREO = 1 /**< 2 channels, stereo */
 112 } vce_audio_channel_e;
 113
 114 /**
 115  * @brief Enumeration for TTS feedback events.
 116  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 117  */
 118 typedef enum {
 119         VCE_FEEDBACK_EVENT_FAIL = -1, /**< Failed */
 120         VCE_FEEDBACK_EVENT_START = 1, /**< Start event */
 121         VCE_FEEDBACK_EVENT_CONTINUE = 2, /**< Continue event */
 122         VCE_FEEDBACK_EVENT_FINISH = 3 /**< Finish event */
 123 } vce_feedback_event_e;
 124
 125 /**
 126  * @brief A structure of handle for VC command.
 127  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 128  */
 129 typedef struct vce_cmd_s* vce_cmd_h;
 130
 131 /**
 132  * @brief Definition for foreground command type.
 133  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 134  */
 135 #define VCE_COMMAND_TYPE_FOREGROUND     1
 136
 137 /**
 138  * @brief Definition for background command type.
 139  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 140  */
 141 #define VCE_COMMAND_TYPE_BACKGROUND     2
 142
 143 /**
 144  * @brief Definition for widget command type.
 145  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 146  */
 147 #define VCE_COMMAND_TYPE_WIDGET         3
 148
 149 /**
 150  * @brief Definition for system command type.
 151  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 152  */
 153 #define VCE_COMMAND_TYPE_SYSTEM         4
 154
 155 /**
 156  * @brief Definition for system background command type.
 157  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 158  */
 159 #define VCE_COMMAND_TYPE_SYSTEM_BACKGROUND      5
 160
 161 /**
 162  * @brief Definitions for exclusive command type.
 163  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 164  */
 165 #define VCE_COMMAND_TYPE_EXCLUSIVE      6
 166
 167 /**
 168  * @brief Definition of bluetooth audio id.
 169  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 170  */
 171 #define VCE_AUDIO_ID_BLUETOOTH          "VC_AUDIO_ID_BLUETOOTH"         /**< Bluetooth audio id */
 172
 173 /**
 174  * @brief Definition of Wi-Fi audio id.
 175  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 176  */
 177 #define VCE_AUDIO_ID_WIFI               "VC_AUDIO_ID_WIFI"              /**< Wi-Fi audio id */
 178
 179 /**
 180  * @brief Definition for none message.
 181  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 182  */
 183 #define VC_RESULT_MESSAGE_NONE                  "vc.result.message.none"
 184
 185 /**
 186  * @brief Definition for failed recognition because the speech is too loud to listen.
 187  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 188  */
 189 #define VC_RESULT_MESSAGE_ERROR_TOO_LOUD        "vc.result.message.error.too.loud"
 190
 191 /**
 192  * @brief Called when VC engine informs the engine service user about whole supported languages.
 193  * @details This callback function is implemented by the engine service user. Therefore, the engine developer does NOT have to implement this callback function.
 194  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 195  * @remarks This callback function is called by vce_foreach_supported_languages_cb() to retrieve the whole supported language list.
 196  *          The @a user_data must be transferred from vce_foreach_supported_languages_cb().
 197  *          The @a language can be used only in the callback. To use outside, make a copy.
 198  * @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
 199  *            For example, "ko_KR" for Korean, "en_US" for American English.
 200  * @param[in] user_data The user data passed from the foreach function
 201  * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
 202  * @pre vce_foreach_supported_languages_cb() will invoke this callback.
 203  * @see vce_foreach_supported_languages_cb()
 204  */
 205 typedef bool (*vce_supported_language_cb)(const char* language, void* user_data);
 206
 207 /**
 208  * @brief Called when the engine service user initializes Voice Control (VC) engine.
 209  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 210  * @remarks This callback function is mandatory and must be registered using vce_main().
 211  * @return 0 on success, otherwise a negative error value
 212  * @retval #VCE_ERROR_NONE Successful
 213  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 214  * @retval #VCE_ERROR_INVALID_STATE Already initialized
 215  * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
 216  * @see vce_deinitialize_cb()
 217  */
 218 typedef int (*vce_initialize_cb)(void);
 219
 220 /**
 221  * @brief Called when the engine service user deinitializes VC engine.
 222  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 223  * @remarks This callback function is mandatory and must be registered using vce_main().
 224  * @return 0 on success, otherwise a negative error value
 225  * @retval #VCE_ERROR_NONE Successful
 226  * @retval #VCE_ERROR_INVALID_STATE Not initialized
 227  * @see vce_initialize_cb()
 228  */
 229 typedef int (*vce_deinitialize_cb)(void);
 230
 231 /**
 232  * @brief Called when the engine service user requests the recording format of VC engine.
 233  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 234  * @remarks This callback function is mandatory and must be registered using vce_main().
 235  *          The @a audio_id can be used only in the callback. To use outside, make a copy.
 236  *          The @a types is managed by the platform and will be released when this callback function is completed.
 237  *          The @a rate is managed by the platform and will be released when this callback function is completed.
 238  *          The @a channels is managed by the platform and will be released when this callback function is completed.
 239  * @param[in] audio_id The audio device id. (e.g. #VCE_AUDIO_ID_BLUETOOTH or #VCE_AUDIO_ID_WIFI)
 240  * @param[out] types The format used by the recorder.
 241  * @param[out] rate The sample rate used by the recorder.
 242  * @param[out] channels The number of channels used by the recorder.
 243  * @return 0 on success, otherwise a negative error value
 244  * @retval #VCE_ERROR_NONE Successful
 245  * @retval #VCE_ERROR_INVALID_PARAMETER Not initialized
 246  */
 247 typedef int (*vce_get_recording_format_cb)(const char* audio_id, vce_audio_type_e* types, int* rate, int* channels);
 248
 249 /**
 250  * @brief Called when the engine service user retrieves all supported languages of VC engine.
 251  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 252  * @remarks This callback function is mandatory and must be registered using vce_main().
 253  * @param[in] callback a callback function
 254  * @param[in] user_data The user data to be passed to the callback function
 255  * @return 0 on success, otherwise a negative error value
 256  * @retval #VCE_ERROR_NONE Successful
 257  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 258  * @retval #VCE_ERROR_INVALID_STATE Not initialized
 259  * @post This function invokes vce_supported_language_cb() repeatedly for getting supported languages.
 260  *
 261  * @see vce_supported_language_cb()
 262  */
 263 typedef int (*vce_foreach_supported_languages_cb)(vce_supported_language_cb callback, void* user_data);
 264
 265 /**
 266  * @brief Called when the engine service user checks whether a language is supported or not.
 267  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 268  * @remarks This callback function is mandatory and must be registered using vce_main().
 269  *          The @a language can be used only in the callback. To use outside, make a copy.
 270  * @param[in] language A language
 271  * @return @c true = supported, \n @c false = not supported.
 272  */
 273 typedef bool (*vce_is_language_supported_cb)(const char* language);
 274
 275 /**
 276  * @brief Called when the engine service user sets language.
 277  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 278  * @remarks The @a language can be used only in the callback. To use outside, make a copy.
 279  * @param[in] language A language.
 280  * @return 0 on success, otherwise a negative error value
 281  * @retval #VCE_ERROR_NONE Successful
 282  * @retval #VCE_ERROR_INVALID_LANGUAGE Invalid language
 283  * @retval #VCE_ERROR_INVALID_STATE Not initialized
 284  * @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
 285  */
 286 typedef int (*vce_set_language_cb)(const char* language);
 287
 288 /**
 289  * @brief Called when the engine service user sets command list before recognition.
 290  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 291  * @remarks This function should set commands via vcd_foreach_command().
 292  *          The @a vc_command should not be released.
 293  *          The @a vc_command can be used only in the callback. To use outside, make a copy.
 294  * @param[in] vc_command command handle. The @a vc_command can be used only in the callback. To use outside, make a copy.
 295  * @return 0 on success, otherwise a negative error value
 296  * @retval #VCE_ERROR_NONE Successful
 297  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 298  * @retval #VCE_ERROR_INVALID_STATE Invalid state
 299  * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
 300  * @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported command type
 301  * @post vce_start_cb() is called after this function is successful.
 302  * @see vce_start_cb()
 303  * @see vcd_foreach_command()
 304  * @see vce_unset_commands()
 305  * @see vce_get_command_count()
 306  */
 307 typedef int (*vce_set_commands_cb)(vce_cmd_h vc_command);
 308
 309 /**
 310  * @brief Called when the engine service user unsets command list for reset.
 311  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 312  * @return 0 on success, otherwise a negative error value
 313  * @retval #VCE_ERROR_NONE Successful
 314  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 315  * @retval #VCE_ERROR_INVALID_STATE Invalid state
 316  * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
 317  * @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
 318  * @see vce_set_commands_cb()
 319  */
 320 typedef int (*vce_unset_commands_cb)(void);
 321
 322 /**
 323  * @brief Called when the engine service user starts recognition.
 324  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 325  * @remarks This callback function is mandatory and must be registered using vce_main().
 326  * @param[in] stop_by_silence Silence detection option.
 327  *                   @c true to detect the silence,
 328  *                   @c false not to detect the silence
 329  * @return 0 on success, otherwise a negative error value
 330  * @retval #VCE_ERROR_NONE Successful
 331  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 332  * @retval #VCE_ERROR_INVALID_STATE Invalid state
 333  * @retval #VCE_ERROR_INVALID_LANGUAGE Invalid language
 334  * @retval #VCE_ERROR_OUT_OF_NETWORK Out of network
 335  * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
 336  * @pre vcd_foreach_command() is successful.
 337  * @see vce_set_recording_data_cb()
 338  * @see vce_stop_cb()
 339  * @see vce_cancel_cb()
 340  */
 341 typedef int (*vce_start_cb)(bool stop_by_silence);
 342
 343 /**
 344  * @brief Called when the engine service user sets recording data for speech recognition from recorder.
 345  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 346  * @remarks This function should be returned immediately after recording data copy.
 347  *          The @a data can be used only in the callback. To use outside, make a copy.
 348  *          The @a speech_detected should not be released. This is managed by the platform.
 349  * @param[in] data A recording data
 350  * @param[in] length A length of recording data
 351  * @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.
 352  * @return 0 on success, otherwise a negative error value
 353  * @retval #VCE_ERROR_NONE Successful
 354  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 355  * @retval #VCE_ERROR_INVALID_STATE Invalid state
 356  * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
 357  * @pre vce_start_cb() is successful.
 358  * @see vce_start_cb()
 359  * @see vce_cancel_cb()
 360  * @see vce_stop_cb()
 361  */
 362 typedef int(*vce_set_recording_data_cb)(const void* data, unsigned int length, vce_speech_detect_e* speech_detected);
 363
 364 /**
 365  * @brief Called when the engine service user stops to get the result of recognition.
 366  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 367  * @return 0 on success, otherwise a negative error value
 368  * @retval #VCE_ERROR_NONE Successful
 369  * @retval #VCE_ERROR_INVALID_STATE Invalid state
 370  * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
 371  * @retval #VCE_ERROR_OUT_OF_NETWORK Out of network
 372  * @pre vce_set_recording_data_cb() is successful.
 373  * @see vce_start_cb()
 374  * @see vce_set_recording_data_cb()
 375  * @see vce_send_result()
 376  * @see vce_cancel_cb()
 377  */
 378 typedef int (*vce_stop_cb)(void);
 379
 380 /**
 381  * @brief Called when the engine service user cancels the recognition process.
 382  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 383  * @return 0 on success, otherwise a negative error value.
 384  * @retval #VCE_ERROR_NONE Successful.
 385  * @retval #VCE_ERROR_INVALID_STATE Invalid state.
 386  * @pre vce_start_cb() is successful.
 387  * @see vce_start_cb()
 388  * @see vce_stop_cb()
 389  */
 390 typedef int (*vce_cancel_cb)(void);
 391
 392 /**
 393  * @brief Called when the engine service user sets audio recording type.
 394  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 395  * @remarks The @a audio_type can be used only in the callback. To use outside, make a copy.
 396  * @param[in] audio_type Current audio type (e.g. #VCE_AUDIO_ID_BLUETOOTH or #VCE_AUDIO_ID_WIFI)
 397  * @return 0 on success, otherwise a negative error value.
 398  * @retval #VCE_ERROR_NONE Successful.
 399  * @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature.
 400  */
 401 typedef int (*vce_set_audio_type_cb)(const char* audio_type);
 402
 403 /**
 404  * @brief Called when the engine service user sets app id which is want to ask server dialog.
 405  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 406  * @remarks The @a app_id and @a credential can be used only in the callback. To use outside, make a copy.
 407  * @param[in] app_id App id which is to want to ask server dialog.
 408  * @param[in] credential Credential key.
 409  * @return 0 on success, otherwise a negative error value.
 410  * @retval #VCE_ERROR_NONE Successful.
 411  * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied.
 412  * @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature.
 413  */
 414 typedef int (*vce_set_server_dialog_cb)(const char* app_id, const char* credential);
 415
 416 /**
 417  * @brief Called when the engine service user sets domain (agent or device type).
 418  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 419  * @remarks The @a domain can be used only in the callback. To use outside, make a copy.
 420  * @param[in] domain Agent (e.g. "music", "news", etc) or device type (e.g. "tv", "mobile", etc) corresponding to the command
 421  * @return 0 on success, otherwise a negative error value.
 422  * @retval #VCE_ERROR_NONE Successful.
 423  * @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
 424  */
 425 typedef int (*vce_set_domain_cb)(const char* domain);
 426
 427 /**
 428  * @brief Called when the engine service user requests essential value from NLU result.
 429  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 430  * @remarks The @a key can be used only in the callback. To use outside, make a copy.
 431  *          The @a value is managed by the platform and will be released when this callback function is completed.
 432  * @param[in] key NLU base info key.
 433  * @param[out] value NLU base info value.
 434  * @return 0 on success, otherwise a negative error value.
 435  * @retval #VCE_ERROR_NONE Successful.
 436  * @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature.
 437  */
 438 typedef int (*vce_nlu_base_info_requested_cb)(const char* key, char** value);
 439
 440 /**
 441  * @brief Called when client gets the specific engine's request from the engine service user.
 442  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 443  * @remarks The @a engine_app_id is managed by the platform and will be released when this callback function is completed.
 444  *          The @a event is managed by the platform and will be released when this callback function is completed.
 445  *          The @a request is managed by the platform and will be released when this callback function is completed.
 446  *
 447  * @param[in] engine_app_id The specific engine's app id
 448  * @param[in] event The specific engine event type
 449  * @param[in] request The specific engine request
 450  *
 451  * @return 0 on success, otherwise a negative error value.
 452  * @retval #VCE_ERROR_NONE Successful
 453  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 454  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 455  *
 456  * @pre An application registers callback function using vce_set_specific_engine_request_cb().
 457  *
 458  * @see vce_set_specific_engine_request_cb()
 459  * @see vce_unset_specific_engine_request_cb()
 460  */
 461 typedef int (*vce_specific_engine_request_cb)(const char* engine_app_id, const char* event, const char* request);
 462
 463 /**
 464  * @brief Called when the engine service user sets private data between app and engine.
 465  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 466  * @remarks The @a key, @a data can be used only in the callback. To use outside, make a copy.
 467  * @param[in] key Private key.
 468  * @param[in] data Private data.
 469  * @return 0 on success, otherwise a negative error value.
 470  * @retval #VCE_ERROR_NONE Successful.
 471  * @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature.
 472  */
 473 typedef int (*vce_private_data_set_cb)(const char* key, const char* data);
 474
 475 /**
 476  * @brief Called when the engine service user requests private data between app and engine.
 477  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 478  * @remarks The @a key can be used only in the callback. To use outside, make a copy.
 479  *          The @a data is managed by the platform and will be released when this callback function is completed.
 480  * @param[in] key Private key.
 481  * @param[out] data Private data.
 482  * @return 0 on success, otherwise a negative error value.
 483  * @retval #VCE_ERROR_NONE Successful.
 484  * @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature.
 485  */
 486 typedef int (*vce_private_data_requested_cb)(const char* key, char** data);
 487
 488 /**
 489  * @brief Called when the engine service user requests process text.
 490  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 491  * @remarks The @a text can be used only in the callback. To use outside, make a copy.
 492  * @param[in] text Requested text
 493  * @return 0 on success, otherwise a negative error value.
 494  * @retval #VCE_ERROR_NONE Successful.
 495  * @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature.
 496  */
 497 typedef int (*vce_process_text_cb)(const char* text);
 498
 499 /**
 500  * @brief Called when the engine service user requests list event.
 501  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 502  * @remarks The @a event can be used only in the callback. To use outside, make a copy.
 503  * @param[in] event Requested list event
 504  * @return 0 on success, otherwise a negative error value.
 505  * @retval #VCE_ERROR_NONE Successful.
 506  * @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature.
 507  */
 508 typedef int (*vce_process_list_event_cb)(const char* event);
 509
 510 /**
 511  * @brief Called when the engine service user requests haptic event.
 512  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 513  * @remarks The @a event can be used only in the callback. To use outside, make a copy.
 514  * @param[in] event Requested haptic event
 515  * @return 0 on success, otherwise a negative error value.
 516  * @retval #VCE_ERROR_NONE Successful.
 517  * @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature.
 518  */
 519 typedef int (*vce_process_haptic_event_cb)(const char* event);
 520
 521 /**
 522  * @brief Called when the engine service user requests the base information of VC engine.
 523  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 524  * @remarks This callback function is mandatory and must be registered using vce_main().
 525  *          The @a engine_uuid is managed by the platform and will be released when this callback function is completed.
 526  *          The @a engine_name is managed by the platform and will be released when this callback function is completed.
 527  *          The @a engine_settings_app_id is managed by the platform and will be released when this callback function is completed.
 528  *          The @a use_network is managed by the platform and will be released when this callback function is completed.
 529  *          In order to upload the engine to Tizen Appstore, both the service app and the UI app (engine settings) are necessary.
 530  *          Therefore, @a engine_settings_app_id should be set to the application ID of the UI application.
 531  *          If there is no UI application, then @a engine_settings_app_id should be set to NULL.
 532  * @param[out] engine_uuid The engine id
 533  * @param[out] engine_name The engine name
 534  * @param[out] engine_settings_app_id The ID of the engine settings application (the UI application)
 535  * @param[out] use_network @c true to need network @c false not to need network.
 536  * @return @c 0 on success, otherwise a negative error code on failure
 537  * @retval #VCE_ERROR_NONE Successful
 538  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 539  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 540  */
 541 typedef int (*vce_get_info_cb)(char** engine_uuid, char** engine_name, char** engine_settings_app_id, bool* use_network);
 542
 543 /**
 544  * @brief Called to retrieve the commands.
 545  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 546  * @remarks The @a command, @a param can be used only in the callback. To use outside, make a copy.
 547  * @param[in] id command id
 548  * @param[in] type command type
 549  * @param[in] format command format
 550  * @param[in] command command text
 551  * @param[in] param parameter text
 552  * @param[in] domain command domain
 553  * @param[in] user_data The user data passed from the foreach function
 554  * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
 555  * @pre vce_get_foreach_command() will invoke this callback.
 556  * @see vce_get_foreach_command()
 557  */
 558 typedef bool (*vce_command_cb)(int id, int type, int format, const char* command, const char* param, int domain, void* user_data);
 559
 560 /**
 561  * @brief Called when the engine service user (voice control client) requests to send TTS feedback.
 562  * @since_tizen 5.0
 563  * @remarks The @a text and @a language can be used only in the callback. To use outside, make a copy.
 564  *
 565  * @param[in] pid The process id of the engine service user (voice control client)
 566  * @param[in] utt_id The utterance id
 567  * @param[in] text The text for TTS feedback
 568  * @param[in] language The language
 569  * @param[in] user_data The user data passed from the callback setter function
 570  *
 571  * @return 0 on success, otherwise a negative error value.
 572  * @retval #VCE_ERROR_NONE Successful
 573  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 574  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 575  *
 576  * @pre An application registers callback function using vce_set_request_tts_cb().
 577  *
 578  * @see vce_set_request_tts_cb()
 579  * @see vce_unset_request_tts_cb()
 580  */
 581 typedef int (*vce_request_tts_cb)(int pid, int utt_id, const char* text, const char* language, void* user_data);
 582
 583 /**
 584  * @brief Called when the engine service user cancels TTS feedback.
 585  * @since_tizen 5.0
 586  *
 587  * @param[in] pid The process id of the engine service user
 588  * @param[in] utt_id The utterance id corresponding to the text
 589  * @param[in] user_data The user data passed from the callback setter function
 590  *
 591  * @return 0 on success, otherwise a negative error value.
 592  * @retval #VCE_ERROR_NONE Successful
 593  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 594  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 595  *
 596  * @pre An application registers callback function using vce_set_cancel_tts_cb().
 597  *
 598  * @see vce_set_cancel_tts_cb()
 599  * @see vce_unset_cancel_tts_cb()
 600 */
 601 typedef int (*vce_cancel_tts_cb)(int pid, int utt_id, void* user_data);
 602
 603 /**
 604  * @brief Called when the engine service user requests TTS audio format.
 605  * @since_tizen 5.0
 606  * @remarks The @a rate, @a channel, and @a audio_type should not be released.
 607  *          The @a rate, @a channel, and @a audio_type are managed by the platform and will be released after the audio format is transferred to the VC client.
 608  *
 609  * @param[out] rate The audio sample rate
 610  * @param[out] channel The audio channel
 611  * @param[out] audio_type The audio type
 612  * @param[in] user_data The user data passed from the callback setter function
 613  *
 614  * @return 0 on success, otherwise a negative error value.
 615  * @retval #VCE_ERROR_NONE Successful
 616  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 617  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 618  *
 619  * @pre An application registers callback function using vce_set_tts_audio_format_request_cb().
 620  *
 621  * @see vce_set_tts_audio_format_request_cb()
 622  * @see vce_unset_get_tts_audio_format_cb()
 623  */
 624 typedef int (*vce_tts_audio_format_request_cb)(int* rate, int* channel, int* audio_type, void* user_data);
 625
 626
 627 /**
 628  * @brief A structure for the VC engine functions.
 629  * @details This structure contains essential callback functions for operating VC engine.
 630  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 631  * @remarks You must register all callbacks except optional callbacks for operating VC engine.\n
 632  *      The following callbacks are optional callbacks : \n
 633  *      - vce_private_data_set_cb() \n
 634  *      - vce_private_data_requested_cb() \n
 635  *      - vce_nlu_base_info_requested_cb() \n
 636  *      - vce_specific_engine_request_cb() \n
 637  *      If you want to use the optional callbacks, you can set them using vce_set_private_data_set_cb(), vce_set_private_data_requested_cb(), vce_set_nlu_base_info_requested_cb(), and vce_set_specific_engine_request_cb() functions.
 638  *
 639  * @see vce_main()
 640  * @see vce_set_private_data_set_cb()
 641  * @see vce_set_private_data_requested_cb()
 642  * @see vce_set_nlu_base_info_requested_cb()
 643  * @see vce_set_specific_engine_request_cb()
 644  */
 645 typedef struct {
 646         int version;                                            /**< Version */
 647
 648         /* Get engine information */
 649         vce_get_info_cb                                         get_info;                               /**< Called when the engine service user requests the basic information of VC engine */
 650         vce_get_recording_format_cb                     get_recording_format;   /**< Get recording format */
 651         vce_foreach_supported_languages_cb      foreach_langs;                  /**< Foreach language list */
 652         vce_is_language_supported_cb            is_lang_supported;              /**< Check language */
 653
 654         vce_initialize_cb                                       initialize;                             /**< Initialize engine */
 655         vce_deinitialize_cb                                     deinitialize;                   /**< Shutdown engine */
 656
 657         /* Set info */
 658         vce_set_language_cb                                     set_language;                   /**< Set language */
 659         vce_set_commands_cb                                     set_commands;                   /**< Request to set current commands */
 660         vce_unset_commands_cb                           unset_commands;                 /**< Request to unset current commands */
 661
 662         /* Control recognition */
 663         vce_start_cb                                            start;                                  /**< Start recognition */
 664         vce_set_recording_data_cb                       set_recording;                  /**< Set recording data */
 665         vce_stop_cb                                                     stop;                                   /**< Stop recording for getting result */
 666         vce_cancel_cb                                           cancel;                                 /**< Cancel recording and processing */
 667
 668         vce_set_audio_type_cb                           set_audio_type;                 /**< Set audio type */
 669         vce_set_server_dialog_cb                        set_server_dialog;              /**< Set server dialog */
 670
 671         vce_set_domain_cb                                       set_domain;                             /**< Set domain */
 672         vce_process_text_cb                                     process_text;                   /**< Request to process text */
 673         vce_process_list_event_cb                       process_list_event;             /**< Request to process list event */
 674         vce_process_haptic_event_cb                     process_haptic_event;   /**< Request to process haptic event */
 675
 676         /* Optional callbacks */
 677         vce_private_data_set_cb                         private_data_set;               /**< Set private data from the app */
 678         vce_private_data_requested_cb           private_data_request;   /**< Send private data to the app */
 679         vce_nlu_base_info_requested_cb          nlu_base_info_request;  /**< Send essential value from NLU result */
 680         vce_specific_engine_request_cb          specific_engine_request;        /**< Get specific engine's request from the engine service user */
 681 } vce_request_callback_s;
 682
 683 /**
 684  * @brief Starts the main function for Voice Control (VC) engine.
 685  * @details This function is the main function for operating VC engine.
 686  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 687  * @privlevel public
 688  * @privilege %http://tizen.org/privilege/recorder \n
 689  *            %http://tizen.org/privilege/appmanager.launch (Since 7.0)  \n
 690  *            %http://tizen.org/privilege/datasharing (Since 7.0)
 691  * @remarks To use this function, privileges of appmanager.launch and datasharing should be included since 7.0. \n
 692  *          The service_app_main() should be used for working the engine after this function.
 693  *
 694  * @param[in] argc The argument count(original)
 695  * @param[in] argv The argument(original)
 696  * @param[in] callback The structure of engine request callback function
 697  * @return This function returns @c zero on success, or negative with error code on failure
 698  * @retval #VCE_ERROR_NONE Successful
 699  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
 700  * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
 701  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 702  * @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
 703  * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
 704  * @pre The vce_get_info_cb() should be successful.
 705  * @see vce_get_info_cb()
 706  * @see vce_request_callback_s
 707  * @code
 708 #include <vce.h>
 709
 710 // Required callback functions - MUST BE IMPLEMENTED
 711 static int vce_default_initialize();
 712 static int vce_default_deinitialize(void);
 713
 714 static int vce_default_get_info(char** engine_uuid, char** engine_name, char** engine_setting, bool* use_network);
 715 static int vce_default_get_recording_format(const char* audio_id, vce_audio_type_e* types, int* rate, int* channels);
 716 static int vce_default_foreach_langs(vce_supported_language_cb callback, void* user_data);
 717 static bool vce_default_is_lang_supported(const char* lang);
 718
 719 static int vce_default_set_language(const char* language);
 720 static int vce_default_set_commands(vce_cmd_h vc_command);
 721 static int vce_default_unset_commands();
 722
 723 static int vce_default_start(bool stop_by_silence);
 724 static int vce_default_set_recording(const void* data, unsigned int length, vce_speech_detect_e* silence_detected);
 725 static int vce_default_stop();
 726 static int vce_default_cancel(void);
 727
 728 static int vce_default_set_audio_type(const char* audio_type);
 729 static int vce_default_set_domain(const char* domain);
 730 static int vce_default_process_text(const char* text);
 731 static int vce_default_process_list_event(const char* event);
 732 static int vce_default_process_haptic_event(const char* event);
 733
 734 // Optional callback function
 735 static int vce_default_private_data_set_cb(const char* key, const char* data);
 736
 737 int main(int argc, char* argv[])
 738 {
 739         // 1. Create a structure 'vce_request_callback_s'
 740         vce_request_callback_s callback = {0,};
 741
 742         callback.version = 1;
 743
 744         callback.initialize     = vce_default_initialize;
 745         callback.deinitialize   = vce_default_deinitialize;
 746
 747         callback.get_info       = vce_default_get_info;
 748         callback.get_recording_format   = vce_default_get_recording_format;
 749         callback.foreach_langs  = vce_default_foreach_langs;
 750         callback.is_lang_supported      = vce_default_is_lang_supported;
 751
 752         callback.set_language   = vce_default_set_language;
 753         callback.set_commands   = vce_default_set_commands;
 754         callback.unset_commands = vce_default_unset_commands;
 755
 756         callback.start          = vce_default_start;
 757         callback.set_recording  = vce_default_set_recording;
 758         callback.stop           = vce_default_stop;
 759         callback.cancel         = vce_default_cancel;
 760
 761         callback.set_audio_type = vce_default_set_audio_type;
 762         callback.set_domain     = vce_default_set_domain;
 763         callback.process_text   = vce_default_process_text;
 764         callback.process_list_event     = vce_default_process_list_event;
 765         callback.process_haptic_event   = vce_default_process_haptic_event;
 766
 767     // 2. Run 'vce_main()'
 768         if (0 != vce_main(argc, argv, &callback)) {
 769                 SLOG(LOG_ERROR, TAG_VCE, "[ERROR] Fail to vce main");
 770                 return -1;
 771         }
 772
 773         // Optional
 774         vce_set_private_data_set_cb(vce_default_private_data_set_cb);
 775
 776     // 3. Set event callbacks for service app and Run 'service_app_main()'
 777         char ad[50] = {0,};
 778         service_app_lifecycle_callback_s event_callback;
 779         app_event_handler_h handlers[5] = {NULL, };
 780
 781         event_callback.create = service_app_create;
 782         event_callback.terminate = service_app_terminate;
 783         event_callback.app_control = service_app_control;
 784
 785         service_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY, service_app_low_battery, &ad);
 786         service_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY], APP_EVENT_LOW_MEMORY, service_app_low_memory, &ad);
 787         service_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED], APP_EVENT_LANGUAGE_CHANGED, service_app_lang_changed, &ad);
 788         service_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED], APP_EVENT_REGION_FORMAT_CHANGED, service_app_region_changed, &ad);
 789
 790         return service_app_main(argc, argv, &event_callback, ad);
 791 }
 792
 793  * @endcode
 794  */
 795 int vce_main(int argc, char** argv, vce_request_callback_s* callback);
 796
 797 /**
 798  * @brief Sends the results to the engine service user.
 799  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 800  * @privlevel public
 801  * @privilege %http://tizen.org/privilege/appmanager.launch (Since 7.0) \n
 802  *            %http://tizen.org/privilege/datasharing (Since 7.0)
 803  * @remarks To use this function, privileges of appmanager.launch and datasharing should be included since 7.0.
 804  *
 805  * @param[in] event A result event
 806  * @param[in] result_id Result ids
 807  * @param[in] count Result count
 808  * @param[in] all_result All result text
 809  * @param[in] non_fixed_result Non-fixed command result text
 810  * @param[in] nlu_result NLU result text
 811  * @param[in] msg Engine message (e.g. #VC_RESULT_MESSAGE_NONE, #VC_RESULT_MESSAGE_ERROR_TOO_LOUD)
 812  * @param[out] user_info A user info (e.g. If ASR result is consumed, the value is 0x01. If not, the value is 0x00.)
 813  * @param[in] user_data The user data passed from set callback function
 814  * @return @c 0 on success, otherwise a negative error value
 815  * @retval #VCE_ERROR_NONE Successful
 816  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
 817  * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
 818  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 819  * @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
 820  * @retval #VCE_ERROR_INVALID_STATE Invalid state
 821  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 822  * @pre The vce_main() function should be invoked before this function is called.
 823  *      vce_stop_cb() will invoke this callback.
 824  * @see vce_stop_cb()
 825  */
 826 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);
 827
 828 /**
 829  * @brief Sends the ASR result to the engine service user.
 830  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 831  * @privlevel public
 832  * @privilege %http://tizen.org/privilege/appmanager.launch (Since 7.0) \n
 833  *            %http://tizen.org/privilege/datasharing (Since 7.0)
 834  * @remarks To use this function, privileges of appmanager.launch and datasharing should be included since 7.0.
 835  *
 836  * @param[in] event A asr result event
 837  * @param[in] asr_result A asr result text
 838  * @param[in] user_data The user data passed from the start
 839  * @return @c 0 on success, otherwise a negative error value
 840  * @retval #VCE_ERROR_NONE Successful
 841  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
 842  * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
 843  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 844  * @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
 845  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 846  * @pre The vce_main() function should be invoked before this function is called.
 847  * @see vce_start_cb()
 848  */
 849 int vce_send_asr_result(vce_asr_result_event_e event, const char* asr_result, void* user_data);
 850
 851 /**
 852  * @brief Sends the NLG (Natural Language Generation) result to the engine service user.
 853  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 854  * @privlevel public
 855  * @privilege %http://tizen.org/privilege/appmanager.launch (Since 7.0) \n
 856  *            %http://tizen.org/privilege/datasharing (Since 7.0)
 857  * @remarks To use this function, privileges of appmanager.launch and datasharing should be included since 7.0.
 858  *
 859  * @param[in] nlg_result A nlg result
 860  * @param[in] user_data The user data passed from the start
 861  * @return @c 0 on success, otherwise a negative error value
 862  * @retval #VCE_ERROR_NONE Successful
 863  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
 864  * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
 865  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 866  * @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
 867  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 868  * @pre The vce_main() function should be invoked before this function is called.
 869  * @see vce_start_cb()
 870  */
 871 int vce_send_nlg_result(const char* nlg_result, void* user_data);
 872
 873 /**
 874  * @brief Sends the specific engine result to the engine service user.
 875  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 876  * @privlevel public
 877  * @privilege %http://tizen.org/privilege/appmanager.launch (Since 7.0) \n
 878  *            %http://tizen.org/privilege/datasharing (Since 7.0)
 879  * @remarks To use this function, privileges of appmanager.launch and datasharing should be included since 7.0.
 880  *
 881  * @param[in] engine_app_id A specific engine's app id
 882  * @param[in] event A specific engine result event
 883  * @param[in] result A specific engine result text
 884  * @param[in] user_info The user info passed from the start
 885  *
 886  * @return 0 on success, otherwise a negative error value
 887  * @retval #VCE_ERROR_NONE Successful
 888  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
 889  * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
 890  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 891  * @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
 892  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 893  * @pre The vce_main() function should be invoked before this function is called.
 894  */
 895 int vce_send_specific_engine_result(const char* engine_app_id, const char* event, const char* result, void *user_info);
 896
 897 /**
 898  * @brief Sends the error to the engine service user.
 899  * @details The following error codes can be delivered. \n
 900  *          #VCE_ERROR_NONE, \n
 901  *          #VCE_ERROR_OUT_OF_MEMORY, \n
 902  *          #VCE_ERROR_IO_ERROR, \n
 903  *          #VCE_ERROR_INVALID_PARAMETER, \n
 904  *          #VCE_ERROR_OUT_OF_NETWORK, \n
 905  *          #VCE_ERROR_RECORDER_BUSY, \n
 906  *          #VCE_ERROR_NOT_SUPPORTED, \n
 907  *          #VCE_ERROR_INVALID_STATE, \n
 908  *          #VCE_ERROR_INVALID_LANGUAGE, \n
 909  *          #VCE_ERROR_OPERATION_FAILED, \n
 910  *          #VCE_ERROR_PERMISSION_DENIED, \n
 911  *          #VCE_ERROR_NOT_SUPPORTED_FEATURE \n
 912  *          #VCE_ERROR_TTS_FAILED.
 913  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 914  * @privlevel public
 915  * @privilege %http://tizen.org/privilege/appmanager.launch (Since 7.0) \n
 916  *            %http://tizen.org/privilege/datasharing (Since 7.0)
 917  * @remarks To use this function, privileges of appmanager.launch and datasharing should be included since 7.0.
 918  *
 919  * @param[in] error Error type
 920  * @param[in] msg Error message
 921  * @param[in] user_data The user data passed from set callback function
 922  * @return @c 0 on success, otherwise a negative error value
 923  * @retval #VCE_ERROR_NONE Successful
 924  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
 925  * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
 926  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 927  * @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
 928  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 929  * @pre The vce_main() function should be invoked before this function is called.
 930  */
 931 int vce_send_error(vce_error_e error, const char* msg, void* user_data);
 932
 933 /**
 934  * @brief Sets a callback function for setting the private data to the engine service.
 935  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 936  * @privlevel public
 937  * @privilege %http://tizen.org/privilege/recorder
 938  * @remarks The vce_private_data_set_cb() function is called when the engine service user sets the private data to the engine service.
 939  *
 940  * @param[in] callback_func vce_private_data_set event callback function
 941  * @return @c 0 on success, otherwise a negative error value
 942  * @retval #VCE_ERROR_NONE Successful
 943  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
 944  * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
 945  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 946  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 947  * @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
 948  * @pre The vce_main() function should be invoked before this function is called.
 949  * @see vce_private_data_set_cb()
 950  */
 951 int vce_set_private_data_set_cb(vce_private_data_set_cb callback_func);
 952
 953 /**
 954  * @brief Sets a callback function for requesting the private data to the engine service.
 955  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 956  * @privlevel public
 957  * @privilege %http://tizen.org/privilege/recorder
 958  * @remarks The vce_private_data_requested_cb() function is called when the engine service user requests the private data to the engine service.
 959  *
 960  * @param[in] callback_func vce_private_data_requested event callback function
 961  * @return @c 0 on success, otherwise a negative error value
 962  * @retval #VCE_ERROR_NONE Successful
 963  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
 964  * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
 965  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 966  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 967  * @see vce_private_data_requested_cb()
 968  */
 969 int vce_set_private_data_requested_cb(vce_private_data_requested_cb callback_func);
 970
 971 /**
 972  * @brief Sets a callback function for requesting the NLU base information to the engine service.
 973  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 974  * @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.
 975  * @param[in] callback_func vce_nlu_base_info_requested event callback function
 976  * @return @c 0 on success, otherwise a negative error value
 977  * @retval #VCE_ERROR_NONE Successful
 978  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
 979  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 980  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
 981  * @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
 982  * @see vce_nlu_base_info_requested_cb()
 983  */
 984 int vce_set_nlu_base_info_requested_cb(vce_nlu_base_info_requested_cb callback_func);
 985
 986 /**
 987  * @brief Sets a callback function for getting the engine service request.
 988  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
 989  *
 990  * @param[in] callback_func Callback function to register
 991  *
 992  * @return 0 on success, otherwise a negative error value
 993  * @retval #VCE_ERROR_NONE Successful
 994  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
 995  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
 996  *
 997  * @see vce_unset_specific_engine_request_cb()
 998  */
 999 int vce_set_specific_engine_request_cb(vce_specific_engine_request_cb callback_func);
1000
1001 /**
1002  * @brief Unsets the engine service request callback function.
1003  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
1004  *
1005  * @return 0 on success, otherwise a negative error value
1006  * @retval #VCE_ERROR_NONE Successful
1007  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
1008  *
1009  * @see vce_set_specific_engine_request_cb()
1010  */
1011 int vce_unset_specific_engine_request_cb(void);
1012
1013 /**
1014  * @brief Retrieves all commands using callback function.
1015  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
1016  *
1017  * @param[in] vce_command The handle to be passed to the vce_set_commands_cb() function
1018  * @param[in] callback The callback function to invoke
1019  * @param[in] user_data The user data to be passed to the callback function
1020  *
1021  * @return 0 on success, otherwise a negative error value
1022  * @retval #VCE_ERROR_NONE Successful
1023  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
1024  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
1025  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
1026  * @retval #VCE_ERROR_INVALID_STATE Invalid state
1027  * @post This function invokes vce_command_cb() repeatedly for getting commands.
1028  * @see vce_command_cb()
1029  * @see vce_set_commands_cb()
1030  */
1031 int vce_get_foreach_command(vce_cmd_h vce_command, vce_command_cb callback, void* user_data);
1032
1033 /**
1034  * @brief Gets command length.
1035  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
1036  *
1037  * @param[in] vce_command The handle to be passed to the vce_set_commands_cb() function
1038  * @param[out] count The command count value
1039  *
1040  * @return 0 on success, otherwise a negative error value.
1041  * @retval #VCE_ERROR_NONE Successful
1042  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
1043  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
1044  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
1045  * @see vce_set_commands_cb()
1046  */
1047 int vce_get_command_count(vce_cmd_h vce_command, int* count);
1048
1049 /**
1050  * @brief Gets current audio type.
1051  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
1052  * @privlevel public
1053  * @privilege %http://tizen.org/privilege/recorder
1054  * @remarks The @a audio_type must be released using free() when it is no longer required.
1055  *
1056  * @param[in] audio_type Current audio type (e.g. #VCE_AUDIO_ID_BLUETOOTH or #VCE_AUDIO_ID_WIFI)
1057  * @return the value greater than 0 on success, otherwise a negative error value
1058  * @retval #VCE_ERROR_NONE Successful
1059  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
1060  * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
1061  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
1062  */
1063 int vce_get_audio_type(char** audio_type);
1064
1065 /**
1066  * @brief Sets private data to a voice manager client.
1067  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
1068  * @privlevel public
1069  * @privilege %http://tizen.org/privilege/recorder \n
1070  *            %http://tizen.org/privilege/appmanager.launch (Since 7.0) \n
1071  *            %http://tizen.org/privilege/datasharing (Since 7.0)
1072  * @remarks To use this function, privileges of appmanager.launch and datasharing should be included since 7.0.
1073  *
1074  * @param[in] key Private key
1075  * @param[in] data Private data
1076  * @return 0 on success, otherwise a negative error value.
1077  * @retval #VCE_ERROR_NONE Successful
1078  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
1079  * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
1080  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
1081  * @retval #VCE_ERROR_INVALID_STATE Invalid state
1082  * @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
1083  * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
1084  */
1085 int vce_set_private_data(const char* key, const char* data);
1086
1087 /**
1088  * @brief Gets private data from a voice manager client.
1089  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
1090  * @privlevel public
1091  * @privilege %http://tizen.org/privilege/recorder \n
1092  *            %http://tizen.org/privilege/appmanager.launch (Since 7.0) \n
1093  *            %http://tizen.org/privilege/datasharing (Since 7.0)
1094  * @remarks To use this function, privileges of appmanager.launch and datasharing should be included since 7.0. \n
1095  *          The @a data must be released using free() when it is no longer required.
1096  *
1097  * @param[in] key Private key
1098  * @param[out] data Private data
1099  * @return 0 on success, otherwise a negative error value.
1100  * @retval #VCE_ERROR_NONE Successful
1101  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
1102  * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
1103  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
1104  * @retval #VCE_ERROR_INVALID_STATE Invalid state
1105  * @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
1106  * @retval #VCE_ERROR_OPERATION_FAILED Operation failed
1107  */
1108 int vce_get_private_data(const char* key, char** data);
1109
1110 /**
1111  * @brief Starts recording voice.
1112  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
1113  * @privlevel public
1114  * @privilege %http://tizen.org/privilege/recorder \n
1115  *            %http://tizen.org/privilege/appmanager.launch (Since 7.0) \n
1116  *            %http://tizen.org/privilege/datasharing (Since 7.0)
1117  * @remarks To use this function, privileges of appmanager.launch and datasharing should be included since 7.0.
1118  *
1119  * @return 0 on success, otherwise a negative error value.
1120  * @retval #VCE_ERROR_NONE Successful
1121  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
1122  * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
1123  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
1124  * @retval #VCE_ERROR_RECORDER_BUSY Busy recorder
1125  */
1126 int vce_start_recording(void);
1127
1128 /**
1129  * @brief Stops recording voice.
1130  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
1131  * @privlevel public
1132  * @privilege %http://tizen.org/privilege/recorder
1133  *
1134  * @return 0 on success, otherwise a negative error value.
1135  * @retval #VCE_ERROR_NONE Successful
1136  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
1137  * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
1138  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
1139  */
1140 int vce_stop_recording(void);
1141
1142 /**
1143  * @brief Sends audio formats necessary for playing TTS feedback.
1144  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
1145  * @privlevel public
1146  * @privilege %http://tizen.org/privilege/appmanager.launch (Since 7.0) \n
1147  *            %http://tizen.org/privilege/datasharing (Since 7.0)
1148  * @remarks To use this function, privileges of appmanager.launch and datasharing should be included since 7.0.
1149  *
1150  * @param[in] rate A sampling rate
1151  * @param[in] channel The audio channel
1152  * @param[in] audio_type The audio type
1153  *
1154  * @return 0 on success, otherwise a negative error value.
1155  * @retval #VCE_ERROR_NONE Successful
1156  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
1157  * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
1158  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
1159  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
1160  * @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
1161  */
1162 int vce_send_feedback_audio_format(int rate, vce_audio_channel_e channel, vce_audio_type_e audio_type);
1163
1164 /**
1165  * @brief Sends audio streaming necessary for playing TTS feedback.
1166  * @since_tizen @if MOBILE 4.0 @elseif WEARABLE 5.0 @endif
1167  * @privlevel public
1168  * @privilege %http://tizen.org/privilege/appmanager.launch (Since 7.0) \n
1169  *            %http://tizen.org/privilege/datasharing (Since 7.0)
1170  * @remarks To use this function, privileges of appmanager.launch and datasharing should be included since 7.0.
1171  *
1172  * @param[in] event A feedback event
1173  * @param[in] buffer The feedback data
1174  * @param[in] len The length of the feedback data
1175  *
1176  * @return 0 on success, otherwise a negative error value.
1177  * @retval #VCE_ERROR_NONE Successful
1178  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
1179  * @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
1180  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
1181  * @retval #VCE_ERROR_OPERATION_FAILED Operation failure
1182  * @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
1183  */
1184 int vce_send_feedback_streaming(vce_feedback_event_e event, char* buffer, int len);
1185
1186 /**
1187  * @brief Sets a callback function for getting the request of sending TTS feedback from the engine service user.
1188  * @since_tizen 5.0
1189  *
1190  * @param[in] callback_func Callback function to be registered
1191  * @param[in] user_data The user data passed to the callback function
1192  *
1193  * @return 0 on success, otherwise a negative error value
1194  * @retval #VCE_ERROR_NONE Successful
1195  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
1196  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
1197  *
1198  * @see vce_request_tts_cb()
1199  * @see vce_unset_request_tts_cb()
1200  */
1201 int vce_set_request_tts_cb(vce_request_tts_cb callback_func, void* user_data);
1202
1203 /**
1204  * @brief Unsets the TTS feedback request callback function.
1205  * @since_tizen 5.0
1206  *
1207  * @return 0 on success, otherwise a negative error value
1208  * @retval #VCE_ERROR_NONE Successful
1209  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
1210  *
1211  * @see vce_set_request_tts_cb()
1212  */
1213 int vce_unset_request_tts_cb(void);
1214
1215 /**
1216  * @brief Sets a callback function for getting the request of canceling TTS feedback from the engine service user.
1217  * @since_tizen 5.0
1218  *
1219  * @param[in] callback_func Callback function to be registered
1220  * @param[in] user_data The user data passed to the callback function
1221  *
1222  * @return 0 on success, otherwise a negative error value
1223  * @retval #VCE_ERROR_NONE Successful
1224  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
1225  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
1226  *
1227  * @see vce_cancel_tts_cb()
1228  * @see vce_unset_cancel_tts_cb()
1229  */
1230 int vce_set_cancel_tts_cb(vce_cancel_tts_cb callback_func, void* user_data);
1231
1232 /**
1233  * @brief Unsets the TTS feedback cancellation callback function.
1234  * @since_tizen 5.0
1235  *
1236  * @return 0 on success, otherwise a negative error value
1237  * @retval #VCE_ERROR_NONE Successful
1238  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
1239  *
1240  * @see vce_set_cancel_tts_cb()
1241  */
1242 int vce_unset_cancel_tts_cb(void);
1243
1244 /**
1245  * @brief Sets a callback function for sending TTS audio format to the engine service user.
1246  * @since_tizen 5.0
1247  *
1248  * @param[in] callback_func Callback function to be registered
1249  * @param[in] user_data The user data passed to the callback function
1250  *
1251  * @return 0 on success, otherwise a negative error value
1252  * @retval #VCE_ERROR_NONE Successful
1253  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
1254  * @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
1255  *
1256  * @see vce_tts_audio_format_request_cb()
1257  * @see vce_unset_get_tts_audio_format_cb()
1258  */
1259 int vce_set_tts_audio_format_request_cb(vce_tts_audio_format_request_cb callback_func, void* user_data);
1260
1261 /**
1262  * @brief Unsets the TTS audio format request callback function.
1263  * @since_tizen 5.0
1264  *
1265  * @return 0 on success, otherwise a negative error value
1266  * @retval #VCE_ERROR_NONE Successful
1267  * @retval #VCE_ERROR_NOT_SUPPORTED Not supported
1268  *
1269  * @see vce_set_tts_audio_format_request_cb()
1270  */
1271 int vce_unset_get_tts_audio_format_cb(void);
1272
1273
1274 #ifdef __cplusplus
1275 }
1276 #endif
1277
1278 /**
1279  * @}
1280  */
1281
1282 #endif /* __VCE_H__ */
1283
1284