doc/uix_vc_mgr_doc.h

   1 /*
   2  * Copyright (c) 2011-2018 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   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
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17
  18 #ifndef __TIZEN_UIX_VOICE_CONTROL_MANAGER_DOC_H__
  19 #define __TIZEN_UIX_VOICE_CONTROL_MANAGER_DOC_H__
  20
  21
  22 /**
  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>
  28  *
  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 controlling Voice Control applications.
  34  * Like this, the Voice Control Manager application takes a role of controlling Voice Control applications.
  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>
  37  * 1. Initialize <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().
  56  *
  57  *
  58  * @section CAPI_UIX_VOICE_CONTROL_MANAGER_MODULE_STATE_TRANSITIONS State Transitions
  59  * <table>
  60  * <tr>
  61  * <th>FUNCTION</th>
  62  * <th>PRE-STATE</th>
  63  * <th>POST-STATE</th>
  64  * <th>SYNC TYPE</th>
  65  * </tr>
  66  * <tr>
  67  * <td>vc_mgr_initialize()</td>
  68  * <td>None</td>
  69  * <td>Initialized</td>
  70  * <td>SYNC</td>
  71  * </tr>
  72  * <tr>
  73  * <td>vc_mgr_deinitialize()</td>
  74  * <td>None, Initialized, Ready</td>
  75  * <td>None</td>
  76  * <td>SYNC</td>
  77  * </tr>
  78  * <tr>
  79  * <td>vc_mgr_prepare()</td>
  80  * <td>Initialized</td>
  81  * <td>Ready</td>
  82  * <td>ASYNC</td>
  83  * </tr>
  84  * <tr>
  85  * <td>vc_mgr_unprepare()</td>
  86  * <td>Ready</td>
  87  * <td>Initialized</td>
  88  * <td>SYNC</td>
  89  * </tr>
  90  * </table>
  91  *
  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.
  96  * <table>
  97  * <tr>
  98  * <th>FUNCTION</th>
  99  * <th>VALID STATES</th>
 100  * <th>DESCRIPTION</th>
 101  * </tr>
 102  * <tr>
 103  * <td>vc_mgr_initialize()</td>
 104  * <td>None</td>
 105  * <td>All functions must be called after vc_mgr_initialize()</td>
 106  * </tr>
 107  * <tr>
 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>
 111  * </tr>
 112  * <tr>
 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>
 116  * </tr>
 117  * <tr>
 118  * <td>vc_mgr_unprepare()</td>
 119  * <td>Ready</td>
 120  * <td></td>
 121  * </tr>
 122  * <tr>
 123  * <td>vc_mgr_foreach_supported_languages()</td>
 124  * <td>Initialized, Ready</td>
 125  * <td></td>
 126  * </tr>
 127  * <tr>
 128  * <td>vc_mgr_get_current_language()</td>
 129  * <td>Initialized, Ready</td>
 130  * <td></td>
 131  * </tr>
 132  * <tr>
 133  * <td>vc_mgr_get_state()</td>
 134  * <td>Initialized, Ready</td>
 135  * <td></td>
 136  * </tr>
 137  * <tr>
 138  * <td>vc_mgr_get_service_state()</td>
 139  * <td>Ready</td>
 140  * <td></td>
 141  * </tr>
 142  * <tr>
 143  * <td>vc_mgr_is_command_format_supported()</td>
 144  * <td>Ready</td>
 145  * <td></td>
 146  * </tr>
 147  * <tr>
 148  * <td>vc_mgr_set_command_list()</td>
 149  * <td>Ready</td>
 150  * <td></td>
 151  * </tr>
 152  * <tr>
 153  * <td>vc_mgr_unset_command_list()</td>
 154  * <td>Ready</td>
 155  * <td></td>
 156  * </tr>
 157  * <tr>
 158  * <td>vc_mgr_set_command_list_from_file()</td>
 159  * <td>Ready</td>
 160  * <td></td>
 161  * </tr>
 162  * <tr>
 163  * <td>vc_mgr_set_preloaded_commands_from_file()</td>
 164  * <td>Ready</td>
 165  * <td></td>
 166  * </tr>
 167  * <tr>
 168  * <td>vc_mgr_get_current_commands()</td>
 169  * <td>Ready</td>
 170  * <td>The service state should be #VC_SERVICE_STATE_READY.</td>
 171  * </tr>
 172  * <tr>
 173  * <td>vc_mgr_set_audio_type()</td>
 174  * <td>Ready</td>
 175  * <td>The service state should be #VC_SERVICE_STATE_READY.</td>
 176  * </tr>
 177  * <tr>
 178  * <td>vc_mgr_get_audio_type()</td>
 179  * <td>Ready</td>
 180  * <td>The service state should be #VC_SERVICE_STATE_READY.</td>
 181  * </tr>
 182  * <tr>
 183  * <td>vc_mgr_set_recognition_mode()</td>
 184  * <td>Ready</td>
 185  * <td>The service state should be #VC_SERVICE_STATE_READY.</td>
 186  * </tr>
 187  * <tr>
 188  * <td>vc_mgr_get_recognition_mode()</td>
 189  * <td>Ready</td>
 190  * <td></td>
 191  * </tr>
 192  * <tr>
 193  * <td>vc_mgr_set_private_data()</td>
 194  * <td>Ready</td>
 195  * <td></td>
 196  * </tr>
 197  * <tr>
 198  * <td>vc_mgr_get_private_data()</td>
 199  * <td>Ready</td>
 200  * <td></td>
 201  * </tr>
 202  * <tr>
 203  * <td>vc_mgr_do_action()</td>
 204  * <td>Ready</td>
 205  * <td></td>
 206  * </tr>
 207  * <tr>
 208  * <td>vc_mgr_start()</td>
 209  * <td>Ready</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>
 211  * </tr>
 212  * <tr>
 213  * <td>vc_mgr_stop()</td>
 214  * <td>Ready</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>
 216  * </tr>
 217  * <tr>
 218  * <td>vc_mgr_cancel()</td>
 219  * <td>Ready</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>
 221  * </tr>
 222  * <tr>
 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>
 226  * </tr>
 227  * <tr>
 228  * <td>vc_mgr_set_selected_results()</td>
 229  * <td>None, Initialized, Ready</td>
 230  * <td></td>
 231  * </tr>
 232  * <tr>
 233  * <td>vc_mgr_get_error_message()</td>
 234  * <td>None, Initialized, Ready</td>
 235  * <td></td>
 236  * </tr>
 237  * <tr>
 238  * <td>vc_mgr_enable_command_type()</td>
 239  * <td>Ready</td>
 240  * <td></td>
 241  * </tr>
 242  * <tr>
 243  * <td>vc_mgr_disable_command_type()</td>
 244  * <td>Ready</td>
 245  * <td></td>
 246  * </tr>
 247  * <tr>
 248  * <td>
 249  * vc_mgr_set_all_result_cb()<br>
 250  * vc_mgr_unset_all_result_cb()<br>
 251  * vc_mgr_set_pre_result_cb()<br>
 252  * vc_mgr_unset_pre_result_cb()<br>
 253  * vc_mgr_set_result_cb()<br>
 254  * vc_mgr_unset_result_cb()<br>
 255  * vc_mgr_set_state_changed_cb()<br>
 256  * vc_mgr_unset_state_changed_cb()<br>
 257  * vc_mgr_set_service_state_changed_cb()<br>
 258  * vc_mgr_unset_service_state_changed_cb()<br>
 259  * vc_mgr_set_speech_detected_cb()<br>
 260  * vc_mgr_unset_speech_detected_cb()<br>
 261  * vc_mgr_set_current_language_changed_cb()<br>
 262  * vc_mgr_unset_current_language_changed_cb()<br>
 263  * vc_mgr_set_error_cb()<br>
 264  * vc_mgr_unset_error_cb()<br>
 265  * vc_mgr_set_dialog_request_cb()<br>
 266  * vc_mgr_unset_dialog_request_cb()<br>
 267  * vc_mgr_set_private_data_set_cb()<br>
 268  * vc_mgr_unset_private_data_set_cb()<br>
 269  * vc_mgr_set_private_data_requested_cb()<br>
 270  * vc_mgr_unset_private_data_requested_cb()</td>
 271  * <td>Initialized</td>
 272  * <td> All callback function should be registered in Initialized state </td>
 273  * </tr>
 274  * </table>
 275  *
 276  * @section CAPI_UIX_VOICE_CONTROL_MANAGER_MODULE_FEATURES Related Features
 277  * This API is related with the following features:<br>
 278  * - %http://tizen.org/feature/microphone<br>
 279  * - %http://tizen.org/feature/speech.control_manager<br>
 280  * It is recommended to design feature related codes in your application for reliability.<br>
 281  * 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>
 282  * 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>
 283  * 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>
 284  */
 285
 286
 287 #endif /* __TIZEN_UIX_VOICE_CONTROL_MANAGER_DOC_H__ */
 288
 289
 290
 291