Tizen Native API  4.0
Voice control engine

The Voice control engine APIs provide functions to operate Voice-Control Engine.

Required Header

#include <vce.h>

Overview

Voice-Control-Engine (below VCE) is an engine for recognize the sound data recorded by the user and send the result as a predefined command. Using the Voice control engine APIs, VCE developers can provide VCE service users, who want to apply VCE, with functions necessary to operate the engine. According to the indispensability of VCE services, there are two ways to provide them to the users.

A. Required VCE services
These services are indispensable to operate VCE. Therefore, the VCE developers MUST implement callback functions corresponding to the required VCE services. The following is a list of the callback functions.

vce_get_info_cb() Called when the engine service user requests the basic information of VCE.
vce_get_recording_format_cb() Called when the engine service user requests the recording format of VCE.
vce_foreach_supported_languages_cb() Called when the engine service user retrieves all supported languages of VC engine.
vce_is_language_supported_cb() Called when the engine service user retrieves all supported languages of VCE.
vce_initialize_cb() Called when the engine service user initializes VCE.
vce_deinitialize_cb() Called when the engine service user deinitializes VCE.
vce_set_language_cb() Called when the engine service user sets language.
vce_set_commands_cb() Called when the engine service user sets command list before recognition.
vce_unset_commands_cb() Called when the engine service user unsets command list for reset.
vce_start_cb() Called when the engine service user starts recognition.
vce_set_recording_data_cb() Called when the engine service user sets recording data for speech recognition from recorder.
vce_stop_cb() Called when the engine service user stops to get the result of recognition.
vce_cancel_cb() Called when the engine service user cancels the recognition process.
vce_set_audio_type_cb() Called when the engine service user sets audio recording type.
vce_set_server_dialog_cb() Called when the engine service user sets app id which is want to ask server dialog.
vce_set_domain_cb() Called when the engine service user sets domain (agent or device type).
vce_process_text_cb() Called when the engine service user requests process text.
vce_process_list_event_cb() Called when the engine service user requests list event.
vce_process_haptic_event_cb() Called when the engine service user requests haptic event.

The VCE developers can register the above callback functions at a time with using a structure 'vce_request_callback_s' and an API 'vce_main()'. To operate VCE, the following steps should be used:
1. Create a structure 'vce_request_callback_s' 2. Implement callback functions. (NOTE that the callback functions should return appropriate values in accordance with the instruction. If the callback function returns an unstated value, VCE framework will handle it as VCE_ERROR_OPERATION_FAILED.)
3. Register callback functions using 'vce_main()'. (The registered callback functions will be invoked when the VCE service users request the VCE services.)
4. Use 'service_app_main()' for working VCE.

B. Optional VCE services
Unlike the required VCE services, these services are optional to operate VCE. The followings are optional VCE services.

  • receive/provide the private data

If the VCE developers want to provide the above services, use the following APIs and implement the corresponding callback functions:

FUNCTION DESCRIPTION CORRESPONDING CALLBACK
vce_set_private_data_set_cb() Sets a callback function for setting the private data to the engine service. vce_private_data_set_cb()
vce_set_private_data_requested_cb() Sets a callback function for requesting the private data to the engine service. vce_private_data_requested_cb()
vce_set_nlu_base_info_requested_cb() Sets a callback function for requesting the NLU base information to the engine service. vce_nlu_base_info_requested_cb()

Using the above APIs, the VCE developers can register the optional callback functions respectively. (For normal operation, put those APIs before 'service_app_main()' starts.)

Unlike callback functions, the following APIs are functions for getting and sending data. The VCE developers can use these APIs when they implement VCE services:

FUNCTION DESCRIPTION
vce_send_result() Sends the results to the engine service user.
vce_send_asr_result() Sends the ASR result to the engine service user.
vce_send_nlg_result() Sends the NLG (Natural Language Generation) result to the engine service user.
vce_send_error() Sends the error to the engine service user.
vce_get_foreach_command() Retrieves all commands using callback function.
vce_get_command_count() Gets command length.
vce_get_audio_type() Gets current audio type.
vce_set_private_data() Sets private data to a voice manager client.
vce_get_private_data() Gets private data from a voice manager client.
vce_start_recording() Starts recording voice.
vce_stop_recording() Stops recording voice.

Related Features

This API is related with the following features:

  • http://tizen.org/feature/microphone
  • http://tizen.org/feature/speech.control
    It is recommended to design feature related codes in your application for reliability.
    You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
    To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
    More details on featuring your application can be found from Feature Element.

Functions

int vce_main (int argc, char **argv, vce_request_callback_s *callback)
 Starts the main function for Voice Control (VC) engine.
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)
 Sends the results to the engine service user.
int vce_send_asr_result (vce_asr_result_event_e event, const char *asr_result, void *user_data)
 Sends the ASR result to the engine service user.
int vce_send_nlg_result (const char *nlg_result, void *user_data)
 Sends the NLG (Natural Language Generation) result to the engine service user.
int vce_send_specific_engine_result (const char *engine_app_id, const char *event, const char *result, void *user_info)
 Sends the specific engine result to the engine service user.
int vce_send_error (vce_error_e error, const char *msg, void *user_data)
 Sends the error to the engine service user.
int vce_set_private_data_set_cb (vce_private_data_set_cb callback_func)
 Sets a callback function for setting the private data to the engine service.
