2 * Copyright (c) 2011-2015 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 #ifndef __VOICE_CONTROL_AUTHORITY_H__
19 #define __VOICE_CONTROL_AUTHORITY_H__
21 #include <voice_control_common.h>
24 * @addtogroup VOICE_CONTROL_AUTHORITY
36 VC_AUTH_STATE_NONE = 0,
37 VC_AUTH_STATE_VALID = 1,
38 VC_AUTH_STATE_INVALID = 2
43 * @brief Called when authority state of client is changed.
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
49 * @pre An application registers callback function.
51 * @see vc_set_auth_state_changed_cb()
53 typedef void (*vc_auth_state_changed_cb)(vc_auth_state_e previous, vc_auth_state_e current, void* user_data);
56 * @brief Enable authority about start/stop/cancel recognition.
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
63 * @pre The state should be #VC_STATE_READY.
65 * @see vc_auth_disable()
70 * @brief Disable authority.
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
77 * @pre The state should be #VC_STATE_READY.
79 * @see vc_auth_enable()
81 int vc_auth_disable();
84 * @brief Get current authority state.
86 * @return 0 on success, otherwise a negative error value
87 * @retval #VC_ERROR_NONE Successful
88 * @retval #VC_ERROR_INVALID_STATE Invalid state
90 * @pre The state should be #VC_STATE_READY.
92 int vc_auth_get_state(vc_auth_state_e* status);
95 * @brief Set callback for authority state changing.
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
102 * @pre This function should be called when the authority state is #VC_AUTH_STATE_VALID or #VC_AUTH_STATE_INVALID.
104 * @see vc_auth_unset_state_changed_cb()
105 * @see vc_auth_state_changed_cb()
107 int vc_auth_set_state_changed_cb(vc_auth_state_changed_cb callback, void* user_data);
110 * @brief Unset callback for authority state changing.
112 * @remarks This function will be called in vc_auth_disable() automatically.
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
119 * @pre This function should be called when the authority state is #VC_AUTH_STATE_VALID or #VC_AUTH_STATE_INVALID.
121 * @see vc_auth_set_state_changed_cb()
123 int vc_auth_unset_state_changed_cb();
126 * @brief Start recognition.
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
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.
138 * @see vc_auth_stop()
139 * @see vc_auth_cancel()
144 * @brief Stop recognition.
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
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.
156 * @see vc_auth_start()
157 * @see vc_auth_cancel()
162 * @brief Cancel recognition.
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
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.
174 * @see vc_auth_start()
175 * @see vc_auth_stop()
177 int vc_auth_cancel();
188 #endif /* __VOICE_CONTROL_AUTHORITY_H__ */