2 * Copyright (c) 2011-2018 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the License);
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an AS IS BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 #ifndef __TIZEN_UIX_VOICE_CONTROL_MANAGER_DOC_H__
19 #define __TIZEN_UIX_VOICE_CONTROL_MANAGER_DOC_H__
23 * @ingroup CAPI_UIX_FRAMEWORK
24 * @defgroup CAPI_UIX_VOICE_CONTROL_MANAGER_MODULE Voice control manager
25 * @brief The @ref CAPI_UIX_VOICE_CONTROL_MANAGER_MODULE API provides functions for recording voice and giving responses for recognized voice commands to users.
26 * @section CAPI_UIX_VOICE_CONTROLMANAGER_MODULE_HEADER Required Header
27 * \#include <voice_control_manager.h><br>
29 * @section CAPI_UIX_VOICE_CONTROL_MANAGER_MODULE_OVERVIEW Overview
30 * A main function of Voice Control Manager API records voice and gives responses for recognized voice commands.
31 * A Voice Control Manager application can start recording user's utterance and get responses from Voice Control engine service.
32 * The responses are dependent on the Voice Control engine service. For example, the engine service may send ASR(Automatic Speech Recognition) results or NLU(Natural Language Understanding) results.
33 * Also, it may send plural results. Therefore, the application can get various recognition results from the engine service and handle them by showing responses to users or controling Voice Control applications.
34 * Like this, the Voice Control Manager application takes a role of controlling Voice Control applcations.
35 * For this reason, developers who have an authority granted by Tizen platform can make the Voice Control Manager application.<br><br>
36 * To use of Voice Control Manager, use the following steps: <br>
38 * 2. Register callback functions for notifications <br>
39 * 3. Connect to voice control service asynchronously. The state should be changed to Ready <br>
40 * 4. Make command list as the following step and Step 4 is called repeatedly for each command which an application wants <br>
41 * 4-1. Create command list handle <br>
42 * 4-2. Create command handle <br>
43 * 4-3. Set command and type for command handle <br>
44 * 4-4. Add command handle to command list <br>
45 * 5. Set command list for recognition <br>
46 * 6. Get recognition results <br>
47 * 7. Request the dialogue <br>
48 * 8. If an application wants to finish voice control,<br>
49 * 8-1. Destroy command and command list handle <br>
50 * 8-2. Deinitialize <br>
51 * An application can obtain command handle from command list, and also get information from handle.
52 * The Voice Control API also notifies you (by callback mechanism) when the states of client and service are changed,
53 * command is recognized, current language is changed or error occurred.
54 * An application should register callback functions: vc_state_changed_cb(), vc_service_state_changed_cb(), vc_mgr_all_result_cb(), vc_mgr_pre_result_cb(), vc_result_cb(),
55 * vc_mgr_begin_speech_detected_cb(), vc_current_language_changed_cb(), vc_error_cb(), vc_mgr_dialog_request_cb(), vc_mgr_private_data_set_cb(), vc_mgr_private_data_requested_cb().
58 * @section CAPI_UIX_VOICE_CONTROL_MANAGER_MODULE_STATE_TRANSITIONS State Transitions
67 * <td>vc_mgr_initialize()</td>
69 * <td>Initialized</td>
73 * <td>vc_mgr_deinitialize()</td>
74 * <td>None, Initialized, Ready</td>
79 * <td>vc_mgr_prepare()</td>
80 * <td>Initialized</td>
85 * <td>vc_mgr_unprepare()</td>
87 * <td>Initialized</td>
92 * @section CAPI_UIX_VOICE_CONTROL_MANAGER_MODULE_STATE_DEPENDENT_FUNCTION_CALLS State Dependent Function Calls
93 * The following table shows state-dependent function calls.
94 * It is forbidden to call functions listed below in wrong states.
95 * Violation of this rule may result in an unpredictable behavior.
99 * <th>VALID STATES</th>
100 * <th>DESCRIPTION</th>
103 * <td>vc_mgr_initialize()</td>
105 * <td>All functions must be called after vc_mgr_initialize()</td>
108 * <td>vc_mgr_deinitialize()</td>
109 * <td>None, Initialized, Ready</td>
110 * <td>This function should be called when an application want to finalize voice control manager using</td>
113 * <td>vc_mgr_prepare()</td>
114 * <td>Initialized</td>
115 * <td>This function works asynchronously. If service start is failed, application gets the error callback.</td>
118 * <td>vc_mgr_unprepare()</td>
123 * <td>vc_mgr_foreach_supported_languages()</td>
124 * <td>Initialized, Ready</td>
128 * <td>vc_mgr_get_current_language()</td>
129 * <td>Initialized, Ready</td>
133 * <td>vc_mgr_get_state()</td>
134 * <td>Initialized, Ready</td>
138 * <td>vc_mgr_get_service_state()</td>
143 * <td>vc_mgr_is_command_format_supported()</td>
148 * <td>vc_mgr_set_command_list()</td>
153 * <td>vc_mgr_unset_command_list()</td>
158 * <td>vc_mgr_set_command_list_from_file()</td>
163 * <td>vc_mgr_set_preloaded_commands_from_file()</td>
168 * <td>vc_mgr_get_current_commands()</td>
170 * <td>The service state should be #VC_SERVICE_STATE_READY.</td>
173 * <td>vc_mgr_set_audio_type()</td>
175 * <td>The service state should be #VC_SERVICE_STATE_READY.</td>
178 * <td>vc_mgr_get_audio_type()</td>
180 * <td>The service state should be #VC_SERVICE_STATE_READY.</td>
183 * <td>vc_mgr_set_recognition_mode()</td>
185 * <td>The service state should be #VC_SERVICE_STATE_READY.</td>
188 * <td>vc_mgr_get_recognition_mode()</td>
193 * <td>vc_mgr_set_private_data()</td>
198 * <td>vc_mgr_get_private_data()</td>
203 * <td>vc_mgr_do_action()</td>
208 * <td>vc_mgr_start()</td>
210 * <td>The service state should be #VC_SERVICE_STATE_READY. If this function succeeds, the service state will be changed to #VC_SERVICE_STATE_RECORDING.</td>
213 * <td>vc_mgr_stop()</td>
215 * <td>The service state should be #VC_SERVICE_STATE_RECORDING. If this function succeeds, the service state will be changed to #VC_SERVICE_STATE_PROCESSING.</td>
218 * <td>vc_mgr_cancel()</td>
220 * <td>The service state should be #VC_SERVICE_STATE_RECORDING or #VC_SERVICE_STATE_PROCESSING. If this function succeeds, the service state will be changed to #VC_SERVICE_STATE_READY.</td>
223 * <td>vc_mgr_get_recording_volume()</td>
224 * <td>None, Initialized, Ready</td>
225 * <td>The service state should be #VC_SERVICE_STATE_RECORDING.</td>
228 * <td>vc_mgr_set_selected_results()</td>
229 * <td>None, Initialized, Ready</td>
233 * <td>vc_mgr_get_error_message()</td>
234 * <td>None, Initialized, Ready</td>
238 * <td>vc_mgr_enable_command_type()</td>
244 * <td>vc_mgr_disable_command_type()</td>
250 * vc_mgr_set_all_result_cb()<br>
251 * vc_mgr_unset_all_result_cb()<br>
252 * vc_mgr_set_pre_result_cb()<br>
253 * vc_mgr_unset_pre_result_cb()<br>
254 * vc_mgr_set_result_cb()<br>
255 * vc_mgr_unset_result_cb()<br>
256 * vc_mgr_set_state_changed_cb()<br>
257 * vc_mgr_unset_state_changed_cb()<br>
258 * vc_mgr_set_service_state_changed_cb()<br>
259 * vc_mgr_unset_service_state_changed_cb()<br>
260 * vc_mgr_set_speech_detected_cb()<br>
261 * vc_mgr_unset_speech_detected_cb()<br>
262 * vc_mgr_set_current_language_changed_cb()<br>
263 * vc_mgr_unset_current_language_changed_cb()<br>
264 * vc_mgr_set_error_cb()<br>
265 * vc_mgr_unset_error_cb()</td>
266 * vc_mgr_set_dialog_request_cb()<br>
267 * vc_mgr_unset_dialog_request_cb()</td>
268 * vc_mgr_set_private_data_set_cb()<br>
269 * vc_mgr_unset_private_data_set_cb()</td>
270 * vc_mgr_set_private_data_requested_cb()<br>
271 * vc_mgr_unset_private_data_requested_cb()</td>
272 * <td>Initialized</td>
273 * <td> All callback function should be registered in Initialized state </td>
277 * @section CAPI_UIX_VOICE_CONTROL_MANAGER_MODULE_FEATURES Related Features
278 * This API is related with the following features:<br>
279 * - http://tizen.org/feature/microphone<br>
280 * - http://tizen.org/feature/speech.control<br>
281 * It is recommended to design feature related codes in your application for reliability.<br>
282 * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.<br>
283 * 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.<br>
284 * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tizen-studio/native-tools/configuring-your-app/manifest-text-editor#feature"><b>Feature Element</b>.</a>
288 #endif /* __TIZEN_UIX_VOICE_CONTROL_MANAGER_DOC_H__ */