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