2 * Copyright (c) 2011-2014 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_DOC_H__
19 #define __TIZEN_UIX_VOICE_CONTROL_DOC_H__
23 * @ingroup CAPI_UIX_FRAMEWORK
24 * @defgroup CAPI_UIX_VOICE_CONTROL_MODULE Voice control
25 * @brief The @ref CAPI_UIX_VOICE_CONTROL_MODULE API provides functions for registering command and getting notification when registered command is recognized.
26 * @section CAPI_UIX_VOICE_CONTROL_MODULE_HEADER Required Header
27 * \#include <voice_control.h><br>
29 * @section CAPI_UIX_VOICE_CONTROL_MODULE_OVERVIEW Overview
30 * A main function of Voice Control API register command and gets notification for recognition result.
31 * Applications can add their own commands and be provided result when their command is recognized by user voice input.
32 * To use of Voice Control, use the following steps: <br>
34 * 2. Register callback functions for notifications <br>
35 * 3. Connect to voice control service asynchronously. The state should be changed to Ready <br>
36 * 4. Make command list as the following step and Step 4 is called repeatedly for each command which an application wants <br>
37 * 4-1. Create command list handle <br>
38 * 4-2. Create command handle <br>
39 * 4-3. Set command and type for command handle <br>
40 * 4-4. Add command handle to command list <br>
41 * 5. Set command list for recognition <br>
42 * 6. Set an invocation name for an application <br>
43 * 7. Get recognition results <br>
44 * 8. Request the dialogue <br>
45 * 9. If an application wants to finish voice control,<br>
46 * 9-1. Destroy command and command list handle <br>
47 * 9-2. Deinitialize <br>
48 * An application can obtain command handle from command list, and also get information from handle.
49 * The Voice Control API also notifies you (by callback mechanism) when the states of client and service are changed,
50 * command is recognized, current language is changed or error occurred.
51 * An application should register callback functions: vc_state_changed_cb(), vc_service_state_changed_cb(), vc_result_cb(),
52 * vc_current_language_changed_cb(), vc_error_cb().
54 * @section CAPI_UIX_VOICE_CONTROL_MODULE_STATE_DIAGRAM State Diagram
55 * The following diagram shows the life cycle and the states of the Voice Control.
57 * @image html capi_uix_voice_control_state_diagram.png "<State diagram> "
58 * The following diagram shows the states of Voice Control service.
60 * @image html capi_uix_voice_control_service_state_diagram.png "<Service state diagram>"
62 * @section CAPI_UIX_VOICE_CONTROL_MODULE_STATE_TRANSITIONS State Transitions
71 * <td>vc_initialize()</td>
73 * <td>Initialized</td>
77 * <td>vc_deinitialize()</td>
78 * <td>Initialized</td>
83 * <td>vc_prepare()</td>
84 * <td>Initialized</td>
89 * <td>vc_unprepare()</td>
91 * <td>Initialized</td>
96 * @section CAPI_UIX_VOICE_CONTROL_MODULE_STATE_DEPENDENT_FUNCTION_CALLS State Dependent Function Calls
97 * The following table shows state-dependent function calls.
98 * It is forbidden to call functions listed below in wrong states.
99 * Violation of this rule may result in an unpredictable behavior.
103 * <th>VALID STATES</th>
104 * <th>DESCRIPTION</th>
107 * <td>vc_initialize()</td>
109 * <td>All functions must be called after vc_initialize()</td>
112 * <td>vc_deinitialize()</td>
113 * <td>Initialized, Ready</td>
114 * <td>This function should be called when an application want to finalize voice control using</td>
117 * <td>vc_prepare()</td>
118 * <td>Initialized</td>
119 * <td>This function works asynchronously. If service start is failed, application gets the error callback.</td>
122 * <td>vc_unprepare()</td>
127 * <td>vc_foreach_supported_languages()</td>
128 * <td>Initialized, Ready</td>
132 * <td>vc_get_current_language()</td>
133 * <td>Initialized, Ready</td>
137 * <td>vc_get_state()</td>
138 * <td>Initialized, Ready</td>
142 * <td>vc_get_service_state()</td>
143 * <td>Initialized, Ready</td>
147 * <td>vc_get_result()</td>
152 * <td>vc_get_system_command_list()</td>
157 * <td>vc_set_command_list()</td>
162 * <td>vc_unset_command_list()</td>
167 * <td>vc_set_invocation_name()</td>
172 * <td>vc_set_server_dialog()</td>
177 * <td>vc_request_dialog()</td>
183 * vc_set_result_cb()<br>
184 * vc_unset_result_cb()<br>
185 * vc_set_state_changed_cb()<br>
186 * vc_unset_state_changed_cb()<br>
187 * vc_set_service_state_changed_cb()<br>
188 * vc_unset_service_state_changed_cb()<br>
189 * vc_set_current_language_changed_cb()<br>
190 * vc_unset_current_language_changed_cb()<br>
191 * vc_set_error_cb()<br>
192 * vc_unset_error_cb()</td>
193 * <td>Initialized</td>
194 * <td> All callback function should be registered in Initialized state </td>
198 * @section CAPI_UIX_VOICE_CONTROL_MODULE_FEATURES Related Features
199 * This API is related with the following features:<br>
200 * - %http://tizen.org/feature/microphone<br>
201 * - %http://tizen.org/feature/speech.control<br>
202 * It is recommended to design feature related codes in your application for reliability.<br>
203 * 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>
204 * 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>
205 * More details on featuring your application can be found from <a href="https://docs.tizen.org/application/tizen-studio/native-tools/manifest-text-editor#feature-element"><b>Feature Element</b>.</a>
209 #endif /* __TIZEN_UIX_VOICE_CONTROL_DOC_H__ */