int vce_set_private_data_requested_cb (vce_private_data_requested_cb callback_func)
 Sets a callback function for requesting the private data to the engine service.
int vce_set_nlu_base_info_requested_cb (vce_nlu_base_info_requested_cb callback_func)
 Sets a callback function for requesting the NLU base information to the engine service.
int vce_set_specific_engine_request_cb (vce_specific_engine_request_cb callback_func)
 Sets a callback function for getting the engine service request.
int vce_unset_specific_engine_request_cb (void)
 Unsets the engine service request callback function.
int vce_get_foreach_command (vce_cmd_h vce_command, vce_command_cb callback, void *user_data)
 Retrieves all commands using callback function.
int vce_get_command_count (vce_cmd_h vce_command, int *count)
 Gets command length.
int vce_get_audio_type (char **audio_type)
 Gets current audio type.
int vce_set_private_data (const char *key, const char *data)
 Sets private data to a voice manager client.
int vce_get_private_data (const char *key, char **data)
 Gets private data from a voice manager client.
int vce_start_recording (void)
 Starts recording voice.
int vce_stop_recording (void)
 Stops recording voice.
int vce_send_feedback_audio_format (int rate, vce_audio_channel_e channel, vce_audio_type_e audio_type)
 Sends audio formats necessary for playing TTS feedback.
int vce_send_feedback_streaming (vce_feedback_event_e event, char *buffer, int len)
 Sends audio streaming necessary for playing TTS feedback.

Typedefs

typedef struct vce_cmd_s * vce_cmd_h
 A structure of handle for VC command.
typedef bool(* vce_supported_language_cb )(const char *language, void *user_data)
 Called when VC engine informs the engine service user about whole supported languages.
typedef int(* vce_initialize_cb )(void)
 Called when the engine service user initializes Voice Control (VC) engine.
typedef int(* vce_deinitialize_cb )(void)
 Called when the engine service user deinitializes VC engine.
typedef int(* vce_get_recording_format_cb )(const char *audio_id, vce_audio_type_e *types, int *rate, int *channels)
 Called when the engine service user requests the recording format of VC engine.
typedef int(* vce_foreach_supported_languages_cb )(vce_supported_language_cb callback, void *user_data)
 Called when the engine service user retrieves all supported languages of VC engine.
typedef bool(* vce_is_language_supported_cb )(const char *language)
 Called when the engine service user checks whether a language is supported or not.
typedef int(* vce_set_language_cb )(const char *language)
 Called when the engine service user sets language.
typedef int(* vce_set_commands_cb )(vce_cmd_h vc_command)
 Called when the engine service user sets command list before recognition.
typedef int(* vce_unset_commands_cb )(void)
 Called when the engine service user unsets command list for reset.
typedef int(* vce_start_cb )(bool stop_by_silence)
 Called when the engine service user starts recognition.
typedef int(* vce_set_recording_data_cb )(const void *data, unsigned int length, vce_speech_detect_e *speech_detected)
 Called when the engine service user sets recording data for speech recognition from recorder.
typedef int(* vce_stop_cb )(void)
 Called when the engine service user stops to get the result of recognition.
typedef int(* vce_cancel_cb )(void)
 Called when the engine service user cancels the recognition process.
typedef int(* vce_set_audio_type_cb )(const char *audio_type)
 Called when the engine service user sets audio recording type.
typedef int(* vce_set_server_dialog_cb )(const char *app_id, const char *credential)
 Called when the engine service user sets app id which is want to ask server dialog.
typedef int(* vce_set_domain_cb )(const char *domain)
 Called when the engine service user sets domain (agent or device type).
typedef int(* vce_nlu_base_info_requested_cb )(const char *key, char **value)
 Called when the engine service user requests essential value from NLU result.
typedef int(* vce_specific_engine_request_cb )(const char *engine_app_id, const char *event, const char *request)
 Called when client gets the specific engine's request from the engine service user.
typedef int(* vce_private_data_set_cb )(const char *key, const char *data)
 Called when the engine service user sets private data between app and engine.
typedef int(* vce_private_data_requested_cb )(const char *key, char **data)
 Called when the engine service user requests private data between app and engine.
typedef int(* vce_process_text_cb )(const char *text)
 Called when the engine service user requests process text.
typedef int(* vce_process_list_event_cb )(const char *event)
 Called when the engine service user requests list event.
typedef int(* vce_process_haptic_event_cb )(const char *event)
 Called when the engine service user requests haptic event.
typedef int(* vce_get_info_cb )(char **engine_uuid, char **engine_name, char **engine_settings_app_id, bool *use_network)
 Called when the engine service user requests the base information of VC engine.
typedef bool(* vce_command_cb )(int id, int type, int format, const char *command, const char *param, int domain, void *user_data)
 Called to retrieve the commands.

Defines

#define VCE_COMMAND_TYPE_FOREGROUND   1
 Definition for foreground command type.
#define VCE_COMMAND_TYPE_BACKGROUND   2
 Definition for background command type.
#define VCE_COMMAND_TYPE_WIDGET   3
 Definition for widget command type.
#define VCE_COMMAND_TYPE_SYSTEM   4
 Definition for system command type.
#define VCE_COMMAND_TYPE_SYSTEM_BACKGROUND   5
 Definition for system background command type.
#define VCE_COMMAND_TYPE_EXCLUSIVE   6
 Definitions for exclusive command type.
