Tizen Native API
|
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.
The following diagram shows the states of Voice Control service.
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
#define VC_COMMAND_TYPE_BACKGROUND 2 |
Definitions for background command type.
- Since :
- 2.4
#define VC_COMMAND_TYPE_FOREGROUND 1 |
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] previous Previous language [in] current Current language [in] user_data The 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] reason The error type (e.g. VC_ERROR_OUT_OF_MEMORY, VC_ERROR_TIMED_OUT) [in] user_data The 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] event The result event (e.g. VC_RESULT_EVENT_RESULT_SUCCESS, VC_RESULT_EVENT_REJECTED) [in] vc_cmd_list The recognized command list [in] result The spoken text [in] user_data The 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] previous A previous state [in] current A current state [in] user_data The 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] previous A previous state [in] current A current state [in] user_data The 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] 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.
For example, "ko_KR" for Korean, "en_US" for American English.[in] user_data The 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:
enum vc_result_event_e |
enum vc_service_state_e |
enum vc_state_e |
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_NONE Successful VC_ERROR_INVALID_STATE Invalid state VC_ERROR_OPERATION_FAILED Operation failure VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not 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] callback Callback function to invoke [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
VC_ERROR_NONE Successful VC_ERROR_INVALID_PARAMETER Invalid parameter VC_ERROR_OPERATION_FAILED Operation failure VC_ERROR_INVALID_STATE Invalid state VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not 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.
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] 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.
For example, "ko_KR" for Korean, "en_US" for American English.
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
VC_ERROR_NONE Successful VC_ERROR_INVALID_PARAMETER Invalid parameter VC_ERROR_OUT_OF_MEMORY Out of memory VC_ERROR_OPERATION_FAILED Operation failure VC_ERROR_INVALID_STATE Invalid state VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state should be VC_STATE_INITIALIZED or VC_STATE_READY.
- See also:
- vc_foreach_supported_languages()
int vc_get_service_state | ( | vc_service_state_e * | state | ) |
Gets current state of voice control service.
- Since :
- 2.4
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/recorder
- Parameters:
-
[out] state The current state
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
VC_ERROR_NONE Successful VC_ERROR_INVALID_PARAMETER Invalid parameter VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not 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] state The current state
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
VC_ERROR_NONE Successful VC_ERROR_INVALID_PARAMETER Invalid parameter VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not supported
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_NONE Successful VC_ERROR_OUT_OF_MEMORY Out of memory VC_ERROR_OPERATION_FAILED Operation failure VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not 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_NONE Successful VC_ERROR_INVALID_STATE Invalid state VC_ERROR_OPERATION_FAILED Operation failure VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not 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_list Command list handle [in] type Command type
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
VC_ERROR_NONE Successful VC_ERROR_INVALID_PARAMETER Invalid parameter VC_ERROR_INVALID_STATE Invalid state VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not 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] callback Callback function to register [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
VC_ERROR_NONE Successful VC_ERROR_INVALID_PARAMETER Invalid parameter VC_ERROR_INVALID_STATE Invalid state VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state should be VC_STATE_INITIALIZED.
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] callback Callback function to register [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
VC_ERROR_NONE Successful VC_ERROR_INVALID_PARAMETER Invalid parameter VC_ERROR_INVALID_STATE Invalid state VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not 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] callback Callback function to register [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
VC_ERROR_NONE Successful VC_ERROR_INVALID_PARAMETER Invalid parameter VC_ERROR_INVALID_STATE Invalid state VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not 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] callback Callback function to register [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
VC_ERROR_NONE Successful VC_ERROR_INVALID_PARAMETER Invalid parameter VC_ERROR_INVALID_STATE Invalid state VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state should be VC_STATE_INITIALIZED.
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] callback Callback function to register [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
VC_ERROR_NONE Successful VC_ERROR_INVALID_PARAMETER Invalid parameter VC_ERROR_INVALID_STATE Invalid state VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state should be VC_STATE_INITIALIZED.
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_NONE Successful VC_ERROR_INVALID_STATE Invalid state VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not 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] type Command type
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
VC_ERROR_NONE Successful VC_ERROR_INVALID_PARAMETER Invalid parameter VC_ERROR_INVALID_STATE Invalid state VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state should be VC_STATE_READY.
- See also:
- vc_set_command_list()
int vc_unset_current_language_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_NONE Successful VC_ERROR_INVALID_STATE Invalid state VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not 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_NONE Successful VC_ERROR_INVALID_STATE Invalid state VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not 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_NONE Successful VC_ERROR_INVALID_STATE Invalid state VC_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state should be VC_STATE_INITIALIZED.
- See also:
- vc_set_result_cb()
int vc_unset_service_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_NONE Successful VC_ERROR_INVALID_STATE Invalid state VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not 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_NONE Successful VC_ERROR_INVALID_STATE Invalid state VC_ERROR_PERMISSION_DENIED Permission denied VC_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state should be VC_STATE_INITIALIZED.
- See also:
- vc_set_state_changed_cb()