Tizen Native API
Voice control

Functions

int vc_initialize (void)
 Initializes voice control.
int vc_deinitialize (void)
 Deinitializes voice control.
int vc_prepare (void)
 Connects the voice control service.
int vc_unprepare (void)
 Disconnects the voice control service.
int vc_foreach_supported_languages (vc_supported_language_cb callback, void *user_data)
 Retrieves all supported languages using callback function.
int vc_get_current_language (char **language)
 Gets current language.
int vc_get_state (vc_state_e *state)
 Gets current state of voice control client.
int vc_get_service_state (vc_service_state_e *state)
 Gets current state of voice control service.
int vc_set_command_list (vc_cmd_list_h vc_cmd_list, int type)
 Sets command list.
int vc_unset_command_list (int type)
 Unsets command list.
int vc_set_result_cb (vc_result_cb callback, void *user_data)
 Registers a callback function for getting recognition result.
int vc_unset_result_cb (void)
 Unregisters the callback function.
int vc_set_service_state_changed_cb (vc_service_state_changed_cb callback, void *user_data)
 Registers a callback function to be called when state is changed.
int vc_unset_service_state_changed_cb (void)
 Unregisters the callback function.
int vc_set_state_changed_cb (vc_state_changed_cb callback, void *user_data)
 Registers a callback function to be called when state is changed.
int vc_unset_state_changed_cb (void)
 Unregisters the callback function.
int vc_set_current_language_changed_cb (vc_current_language_changed_cb callback, void *user_data)
 Registers a callback function to be called when current language is changed.
int vc_unset_current_language_changed_cb (void)
 Unregisters the callback function.
int vc_set_error_cb (vc_error_cb callback, void *user_data)
 Registers a callback function to be called when an error occurred.
int vc_unset_error_cb (void)
 Unregisters the callback function.

Typedefs

typedef void(* vc_result_cb )(vc_result_event_e event, vc_cmd_list_h vc_cmd_list, const char *result, void *user_data)
 Called when client gets the recognition result.
typedef void(* vc_current_language_changed_cb )(const char *previous, const char *current, void *user_data)
 Called when default language is changed.
typedef bool(* vc_supported_language_cb )(const char *language, void *user_data)
 Called to retrieve supported language.
typedef void(* vc_state_changed_cb )(vc_state_e previous, vc_state_e current, void *user_data)
 Called when the state of voice control client is changed.
typedef void(* vc_service_state_changed_cb )(vc_service_state_e previous, vc_service_state_e current, void *user_data)
 Called when the state of voice control service is changed.
typedef void(* vc_error_cb )(vc_error_e reason, void *user_data)
 Called when error occurred.

Defines

#define VC_COMMAND_TYPE_FOREGROUND   1
 Definitions for foreground command type.
#define VC_COMMAND_TYPE_BACKGROUND   2
 Definitions for background command type.

The Voice control API provides functions for registering command and getting notification when registered command is recognized.

Required Header

#include <voice_control.h>

Overview

A main function of Voice Control API register command and gets notification for recognition result. Applications can add their own commands and be provided result when their command is recognized by user voice input.

To use of Voice Control, use the following steps:
1. Initialize
2. Register callback functions for notifications
3. Connect to voice control service asynchronously. The state should be changed to Ready
4. Make command list as the following step and Step 4 is called repeatedly for each command which an application wants
4-1. Create command list handle
4-2. Create command handle
4-3. Set command and type for command handle
4-4. Add command handle to command list
5. Set command list for recognition
6. If an application wants to finish voice control,
6-1. Destroy command and command list handle
6-2. Deinitialize

An application can obtain command handle from command list, and also get information from handle.

The Voice Control API also notifies you (by callback mechanism) when the states of client and service are changed, command is recognized, current language is changed or error occurred. An application should register callback functions: vc_state_changed_cb(), vc_service_state_changed_cb(), vc_result_cb(), vc_current_language_changed_cb(), vc_error_cb().

State Diagram

The following diagram shows the life cycle and the states of the Voice Control.

capi_uix_voice_control_state_diagram.png
<State diagram>

The following diagram shows the states of Voice Control service.

capi_uix_voice_control_service_state_diagram.png
<Service state diagram>

State Transitions

