doc/uix_vc_engine_main_doc.h

   1 /*
   2  * Copyright (c) 2011-2017 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_ENGINE_DOC_H__
  19 #define __TIZEN_UIX_VOICE_CONTROL_ENGINE_DOC_H__
  20
  21
  22 /**
  23  * @ingroup CAPI_UIX_FRAMEWORK
  24  * @defgroup CAPI_UIX_VOICE_CONTROL_ENGINE_MODULE Voice control engine
  25  * @brief The @ref CAPI_UIX_VOICE_CONTROL_ENGINE_MODULE APIs provide functions to operate Voice-Control Engine.
  26  * @section CAPI_UIX_VOICE_CONTROL_ENGINE_MODULE_HEADER Required Header
  27  * \#include <vce.h><br>
  28  *
  29  * @section CAPI_UIX_VOICE_CONTROL_ENGINE_OVERVIEW Overview
  30  * Voice-Control-Engine (below VCE) is an engine for recognize the sound data recorded by the user and send the result as a predefined command.
  31  * Using the @ref CAPI_UIX_VOICE_CONTROL_ENGINE_MODULE APIs, VCE developers can provide VCE service users, who want to apply VCE, with functions necessary to operate the engine.
  32  * According to the indispensability of VCE services, there are two ways to provide them to the users. <br>
  33  *
  34  * <b>A. Required VCE services</b> <br>
  35  * These services are indispensable to operate VCE. Therefore, the VCE developers MUST implement callback functions corresponding to the required VCE services.
  36  * The following is a list of the callback functions. <br>
  37  *
  38  * <table>
  39  * <tr>
  40  * <td>vce_get_info_cb()</td>
  41  * <td>Called when the engine service user requests the basic information of VCE.</td>
  42  * </tr>
  43  * <tr>
  44  * <td>vce_get_recording_format_cb()</td>
  45  * <td>Called when the engine service user requests the recording format of VCE.</td>
  46  * </tr>
  47  * <tr>
  48  * <td>vce_foreach_supported_languages_cb()</td>
  49  * <td>Called when the engine service user retrieves all supported languages of VC engine.</td>
  50  * </tr>
  51  * <tr>
  52  * <td>vce_is_language_supported_cb()</td>
  53  * <td>Called when the engine service user retrieves all supported languages of VCE.</td>
  54  * </tr>
  55  * <tr>
  56  * <td>vce_initialize_cb()</td>
  57  * <td>Called when the engine service user initializes VCE.</td>
  58  * </tr>
  59  * <tr>
  60  * <td>vce_deinitialize_cb()</td>
  61  * <td>Called when the engine service user deinitializes VCE.</td>
  62  * </tr>
  63  * <tr>
  64  * <td>vce_set_language_cb()</td>
  65  * <td>Called when the engine service user sets language.</td>
  66  * </tr>
  67  * <tr>
  68  * <td>vce_set_commands_cb()</td>
  69  * <td>Called when the engine service user sets command list before recognition.</td>
  70  * </tr>
  71  * <tr>
  72  * <td>vce_unset_commands_cb()</td>
  73  * <td>Called when the engine service user unsets command list for reset.</td>
  74  * </tr>
  75  * <tr>
  76  * <td>vce_start_cb()</td>
  77  * <td>Called when the engine service user starts recognition.</td>
  78  * </tr>
  79  * <tr>
  80  * <td>vce_set_recording_data_cb()</td>
  81  * <td>Called when the engine service user sets recording data for speech recognition from recorder.</td>
  82  * </tr>
  83  * <tr>
  84  * <td>vce_stop_cb()</td>
  85  * <td>Called when the engine service user stops to get the result of recognition.</td>
  86  * </tr>
  87  * <tr>
  88  * <td>vce_cancel_cb()</td>
  89  * <td>Called when the engine service user cancels the recognition process.</td>
  90  * </tr>
  91  * <tr>
  92  * <td>vce_set_audio_type_cb()</td>
  93  * <td>Called when the engine service user sets audio recording type.</td>
  94  * </tr>
  95  * <tr>
  96  * <td>vce_set_server_dialog_cb()</td>
  97  * <td>Called when the engine service user sets app id which is want to ask server dialog.</td>
  98  * </tr>
  99  * <tr>
 100  * <td>vce_set_domain_cb()</td>
 101  * <td>Called when the engine service user sets domain (agent or device type).</td>
 102  * </tr>
 103  * <tr>
 104  * <td>vce_process_text_cb()</td>
 105  * <td>Called when the engine service user requests process text.</td>
 106  * </tr>
 107  * <tr>
 108  * <td>vce_process_list_event_cb()</td>
 109  * <td>Called when the engine service user requests list event.</td>
 110  * </tr>
 111  * <tr>
 112  * <td>vce_process_haptic_event_cb()</td>
 113  * <td>Called when the engine service user requests haptic event.</td>
 114  * </tr>
 115  * </table>
 116  *
 117  * The VCE developers can register the above callback functions at a time with using a structure 'vce_request_callback_s' and an API 'vce_main()'.
 118  * To operate VCE, the following steps should be used: <br>
 119  * 1. Create a structure 'vce_request_callback_s'
 120  * 2. Implement callback functions. (NOTE that the callback functions should return appropriate values in accordance with the instruction.
 121  *      If the callback function returns an unstated value, VCE framework will handle it as #VCE_ERROR_OPERATION_FAILED.) <br>
 122  * 3. Register callback functions using 'vce_main()'. (The registered callback functions will be invoked when the VCE service users request the VCE services.) <br>
 123  * 4. Use 'service_app_main()' for working VCE. <br>
 124  *
 125  * <b>B. Optional VCE services</b> <br>
 126  * Unlike the required VCE services, these services are optional to operate VCE. The followings are optional VCE services. <br>
 127  * - receive/provide the private data <br>
 128  *
 129  * If the VCE developers want to provide the above services, use the following APIs and implement the corresponding callback functions: <br>
 130  * <table>
 131  * <tr>
 132  * <th>FUNCTION</th>
 133  * <th>DESCRIPTION</th>
 134  * <th>CORRESPONDING CALLBACK</th>
 135  * </tr>
 136  * <tr>
 137  * <td>vce_set_private_data_set_cb()</td>
 138  * <td>Sets a callback function for setting the private data to the engine service.</td>
 139  * <td>vce_private_data_set_cb()</td>
 140  * </tr>
 141  * <tr>
 142  * <td>vce_set_private_data_requested_cb()</td>
 143  * <td>Sets a callback function for requesting the private data to the engine service.</td>
 144  * <td>vce_private_data_requested_cb()</td>
 145  * </tr>
 146  * <tr>
 147  * <td>vce_set_nlu_base_info_requested_cb()</td>
 148  * <td>Sets a callback function for requesting the NLU base information to the engine service.</td>
 149  * <td>vce_nlu_base_info_requested_cb()</td>
 150  * </tr>
 151  * </table>
 152  *
 153  * Using the above APIs, the VCE developers can register the optional callback functions respectively.
 154  * (For normal operation, put those APIs before 'service_app_main()' starts.)
 155  *
 156  * Unlike callback functions, the following APIs are functions for getting and sending data. The VCE developers can use these APIs when they implement VCE services: <br>
 157  * <table>
 158  * <tr>
 159  * <th>FUNCTION</th>
 160  * <th>DESCRIPTION</th>
 161  * </tr>
 162  * <tr>
 163  * <td>vce_send_result()</td>
 164  * <td>Sends the results to the engine service user.</td>
 165  * </tr>
 166  * <tr>
 167  * <td>vce_send_asr_result()</td>
 168  * <td>Sends the ASR result to the engine service user.</td>
 169  * </tr>
 170  * <tr>
 171  * <td>vce_send_nlg_result()</td>
 172  * <td>Sends the NLG (Natural Language Generation) result to the engine service user.</td>
 173  * </tr>
 174  * <tr>
 175  * <td>vce_send_error()</td>
 176  * <td>Sends the error to the engine service user.</td>
 177  * </tr>
 178  * <tr>
 179  * <td>vce_get_foreach_command()</td>
 180  * <td>Retrieves all commands using callback function.</td>
 181  * </tr>
 182  * <tr>
 183  * <td>vce_get_command_count()</td>
 184  * <td>Gets command length.</td>
 185  * </tr>
 186  * <tr>
 187  * <td>vce_get_audio_type()</td>
 188  * <td>Gets current audio type.</td>
 189  * </tr>
 190  * <tr>
 191  * <td>vce_set_private_data()</td>
 192  * <td>Sets private data to a voice manager client.</td>
 193  * </tr>
 194  * <tr>
 195  * <td>vce_get_private_data()</td>
 196  * <td>Gets private data from a voice manager client.</td>
 197  * </tr>
 198  * <tr>
 199  * <td>vce_start_recording()</td>
 200  * <td>Starts recording voice.</td>
 201  * </tr>
 202  * <tr>
 203  * <td>vce_stop_recording()</td>
 204  * <td>Stops recording voice.</td>
 205  * </tr>
 206  * </table>
 207  *
 208  * @section CAPI_UIX_VOICE_CONTROL_ENGINE_MODULE_FEATURES Related Features
 209  * This API is related with the following features:<br>
 210  * - %http://tizen.org/feature/microphone<br>
 211  * - %http://tizen.org/feature/speech.control<br>
 212  * It is recommended to design feature related codes in your application for reliability.<br>
 213  * 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>
 214  * 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>
 215  * 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>
 216  */
 217
 218 #endif /* __TIZEN_UIX_VOICE_CONTROL_ENGINE_DOC_H__ */
 219