#define VCE_AUDIO_ID_BLUETOOTH   "VC_AUDIO_ID_BLUETOOTH"
 Definition of bluetooth audio id.
#define VCE_AUDIO_ID_WIFI   "VC_AUDIO_ID_WIFI"
 Definition of Wi-Fi audio id.
#define VC_RESULT_MESSAGE_NONE   "vc.result.message.none"
 Definition for none message.
#define VC_RESULT_MESSAGE_ERROR_TOO_LOUD   "vc.result.message.error.too.loud"
 Definition for failed recognition because the speech is too loud to listen.

Define Documentation

#define VC_RESULT_MESSAGE_ERROR_TOO_LOUD   "vc.result.message.error.too.loud"

Definition for failed recognition because the speech is too loud to listen.

Since :
4.0
#define VC_RESULT_MESSAGE_NONE   "vc.result.message.none"

Definition for none message.

Since :
4.0
#define VCE_AUDIO_ID_BLUETOOTH   "VC_AUDIO_ID_BLUETOOTH"

Definition of bluetooth audio id.

Since :
4.0 Bluetooth audio id
#define VCE_AUDIO_ID_WIFI   "VC_AUDIO_ID_WIFI"

Definition of Wi-Fi audio id.

Since :
4.0 Wi-Fi audio id

Definition for background command type.

Since :
4.0

Definitions for exclusive command type.

Since :
4.0

Definition for foreground command type.

Since :
4.0
#define VCE_COMMAND_TYPE_SYSTEM   4

Definition for system command type.

Since :
4.0

Definition for system background command type.

Since :
4.0
#define VCE_COMMAND_TYPE_WIDGET   3

Definition for widget command type.

Since :
4.0

Typedef Documentation

typedef int(* vce_cancel_cb)(void)

Called when the engine service user cancels the recognition process.

Since :
4.0
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful.
VCE_ERROR_INVALID_STATEInvalid state.
Precondition:
vce_start() is successful.
See also:
vce_start()
vce_stop()
typedef struct vce_cmd_s* vce_cmd_h

A structure of handle for VC command.

Since :
4.0
typedef bool(* vce_command_cb)(int id, int type, int format, const char *command, const char *param, int domain, void *user_data)

Called to retrieve the commands.

Since :
4.0
Remarks:
The command, param can be used only in the callback. To use outside, make a copy.
Parameters:
[in]idcommand id
[in]typecommand type
[in]formatcommand format
[in]commandcommand text
[in]paramparameter text
[in]domaincommand domain
[in]user_dataThe user data passed from the foreach function
Returns:
true to continue with the next iteration of the loop,
false to break out of the loop.
Precondition:
vce_get_foreach_command() will invoke this callback.
See also:
vce_get_foreach_command()
typedef int(* vce_deinitialize_cb)(void)

Called when the engine service user deinitializes VC engine.

Since :
4.0
Remarks:
This callback function is mandatory and must be registered using vce_main().
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_STATENot initialized
See also:
vce_initialize_cb()
typedef int(* vce_foreach_supported_languages_cb)(vce_supported_language_cb callback, void *user_data)

Called when the engine service user retrieves all supported languages of VC engine.

Since :
4.0
Remarks:
This callback function is mandatory and must be registered using vce_main().
Parameters:
[in]callbacka callback function
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_INVALID_STATENot initialized
Postcondition:
This function invokes vce_supported_language_cb() repeatedly for getting supported languages.
See also:
vce_supported_language_cb()
typedef int(* vce_get_info_cb)(char **engine_uuid, char **engine_name, char **engine_settings_app_id, bool *use_network)

Called when the engine service user requests the base information of VC engine.

Since :
4.0
Remarks:
This callback function is mandatory and must be registered using vce_main(). The engine_uuid is managed by the platform and will be released when this callback function is completed. The engine_name is managed by the platform and will be released when this callback function is completed. The engine_settings_app_id is managed by the platform and will be released when this callback function is completed. The use_network is managed by the platform and will be released when this callback function is completed. In order to upload the engine to Tizen Appstore, both the service app and the UI app (engine settings) are necessary. Therefore, engine_settings_app_id should be set to the application ID of the UI application. If there is no UI application, then engine_settings_app_id should be set to NULL.
Parameters:
[out]engine_uuidThe engine id
[out]engine_nameThe engine name
[out]engine_settings_app_idThe ID of the engine settings application (the UI application)
[out]use_networktrue to need network false not to need network.
Returns:
0 on success, otherwise a negative error code on failure
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_OPERATION_FAILEDOperation failure
typedef int(* vce_get_recording_format_cb)(const char *audio_id, vce_audio_type_e *types, int *rate, int *channels)

Called when the engine service user requests the recording format of VC engine.

Since :
4.0
Remarks:
This callback function is mandatory and must be registered using vce_main(). The audio_id can be used only in the callback. To use outside, make a copy. The types is managed by the platform and will be released when this callback function is completed. The rate is managed by the platform and will be released when this callback function is completed. The channels is managed by the platform and will be released when this callback function is completed.
Parameters:
[in]audio_idThe audio device id. (e.g. VCE_AUDIO_ID_BLUETOOTH or VCE_AUDIO_ID_WIFI)
[out]typesThe format used by the recorder.
[out]rateThe sample rate used by the recorder.
[out]channelsThe number of channels used by the recorder.
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERNot initialized
typedef int(* vce_initialize_cb)(void)