FUNCTION PRE-STATE POST-STATE SYNC TYPE
vc_initialize() None Initialized SYNC
vc_deinitialize() Initialized None SYNC
vc_prepare() Initialized Ready ASYNC
vc_unprepare() Ready Initialized

SYNC

State Dependent Function Calls

The following table shows state-dependent function calls. It is forbidden to call functions listed below in wrong states. Violation of this rule may result in an unpredictable behavior.

FUNCTION VALID STATES DESCRIPTION
vc_initialize() None All functions must be called after vc_initialize()
vc_deinitialize() Initialized, Ready This function should be called when an application want to finalize voice control using
vc_prepare() Initialized This function works asynchronously. If service start is failed, application gets the error callback.
vc_unprepare() Ready
vc_foreach_supported_languages() Initialized, Ready
vc_get_current_language() Initialized, Ready
vc_get_state() Initialized, Ready
vc_get_service_state() Initialized, Ready
vc_set_command_list() Ready
vc_unset_command_list() Ready
vc_set_result_cb()
vc_unset_result_cb()
vc_set_state_changed_cb()
vc_unset_state_changed_cb()
vc_set_service_state_changed_cb()
vc_unset_service_state_changed_cb()
vc_set_current_language_changed_cb()
vc_unset_current_language_changed_cb()
vc_set_error_cb()
vc_unset_error_cb()
Initialized All callback function should be registered in Initialized state

Related Features

This API is related with the following features:

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.


Define Documentation

Definitions for background command type.

Since :
2.4

Definitions for foreground command type.

Since :
2.4

Typedef Documentation

typedef void(* vc_current_language_changed_cb)(const char *previous, const char *current, void *user_data)

Called when default language is changed.

Since :
2.4
Parameters:
[in]previousPrevious language
[in]currentCurrent language
[in]user_dataThe user data passed from the callback registration function
Precondition:
An application registers this callback to detect changing mode.
See also:
vc_set_current_language_changed_cb()
typedef void(* vc_error_cb)(vc_error_e reason, void *user_data)

Called when error occurred.

Since :
2.4
Parameters:
[in]reasonThe error type (e.g. VC_ERROR_OUT_OF_MEMORY, VC_ERROR_TIMED_OUT)
[in]user_dataThe user data passed from the callback registration function
Precondition:
An application registers this callback to detect error.
See also:
vc_set_error_cb()
typedef void(* vc_result_cb)(vc_result_event_e event, vc_cmd_list_h vc_cmd_list, const char *result, void *user_data)

Called when client gets the recognition result.

Since :
2.4
Remarks:
If the duplicated commands are recognized, the event(e.g. VC_RESULT_EVENT_REJECTED) of command may be rejected
for selecting command as priority. If you set similar or same commands or the recognized results are multi-results, vc_cmd_list has the multi commands.
Parameters:
[in]eventThe result event (e.g. VC_RESULT_EVENT_RESULT_SUCCESS, VC_RESULT_EVENT_REJECTED)
[in]vc_cmd_listThe recognized command list
[in]resultThe spoken text
[in]user_dataThe user data passed from the callback registration function
Precondition:
An application registers callback function.
See also:
vc_set_result_cb()
typedef void(* vc_service_state_changed_cb)(vc_service_state_e previous, vc_service_state_e current, void *user_data)

Called when the state of voice control service is changed.

Since :
2.4
Parameters:
[in]previousA previous state
[in]currentA current state
[in]user_dataThe user data passed from the callback registration function
Precondition:
An application registers this callback to detect changing service state.
See also:
vc_set_service_state_changed_cb()
typedef void(* vc_state_changed_cb)(vc_state_e previous, vc_state_e current, void *user_data)

Called when the state of voice control client is changed.

Since :
2.4
Parameters:
[in]previousA previous state
[in]currentA current state
[in]user_dataThe user data passed from the callback registration function
Precondition:
An application registers this callback to detect changing state.
See also:
vc_set_state_changed_cb()
typedef bool(* vc_supported_language_cb)(const char *language, void *user_data)

Called to retrieve supported language.

Since :
2.4
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:
The function will invoke this callback.

Enumeration Type Documentation

enum vc_error_e

Enumerations of error codes.

Since :
2.4
Enumerator:
VC_ERROR_NONE 

