Fix API reference
[platform/core/uifw/stt.git] / include / stt.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 #ifndef __STT_H__
18 #define __STT_H__
19
20 #include <tizen.h>
21
22 /**
23  * @file stt.h
24  */
25
26 /**
27 * @addtogroup CAPI_UIX_STT_MODULE
28 * @{
29 */
30
31 #ifdef __cplusplus
32 extern "C"
33 {
34 #endif
35
36 /**
37  * @brief Enumerations for error codes.
38  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
39 */
40 typedef enum {
41         STT_ERROR_NONE                          = TIZEN_ERROR_NONE,             /**< Successful */
42         STT_ERROR_OUT_OF_MEMORY                 = TIZEN_ERROR_OUT_OF_MEMORY,    /**< Out of Memory */
43         STT_ERROR_IO_ERROR                      = TIZEN_ERROR_IO_ERROR,         /**< I/O error */
44         STT_ERROR_INVALID_PARAMETER             = TIZEN_ERROR_INVALID_PARAMETER,/**< Invalid parameter */
45         STT_ERROR_TIMED_OUT                     = TIZEN_ERROR_TIMED_OUT,        /**< No answer from the STT service */
46         STT_ERROR_RECORDER_BUSY                 = TIZEN_ERROR_RESOURCE_BUSY,    /**< Device or resource busy */
47         STT_ERROR_OUT_OF_NETWORK                = TIZEN_ERROR_NETWORK_DOWN,     /**< Network is down */
48         STT_ERROR_PERMISSION_DENIED             = TIZEN_ERROR_PERMISSION_DENIED,/**< Permission denied */
49         STT_ERROR_NOT_SUPPORTED                 = TIZEN_ERROR_NOT_SUPPORTED,    /**< STT NOT supported */
50         STT_ERROR_INVALID_STATE                 = TIZEN_ERROR_STT | 0x01,       /**< Invalid state */
51         STT_ERROR_INVALID_LANGUAGE              = TIZEN_ERROR_STT | 0x02,       /**< Invalid language */
52         STT_ERROR_ENGINE_NOT_FOUND              = TIZEN_ERROR_STT | 0x03,       /**< No available engine  */
53         STT_ERROR_OPERATION_FAILED              = TIZEN_ERROR_STT | 0x04,       /**< Operation failed  */
54         STT_ERROR_NOT_SUPPORTED_FEATURE         = TIZEN_ERROR_STT | 0x05,       /**< Not supported feature of current engine */
55         STT_ERROR_RECORDING_TIMED_OUT           = TIZEN_ERROR_STT | 0x06,       /**< Recording timed out @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
56         STT_ERROR_NO_SPEECH                     = TIZEN_ERROR_STT | 0x07,       /**< No speech while recording @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
57         STT_ERROR_IN_PROGRESS_TO_READY          = TIZEN_ERROR_STT | 0x08,       /**< Progress to ready is not finished @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
58         STT_ERROR_IN_PROGRESS_TO_RECORDING      = TIZEN_ERROR_STT | 0x09,       /**< Progress to recording is not finished @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
59         STT_ERROR_IN_PROGRESS_TO_PROCESSING     = TIZEN_ERROR_STT | 0x10,       /**< Progress to processing is not finished @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
60         STT_ERROR_SERVICE_RESET                 = TIZEN_ERROR_STT | 0x11        /**< Service reset @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
61 } stt_error_e;
62
63 /**
64  * @brief Definition for free form dictation and default type.
65  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
66 */
67 #define STT_RECOGNITION_TYPE_FREE               "stt.recognition.type.FREE"
68
69 /**
70  * @brief Definition for continuous free dictation.
71  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
72 */
73 #define STT_RECOGNITION_TYPE_FREE_PARTIAL       "stt.recognition.type.FREE.PARTIAL"
74
75 /**
76  * @brief Definition for search.
77  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
78 */
79 #define STT_RECOGNITION_TYPE_SEARCH             "stt.recognition.type.SEARCH"
80
81 /**
82  * @brief Definition for web search.
83  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
84 */
85 #define STT_RECOGNITION_TYPE_WEB_SEARCH         "stt.recognition.type.WEB_SEARCH"
86
87 /**
88  * @brief Definition for map.
89  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
90 */
91 #define STT_RECOGNITION_TYPE_MAP                "stt.recognition.type.MAP"
92
93 /**
94  * @brief Definition for none message.
95  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
96 */
97 #define STT_RESULT_MESSAGE_NONE                 "stt.result.message.none"
98
99 /**
100  * @brief Definition for failed recognition because the speech started too soon.
101  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
102 */
103 #define STT_RESULT_MESSAGE_ERROR_TOO_SOON       "stt.result.message.error.too.soon"
104
105 /**
106  * @brief Definition for failed recognition because the speech is too short.
107  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
108 */
109 #define STT_RESULT_MESSAGE_ERROR_TOO_SHORT      "stt.result.message.error.too.short"
110
111 /**
112  * @brief Definition for failed recognition because the speech is too long.
113  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
114 */
115 #define STT_RESULT_MESSAGE_ERROR_TOO_LONG       "stt.result.message.error.too.long"
116
117 /**
118  * @brief Definition for failed recognition because the speech is too quiet to listen.
119  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
120 */
121 #define STT_RESULT_MESSAGE_ERROR_TOO_QUIET      "stt.result.message.error.too.quiet"
122
123 /**
124  * @brief Definition for failed recognition because the speech is too loud to listen.
125  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
126 */
127 #define STT_RESULT_MESSAGE_ERROR_TOO_LOUD       "stt.result.message.error.too.loud"
128
129 /**
130  * @brief Definition for failed recognition because the speech is too fast to listen.
131  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
132 */
133 #define STT_RESULT_MESSAGE_ERROR_TOO_FAST       "stt.result.message.error.too.fast"
134
135
136 /**
137  * @brief Enumeration for state.
138  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
139 */
140 typedef enum {
141         STT_STATE_CREATED       = 0,            /**< 'CREATED' state */
142         STT_STATE_READY         = 1,            /**< 'READY' state */
143         STT_STATE_RECORDING     = 2,            /**< 'RECORDING' state */
144         STT_STATE_PROCESSING    = 3             /**< 'PROCESSING' state*/
145 } stt_state_e;
146
147 /**
148  * @brief Enumeration for result event.
149  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
150 */
151 typedef enum {
152         STT_RESULT_EVENT_FINAL_RESULT = 0,      /**< Event when the recognition full or last result is ready  */
153         STT_RESULT_EVENT_PARTIAL_RESULT,        /**< Event when the recognition partial result is ready  */
154         STT_RESULT_EVENT_ERROR                  /**< Event when the recognition has failed */
155 } stt_result_event_e;
156
157 /**
158  * @brief Enumeration for result time callback event.
159  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
160 */
161 typedef enum {
162         STT_RESULT_TIME_EVENT_BEGINNING = 0,    /**< Event when the token is beginning type */
163         STT_RESULT_TIME_EVENT_MIDDLE = 1,       /**< Event when the token is middle type */
164         STT_RESULT_TIME_EVENT_END = 2           /**< Event when the token is end type */
165 } stt_result_time_event_e;
166
167 /**
168  * @brief Enumeration for silence detection type.
169  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
170 */
171 typedef enum {
172         STT_OPTION_SILENCE_DETECTION_FALSE = 0, /**< Silence detection type - False */
173         STT_OPTION_SILENCE_DETECTION_TRUE = 1,  /**< Silence detection type - True */
174         STT_OPTION_SILENCE_DETECTION_AUTO = 2   /**< Silence detection type - Auto */
175 } stt_option_silence_detection_e;
176
177 /**
178  * @brief A structure of STT handler.
179  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
180 */
181 typedef struct stt_s *stt_h;
182
183 /**
184  * @brief Called to get the engine information.
185  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
186  *
187  * @param[in] engine_id Engine id
188  * @param[in] engine_name Engine name
189  * @param[in] user_data User data passed from the stt_setting_foreach_supported_engines()
190  *
191  * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
192  * @pre stt_foreach_supported_engines() will invoke this callback.
193  *
194  * @see stt_foreach_supported_engines()
195 */
196 typedef bool(*stt_supported_engine_cb)(stt_h stt, const char* engine_id, const char* engine_name, void* user_data);
197
198 /**
199  * @brief Called when STT gets the recognition result from the engine.
200  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
201  *
202  * @remarks After stt_stop() is called, silence is detected from recording, or partial result is occured,
203  *      this function is called.
204  *
205  * @param[in] stt The STT handle
206  * @param[in] event The result event
207  * @param[in] data Result texts
208  * @param[in] data_count Result text count
209  * @param[in] msg Engine message (e.g. #STT_RESULT_MESSAGE_NONE, #STT_RESULT_MESSAGE_ERROR_TOO_SHORT)
210  * @param[in] user_data The user data passed from the callback registration function
211  *
212  * @pre stt_stop() will invoke this callback if you register it using stt_set_result_cb().
213  * @post If this function is called and event is #STT_RESULT_EVENT_FINAL_RESULT, the STT state will be #STT_STATE_READY.
214  *
215  * @see stt_stop()
216  * @see stt_set_recognition_result_cb()
217  * @see stt_unset_recognition_result_cb()
218 */
219 typedef void (*stt_recognition_result_cb)(stt_h stt, stt_result_event_e event, const char** data, int data_count,
220                                           const char* msg, void *user_data);
221
222 /**
223  * @brief Called when STT get the result time stamp in free partial type.
224  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
225  *
226  * @param[in] stt The STT handle
227  * @param[in] index The result index
228  * @param[in] event The token event
229  * @param[in] text The result text
230  * @param[in] start_time The start time of result text
231  * @param[in] end_time The end time of result text
232  * @param[in] user_data The user data passed from the foreach function
233  *
234  * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
235  *
236  * @pre stt_recognition_result_cb() should be called.
237  *
238  * @see stt_recognition_result_cb()
239 */
240 typedef bool (*stt_result_time_cb)(stt_h stt, int index, stt_result_time_event_e event, const char* text,
241                                    long start_time, long end_time, void* user_data);
242
243 /**
244  * @brief Called when the state of STT is changed.
245  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
246  *
247  * @param[in] stt The STT handle
248  * @param[in] previous A previous state
249  * @param[in] current A current state
250  * @param[in] user_data The user data passed from the callback registration function
251  *
252  * @pre An application registers this callback using stt_set_state_changed_cb() to detect changing state.
253  *
254  * @see stt_set_state_changed_cb()
255  * @see stt_unset_state_changed_cb()
256 */
257 typedef void (*stt_state_changed_cb)(stt_h stt, stt_state_e previous, stt_state_e current, void* user_data);
258
259 /**
260  * @brief Called when an error occurs.
261  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
262  *
263  * @param[in] stt The STT handle
264  * @param[in] reason The error type (e.g. #STT_ERROR_OUT_OF_NETWORK, #STT_ERROR_IO_ERROR)
265  * @param[in] user_data The user data passed from the callback registration function
266  *
267  * @pre An application registers this callback using stt_set_error_cb() to detect error.
268  *
269  * @see stt_set_error_cb()
270  * @see stt_unset_error_cb()
271 */
272 typedef void (*stt_error_cb)(stt_h stt, stt_error_e reason, void *user_data);
273
274 /**
275  * @brief Called to retrieve the supported languages.
276  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
277  * @remarks The language is specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code. For example, "ko_KR" for Korean, "en_US" for American English.
278  *
279  * @param[in] stt The STT handle
280  * @param[in] language The language
281  * @param[in] user_data The user data passed from the foreach function
282  *
283  * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop
284  * @pre stt_foreach_supported_languages() will invoke this callback.
285  *
286  * @see stt_foreach_supported_languages()
287 */
288 typedef bool (*stt_supported_language_cb)(stt_h stt, const char* language, void* user_data);
289
290 /**
291  * @brief Called when the default language is changed.
292  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
293  *
294  * @param[in] stt The STT handle
295  * @param[in] previous_language A previous language
296  * @param[in] current_language A current language
297  * @param[in] user_data The user data passed from the callback registration function
298  *
299  * @see stt_set_default_language_changed_cb()
300 */
301 typedef void (*stt_default_language_changed_cb)(stt_h stt, const char* previous_language,
302                                                 const char* current_language, void* user_data);
303
304 /**
305  * @brief Called when the engine is changed.
306  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
307  *
308  * @remarks The language is specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code. For example, "ko_KR" for Korean, "en_US" for American English.
309  *
310  * @param[in] stt The STT handle
311  * @param[in] engine_id Engine id
312  * @param[in] language The default language
313  * @param[in] support_silence Whether the silence detection is supported or not
314  * @param[in] need_credential The necessity of credential
315  * @param[in] user_data The user data passed from the callback registration function
316  *
317  * @see stt_set_engine_changed_cb()
318 */
319 typedef void (*stt_engine_changed_cb)(stt_h stt, const char* engine_id, const char* language,
320                                                 bool support_silence, bool need_credential, void* user_data);
321
322 /**
323  * @brief Creates a STT handle.
324  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
325  * @privlevel public
326  * @privilege %http://tizen.org/privilege/recorder
327  *
328  * @remarks If the function succeeds, @a stt handle must be released with stt_destroy().
329  *
330  * @param[out] stt The STT handle
331  *
332  * @return 0 on success, otherwise a negative error value
333  * @retval #STT_ERROR_NONE Successful
334  * @retval #STT_ERROR_OUT_OF_MEMORY Out of memory
335  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
336  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
337  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
338  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
339  *
340  * @post If this function is called, the STT state will be #STT_STATE_CREATED.
341  *
342  * @see stt_destroy()
343 */
344 int stt_create(stt_h* stt);
345
346 /**
347  * @brief Destroys a STT handle.
348  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
349  * @privlevel public
350  * @privilege %http://tizen.org/privilege/recorder
351  *
352  * @param[in] stt The STT handle
353  *
354  * @return 0 on success, otherwise a negative error value
355  * @retval #STT_ERROR_NONE Successful
356  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
357  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
358  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
359  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
360  *
361  * @see stt_create()
362 */
363 int stt_destroy(stt_h stt);
364
365 /**
366  * @brief Retrieves supported engine information using a callback function.
367  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
368  * @privlevel public
369  * @privilege %http://tizen.org/privilege/recorder
370  *
371  * @param[in] stt The STT handle
372  * @param[in] callback The callback function to invoke
373  * @param[in] user_data The user data to be passed to the callback function
374  *
375  * @return 0 on success, otherwise a negative error value
376  * @retval #STT_ERROR_NONE Success
377  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
378  * @retval #STT_ERROR_INVALID_STATE STT Not initialized
379  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
380  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
381  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
382  *
383  * @pre The state should be #STT_STATE_CREATED.
384  * @post This function invokes stt_supported_engine_cb() repeatedly for getting engine information.
385  *
386  * @see stt_supported_engine_cb()
387 */
388 int stt_foreach_supported_engines(stt_h stt, stt_supported_engine_cb callback, void* user_data);
389
390 /**
391  * @brief Gets the current engine id.
392  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
393  * @privlevel public
394  * @privilege %http://tizen.org/privilege/recorder
395  *
396  * @remarks If the function is success, @a engine_id must be released using free().
397  *
398  * @param[in] stt The STT handle
399  * @param[out] engine_id Engine id
400  *
401  * @return 0 on success, otherwise a negative error value
402  * @retval #STT_ERROR_NONE Success
403  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
404  * @retval #STT_ERROR_INVALID_STATE STT Not initialized
405  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
406  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
407  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
408  *
409  * @pre The state should be #STT_STATE_CREATED.
410  *
411  * @see stt_set_engine()
412 */
413 int stt_get_engine(stt_h stt, char** engine_id);
414
415 /**
416  * @brief Sets the engine id.
417  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
418  * @privlevel public
419  * @privilege %http://tizen.org/privilege/recorder
420  *
421  * @param[in] stt The STT handle
422  * @param[in] engine_id Engine id
423  *
424  * @return 0 on success, otherwise a negative error value
425  * @retval #STT_ERROR_NONE Success
426  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
427  * @retval #STT_ERROR_INVALID_STATE STT Not initialized
428  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
429  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
430  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
431  *
432  * @pre The state should be #STT_STATE_CREATED.
433  *
434  * @see stt_get_engine()
435 */
436 int stt_set_engine(stt_h stt, const char* engine_id);
437
438 /**
439  * @brief Sets the app credential.
440  * @details Using this API, the application can set a credential.
441  *      The credential is a key to verify the authorization about using the engine.
442  *      If the application sets the credential, it will be able to use functions of the engine entirely.
443  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
444  *
445  * @remarks The necessity of the credential depends on the engine. In case of the engine which is basically embedded in Tizen, the credential is not necessary so far.
446  *      However, if the user wants to apply the 3rd party's engine, the credential may be necessary. In that case, please follow the policy provided by the corresponding engine.
447  *
448  * @param[in] stt The STT handle
449  * @param[in] credential The app credential
450  *
451  * @return 0 on success, otherwise a negative error value
452  * @retval #STT_ERROR_NONE Success
453  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
454  * @retval #STT_ERROR_INVALID_STATE Invalid state
455  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
456  *
457  * @pre The state should be #STT_STATE_CREATED or #STT_STATE_READY.
458  *
459  * @see stt_start()
460 */
461
462 int stt_set_credential(stt_h stt, const char* credential);
463
464 /**
465  * @brief Sets the private data to stt engine.
466  * @details The private data is the setting parameter for applying keys provided by the engine.
467  *      Using this API, the application can set the private data and use the corresponding key of the engine.
468  *      For example, if the engine provides 'partial recognition' as a recognition type, the application can set the private data as the following. \n
469  *      int ret = stt_set_private_data(stt_h, "recognition_type", "PARTIAL");
470  *
471  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
472  *
473  * @remarks If the engine is replaced with the other engine, the key may be ignored.
474  *
475  * @param[in] stt The STT handle
476  * @param[in] key The field name of private data
477  * @param[in] data The data for set
478  *
479  * @return 0 on success, otherwise a negative error value
480  * @retval #STT_ERROR_NONE Successful
481  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
482  * @retval #STT_ERROR_INVALID_STATE Invalid state
483  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
484  * @retval #STT_ERROR_TIMED_OUT No answer from the STT service
485  *
486  * @pre The state should be #STT_STATE_READY.
487  *
488  * @see stt_get_private_data()
489 */
490 int stt_set_private_data(stt_h stt, const char* key, const char* data);
491
492 /**
493  * @brief Gets the private data from stt engine.
494  * @details The private data is the information provided by the engine.
495  *      Using this API, the application can get the private data which corresponds to the key from the engine.
496
497  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
498  *
499  * @remarks If the engine is replaced with the other engine, the key may be ignored.
500  *
501  * @param[in] stt The STT handle
502  * @param[in] key The field name of private data
503  * @param[out] data The data field of private data
504  *
505  * @remarks The @a data must be released using free() when it is no longer required.
506  *
507  * @return 0 on success, otherwise a negative error value
508  * @retval #STT_ERROR_NONE Successful
509  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
510  * @retval #STT_ERROR_INVALID_STATE Invalid state
511  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
512  * @retval #STT_ERROR_TIMED_OUT No answer from the STT service
513  *
514  * @pre The state should be #STT_STATE_READY.
515  *
516  * @see stt_set_private_data()
517 */
518 int stt_get_private_data(stt_h stt, const char* key, char** data);
519
520 /**
521  * @brief Connects the STT service asynchronously.
522  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
523  * @privlevel public
524  * @privilege %http://tizen.org/privilege/recorder
525  *
526  * @param[in] stt The STT handle
527  *
528  * @return 0 on success, otherwise a negative error value
529  * @retval #STT_ERROR_NONE Successful
530  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
531  * @retval #STT_ERROR_INVALID_STATE Invalid state
532  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
533  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
534  *
535  * @pre The state should be #STT_STATE_CREATED.
536  * @post If this function is successful, the STT state will be #STT_STATE_READY. \n
537  *      If this function is failed, the error callback is called. (e.g. #STT_ERROR_ENGINE_NOT_FOUND)
538  *
539  * @see stt_unprepare()
540 */
541 int stt_prepare(stt_h stt);
542
543 /**
544  * @brief Disconnects the STT service.
545  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
546  * @privlevel public
547  * @privilege %http://tizen.org/privilege/recorder
548  *
549  * @param[in] stt The STT handle
550  *
551  * @return 0 on success, otherwise a negative error value
552  * @retval #STT_ERROR_NONE Successful
553  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
554  * @retval #STT_ERROR_INVALID_STATE Invalid state
555  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
556  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
557  *
558  * @pre The state should be #STT_STATE_READY.
559  * @post If this function is called, the STT state will be #STT_STATE_CREATED.
560  *
561  * @see stt_prepare()
562 */
563 int stt_unprepare(stt_h stt);
564
565 /**
566  * @brief Retrieves all supported languages of current engine using callback function.
567  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
568  * @privlevel public
569  * @privilege %http://tizen.org/privilege/recorder
570  *
571  * @param[in] stt The STT handle
572  * @param[in] callback The callback function to invoke
573  * @param[in] user_data The user data to be passed to the callback function
574  *
575  * @return 0 on success, otherwise a negative error value
576  * @retval #STT_ERROR_NONE Successful
577  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
578  * @retval #STT_ERROR_OUT_OF_MEMORY Out of memory
579  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
580  * @retval #STT_ERROR_ENGINE_NOT_FOUND No available engine
581  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
582  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
583  *
584  * @post This function invokes stt_supported_language_cb() repeatedly for getting languages.
585  *
586  * @see stt_supported_language_cb()
587  * @see stt_get_default_language()
588 */
589 int stt_foreach_supported_languages(stt_h stt, stt_supported_language_cb callback, void* user_data);
590
591 /**
592  * @brief Gets the default language set by the user.
593  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
594  * @privlevel public
595  * @privilege %http://tizen.org/privilege/recorder
596  * @remarks The language is specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code. \n
597  * For example, "ko_KR" for Korean, "en_US" for American English. \n
598  * If the function succeeds, @a language must be released using free() when it is no longer required.
599  *
600  * @param[in] stt The STT handle
601  * @param[out] language The language
602  *
603  * @return 0 on success, otherwise a negative error value
604  * @retval #STT_ERROR_NONE Successful
605  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
606  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
607  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
608  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
609  *
610  * @see stt_foreach_supported_languages()
611 */
612 int stt_get_default_language(stt_h stt, char** language);
613
614 /**
615  * @brief Gets the current STT state.
616  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
617  * @privlevel public
618  * @privilege %http://tizen.org/privilege/recorder
619  *
620  * @param[in] stt The STT handle
621  * @param[out] state The current STT state
622  *
623  * @return 0 on success, otherwise a negative error value
624  * @retval #STT_ERROR_NONE Successful
625  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
626  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
627  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
628  *
629  * @see stt_start()
630  * @see stt_stop()
631  * @see stt_cancel()
632  * @see stt_state_changed_cb()
633 */
634 int stt_get_state(stt_h stt, stt_state_e* state);
635
636 /**
637  * @brief Gets the current error message.
638  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
639  * @remarks This function should be called during an stt error callback. If not, the error as operation failure will be returned. \n
640  *      If the function succeeds, @a err_msg must be released using free() when it is no longer required.
641  *
642  * @param[in] stt The STT handle
643  * @param[out] err_msg The current error message
644  *
645  * @return 0 on success, otherwise a negative error value
646  * @retval #STT_ERROR_NONE Successful
647  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
648  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
649  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
650  *
651  * @see stt_set_error_cb()
652  * @see stt_unset_error_cb()
653 */
654 int stt_get_error_message(stt_h stt, char** err_msg);
655
656 /**
657  * @brief Checks whether the recognition type is supported.
658  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
659  * @privlevel public
660  * @privilege %http://tizen.org/privilege/recorder
661  *
662  * @param[in] stt The STT handle
663  * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_FREE_PARTIAL)
664  * @param[out] support The result status @c true = supported, @c false = not supported
665  *
666  * @return 0 on success, otherwise a negative error value
667  * @retval #STT_ERROR_NONE Successful
668  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
669  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
670  * @retval #STT_ERROR_INVALID_STATE Invalid state
671  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
672  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
673  *
674  * @pre The state should be #STT_STATE_READY.
675 */
676 int stt_is_recognition_type_supported(stt_h stt, const char* type, bool* support);
677
678 /**
679  * @brief Sets the silence detection.
680  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
681  * @privlevel public
682  * @privilege %http://tizen.org/privilege/recorder
683  *
684  * @param[in] stt The STT handle
685  * @param[in] type The option type
686  *
687  * @return 0 on success, otherwise a negative error value
688  * @retval #STT_ERROR_NONE Successful
689  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
690  * @retval #STT_ERROR_INVALID_STATE Invalid state
691  * @retval #STT_ERROR_NOT_SUPPORTED_FEATURE Not supported feature of current engine
692  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
693  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
694  *
695  * @pre The state should be #STT_STATE_READY.
696 */
697 int stt_set_silence_detection(stt_h stt, stt_option_silence_detection_e type);
698
699 /**
700  * @brief Sets the sound to start recording.
701  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
702  * @privlevel public
703  * @privilege %http://tizen.org/privilege/recorder
704  *
705  * @remarks Sound file type should be wav type.
706  *
707  * @param[in] stt The STT handle
708  * @param[in] filename The sound file path
709  *
710  * @return 0 on success, otherwise a negative error value
711  * @retval #STT_ERROR_NONE Successful
712  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
713  * @retval #STT_ERROR_INVALID_STATE Invalid state
714  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
715  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
716  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
717  *
718  * @pre The state should be #STT_STATE_READY.
719 */
720 int stt_set_start_sound(stt_h stt, const char* filename);
721
722 /**
723  * @brief Unsets the sound to start recording.
724  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
725  * @privlevel public
726  * @privilege %http://tizen.org/privilege/recorder
727  *
728  * @param[in] stt The STT handle
729  *
730  * @return 0 on success, otherwise a negative error value
731  * @retval #STT_ERROR_NONE Successful
732  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
733  * @retval #STT_ERROR_INVALID_STATE Invalid state
734  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
735  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
736  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
737  *
738  * @pre The state should be #STT_STATE_READY.
739 */
740 int stt_unset_start_sound(stt_h stt);
741
742 /**
743  * @brief Sets the sound to stop recording.
744  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
745  * @privlevel public
746  * @privilege %http://tizen.org/privilege/recorder
747  *
748  * @remarks Sound file type should be wav type.
749  *
750  * @param[in] stt The STT handle
751  * @param[in] filename The sound file path
752  *
753  * @return 0 on success, otherwise a negative error value
754  * @retval #STT_ERROR_NONE Successful
755  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
756  * @retval #STT_ERROR_INVALID_STATE Invalid state
757  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
758  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
759  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
760  *
761  * @pre The state should be #STT_STATE_READY.
762 */
763 int stt_set_stop_sound(stt_h stt, const char* filename);
764
765 /**
766  * @brief Unsets the sound to stop recording.
767  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
768  * @privlevel public
769  * @privilege %http://tizen.org/privilege/recorder
770  *
771  * @param[in] stt The STT handle
772  *
773  * @return 0 on success, otherwise a negative error value
774  * @retval #STT_ERROR_NONE Successful
775  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
776  * @retval #STT_ERROR_INVALID_STATE Invalid state
777  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
778  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
779  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
780  *
781  * @pre The state should be #STT_STATE_READY.
782 */
783 int stt_unset_stop_sound(stt_h stt);
784
785 /**
786  * @brief Starts recording and recognition asynchronously.
787  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
788  * @privlevel public
789  * @privilege %http://tizen.org/privilege/recorder
790  *
791  * @remarks This function starts recording in the STT service and sending recording data to engine. \n
792  * This work continues until stt_stop(), stt_cancel() or silence detected by engine.
793  *
794  * @param[in] stt The STT handle
795  * @param[in] language The language selected from stt_foreach_supported_languages()
796  * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_FREE_PARTIAL)
797  *
798  * @return 0 on success, otherwise a negative error value
799  * @retval #STT_ERROR_NONE Successful
800  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
801  * @retval #STT_ERROR_INVALID_STATE Invalid state
802  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
803  * @retval #STT_ERROR_RECORDER_BUSY Recorder busy
804  * @retval #STT_ERROR_INVALID_LANGUAGE Invalid language
805  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
806  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
807  * @retval #STT_ERROR_IN_PROGRESS_TO_RECORDING Progress to recording is not finished
808  *
809  * @pre The state should be #STT_STATE_READY.
810  * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb(). \n
811  * If this function succeeds, the STT state will be #STT_STATE_RECORDING.
812  * If you call this function again before state changes, you will receive STT_ERROR_IN_PROGRESS_TO_RECORDING.
813  *
814  * @see stt_stop()
815  * @see stt_cancel()
816  * @see stt_state_changed_cb()
817 */
818 int stt_start(stt_h stt, const char* language, const char* type);
819
820 /**
821  * @brief Finishes the recording and starts recognition processing in engine asynchronously.
822  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
823  * @privlevel public
824  * @privilege %http://tizen.org/privilege/recorder
825  *
826  * @param[in] stt The STT handle
827  *
828  * @return 0 on success, otherwise a negative error value
829  * @retval #STT_ERROR_NONE Successful
830  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
831  * @retval #STT_ERROR_INVALID_STATE Invalid state
832  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
833  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
834  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
835  * @retval #STT_ERROR_IN_PROGRESS_TO_READY Progress to ready is not finished
836  * @retval #STT_ERROR_IN_PROGRESS_TO_RECORDING Progress to recording is not finished
837  * @retval #STT_ERROR_IN_PROGRESS_TO_PROCESSING Progress to processing is not finished
838  *
839  * @pre The state should be #STT_STATE_RECORDING.
840  * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb(). \n
841  * If this function succeeds, the STT state will be #STT_STATE_PROCESSING. \n
842  * If you call this function again before state changes, you will receive STT_ERROR_IN_PROGRESS_TO_PROCESSING.
843  * After processing of engine, stt_result_cb() is called.
844  *
845  * @see stt_start()
846  * @see stt_cancel()
847  * @see stt_state_changed_cb()
848 */
849 int stt_stop(stt_h stt);
850
851 /**
852  * @brief Cancels processing recognition and recording asynchronously.
853  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
854  * @privlevel public
855  * @privilege %http://tizen.org/privilege/recorder
856  *
857  * @remarks This function cancels recording and engine cancels recognition processing. \n
858  * After successful cancel, stt_state_changed_cb() is called otherwise if error is occurred, stt_error_cb() is called.
859  *
860  * @param[in] stt The STT handle
861  *
862  * @return 0 on success, otherwise a negative error value
863  * @retval #STT_ERROR_NONE Successful
864  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
865  * @retval #STT_ERROR_INVALID_STATE Invalid state
866  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
867  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
868  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
869  * @retval #STT_ERROR_IN_PROGRESS_TO_READY Progress to ready is not finished
870  * @retval #STT_ERROR_IN_PROGRESS_TO_RECORDING Progress to recording is not finished
871  * @retval #STT_ERROR_IN_PROGRESS_TO_PROCESSING Progress to processing is not finished
872  *
873  * @pre The state should be #STT_STATE_RECORDING or #STT_STATE_PROCESSING.
874  * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb(). \n
875  * If this function succeeds, the STT state will be #STT_STATE_READY.
876  * If you call this function again before state changes, you will receive STT_ERROR_IN_PROGRESS_TO_READY.
877  *
878  * @see stt_start()
879  * @see stt_stop()
880  * @see stt_state_changed_cb()
881 */
882 int stt_cancel(stt_h stt);
883
884 /**
885  * @brief Gets the microphone volume during recording.
886  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
887  * @privlevel public
888  * @privilege %http://tizen.org/privilege/recorder
889  *
890  * @param[in] stt The STT handle
891  * @param[out] volume Recording volume
892  *
893  * @return 0 on success, otherwise a negative error value
894  * @retval #STT_ERROR_NONE Successful
895  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
896  * @retval #STT_ERROR_INVALID_STATE Invalid state
897  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
898  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
899  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
900  *
901  * @pre The state should be #STT_STATE_RECORDING.
902  *
903  * @see stt_start()
904 */
905 int stt_get_recording_volume(stt_h stt, float* volume);
906
907 /**
908  * @brief Retrieves the time stamp of the current recognition result using the callback function.
909  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
910  * @privlevel public
911  * @privilege %http://tizen.org/privilege/recorder
912  *
913  * @remarks This function should be called in stt_recognition_result_cb().
914  *      After stt_recognition_result_cb(), result data is NOT valid.
915  *
916  * @param[in] stt The STT handle
917  * @param[in] callback The callback function to invoke
918  * @param[in] user_data The user data to be passed to the callback function
919  *
920  * @return 0 on success, otherwise a negative error value
921  * @retval #STT_ERROR_NONE Successful
922  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
923  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
924  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
925  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
926  *
927  * @pre This function should be called in stt_recognition_result_cb().
928  * @post This function invokes stt_result_time_cb() repeatedly for getting time information.
929  *
930  * @see stt_result_time_cb()
931  * @see stt_recognition_result_cb()
932 */
933 int stt_foreach_detailed_result(stt_h stt, stt_result_time_cb callback, void* user_data);
934
935 /**
936  * @brief Registers a callback function to get the recognition result.
937  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
938  * @privlevel public
939  * @privilege %http://tizen.org/privilege/recorder
940  *
941  * @param[in] stt The STT handle
942  * @param[in] callback The callback function to register
943  * @param[in] user_data The user data to be passed to the callback function
944  *
945  * @return 0 on success, otherwise a negative error value
946  * @retval #STT_ERROR_NONE Successful
947  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
948  * @retval #STT_ERROR_INVALID_STATE Invalid state
949  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
950  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
951  *
952  * @pre The state should be #STT_STATE_CREATED.
953  *
954  * @see stt_recognition_result_cb()
955  * @see stt_unset_recognition_result_cb()
956 */
957 int stt_set_recognition_result_cb(stt_h stt, stt_recognition_result_cb callback, void* user_data);
958
959 /**
960  * @brief Unregisters the callback function.
961  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
962  * @privlevel public
963  * @privilege %http://tizen.org/privilege/recorder
964  *
965  * @param[in] stt The STT handle
966  *
967  * @return 0 on success, otherwise a negative error value
968  * @retval #STT_ERROR_NONE Successful
969  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
970  * @retval #STT_ERROR_INVALID_STATE Invalid state
971  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
972  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
973  *
974  * @pre The state should be #STT_STATE_CREATED.
975  *
976  * @see stt_set_recognition_result_cb()
977 */
978 int stt_unset_recognition_result_cb(stt_h stt);
979
980 /**
981  * @brief Registers a callback function to be called when STT state changes.
982  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
983  * @privlevel public
984  * @privilege %http://tizen.org/privilege/recorder
985  *
986  * @param[in] stt The STT handle
987  * @param[in] callback The callback function to register
988  * @param[in] user_data The user data to be passed to the callback function
989  *
990  * @return 0 on success, otherwise a negative error value
991  * @retval #STT_ERROR_NONE Successful
992  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
993  * @retval #STT_ERROR_INVALID_STATE Invalid state
994  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
995  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
996  *
997  * @pre The state should be #STT_STATE_CREATED.
998  *
999  * @see stt_state_changed_cb()
1000  * @see stt_unset_state_changed_cb()
1001 */
1002 int stt_set_state_changed_cb(stt_h stt, stt_state_changed_cb callback, void* user_data);
1003
1004 /**
1005  * @brief Unregisters the callback function.
1006  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1007  * @privlevel public
1008  * @privilege %http://tizen.org/privilege/recorder
1009  *
1010  * @param[in] stt The STT handle
1011  *
1012  * @return 0 on success, otherwise a negative error value
1013  * @retval #STT_ERROR_NONE Successful
1014  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1015  * @retval #STT_ERROR_INVALID_STATE Invalid state
1016  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1017  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1018  *
1019  * @pre The state should be #STT_STATE_CREATED.
1020  *
1021  * @see stt_set_state_changed_cb()
1022 */
1023 int stt_unset_state_changed_cb(stt_h stt);
1024
1025 /**
1026  * @brief Registers a callback function to be called when an error occurred.
1027  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1028  * @privlevel public
1029  * @privilege %http://tizen.org/privilege/recorder
1030  *
1031  * @param[in] stt The STT handle
1032  * @param[in] callback The callback function to register
1033  * @param[in] user_data The user data to be passed to the callback function
1034  *
1035  * @return 0 on success, otherwise a negative error value
1036  * @retval #STT_ERROR_NONE Successful
1037  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1038  * @retval #STT_ERROR_INVALID_STATE Invalid state
1039  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1040  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1041  *
1042  * @pre The state should be #STT_STATE_CREATED.
1043  *
1044  * @see stt_error_cb()
1045  * @see stt_unset_error_cb()
1046 */
1047 int stt_set_error_cb(stt_h stt, stt_error_cb callback, void* user_data);
1048
1049 /**
1050  * @brief Unregisters the callback function.
1051  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1052  * @privlevel public
1053  * @privilege %http://tizen.org/privilege/recorder
1054  *
1055  * @param[in] stt The STT handle
1056  *
1057  * @return 0 on success, otherwise a negative error value
1058  * @retval #STT_ERROR_NONE Successful
1059  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1060  * @retval #STT_ERROR_INVALID_STATE Invalid state
1061  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1062  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1063  *
1064  * @pre The state should be #STT_STATE_CREATED.
1065  *
1066  * @see stt_set_error_cb()
1067 */
1068 int stt_unset_error_cb(stt_h stt);
1069
1070 /**
1071  * @brief Registers a callback function to detect the default language change.
1072  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1073  * @privlevel public
1074  * @privilege %http://tizen.org/privilege/recorder
1075  *
1076  * @param[in] stt The STT handle
1077  * @param[in] callback The callback function to register
1078  * @param[in] user_data The user data to be passed to the callback function
1079  *
1080  * @return 0 on success, otherwise a negative error value
1081  * @retval #STT_ERROR_NONE Successful
1082  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1083  * @retval #STT_ERROR_INVALID_STATE Invalid state
1084  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1085  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1086  *
1087  * @pre The state should be #STT_STATE_CREATED.
1088  *
1089  * @see stt_default_language_changed_cb()
1090  * @see stt_unset_default_language_changed_cb()
1091 */
1092 int stt_set_default_language_changed_cb(stt_h stt, stt_default_language_changed_cb callback, void* user_data);
1093
1094 /**
1095  * @brief Unregisters the callback function.
1096  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1097  * @privlevel public
1098  * @privilege %http://tizen.org/privilege/recorder
1099  *
1100  * @param[in] stt The STT handle
1101  *
1102  * @return 0 on success, otherwise a negative error value
1103  * @retval #STT_ERROR_NONE Successful
1104  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1105  * @retval #STT_ERROR_INVALID_STATE Invalid state
1106  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1107  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1108  *
1109  * @pre The state should be #STT_STATE_CREATED.
1110  *
1111  * @see stt_set_default_language_changed_cb()
1112 */
1113 int stt_unset_default_language_changed_cb(stt_h stt);
1114
1115 /**
1116  * @brief Registers a callback function to detect the engine change.
1117  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1118  *
1119  * @param[in] stt The STT handle
1120  * @param[in] callback The callback function to register
1121  * @param[in] user_data The user data to be passed to the callback function
1122  *
1123  * @return 0 on success, otherwise a negative error value
1124  * @retval #STT_ERROR_NONE Successful
1125  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1126  * @retval #STT_ERROR_INVALID_STATE Invalid state
1127  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1128  *
1129  * @pre The state should be #STT_STATE_CREATED.
1130  *
1131  * @see stt_engine_changed_cb()
1132  * @see stt_unset_engine_changed_cb()
1133 */
1134 int stt_set_engine_changed_cb(stt_h stt, stt_engine_changed_cb callback, void* user_data);
1135
1136 /**
1137  * @brief Unregisters the callback function.
1138  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1139  *
1140  * @param[in] stt The STT handle
1141  *
1142  * @return 0 on success, otherwise a negative error value
1143  * @retval #STT_ERROR_NONE Successful
1144  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1145  * @retval #STT_ERROR_INVALID_STATE Invalid state
1146  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1147  *
1148  * @pre The state should be #STT_STATE_CREATED.
1149  *
1150  * @see stt_set_engine_changed_cb()
1151 */
1152 int stt_unset_engine_changed_cb(stt_h stt);
1153
1154
1155 #ifdef __cplusplus
1156 }
1157 #endif
1158
1159 /**
1160  * @}@}
1161  */
1162
1163 #endif /* __STT_H__ */
1164