Called when the engine service user initializes Voice Control (VC) engine.

Since :
4.0
Remarks:
This callback function is mandatory and must be registered using vce_main().
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_INVALID_STATEAlready initialized
VCE_ERROR_OPERATION_FAILEDOperation failed
See also:
vce_deinitialize_cb()
typedef bool(* vce_is_language_supported_cb)(const char *language)

Called when the engine service user checks whether a language is supported or not.

Since :
4.0
Remarks:
This callback function is mandatory and must be registered using vce_main(). The language can be used only in the callback. To use outside, make a copy.
Parameters:
[in]languageA language
Returns:
true = supported,
false = not supported.
typedef int(* vce_nlu_base_info_requested_cb)(const char *key, char **value)

Called when the engine service user requests essential value from NLU result.

Since :
4.0
Remarks:
The key can be used only in the callback. To use outside, make a copy. The value is managed by the platform and will be released when this callback function is completed.
Parameters:
[in]keyNLU base info key.
[out]valueNLU base info value.
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful.
VCE_ERROR_NOT_SUPPORTED_FEATURENot supported feature.
typedef int(* vce_private_data_requested_cb)(const char *key, char **data)

Called when the engine service user requests private data between app and engine.

Since :
4.0
Remarks:
The key can be used only in the callback. To use outside, make a copy. The data is managed by the platform and will be released when this callback function is completed.
Parameters:
[in]keyPrivate key.
[out]dataPrivate data.
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful.
VCE_ERROR_NOT_SUPPORTED_FEATURENot supported feature.
typedef int(* vce_private_data_set_cb)(const char *key, const char *data)

Called when the engine service user sets private data between app and engine.

Since :
4.0
Remarks:
The key, data can be used only in the callback. To use outside, make a copy.
Parameters:
[in]keyPrivate key.
[in]dataPrivate data.
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful.
VCE_ERROR_NOT_SUPPORTED_FEATURENot supported feature.
typedef int(* vce_process_haptic_event_cb)(const char *event)

Called when the engine service user requests haptic event.

Since :
4.0
Remarks:
The event can be used only in the callback. To use outside, make a copy.
Parameters:
[in]eventRequested haptic event
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful.
VCE_ERROR_NOT_SUPPORTED_FEATURENot supported feature.
typedef int(* vce_process_list_event_cb)(const char *event)

Called when the engine service user requests list event.

Since :
4.0
Remarks:
The event can be used only in the callback. To use outside, make a copy.
Parameters:
[in]eventRequested list event
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful.
VCE_ERROR_NOT_SUPPORTED_FEATURENot supported feature.
typedef int(* vce_process_text_cb)(const char *text)

Called when the engine service user requests process text.

Since :
4.0
Remarks:
The text can be used only in the callback. To use outside, make a copy.
Parameters:
[in]textRequested text
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful.
VCE_ERROR_NOT_SUPPORTED_FEATURENot supported feature.
typedef int(* vce_set_audio_type_cb)(const char *audio_type)

Called when the engine service user sets audio recording type.

Since :
4.0
Remarks:
The audio_type can be used only in the callback. To use outside, make a copy.
Parameters:
[in]audio_typeCurrent audio type (e.g. VCE_AUDIO_ID_BLUETOOTH or VCE_AUDIO_ID_WIFI)
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful.
VCE_ERROR_NOT_SUPPORTED_FEATURENot supported feature.
typedef int(* vce_set_commands_cb)(vce_cmd_h vc_command)

Called when the engine service user sets command list before recognition.

Since :
4.0
Remarks:
This function should set commands via vcd_foreach_command(). The vc_command should not be released. The vc_command can be used only in the callback. To use outside, make a copy.
Parameters:
[in]vc_commandcommand handle. The vc_command can be used only in the callback. To use outside, make a copy.
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_INVALID_STATEInvalid state
VCE_ERROR_OPERATION_FAILEDOperation failed
VCE_ERROR_NOT_SUPPORTED_FEATURENot supported command type
Postcondition:
vce_start() is called after this function is successful.
See also:
vce_start()
vcd_foreach_command()
vce_unset_commands()
vce_get_command_count()
typedef int(* vce_set_domain_cb)(const char *domain)

Called when the engine service user sets domain (agent or device type).

Since :
4.0
Remarks:
The domain can be used only in the callback. To use outside, make a copy.
Parameters:
[in]domainAgent (e.g. "music", "news", etc) or device type (e.g. "tv", "mobile", etc) corresponding to the command
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful.
VCE_ERROR_NOT_SUPPORTED_FEATURENot supported feature
typedef int(* vce_set_language_cb)(const char *language)

Called when the engine service user sets language.

Since :
4.0
Remarks:
The language can be used only in the callback. To use outside, make a copy.
Parameters:
[in]languageA language.
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_LANGUAGEInvalid language
VCE_ERROR_INVALID_STATENot initialized
VCE_ERROR_NOT_SUPPORTED_FEATURENot supported feature
typedef int(* vce_set_recording_data_cb)(const void *data, unsigned int length, vce_speech_detect_e *speech_detected)

Called when the engine service user sets recording data for speech recognition from recorder.