Successful

VC_ERROR_OUT_OF_MEMORY 

Out of Memory

VC_ERROR_IO_ERROR 

I/O error

VC_ERROR_INVALID_PARAMETER 

Invalid parameter

VC_ERROR_TIMED_OUT 

No answer from service

VC_ERROR_RECORDER_BUSY 

Busy recorder

VC_ERROR_PERMISSION_DENIED 

Permission denied

VC_ERROR_NOT_SUPPORTED 

VC NOT supported

VC_ERROR_INVALID_STATE 

Invalid state

VC_ERROR_INVALID_LANGUAGE 

Invalid language

VC_ERROR_ENGINE_NOT_FOUND 

No available engine

VC_ERROR_OPERATION_FAILED 

Operation failed

VC_ERROR_OPERATION_REJECTED 

Operation rejected

VC_ERROR_ITERATION_END 

List reached end

VC_ERROR_EMPTY 

List empty

Enumerations of result event.

Since :
2.4
Enumerator:
VC_RESULT_EVENT_RESULT_SUCCESS 

Normal result

VC_RESULT_EVENT_REJECTED 

Rejected result

Enumerations of service state.

Since :
2.4
Enumerator:
VC_SERVICE_STATE_NONE 

'None' state

VC_SERVICE_STATE_READY 

'Ready' state

VC_SERVICE_STATE_RECORDING 

'Recording' state

VC_SERVICE_STATE_PROCESSING 

'Processing' state

enum vc_state_e

Enumerations of client state.

Since :
2.4
Enumerator:
VC_STATE_NONE 

'None' state

VC_STATE_INITIALIZED 

'Initialized' state

VC_STATE_READY 

'Ready' state


Function Documentation

int vc_deinitialize ( void  )

Deinitializes voice control.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_STATEInvalid state
VC_ERROR_OPERATION_FAILEDOperation failure
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
See also:
vc_deinitialize()
int vc_foreach_supported_languages ( vc_supported_language_cb  callback,
void *  user_data 
)

Retrieves all supported languages using callback function.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Parameters:
[in]callbackCallback 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:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_PARAMETERInvalid parameter
VC_ERROR_OPERATION_FAILEDOperation failure
VC_ERROR_INVALID_STATEInvalid state
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state should be VC_STATE_INITIALIZED or VC_STATE_READY.
Postcondition:
This function invokes vc_supported_language_cb() repeatedly for getting languages.
See also:
vc_supported_language_cb()
vc_get_current_language()
int vc_get_current_language ( char **  language)

Gets current language.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Remarks:
If the function succeeds, language must be released with free() by you when you no longer need it.
Parameters:
[out]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.
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_PARAMETERInvalid parameter
VC_ERROR_OUT_OF_MEMORYOut of memory
VC_ERROR_OPERATION_FAILEDOperation failure
VC_ERROR_INVALID_STATEInvalid state
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state should be VC_STATE_INITIALIZED or VC_STATE_READY.
See also:
vc_foreach_supported_languages()

Gets current state of voice control service.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Parameters:
[out]stateThe current state
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_PARAMETERInvalid parameter
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state should be VC_STATE_READY.
See also:
vc_request_start()
vc_request_stop()
vc_request_cancel()
vc_set_service_state_changed_cb()
vc_unset_service_state_changed_cb()
int vc_get_state ( vc_state_e state)

Gets current state of voice control client.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Parameters:
[out]stateThe current state
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_PARAMETERInvalid parameter
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
See also:
vc_state_changed_cb()
vc_set_state_changed_cb()
int vc_initialize ( void  )

Initializes voice control.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Remarks:
If the function succeeds, vc must be released with vc_deinitialize().
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_OUT_OF_MEMORYOut of memory
VC_ERROR_OPERATION_FAILEDOperation failure
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
Postcondition:
If this function is called, the state will be VC_STATE_INITIALIZED.
See also:
vc_deinitialize()
int vc_prepare ( void  )

Connects the voice control service.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_STATEInvalid state
VC_ERROR_OPERATION_FAILEDOperation failure
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state should be VC_STATE_INITIALIZED.
Postcondition:
If this function is called, the state will be VC_STATE_READY.
See also:
vc_unprepare()
int vc_set_command_list ( vc_cmd_list_h  vc_cmd_list,
int  type 
)

