doc/uix_vc_doc.h

   1 /*
   2  * Copyright (c) 2011-2014 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_DOC_H__
  19 #define __TIZEN_UIX_VOICE_CONTROL_DOC_H__
  20
  21 /**
  22  * @defgroup CAPI_UIX_VOICE_CONTROL_MODULE Voice control
  23  * @ingroup CAPI_UIX_FRAMEWORK
  24  * @brief The @ref CAPI_UIX_VOICE_CONTROL_MODULE API provides functions for registering command and getting notification when registered command is recognized.
  25  *
  26  * @section CAPI_UIX_VOICE_CONTROL_MODULE_HEADER Required Header
  27  *   \#include <voice_control.h><br>
  28  *
  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  *
  33  * To use of Voice Control, use the following steps: <br>
  34  * 1. Initialize <br>
  35  * 2. Register callback functions for notifications <br>
  36  * 3. Connect to voice control service asynchronously. The state should be changed to Ready <br>
  37  * 4. Make command list as the following step and Step 4 is called repeatedly for each command which an application wants <br>
  38  * 4-1. Create command list handle <br>
  39  * 4-2. Create command handle <br>
  40  * 4-3. Set command and type for command handle <br>
  41  * 4-4. Add command handle to command list <br>
  42  * 5. Set command list for recognition <br>
  43  * 6. If an application wants to finish voice control,<br>
  44  * 6-1. Destroy command and command list handle <br>
  45  * 6-2. Deinitialize <br>
  46  *
  47  * An application can obtain command handle from command list, and also get information from handle.
  48  *
  49  *
  50  * The Voice Control API also notifies you (by callback mechanism) when the states of client and service are changed,
  51  * command is recognized, current language is changed or error occurred.
  52  * An application should register callback functions: vc_state_changed_cb(), vc_service_state_changed_cb(), vc_result_cb(),
  53  * vc_current_language_changed_cb(), vc_error_cb().
  54  *
  55  * @section CAPI_UIX_VOICE_CONTROL_MODULE_STATE_DIAGRAM State Diagram
  56  * The following diagram shows the life cycle and the states of the Voice Control.
  57  *
  58  * @image html capi_uix_voice_control_state_diagram.png "<State diagram>    "
  59  * The following diagram shows the states of Voice Control service.
  60  * @image html capi_uix_voice_control_service_state_diagram.png "<Service state diagram>"
  61  *
  62  * @section CAPI_UIX_VOICE_CONTROL_MODULE_STATE_TRANSITIONS State Transitions
  63  *
  64  * <table>
  65  * <tr>
  66  * <th>FUNCTION</th>
  67  * <th>PRE-STATE</th>
  68  * <th>POST-STATE</th>
  69  * <th>SYNC TYPE</th>
  70  * </tr>
  71  * <tr>
  72  * <td>vc_initialize()</td>
  73  * <td>None</td>
  74  * <td>Initialized</td>
  75  * <td>SYNC</td>
  76  * </tr>
  77  * <tr>
  78  * <td>vc_deinitialize()</td>
  79  * <td>Initialized</td>
  80  * <td>None</td>
  81  * <td>SYNC</td>
  82  * </tr>
  83  * <tr>
  84  * <td>vc_prepare()</td>
  85  * <td>Initialized</td>
  86  * <td>Ready</td>
  87  * <td>ASYNC</td>
  88  * </tr>
  89  * <tr>
  90  * <td>vc_unprepare()</td>
  91  * <td>Ready</td>
  92  * <td>Initialized</td>
  93  * <td>SYNC</td>
  94  * </tr>
  95
  96  * </table>
  97  *
  98  * @section CAPI_UIX_VOICE_CONTROL_MODULE_STATE_DEPENDENT_FUNCTION_CALLS State Dependent Function Calls
  99  * The following table shows state-dependent function calls.
 100  * It is forbidden to call functions listed below in wrong states.
 101  * Violation of this rule may result in an unpredictable behavior.
 102  *
 103  * <table>
 104  * <tr>
 105  * <th>FUNCTION</th>
 106  * <th>VALID STATES</th>
 107  * <th>DESCRIPTION</th>
 108  * </tr>
 109  * <tr>
 110  * <td>vc_initialize()</td>
 111  * <td>None</td>
 112  * <td>All functions must be called after vc_initialize()</td>
 113  * </tr>
 114  * <tr>
 115  * <td>vc_deinitialize()</td>
 116  * <td>Initialized, Ready</td>
 117  * <td>This function should be called when an application want to finalize voice control using</td>
 118  * </tr>
 119  * <tr>
 120  * <td>vc_prepare()</td>
 121  * <td>Initialized</td>
 122  * <td>This function works asynchronously. If service start is failed, application gets the error callback.</td>
 123  * </tr>
 124  * <tr>
 125  * <td>vc_unprepare()</td>
 126  * <td>Ready</td>
 127  * <td></td>
 128  * </tr>
 129  * <tr>
 130  * <td>vc_foreach_supported_languages()</td>
 131  * <td>Initialized, Ready</td>
 132  * <td></td>
 133  * </tr>
 134  * <tr>
 135  * <td>vc_get_current_language()</td>
 136  * <td>Initialized, Ready</td>
 137  * <td></td>
 138  * </tr>
 139  * <tr>
 140  * <td>vc_get_state()</td>
 141  * <td>Initialized, Ready</td>
 142  * <td></td>
 143  * </tr>
 144  * <tr>
 145  * <td>vc_get_service_state()</td>
 146  * <td>Initialized, Ready</td>
 147  * <td></td>
 148  * </tr>
 149  * <tr>
 150  * <td>vc_set_command_list()</td>
 151  * <td>Ready</td>
 152  * <td></td>
 153  * </tr>
 154  * <tr>
 155  * <td>vc_unset_command_list()</td>
 156  * <td>Ready</td>
 157  * <td></td>
 158  * </tr>
 159  * <tr>
 160  * <td>
 161  * vc_set_result_cb()<br>
 162  * vc_unset_result_cb()<br>
 163  * vc_set_state_changed_cb()<br>
 164  * vc_unset_state_changed_cb()<br>
 165  * vc_set_service_state_changed_cb()<br>
 166  * vc_unset_service_state_changed_cb()<br>
 167  * vc_set_current_language_changed_cb()<br>
 168  * vc_unset_current_language_changed_cb()<br>
 169  * vc_set_error_cb()<br>
 170  * vc_unset_error_cb()</td>
 171  * <td>Initialized</td>
 172  * <td> All callback function should be registered in Initialized state </td>
 173  * </tr>
 174  * </table>
 175  *
 176  * @section CAPI_UIX_VOICE_CONTROL_MODULE Related Features
 177  * This API is related with the following features:<br>
 178  *  - http://tizen.org/feature/microphone<br>
 179  *  - http://tizen.org/feature/speech.control<br>
 180  *
 181  * It is recommended to design feature related codes in your application for reliability.<br>
 182  * 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>
 183  * 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>
 184  * More details on featuring your application can be found from <a href="../org.tizen.mobile.native.appprogramming/html/ide_sdk_tools/feature_element.htm"><b>Feature Element</b>.</a>
 185  *
 186  */
 187
 188 #endif /* __TIZEN_UIX_VOICE_CONTROL_DOC_H__ */
 189