Since :
4.0
Remarks:
This function should be returned immediately after recording data copy. The data can be used only in the callback. To use outside, make a copy. The speech_detected should not be released. This is managed by the platform.
Parameters:
[in]dataA recording data
[in]lengthA length of recording data
[out]speech_detectedThe status of speech (e.g. VCE_SPEECH_DETECT_BEGIN or VCE_SPEECH_DETECT_END). The speech_detected can be used only in the callback. To use outside, make a copy.
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_INVALID_STATEInvalid state
VCE_ERROR_OPERATION_FAILEDOperation failed
Precondition:
vce_start() is successful.
See also:
vce_start()
vce_cancel()
vce_stop()
typedef int(* vce_set_server_dialog_cb)(const char *app_id, const char *credential)

Called when the engine service user sets app id which is want to ask server dialog.

Since :
4.0
Remarks:
The app_id and credential can be used only in the callback. To use outside, make a copy.
Parameters:
[in]app_idApp id which is to want to ask server dialog.
[in]credentialCredential key.
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful.
VCE_ERROR_NOT_SUPPORTED_FEATURENot supported feature.
VCE_ERROR_PERMISSION_DENIEDPermission denied.
typedef int(* vce_specific_engine_request_cb)(const char *engine_app_id, const char *event, const char *request)

Called when client gets the specific engine's request from the engine service user.

Since :
4.0
Remarks:
The engine_app_id is managed by the platform and will be released when this callback function is completed. The event is managed by the platform and will be released when this callback function is completed. The request is managed by the platform and will be released when this callback function is completed.
Parameters:
[in]engine_app_idThe specific engine's app id
[in]eventThe specific engine event type
[in]requestThe specific engine request
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_OPERATION_FAILEDOperation failure
Precondition:
An application registers callback function using vce_set_specific_engine_request_cb().
See also:
vce_set_specific_engine_request_cb()
vce_unset_specific_engine_request_cb()
typedef int(* vce_start_cb)(bool stop_by_silence)

Called when the engine service user starts recognition.

Since :
4.0
Remarks:
This callback function is mandatory and must be registered using vce_main().
Parameters:
[in]stop_by_silenceSilence detection option. true to detect the silence, false not to detect the silence
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_INVALID_STATEInvalid state
VCE_ERROR_INVALID_LANGUAGEInvalid language
VCE_ERROR_OUT_OF_NETWORKOut of network
VCE_ERROR_OPERATION_FAILEDOperation failed
Precondition:
vcd_foreach_command() is successful.
See also:
vce_set_recording_data_cb()
vce_stop()
vce_cancel()
typedef int(* vce_stop_cb)(void)

Called when the engine service user stops to get the result of recognition.

Since :
4.0
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_STATEInvalid state
VCE_ERROR_OPERATION_FAILEDOperation failed
VCE_ERROR_OUT_OF_NETWORKOut of network
Precondition:
vce_set_recording_data() is successful.
See also:
vce_start()
vce_set_recording_data()
vce_result_cb()
vce_cancel()
typedef bool(* vce_supported_language_cb)(const char *language, void *user_data)

Called when VC engine informs the engine service user about whole supported languages.

This callback function is implemented by the engine service user. Therefore, the engine developer does NOT have to implement this callback function.

Since :
4.0
Remarks:
This callback function is called by vce_foreach_supported_languages_cb() to retrieve the whole supported language list. The user_data must be transferred from vce_foreach_supported_languages_cb(). The language can be used only in the callback. To use outside, make a copy.
Parameters:
[in]languageA language is specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code
For example, "ko_KR" for Korean, "en_US" for American English.
[in]user_dataThe user data passed from the foreach function
Returns:
true to continue with the next iteration of the loop
false to break out of the loop
Precondition:
vce_foreach_supported_languages() will invoke this callback.
See also:
vce_foreach_supported_languages()
typedef int(* vce_unset_commands_cb)(void)

Called when the engine service user unsets command list for reset.

Since :
4.0
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_INVALID_STATEInvalid state
VCE_ERROR_OPERATION_FAILEDOperation failed
VCE_ERROR_NOT_SUPPORTED_FEATURENot supported feature
See also:
vce_set_commands_cb()

Enumeration Type Documentation

Enumerations of ASR result events.

Since :
4.0
Enumerator:
VCE_ASR_RESULT_EVENT_FINAL_RESULT 

Event when the ASR result is last data or ASR result is only one result

VCE_ASR_RESULT_EVENT_PARTIAL_RESULT 

Event when the ASR result exist, not first and not last

VCE_ASR_RESULT_EVENT_ERROR 

Event when the ASR result is failed

Enumerations of audio channels.

Since :
4.0
Enumerator:
VCE_AUDIO_CHANNEL_MONO 

1 channel, mono

VCE_AUDIO_CHANNEL_STEREO 

2 channels, stereo

Enumerations of audio type.

Since :
4.0
Enumerator:
VCE_AUDIO_TYPE_PCM_S16_LE 

Signed 16bit audio type, Little endian

VCE_AUDIO_TYPE_PCM_U8 

Unsigned 8bit audio type

Enumerations of command type.

Since :
4.0
Enumerator:
VCE_COMMAND_FORMAT_FIXED 

Fixed command

VCE_COMMAND_FORMAT_FIXED_AND_VFIXED 

Fixed command + variable-fixed command

VCE_COMMAND_FORMAT_VFIXED_AND_FIXED 