Sets command list.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Remarks:
The command type is valid for VC_COMMAND_TYPE_FOREGROUND or VC_COMMAND_TYPE_BACKGROUND.
The matched commands of command list should be set and they should include type and command text at least.
Parameters:
[in]vc_cmd_listCommand list handle
[in]typeCommand type
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_PARAMETERInvalid parameter
VC_ERROR_INVALID_STATEInvalid state
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state should be VC_STATE_READY.
See also:
vc_unset_command_list()
int vc_set_current_language_changed_cb ( vc_current_language_changed_cb  callback,
void *  user_data 
)

Registers a callback function to be called when current language is changed.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Parameters:
[in]callbackCallback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_PARAMETERInvalid parameter
VC_ERROR_INVALID_STATEInvalid state
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state should be VC_STATE_INITIALIZED.
See also:
vc_current_language_changed_cb()
vc_unset_current_language_changed_cb()
int vc_set_error_cb ( vc_error_cb  callback,
void *  user_data 
)

Registers a callback function to be called when an error occurred.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Parameters:
[in]callbackCallback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_PARAMETERInvalid parameter
VC_ERROR_INVALID_STATEInvalid state
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state should be VC_STATE_INITIALIZED.
See also:
vc_error_cb()
vc_unset_error_cb()
int vc_set_result_cb ( vc_result_cb  callback,
void *  user_data 
)

Registers a callback function for getting recognition result.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Parameters:
[in]callbackCallback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_PARAMETERInvalid parameter
VC_ERROR_INVALID_STATEInvalid state
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state should be VC_STATE_INITIALIZED.
See also:
vc_result_cb()
vc_unset_result_cb()
int vc_set_service_state_changed_cb ( vc_service_state_changed_cb  callback,
void *  user_data 
)

Registers a callback function to be called when state is changed.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Parameters:
[in]callbackCallback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_PARAMETERInvalid parameter
VC_ERROR_INVALID_STATEInvalid state
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state should be VC_STATE_INITIALIZED.
See also:
vc_service_state_changed_cb()
vc_unset_service_state_changed_cb()
int vc_set_state_changed_cb ( vc_state_changed_cb  callback,
void *  user_data 
)

Registers a callback function to be called when state is changed.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Parameters:
[in]callbackCallback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_PARAMETERInvalid parameter
VC_ERROR_INVALID_STATEInvalid state
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state should be VC_STATE_INITIALIZED.
See also:
vc_state_changed_cb()
vc_unset_state_changed_cb()
int vc_unprepare ( void  )

Disconnects the voice control service.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_STATEInvalid state
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state should be VC_STATE_READY.
Postcondition:
If this function is called, the state will be VC_STATE_INITIALIZED.
See also:
vc_prepare()
int vc_unset_command_list ( int  type)

Unsets command list.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Parameters:
[in]typeCommand type
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_PARAMETERInvalid parameter
VC_ERROR_INVALID_STATEInvalid state
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state should be VC_STATE_READY.
See also:
vc_set_command_list()

Unregisters the callback function.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_STATEInvalid state
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state should be VC_STATE_INITIALIZED.
See also:
vc_set_current_language_changed_cb()
int vc_unset_error_cb ( void  )

Unregisters the callback function.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_STATEInvalid state
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state should be VC_STATE_INITIALIZED.
See also:
vc_set_error_cb()
int vc_unset_result_cb ( void  )

Unregisters the callback function.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_STATEInvalid state
VC_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state should be VC_STATE_INITIALIZED.
See also:
vc_set_result_cb()

Unregisters the callback function.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_STATEInvalid state
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state should be VC_STATE_INITIALIZED.
See also:
vc_set_service_state_changed_cb()
int vc_unset_state_changed_cb ( void  )

Unregisters the callback function.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/recorder
Returns:
0 on success, otherwise a negative error value
Return values:
VC_ERROR_NONESuccessful
VC_ERROR_INVALID_STATEInvalid state
VC_ERROR_PERMISSION_DENIEDPermission denied
VC_ERROR_NOT_SUPPORTEDNot supported
Precondition:
The state should be VC_STATE_INITIALIZED.
See also:
vc_set_state_changed_cb()