The Multi assistant provides functions for supporting users to use several assistants.
Copyright (c) 2011-2018 Samsung Electronics Co., Ltd All Rights Reserved
Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Required Header
#include <multi_assistant.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. Set an invocation name for an application
7. Get recognition results
8. Request the dialogue
9. If an application wants to finish voice control,
9-1. Destroy command and command list handle
9-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_get_result() | Ready | |
| vc_get_system_command_list() | Ready | |
| vc_set_command_list() | Ready | |
| vc_unset_command_list() | Ready | |
| vc_set_invocation_name() | Ready | |
| vc_set_server_dialog() | Ready | |
| vc_request_dialog() | 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:
- http://tizen.org/feature/microphone
- http://tizen.org/feature/multi_assistant
It is recommended to use features in your application for reliability.
You can check if the device supports the related features for this API by using System Information, and control your application's actions accordingly.
To ensure your application is running only on devices with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on using features in your application can be found in the feature element description.
Copyright (c) 2011-2018 Samsung Electronics Co., Ltd All Rights Reserved
Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Typedefs | |
| typedef void(* | ma_state_changed_cb )(ma_state_e previous, ma_state_e current, void *user_data) |
| Called when the client state is changed. | |
| typedef void(* | ma_error_cb )(ma_error_e reason, void *user_data) |
| Called when the error is occurred. | |
| typedef void(* | ma_language_changed_cb )(const char *previous, const char *current, void *user_data) |
| Called when the default language is changed. | |
| typedef void(* | ma_audio_streaming_cb )(ma_audio_streaming_event_e event, char *buffer, int len, void *user_data) |
| Called when the multi-assistant service sends audio streaming. | |
Typedef Documentation
| typedef void(* ma_audio_streaming_cb)(ma_audio_streaming_event_e event, char *buffer, int len, void *user_data) |
Called when the multi-assistant service sends audio streaming.
- Since :
- 5.0
- Remarks:
- The buffer should not be released and can be used only in the callback. To use outside, make a copy.
- Parameters:
-
[in] event The audio streaming event [in] buffer The audio streaming data [in] len The length of the audio streaming data [in] user_data The user data passed from the callback registration function
| typedef void(* ma_error_cb)(ma_error_e reason, void *user_data) |
Called when the error is occurred.
The following error codes can be received:
MA_ERROR_NONE: Success
MA_ERROR_OUT_OF_MEMORY: Out of Memory
MA_ERROR_IO_ERROR: I/O error
MA_ERROR_INVALID_PARAMETER: Invalid parameter
MA_ERROR_TIMED_OUT: No answer from service
MA_ERROR_RECORDER_BUSY: Busy recorder
MA_ERROR_PERMISSION_DENIED: Permission denied
MA_ERROR_NOT_SUPPORTED: Multi-assistant NOT supported
MA_ERROR_INVALID_STATE: Invalid state
MA_ERROR_INVALID_LANGUAGE: Invalid language
MA_ERROR_ENGINE_NOT_FOUND: No available engine
MA_ERROR_OPERATION_FAILED: Operation failed
MA_ERROR_SERVICE_RESET: Service daemon reset
MA_ERROR_NOT_SUPPORTED_FEATURE: Not supported feature of current engine
- Since :
- 5.0
- Parameters:
-
[in] reason The error reason [in] user_data The user data passed from the callback registration function
| typedef void(* ma_language_changed_cb)(const char *previous, const char *current, void *user_data) |
Called when the default language is changed.
- Since :
- 5.0
- Remarks:
- The previous can be used only in the callback. To use outside, make a copy. The current can be used only in the callback. To use outside, make a copy.
- Parameters:
-
[in] previous The previous language [in] current The current language [in] user_data The user data passed from the callback registration function
| typedef void(* ma_state_changed_cb)(ma_state_e previous, ma_state_e current, void *user_data) |
Called when the client state is changed.
- Since :
- 5.0
- Parameters:
-
[in] previous The previous state [in] current The current state [in] user_data The user data passed from the callback registration function
Enumeration Type Documentation
| enum ma_audio_channel_e |
| enum ma_audio_type_e |
| enum ma_error_e |
Enumerations for multi-assistant error codes.
- Since :
- 5.0
- Enumerator:
| enum ma_state_e |