variable-fixed command + Fixed command

VCE_COMMAND_FORMAT_FIXED_AND_NONFIXED 

Fixed command + Non-fixed command

VCE_COMMAND_FORMAT_NONFIXED_AND_FIXED 

Non-fixed command + Fixed command

VCE_COMMAND_FORMAT_ACTION 

Action command

VCE_COMMAND_FORMAT_PARTIAL 

Partial matched command

Enumerations of error codes.

Since :
4.0
Enumerator:
VCE_ERROR_NONE 

Successful

VCE_ERROR_OUT_OF_MEMORY 

Out of Memory

VCE_ERROR_IO_ERROR 

I/O error

VCE_ERROR_INVALID_PARAMETER 

Invalid parameter

VCE_ERROR_OUT_OF_NETWORK 

Out of network

VCE_ERROR_RECORDER_BUSY 

Busy resource

VCE_ERROR_NOT_SUPPORTED 

VC Engine NOT supported

VCE_ERROR_INVALID_STATE 

Invalid state

VCE_ERROR_INVALID_LANGUAGE 

Invalid language

VCE_ERROR_OPERATION_FAILED 

Operation failed

VCE_ERROR_PERMISSION_DENIED 

Permission denied

VCE_ERROR_NOT_SUPPORTED_FEATURE 

Not supported feature of current engine

Enumeration for TTS feedback events.

Since :
4.0
Enumerator:
VCE_FEEDBACK_EVENT_FAIL 

Failed

VCE_FEEDBACK_EVENT_START 

Start event

VCE_FEEDBACK_EVENT_CONTINUE 

Continue event

VCE_FEEDBACK_EVENT_FINISH 

Finish event

Enumerations of callback event.

Since :
4.0
Enumerator:
VCE_RESULT_EVENT_SUCCESS 

Event when the recognition full result is ready

VCE_RESULT_EVENT_REJECTED 

Event when the recognition result is rejected

VCE_RESULT_EVENT_ERROR 

Event when the recognition has failed

Enumerations of speech detect.

Since :
4.0
Enumerator:
VCE_SPEECH_DETECT_NONE 

No event

VCE_SPEECH_DETECT_BEGIN 

Begin of speech detected

VCE_SPEECH_DETECT_END 

End of speech detected


Function Documentation

int vce_get_audio_type ( char **  audio_type)

Gets current audio type.

Since :
4.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Remarks:
The audio_type must be released using free() when it is no longer required.
Parameters:
[in]audio_typeCurrent audio type (e.g. VCE_AUDIO_ID_BLUETOOTH or VCE_AUDIO_ID_WIFI)
Returns:
the value greater than 0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_PERMISSION_DENIEDPermission denied
VCE_ERROR_NOT_SUPPORTEDNot supported
int vce_get_command_count ( vce_cmd_h  vce_command,
int *  count 
)

Gets command length.

Since :
4.0
Parameters:
[in]vce_commandThe handle to be passed to the vce_set_commands() function
[out]countThe command count value
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_OPERATION_FAILEDOperation failure
See also:
vce_set_commands()
int vce_get_foreach_command ( vce_cmd_h  vce_command,
vce_command_cb  callback,
void *  user_data 
)

Retrieves all commands using callback function.

Since :
4.0
Parameters:
[in]vce_commandThe handle to be passed to the vce_set_commands() function
[in]callbackThe callback function to invoke
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_OPERATION_FAILEDOperation failure
VCE_ERROR_INVALID_STATEInvalid state
Postcondition:
This function invokes vce_command_cb() repeatedly for getting commands.
See also:
vce_foreach_command_cb()
vce_set_commands()
int vce_get_private_data ( const char *  key,
char **  data 
)

Gets private data from a voice manager client.

Since :
4.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Remarks:
The data must be released using free() when it is no longer required.
Parameters:
[in]keyPrivate key
[out]dataPrivate data
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_OUT_OF_MEMORYOut of Memory
VCE_ERROR_PERMISSION_DENIEDPermission denied
VCE_ERROR_NOT_SUPPORTEDNot supported
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_INVALID_STATEInvalid state
VCE_ERROR_OPERATION_FAILEDOperation failed
int vce_main ( int  argc,
char **  argv,
vce_request_callback_s callback 
)

Starts the main function for Voice Control (VC) engine.

This function is the main function for operating VC engine.

Since :
4.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Remarks:
The service_app_main() should be used for working the engine after this function.
Parameters:
[in]argcThe argument count(original)
[in]argvThe argument(original)
[in]callbackThe structure of engine request callback function
Returns:
This function returns zero on success, or negative with error code on failure
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_OUT_OF_MEMORYOut of Memory
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_PERMISSION_DENIEDPermission denied
VCE_ERROR_NOT_SUPPORTEDNot supported
VCE_ERROR_OPERATION_FAILEDOperation failed
Precondition:
The vce_get_engine_info() should be successful.
See also:
vce_get_engine_info()
vce_unload_engine()
vce_request_callback_s
#include <vce.h>

// Required callback functions - MUST BE IMPLEMENTED
static int vce_default_initialize();
static int vce_default_deinitialize(void);

static int vce_default_get_info(char** engine_uuid, char** engine_name, char** engine_setting, bool* use_network);
static int vce_default_get_recording_format(const char* audio_id, vce_audio_type_e* types, int* rate, int* channels);
static int vce_default_foreach_langs(vce_supported_language_cb callback, void* user_data);
static bool vce_default_is_lang_supported(const char* lang);

