doc/uix_stt_engine_main_doc.h

   1 /*
   2  * Copyright (c) 2011-2016 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_STT_ENGINE_DOC_H__
  19 #define __TIZEN_UIX_STT_ENGINE_DOC_H__
  20
  21
  22 /**
  23  * @ingroup CAPI_UIX_FRAMEWORK
  24  * @defgroup CAPI_UIX_STTE_MODULE STT Engine
  25  * @brief The @ref CAPI_UIX_STTE_MODULE APIs provide functions to operate Speech-To-Text Engine.
  26  * @section CAPI_UIX_STTE_MODULE_HEADER Required Header
  27  * \#include <stte.h>
  28  *
  29  * @section CAPI_UIX_STTE_MODULE_OVERVIEW Overview
  30  * Speech-To-Text Engine (below STTE) is an engine for recording speech and resulting in texts of speech recognition.
  31  * Using the @ref CAPI_UIX_STTE_MODULE APIs, STTE developers can provide STTE service users, who want to apply STTE, with functions necessary to operate the engine.
  32  * According to the indispensability of STTE services, there are two ways to provide them to the users. <br>
  33  * <b>A. Required STTE services</b> <br>
  34  * These services are indispensable to operate STTE. Therefore, the STTE developers MUST implement callback functions corresponding to the required STTE services.
  35  * The following is a list of the callback functions. <br>
  36  * <table>
  37  * <tr>
  38  * <th>FUNCTION</th>
  39  * <th>DESCRIPTION</th>
  40  * </tr>
  41  * <tr>
  42  * <td>stte_get_info_cb()</td>
  43  * <td>Called when the engine service user requests the basic information of STT engine.</td>
  44  * </tr>
  45  * <tr>
  46  * <td>stte_initialize_cb()</td>
  47  * <td>Called when the engine service user initializes STT engine.</td>
  48  * </tr>
  49  * <tr>
  50  * <td>stte_deinitialize_cb()</td>
  51  * <td>Called when the engine service user deinitializes STT engine.</td>
  52  * </tr>
  53  * <tr>
  54  * <td>stte_is_valid_language_cb()</td>
  55  * <td>Called when the engine service user checks whether the corresponding language is valid or not.</td>
  56  * </tr>
  57  * <tr>
  58  * <td>stte_foreach_supported_langs_cb()</td>
  59  * <td>Called when the engine service user gets the whole supported language list.</td>
  60  * </tr>
  61  * <tr>
  62  * <td>stte_support_silence_detection_cb()</td>
  63  * <td>Called when the engine service user checks whether STT engine supports silence detection.</td>
  64  * </tr>
  65  * <tr>
  66  * <td>stte_set_silence_detection_cb()</td>
  67  * <td>Called when the engine service user sets the silence detection.</td>
  68  * </tr>
  69  * <tr>
  70  * <td>stte_support_recognition_type_cb()</td>
  71  * <td>Called when the engine service user checks whether STT engine supports the corresponding recognition type.</td>
  72  * </tr>
  73  * <tr>
  74  * <td>stte_get_recording_format_cb()</td>
  75  * <td>Called when the engine service user gets the proper recording format of STT engine.</td>
  76  * </tr>
  77  * <tr>
  78  * <td>stte_set_recording_data_cb()</td>
  79  * <td>Called when the engine service user sets and sends the recording data for speech recognition.</td>
  80  * </tr>
  81  * <tr>
  82  * <td>stte_foreach_result_time_cb()</td>
  83  * <td>Called when the engine service user gets the result time information(stamp).</td>
  84  * </tr>
  85  * <tr>
  86  * <td>stte_start_cb()</td>
  87  * <td>Called when the engine service user starts to recognize the recording data.</td>
  88  * </tr>
  89  * <tr>
  90  * <td>stte_stop_cb()</td>
  91  * <td>Called when the engine service user stops to recognize the recording data.</td>
  92  * </tr>
  93  * <tr>
  94  * <td>stte_cancel_cb()</td>
  95  * <td>Called when the engine service user cancels to recognize the recording data.</td>
  96  * </tr>
  97  * <tr>
  98  * <td>stte_check_app_agreed_cb()</td>
  99  * <td>Called when the engine service user requests for STT engine to check whether the application agreed the usage of STT engine.</td>
 100  * </tr>
 101  * <tr>
 102  * <td>stte_need_app_credential_cb()</td>
 103  * <td>Called when the engine service user checks whether STT engine needs the application's credential.</td>
 104  * </tr>
 105  * </table>
 106  * The STTE developers can register the above callback functions at a time with using a structure 'stte_request_callback_s' and an API 'stte_main()'.
 107  * To operate STTE, the following steps should be used: <br>
 108  * 1. Create a structure 'stte_request_callback_s'. <br>
 109  * 2. Implement callback functions. (NOTE that the callback functions should return appropriate values in accordance with the instruction.
 110  *    If the callback function returns an unstated value, STT framework will handle it as #STTE_ERROR_OPERATION_FAILED.)<br>
 111  * 3. Register callback functions using 'stte_main()'. (The registered callback functions will be called when the STTE service users request the STTE services.) <br>
 112  * 4. Use 'service_app_main()' for working STTE. <br>
 113  * <b>B. Optional STTE services</b> <br>
 114  * Unlike the required STTE services, these services are optional to operate STTE. The followings are optional STTE services. <br>
 115  * - receive/provide the private data <br>
 116  * If the STTE developers want to provide the above services, use the following APIs and implement the corresponding callback functions: <br>
 117  * <table>
 118  * <tr>
 119  * <th>FUNCTION</th>
 120  * <th>DESCRIPTION</th>
 121  * <th>CORRESPONDING CALLBACK</th>
 122  * </tr>
 123  * <tr>
 124  * <td>stte_set_private_data_set_cb()</td>
 125  * <td>Sets a callback function for receiving the private data from the engine service user.</td>
 126  * <td>stte_private_data_set_cb()</td>
 127  * </tr>
 128  * <tr>
 129  * <td>stte_set_private_data_requested_cb()</td>
 130  * <td>Sets a callback function for providing the private data to the engine service user.</td>
 131  * <td>stte_private_data_requested_cb()</td>
 132  * </tr>
 133  * </table>
 134  * <br>
 135  * Using the above APIs, the STTE developers can register the optional callback functions respectively.
 136  * (For normal operation, put those APIs before 'service_app_main()' starts.)
 137  * Unlike callback functions, the following APIs are functions for getting and sending data. The STTE developers can use these APIs when they implement STTE services: <br>
 138  * <table>
 139  * <tr>
 140  * <th>FUNCTION</th>
 141  * <th>DESCRIPTION</th>
 142  * </tr>
 143  * <tr>
 144  * <td>stte_send_result()</td>
 145  * <td>Sends the recognition result to the engine service user.</td>
 146  * </tr>
 147  * <tr>
 148  * <td>stte_send_error()</td>
 149  * <td>Sends the error to the engine service user.</td>
 150  * </tr>
 151  * <tr>
 152  * <td>stte_send_speech_status()</td>
 153  * <td>Sends the speech status to the engine service user when STT engine notifies the change of the speech status.</td>
 154  * </tr>
 155  * </table>
 156  *
 157  * @section CAPI_UIX_STTE_MODULE_FEATURE Related Features
 158  * This API is related with the following features:<br>
 159  * - http://tizen.org/feature/speech.recognition<br>
 160  * - http://tizen.org/feature/microphone<br>
 161  * It is recommended to design feature related codes in your application for reliability.<br>
 162  * 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>
 163  * 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>
 164  * 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>
 165  */
 166
 167
 168 #endif /* __TIZEN_UIX_STT_ENGINE_DOC_H__ */
 169