include/voice_control_authority.h

   1 /*
   2 * Copyright (c) 2011-2015 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 __VOICE_CONTROL_AUTHORITY_H__
  19 #define __VOICE_CONTROL_AUTHORITY_H__
  20
  21 #include <voice_control_common.h>
  22
  23 /**
  24 * @addtogroup VOICE_CONTROL_AUTHORITY
  25 * @{
  26 */
  27
  28 #ifdef __cplusplus
  29 extern "C"
  30 {
  31 #endif
  32
  33 /* Authority */
  34
  35 typedef enum {
  36         VC_AUTH_STATE_NONE      = 0,
  37         VC_AUTH_STATE_VALID     = 1,
  38         VC_AUTH_STATE_INVALID   = 2
  39 } vc_auth_state_e;
  40
  41
  42 /**
  43 * @brief Called when authority state of client is changed.
  44 *
  45 * @param[in] previous Previous state
  46 * @param[in] current Current state
  47 * @param[in] user_data The user data passed from the callback registration function
  48 *
  49 * @pre An application registers callback function.
  50 *
  51 * @see vc_set_auth_state_changed_cb()
  52 */
  53 typedef void (*vc_auth_state_changed_cb)(vc_auth_state_e previous, vc_auth_state_e current, void* user_data);
  54
  55 /**
  56 * @brief Enable authority about start/stop/cancel recognition.
  57 *
  58 * @return 0 on success, otherwise a negative error value
  59 * @retval #VC_ERROR_NONE Successful
  60 * @retval #VC_ERROR_INVALID_STATE Invalid state
  61 * @retval #VC_ERROR_OPERATION_FAILED Operation failed
  62 *
  63 * @pre The state should be #VC_STATE_READY.
  64 *
  65 * @see vc_auth_disable()
  66 */
  67 int vc_auth_enable();
  68
  69 /**
  70 * @brief Disable authority.
  71 *
  72 * @return 0 on success, otherwise a negative error value
  73 * @retval #VC_ERROR_NONE Successful
  74 * @retval #VC_ERROR_INVALID_STATE Invalid state
  75 * @retval #VC_ERROR_OPERATION_FAILED Operation failed
  76 *
  77 * @pre The state should be #VC_STATE_READY.
  78 *
  79 * @see vc_auth_enable()
  80 */
  81 int vc_auth_disable();
  82
  83 /**
  84 * @brief Get current authority state.
  85 *
  86 * @return 0 on success, otherwise a negative error value
  87 * @retval #VC_ERROR_NONE Successful
  88 * @retval #VC_ERROR_INVALID_STATE Invalid state
  89 *
  90 * @pre The state should be #VC_STATE_READY.
  91 */
  92 int vc_auth_get_state(vc_auth_state_e* status);
  93
  94 /**
  95 * @brief Set callback for authority state changing.
  96 *
  97 * @return 0 on success, otherwise a negative error value
  98 * @retval #VC_ERROR_NONE Successful
  99 * @retval #VC_ERROR_INVALID_STATE Invalid state
 100 * @retval #VC_ERROR_OPERATION_FAILED Operation failed
 101 *
 102 * @pre This function should be called when the authority state is #VC_AUTH_STATE_VALID or #VC_AUTH_STATE_INVALID.
 103 *
 104 * @see vc_auth_unset_state_changed_cb()
 105 * @see vc_auth_state_changed_cb()
 106 */
 107 int vc_auth_set_state_changed_cb(vc_auth_state_changed_cb callback, void* user_data);
 108
 109 /**
 110 * @brief Unset callback for authority state changing.
 111 *
 112 * @remarks This function will be called in vc_auth_disable() automatically.
 113 *
 114 * @return 0 on success, otherwise a negative error value
 115 * @retval #VC_ERROR_NONE Successful
 116 * @retval #VC_ERROR_INVALID_STATE Invalid state
 117 * @retval #VC_ERROR_OPERATION_FAILED Operation failed
 118 *
 119 * @pre This function should be called when the authority state is #VC_AUTH_STATE_VALID or #VC_AUTH_STATE_INVALID.
 120 *
 121 * @see vc_auth_set_state_changed_cb()
 122 */
 123 int vc_auth_unset_state_changed_cb();
 124
 125 /**
 126 * @brief Start recognition.
 127 *
 128 * @return 0 on success, otherwise a negative error value
 129 * @retval #VC_ERROR_NONE Successful
 130 * @retval #VC_ERROR_INVALID_STATE Invalid state
 131 * @retval #VC_ERROR_OPERATION_FAILED Operation failed
 132 *
 133 * @pre The state should be #VC_STATE_READY and the service state should be #VC_SERVICE_STATE_READY. \n
 134 * The authority status should be #VC_AUTHORITY_STATUS_VALID.
 135 * @post It will invoke vc_service_state_changed_cb(), if you register a callback with vc_service_state_changed_cb(). \n
 136 * If this function succeeds, the service state will be #VC_SERVICE_STATE_RECORDING.
 137 *
 138 * @see vc_auth_stop()
 139 * @see vc_auth_cancel()
 140 */
 141 int vc_auth_start();
 142
 143 /**
 144 * @brief Stop recognition.
 145 *
 146 * @return 0 on success, otherwise a negative error value
 147 * @retval #VC_ERROR_NONE Successful
 148 * @retval #VC_ERROR_INVALID_STATE Invalid state
 149 * @retval #VC_ERROR_OPERATION_FAILED Operation failed
 150 *
 151 * @pre The service state should be #VC_SERVICE_STATE_RECORDING. \n
 152 * The authority status should be #VC_AUTHORITY_STATUS_VALID.
 153 * @post It will invoke vc_service_state_changed_cb(), if you register a callback with vc_service_state_changed_cb(). \n
 154 * If this function succeeds, the service state will be #VC_SERVICE_STATE_PROCESSING.
 155 *
 156 * @see vc_auth_start()
 157 * @see vc_auth_cancel()
 158 */
 159 int vc_auth_stop();
 160
 161 /**
 162 * @brief Cancel recognition.
 163 *
 164 * @return 0 on success, otherwise a negative error value
 165 * @retval #VC_ERROR_NONE Successful
 166 * @retval #VC_ERROR_INVALID_STATE Invalid state
 167 * @retval #VC_ERROR_OPERATION_FAILED Operation failed
 168 *
 169 * @pre The service state should be #VC_SERVICE_STATE_RECORDING or #VC_SERVICE_STATE_PROCESSING. \n
 170 * The authority status should be #VC_AUTHORITY_STAUS_VALID.
 171 * @post It will invoke vc_service_state_changed_cb(), if you register a callback with vc_service_state_changed_cb(). \n
 172 * If this function succeeds, the service state will be #VC_SERVICE_STATE_READY.
 173 *
 174 * @see vc_auth_start()
 175 * @see vc_auth_stop()
 176 */
 177 int vc_auth_cancel();
 178
 179
 180 #ifdef __cplusplus
 181 }
 182 #endif
 183
 184 /**
 185  * @}
 186  */
 187
 188 #endif /* __VOICE_CONTROL_AUTHORITY_H__ */