static int vce_default_set_language(const char* language);
static int vce_default_set_commands(vce_cmd_h vc_command);
static int vce_default_unset_commands();

static int vce_default_start(bool stop_by_silence);
static int vce_default_set_recording(const void* data, unsigned int length, vce_speech_detect_e* silence_detected);
static int vce_default_stop();
static int vce_default_cancel(void);

static int vce_default_set_audio_type(const char* audio_type);
static int vce_default_set_domain(const char* domain);
static int vce_default_process_text(const char* text);
static int vce_default_process_list_event(const char* event);
static int vce_default_process_haptic_event(const char* event);

// Optional callback function
static int vce_default_private_data_set_cb(const char* key, const char* data);

int main(int argc, char* argv[])
{
    // 1. Create a structure 'vce_request_callback_s'
    vce_request_callback_s callback = {0,};

    callback.version = 1;

    callback.initialize = vce_default_initialize;
    callback.deinitialize   = vce_default_deinitialize;

    callback.get_info   = vce_default_get_info;
    callback.get_recording_format   = vce_default_get_recording_format;
    callback.foreach_langs  = vce_default_foreach_langs;
    callback.is_lang_supported  = vce_default_is_lang_supported;

    callback.set_language   = vce_default_set_language;
    callback.set_commands   = vce_default_set_commands;
    callback.unset_commands = vce_default_unset_commands;

    callback.start      = vce_default_start;
    callback.set_recording  = vce_default_set_recording;
    callback.stop       = vce_default_stop;
    callback.cancel     = vce_default_cancel;

    callback.set_audio_type = vce_default_set_audio_type;
    callback.set_domain = vce_default_set_domain;
    callback.process_text   = vce_default_process_text;
    callback.process_list_event = vce_default_process_list_event;
    callback.process_haptic_event   = vce_default_process_haptic_event;

    // 2. Run 'vce_main()'
    if (0 != vce_main(argc, argv, &callback)) {
        SLOG(LOG_ERROR, TAG_VCE, "[ERROR] Fail to vce main");
        return -1;
    }

    // Optional
    vce_set_private_data_set_cb(vce_default_private_data_set_cb);

    // 3. Set event callbacks for service app and Run 'service_app_main()'
    char ad[50] = {0,};
    service_app_lifecycle_callback_s event_callback;
    app_event_handler_h handlers[5] = {NULL, };

    event_callback.create = service_app_create;
    event_callback.terminate = service_app_terminate;
    event_callback.app_control = service_app_control;

    service_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY, service_app_low_battery, &ad);
    service_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY], APP_EVENT_LOW_MEMORY, service_app_low_memory, &ad);
    service_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED], APP_EVENT_LANGUAGE_CHANGED, service_app_lang_changed, &ad);
    service_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED], APP_EVENT_REGION_FORMAT_CHANGED, service_app_region_changed, &ad);

    return service_app_main(argc, argv, &event_callback, ad);
}
int vce_send_asr_result ( vce_asr_result_event_e  event,
const char *  asr_result,
void *  user_data 
)

Sends the ASR result to the engine service user.

Since :
4.0
Parameters:
[in]eventA asr result event
[in]asr_resultA asr result text
[in]user_dataThe user data passed from the start
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_OUT_OF_MEMORYOut of Memory
VCE_ERROR_OPERATION_FAILEDOperation failure
Precondition:
The vce_main() function should be invoked before this function is called.
See also:
vce_start_cb()
int vce_send_error ( vce_error_e  error,
const char *  msg,
void *  user_data 
)

Sends the error to the engine service user.

The following error codes can be delivered.
VCE_ERROR_NONE,
VCE_ERROR_OUT_OF_MEMORY,
VCE_ERROR_IO_ERROR,
VCE_ERROR_INVALID_PARAMETER,
VCE_ERROR_OUT_OF_NETWORK,
VCE_ERROR_RECORDER_BUSY,
VCE_ERROR_NOT_SUPPORTED,
VCE_ERROR_INVALID_STATE,
VCE_ERROR_INVALID_LANGUAGE,
VCE_ERROR_OPERATION_FAILED,
VCE_ERROR_PERMISSION_DENIED,
VCE_ERROR_NOT_SUPPORTED_FEATURE.

Since :
4.0
Parameters:
[in]errorError type
[in]msgError message
[in]user_dataThe user data passed from set callback function
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_OUT_OF_MEMORYOut of Memory
VCE_ERROR_OPERATION_FAILEDOperation failure
Precondition:
The vce_main() function should be invoked before this function is called.
int vce_send_feedback_audio_format ( int  rate,
vce_audio_channel_e  channel,
vce_audio_type_e  audio_type 
)

Sends audio formats necessary for playing TTS feedback.

Since :
4.0
Parameters:
[in]rateA sampling rate
[in]channelThe audio channel
[in]audio_typeThe audio type
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_NOT_SUPPORTEDNot supported
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_OPERATION_FAILEDOperation failure
VCE_ERROR_OUT_OF_MEMORYOut of Memory
int vce_send_feedback_streaming ( vce_feedback_event_e  event,
char *  buffer,
int  len 
)

Sends audio streaming necessary for playing TTS feedback.

Since :
4.0
Parameters:
[in]eventA feedback event
[in]bufferThe feedback data
[in]lenThe length of the feedback data
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_NOT_SUPPORTEDNot supported
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_OPERATION_FAILEDOperation failure
VCE_ERROR_OUT_OF_MEMORYOut of Memory
int vce_send_nlg_result ( const char *  nlg_result,
void *  user_data 
)

Sends the NLG (Natural Language Generation) result to the engine service user.

Since :
4.0
Parameters:
[in]nlg_resultA nlg result
[in]user_dataThe user data passed from the start
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_OUT_OF_MEMORYOut of Memory
VCE_ERROR_OPERATION_FAILEDOperation failure
Precondition:
The vce_main() function should be invoked before this function is called.
See also:
vce_start_cb()
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 
)

Sends the results to the engine service user.

Since :
4.0
Parameters:
[in]eventA result event
[in]result_idResult ids
[in]countResult count
[in]all_resultAll result text
[in]non_fixed_resultNon-fixed command result text
[in]nlu_resultNLU result text
[in]msgEngine message (e.g. VC_RESULT_MESSAGE_NONE, VC_RESULT_MESSAGE_ERROR_TOO_LOUD)
[out]user_infoA user info (e.g. If ASR result is consumed, the value is 0x01. If not, the value is 0x00.)
[in]user_dataThe user data passed from set callback function
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_OUT_OF_MEMORYOut of Memory
VCE_ERROR_INVALID_STATEInvalid state
VCE_ERROR_OPERATION_FAILEDOperation failure
Precondition:
The vce_main() function should be invoked before this function is called. vce_stop_cb() will invoke this callback.
See also:
vce_stop_cb()
int vce_send_specific_engine_result ( const char *  engine_app_id,
const char *  event,
const char *  result,
void *  user_info 
)

Sends the specific engine result to the engine service user.

Since :
4.0
Parameters:
[in]engine_app_idA specific engine's app id
[in]eventA specific engine result event
[in]resultA specific engine result text
[in]user_infoThe user info passed from the start
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_OUT_OF_MEMORYOut of Memory
VCE_ERROR_OPERATION_FAILEDOperation failure
Precondition:
The vce_main() function should be invoked before this function is called.

Sets a callback function for requesting the NLU base information to the engine service.

Since :
4.0
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.
Parameters:
[in]callback_funcvce_nlu_base_info_requested event callback function
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_OPERATION_FAILEDOperation failure
VCE_ERROR_NOT_SUPPORTED_FEATURENot supported feature
See also:
vce_nlu_base_info_requested_cb()
int vce_set_private_data ( const char *  key,
const char *  data 
)

Sets private data to a voice manager client.

Since :
4.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Parameters:
[in]keyPrivate key
[in]dataPrivate data
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_OUT_OF_MEMORYOut of Memory
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_INVALID_STATEInvalid state
VCE_ERROR_PERMISSION_DENIEDPermission denied
VCE_ERROR_NOT_SUPPORTEDNot supported
VCE_ERROR_OPERATION_FAILEDOperation failed

Sets a callback function for requesting the private data to the engine service.

Since :
4.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Remarks:
The vce_private_data_requested_cb() function is called when the engine service user requests the private data to the engine service.
Parameters:
[in]callback_funcvce_private_data_requested event callback function
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_PERMISSION_DENIEDPermission denied
VCE_ERROR_NOT_SUPPORTEDNot supported
VCE_ERROR_OPERATION_FAILEDOperation failure
See also:
vce_private_data_requested_cb()

Sets a callback function for setting the private data to the engine service.

Since :
4.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Remarks:
The vce_private_data_set_cb() function is called when the engine service user sets the private data to the engine service.
Parameters:
[in]callback_funcvce_private_data_set event callback function
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_PERMISSION_DENIEDPermission denied
VCE_ERROR_NOT_SUPPORTEDNot supported
VCE_ERROR_OPERATION_FAILEDOperation failure
VCE_ERROR_NOT_SUPPORTED_FEATURENot supported feature
Precondition:
The vce_main() function should be invoked before this function is called.
See also:
vce_private_data_set_cb()

Sets a callback function for getting the engine service request.

Since :
4.0
Parameters:
[in]callback_funcCallback function to register
Returns:
0 on success, otherwise a negative error value
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_INVALID_PARAMETERInvalid parameter
VCE_ERROR_NOT_SUPPORTEDNot supported
See also:
vce_unset_specific_engine_request_cb()
int vce_start_recording ( void  )

Starts recording voice.

Since :
4.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_PERMISSION_DENIEDPermission denied
VCE_ERROR_NOT_SUPPORTEDNot supported
VCE_ERROR_OPERATION_FAILEDOperation failure
VCE_ERROR_RECORDER_BUSYBusy recorder
int vce_stop_recording ( void  )

Stops recording voice.

Since :
4.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Returns:
0 on success, otherwise a negative error value.
Return values:
VCE_ERROR_NONESuccessful
VCE_ERROR_PERMISSION_DENIEDPermission denied
VCE_ERROR_NOT_SUPPORTEDNot supported
VCE_ERROR_OPERATION_FAILEDOperation failure

Unsets the engine service request callback function.

Since :
4.0
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_NOT_SUPPORTEDNot supported
See also:
vce_set_specific_engine_request_cb()