--- /dev/null
+/*
+ * Copyright (c) 2011-2017 Samsung Electronics Co., Ltd All Rights Reserved
+ *
+ * Licensed under the Apache License, Version 2.0 (the License);
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an AS IS BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+#ifndef __TIZEN_UIX_VOICE_CONTROL_ENGINE_DOC_H__
+#define __TIZEN_UIX_VOICE_CONTROL_ENGINE_DOC_H__
+
+
+/**
+ * @ingroup CAPI_UIX_FRAMEWORK
+ * @defgroup CAPI_UIX_VOICE_CONTROL_ENGINE_MODULE Voice control engine
+ * @brief The @ref CAPI_UIX_VOICE_CONTROL_ENGINE_MODULE APIs provide functions to operate Voice-Control Engine.
+ * @section CAPI_UIX_VOICE_CONTROL_ENGINE_MODULE_HEADER Required Header
+ * \#include <vce.h><br>
+ *
+ * @section CAPI_UIX_VOICE_CONTROL_ENGINE_OVERVIEW Overview
+ * Voice-Control-Engine (below VCE) is an engine for recognize the sound data recorded by the user and send the result as a predefined command.
+ * Using the @ref CAPI_UIX_VOICE_CONTROL_ENGINE_MODULE APIs, VCE developers can provide VCE service users, who want to apply VCE, with functions necessary to operate the engine.
+ * According to the indispensability of VCE services, there are two ways to provide them to the users. <br>
+ *
+ * <b>A. Required VCE services</b> <br>
+ * These services are indispensable to operate VCE. Therefore, the VCE developers MUST implement callback functions corresponding to the required VCE services.
+ * The following is a list of the callback functions. <br>
+ *
+ * <table>
+ * <tr>
+ * <td>vce_get_info_cb()</td>
+ * <td>Called when the engine service user requests the basic information of VCE.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_get_recording_format_cb()</td>
+ * <td>Called when the engine service user requests the recording format of VCE.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_foreach_supported_languages_cb()</td>
+ * <td>Called when the engine service user retrieves all supported languages of VC engine.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_is_language_supported_cb()</td>
+ * <td>Called when the engine service user retrieves all supported languages of VCE.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_initialize_cb()</td>
+ * <td>Called when the engine service user initializes VCE.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_deinitialize_cb()</td>
+ * <td>Called when the engine service user deinitializes VCE.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_set_language_cb()</td>
+ * <td>Called when the engine service user sets language.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_set_commands_cb()</td>
+ * <td>Called when the engine service user sets command list before recognition.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_unset_commands_cb()</td>
+ * <td>Called when the engine service user unsets command list for reset.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_start_cb()</td>
+ * <td>Called when the engine service user starts recognition.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_set_recording_data_cb()</td>
+ * <td>Called when the engine service user sets recording data for speech recognition from recorder.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_stop_cb()</td>
+ * <td>Called when the engine service user stops to get the result of recognition.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_cancel_cb()</td>
+ * <td>Called when the engine service user cancels the recognition process.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_set_audio_type_cb()</td>
+ * <td>Called when the engine service user sets audio recording type.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_set_domain_cb()</td>
+ * <td>Called when the engine service user sets domain (agent or device type).</td>
+ * </tr>
+ * <tr>
+ * <td>vce_process_text_cb()</td>
+ * <td>Called when the engine service user requests process text.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_process_list_event_cb()</td>
+ * <td>Called when the engine service user requests list event.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_process_haptic_event_cb()</td>
+ * <td>Called when the engine service user requests haptic event.</td>
+ * </tr>
+ * </table>
+ *
+ * The VCE developers can register the above callback functions at a time with using a structure 'vce_request_callback_s' and an API 'vce_main()'.
+ * To operate VCE, the following steps should be used: <br>
+ * 1. Create a structure 'vce_request_callback_s'
+ * 2. Implement callback functions. (NOTE that the callback functions should return appropriate values in accordance with the instruction.
+ * If the callback function returns an unstated value, VCE framework will handle it as #VCE_ERROR_OPERATION_FAILED.) <br>
+ * 3. Register callback functions using 'vce_main()'. (The registered callback functions will be invoked when the VCE service users request the VCE services.) <br>
+ * 4. Use 'service_app_main()' for working VCE. <br>
+ *
+ * <b>B. Optional VCE services</b> <br>
+ * Unlike the required VCE services, these services are optional to operate VCE. The followings are optional VCE services. <br>
+ * - receive/provide the private data <br>
+ *
+ * If the VCE developers want to provide the above services, use the following APIs and implement the corresponding callback functions: <br>
+ * <table>
+ * <tr>
+ * <th>FUNCTION</th>
+ * <th>DESCRIPTION</th>
+ * <th>CORRESPONDING CALLBACK</th>
+ * </tr>
+ * <tr>
+ * <td>vce_set_private_data_set_cb()</td>
+ * <td>Sets a callback function for setting the private data to the engine service.</td>
+ * <td>vce_private_data_set_cb()</td>
+ * </tr>
+ * <tr>
+ * <td>vce_set_private_data_requested_cb()</td>
+ * <td>Sets a callback function for requesting the private data to the engine service.</td>
+ * <td>vce_private_data_requested_cb()</td>
+ * </tr>
+ * <tr>
+ * <td>vce_set_nlu_base_info_requested_cb()</td>
+ * <td>Sets a callback function for requesting the NLU base information to the engine service.</td>
+ * <td>vce_nlu_base_info_requested_cb()</td>
+ * </tr>
+ * </table>
+ *
+ * Using the above APIs, the VCE developers can register the optional callback functions respectively.
+ * (For normal operation, put those APIs before 'service_app_main()' starts.)
+ *
+ * Unlike callback functions, the following APIs are functions for getting and sending data. The VCE developers can use these APIs when they implement VCE services: <br>
+ * <table>
+ * <tr>
+ * <th>FUNCTION</th>
+ * <th>DESCRIPTION</th>
+ * </tr>
+ * <tr>
+ * <td>vce_send_result()</td>
+ * <td>Sends the results to the engine service user.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_send_asr_result()</td>
+ * <td>Sends the ASR result to the engine service user.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_send_nlg_result()</td>
+ * <td>Sends the NLG (Natural Language Generation) result to the engine service user.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_send_error()</td>
+ * <td>Sends the error to the engine service user.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_get_foreach_command()</td>
+ * <td>Retrieves all commands using callback function.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_get_command_count()</td>
+ * <td>Gets command length.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_get_audio_type()</td>
+ * <td>Gets current audio type.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_set_private_data()</td>
+ * <td>Sets private data to a voice manager client.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_get_private_data()</td>
+ * <td>Gets private data from a voice manager client.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_start_recording()</td>
+ * <td>Starts recording voice.</td>
+ * </tr>
+ * <tr>
+ * <td>vce_stop_recording()</td>
+ * <td>Stops recording voice.</td>
+ * </tr>
+ * </table>
+ *
+ * @section CAPI_UIX_VOICE_CONTROL_ENGINE_MODULE_FEATURES Related Features
+ * This API is related with the following features:<br>
+ * - http://tizen.org/feature/microphone<br>
+ * - http://tizen.org/feature/speech.control<br>
+ * It is recommended to design feature related codes in your application for reliability.<br>
+ * 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>
+ * 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>
+ * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tizen-studio/native-tools/configuring-your-app/manifest-text-editor#feature"><b>Feature Element</b>.</a>
+ */
+
+#endif /* __TIZEN_UIX_VOICE_CONTROL_ENGINE_DOC_H__ */
+
VCE_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< I/O error */
VCE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,/**< Invalid parameter */
VCE_ERROR_OUT_OF_NETWORK = TIZEN_ERROR_NETWORK_DOWN, /**< Out of network */
- VCE_ERROR_RECORDER_BUSY = TIZEN_ERROR_RESOURCE_BUSY,/**< Busy resource */
+ VCE_ERROR_RECORDER_BUSY = TIZEN_ERROR_RESOURCE_BUSY,/**< Busy resource */
+ VCE_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< VC Engine NOT supported */
VCE_ERROR_INVALID_STATE = TIZEN_ERROR_VOICE_CONTROL | 0x011, /**< Invalid state */
VCE_ERROR_INVALID_LANGUAGE = TIZEN_ERROR_VOICE_CONTROL | 0x012, /**< Invalid language */
VCE_ERROR_OPERATION_FAILED = TIZEN_ERROR_VOICE_CONTROL | 0x014, /**< Operation failed */
*/
typedef enum {
VCE_RESULT_EVENT_SUCCESS = 0, /**< Event when the recognition full result is ready */
- VCE_RESULT_EVENT_REJECTED, /**< Event when the recognition result is rejected */
- VCE_RESULT_EVENT_ERROR /**< Event when the recognition has failed */
+ VCE_RESULT_EVENT_REJECTED, /**< Event when the recognition result is rejected */
+ VCE_RESULT_EVENT_ERROR /**< Event when the recognition has failed */
} vce_result_event_e;
/**
* @details This callback function is implemented by the engine service user. Therefore, the engine developer does NOT have to implement this callback function.
* @since_tizen 5.0
* @remarks This callback function is called by vce_foreach_supported_languages_cb() to retrieve the whole supported language list.
-* @a user_data must be transferred from vce_foreach_supported_languages_cb().
-* @param[in] language A 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
-* For example, "ko_KR" for Korean, "en_US" for American English
+* The @a user_data must be transferred from vce_foreach_supported_languages_cb().
+* The @a language can be used only in the callback. To use outside, make a copy.
+* @param[in] language A 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
+* For example, "ko_KR" for Korean, "en_US" for American English.
* @param[in] user_data The user data passed from the foreach function
* @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
* @pre vce_foreach_supported_languages() will invoke this callback.
typedef bool (*vce_supported_language_cb)(const char* language, void* user_data);
/**
-* @brief Called when the engine service user initializes VC engine.
+* @brief Called when the engine service user initializes Voice Control (VC) engine.
* @since_tizen 5.0
* @remarks This callback function is mandatory and must be registered using vce_main().
* @return 0 on success, otherwise a negative error value
* @brief Called when the engine service user requests the recording format of VC engine.
* @since_tizen 5.0
* @remarks This callback function is mandatory and must be registered using vce_main().
-* @param[out] audio_id The audio device id. (e.g. #VCE_AUDIO_ID_BLUETOOTH or VCE_AUDIO_ID_WIFI)
+* The @a audio_id can be used only in the callback. To use outside, make a copy.
+* @param[in] audio_id The audio device id. (e.g. #VCE_AUDIO_ID_BLUETOOTH or #VCE_AUDIO_ID_WIFI)
* @param[out] types The format used by the recorder.
* @param[out] rate The sample rate used by the recorder.
* @param[out] channels The number of channels used by the recorder.
* @retval #VCE_ERROR_NONE Successful
* @retval #VCE_ERROR_INVALID_PARAMETER Not initialized
*/
-typedef int (*vce_get_recording_format_cb)(const char* audio_id, const vce_audio_type_e* types, const int* rate, const int* channels);
+typedef int (*vce_get_recording_format_cb)(const char* audio_id, vce_audio_type_e* types, int* rate, int* channels);
/**
* @brief Called when the engine service user retrieves all supported languages of VC engine.
* @brief Called when the engine service user checks whether a language is supported or not.
* @since_tizen 5.0
* @remarks This callback function is mandatory and must be registered using vce_main().
-* @param[out] language A language
+* The @a language can be used only in the callback. To use outside, make a copy.
+* @param[in] language A language
* @return @c true = supported, \n @c false = not supported.
*/
typedef bool (*vce_is_language_supported_cb)(const char* language);
/**
* @brief Called when the engine service user sets language.
* @since_tizen 5.0
+* @remarks The @a language can be used only in the callback. To use outside, make a copy.
* @param[in] language A language.
* @return 0 on success, otherwise a negative error value
* @retval #VCE_ERROR_NONE Successful
* @retval #VCE_ERROR_INVALID_LANGUAGE Invalid language
* @retval #VCE_ERROR_INVALID_STATE Not initialized
+* @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
*/
typedef int (*vce_set_language_cb)(const char* language);
* @brief Called when the engine service user sets command list before recognition.
* @since_tizen 5.0
* @remarks This function should set commands via vcd_foreach_command().
-* @param[in] vc_command command handle.
+* @param[in] vc_command command handle. The @a vc_command can be used only in the callback. To use outside, make a copy.
* @return 0 on success, otherwise a negative error value
* @retval #VCE_ERROR_NONE Successful
* @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #VCE_ERROR_INVALID_STATE Invalid state
* @retval #VCE_ERROR_OPERATION_FAILED Operation failed
+* @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
* @see vce_set_commands_cb()
*/
typedef int (*vce_unset_commands_cb)(void);
* @brief Called when the engine service user sets recording data for speech recognition from recorder.
* @since_tizen 5.0
* @remarks This function should be returned immediately after recording data copy.
-* @param[out] data A recording data
-* @param[out] length A length of recording data
-* @param[in] speech_detected The status of speech (e.g. VCE_SPEECH_DETECT_BEGIN or VCE_SPEECH_DETECT_END)
+* The @a data can be used only in the callback. To use outside, make a copy.
+* @param[in] data A recording data
+* @param[in] length A length of recording data
+* @param[out] speech_detected The status of speech (e.g. #VCE_SPEECH_DETECT_BEGIN or #VCE_SPEECH_DETECT_END). The @a speech_detected can be used only in the callback. To use outside, make a copy.
* @return 0 on success, otherwise a negative error value
* @retval #VCE_ERROR_NONE Successful
* @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
/**
* @brief Called when the engine service user sets audio recording type.
* @since_tizen 5.0
-* @param[in] audio Available agent or device type
+* @remarks The @a audio can be used only in the callback. To use outside, make a copy.
+* @param[in] audio_type Current audio type (e.g. #VCE_AUDIO_ID_BLUETOOTH or #VCE_AUDIO_ID_WIFI)
* @return 0 on success, otherwise a negative error value.
* @retval #VCE_ERROR_NONE Successful.
+* @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature.
*/
-typedef int (*vce_set_audio_type_cb)(const char* audio);
+typedef int (*vce_set_audio_type_cb)(const char* audio_type);
/**
-* @brief Called when the engine service user sets domain (Agent or device type).
+* @brief Called when the engine service user sets domain (agent or device type).
* @since_tizen 5.0
-* @param[in] domain Available agent or device type
+* @remarks The @a domain can be used only in the callback. To use outside, make a copy.
+* @param[in] domain Agent (e.g. "music", "news", etc) or device type (e.g. "tv", "mobile", etc) corresponding to the command
* @return 0 on success, otherwise a negative error value.
* @retval #VCE_ERROR_NONE Successful.
+* @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
*/
typedef int (*vce_set_domain_cb)(const char* domain);
/**
-* @brief Called when the engine service user requests essential value from nlu result.
+* @brief Called when the engine service user requests essential value from NLU result.
* @since_tizen 5.0
-* @remarks This function is available inside vce_nlu_result_cb()
-* @param[in] key NLU base info key
-* @param[out] value NLU base info value
+* @remarks The @a key can be used only in the callback. To use outside, make a copy.
+* @param[in] key NLU base info key.
+* @param[out] value NLU base info value.
* @return 0 on success, otherwise a negative error value.
+* @retval #VCE_ERROR_NONE Successful.
+* @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature.
*/
typedef int (*vce_nlu_base_info_requested_cb)(const char* key, char** value);
/**
* @brief Called when the engine service user sets private data between app and engine.
* @since_tizen 5.0
-* @param[in] key Private key
-* @param[in] data Private data
+* @remarks The @a key, @a data can be used only in the callback. To use outside, make a copy.
+* @param[in] key Private key.
+* @param[in] data Private data.
* @return 0 on success, otherwise a negative error value.
+* @retval #VCE_ERROR_NONE Successful.
+* @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature.
*/
typedef int (*vce_private_data_set_cb)(const char* key, const char* data);
/**
* @brief Called when the engine service user requests private data between app and engine.
* @since_tizen 5.0
-* @param[in] key Private key
-* @param[out] data Private data
+* @remarks The @a key can be used only in the callback. To use outside, make a copy.
+* @param[in] key Private key.
+* @param[out] data Private data.
* @return 0 on success, otherwise a negative error value.
+* @retval #VCE_ERROR_NONE Successful.
+* @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature.
*/
typedef int (*vce_private_data_requested_cb)(const char* key, char** data);
/**
* @brief Called when the engine service user requests process text.
* @since_tizen 5.0
+* @remarks The @a text can be used only in the callback. To use outside, make a copy.
* @param[in] text Requested text
* @return 0 on success, otherwise a negative error value.
+* @retval #VCE_ERROR_NONE Successful.
+* @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature.
*/
typedef int (*vce_process_text_cb)(const char* text);
/**
* @brief Called when the engine service user requests list event.
* @since_tizen 5.0
+* @remarks The @a event can be used only in the callback. To use outside, make a copy.
* @param[in] event Requested list event
* @return 0 on success, otherwise a negative error value.
+* @retval #VCE_ERROR_NONE Successful.
+* @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature.
*/
typedef int (*vce_process_list_event_cb)(const char* event);
/**
* @brief Called when the engine service user requests haptic event.
* @since_tizen 5.0
+* @remarks The @a event can be used only in the callback. To use outside, make a copy.
* @param[in] event Requested haptic event
* @return 0 on success, otherwise a negative error value.
+* @retval #VCE_ERROR_NONE Successful.
+* @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature.
*/
typedef int (*vce_process_haptic_event_cb)(const char* event);
* @brief Called when the engine service user requests the base information of VC engine.
* @since_tizen 5.0
* @remarks This callback function is mandatory and must be registered using vce_main().
-* The allocated @a engine_uuid, @a engine_name, and @a engine_setting will be released internally.
-* In order to upload the engine at Tizen Appstore, both a service app and a ui app are necessary.
-* Therefore, @a engine_setting must be transferred to the engine service user.
+* The allocated @a engine_uuid, @a engine_name, and @a engine_settings_app_id will be released internally.
+* In order to upload the engine to Tizen Appstore, both the service app and the UI app (engine settings) are necessary.
+* Therefore, @a engine_settings_app_id should be set to the application ID of the UI application.
+* If there is no UI application, then @a engine_settings_app_id should be set to NULL.
* @param[out] engine_uuid The engine id
* @param[out] engine_name The engine name
-* @param[out] engine_setting The setting path name
+* @param[out] engine_settings_app_id The ID of the engine settings application (the UI application)
* @param[out] use_network @c true to need network @c false not to need network.
-* @return @c 0 on success,
-* otherwise a negative error code on failure
+* @return @c 0 on success, otherwise a negative error code on failure
* @retval #VCE_ERROR_NONE Successful
* @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #VCE_ERROR_OPERATION_FAILED Operation failure
*/
-typedef int (*vce_get_info_cb)(char** engine_uuid, char** engine_name, char** engine_setting, bool* use_network);
+typedef int (*vce_get_info_cb)(char** engine_uuid, char** engine_name, char** engine_settings_app_id, bool* use_network);
/**
* @brief Called to retrieve the commands.
* @since_tizen 5.0
+* @remarks The @a command, @a param can be used only in the callback. To use outside, make a copy.
* @param[in] id command id
* @param[in] type command type
* @param[in] format command format
int version; /**< Version */
/* Get engine information */
- vce_get_info_cb get_info; /**< Called when the engine service user requests the basic information of VC engine */
- vce_get_recording_format_cb get_recording_format; /**< Get recording format */
- vce_foreach_supported_languages_cb foreach_langs; /**< Foreach language list */
- vce_is_language_supported_cb is_lang_supported; /**< Check language */
+ vce_get_info_cb get_info; /**< Called when the engine service user requests the basic information of VC engine */
+ vce_get_recording_format_cb get_recording_format; /**< Get recording format */
+ vce_foreach_supported_languages_cb foreach_langs; /**< Foreach language list */
+ vce_is_language_supported_cb is_lang_supported; /**< Check language */
- vce_initialize_cb initialize; /**< Initialize engine */
- vce_deinitialize_cb deinitialize; /**< Shutdown engine */
+ vce_initialize_cb initialize; /**< Initialize engine */
+ vce_deinitialize_cb deinitialize; /**< Shutdown engine */
/* Set info */
- vce_set_language_cb set_language; /**< Set language */
- vce_set_commands_cb set_commands; /**< Request to set current commands */
- vce_unset_commands_cb unset_commands; /**< Request to unset current commands */
+ vce_set_language_cb set_language; /**< Set language */
+ vce_set_commands_cb set_commands; /**< Request to set current commands */
+ vce_unset_commands_cb unset_commands; /**< Request to unset current commands */
/* Control recognition */
- vce_start_cb start; /**< Start recognition */
- vce_set_recording_data_cb set_recording; /**< Set recording data */
- vce_stop_cb stop; /**< Stop recording for getting result */
- vce_cancel_cb cancel; /**< Cancel recording and processing */
+ vce_start_cb start; /**< Start recognition */
+ vce_set_recording_data_cb set_recording; /**< Set recording data */
+ vce_stop_cb stop; /**< Stop recording for getting result */
+ vce_cancel_cb cancel; /**< Cancel recording and processing */
- vce_set_audio_type_cb set_audio_type; /**< Set audio type */
+ vce_set_audio_type_cb set_audio_type; /**< Set audio type */
- vce_set_domain_cb set_domain; /**< Set domain */
- vce_process_text_cb process_text; /**< Request to process text */
- vce_process_list_event_cb process_list_event; /**< Request to process list event */
- vce_process_haptic_event_cb process_haptic_event; /**< Request to process haptic event */
+ vce_set_domain_cb set_domain; /**< Set domain */
+ vce_process_text_cb process_text; /**< Request to process text */
+ vce_process_list_event_cb process_list_event; /**< Request to process list event */
+ vce_process_haptic_event_cb process_haptic_event; /**< Request to process haptic event */
} vce_request_callback_s;
/**
* @param[in] argc The argument count(original)
* @param[in] argv The argument(original)
* @param[in] callback The structure of engine request callback function
-* @return This function returns @c zero on success,
-* or negative with error code on failure
+* @return This function returns @c zero on success, or negative with error code on failure
* @retval #VCE_ERROR_NONE Successful
* @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
* @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #VCE_ERROR_NOT_SUPPORTED Not supported
* @retval #VCE_ERROR_OPERATION_FAILED Operation failed
* @pre The vce_get_engine_info() should be successful.
-* @post The daemon calls engine functions of vce_funcs_s.
* @see vce_get_engine_info()
* @see vce_unload_engine()
* @see vce_request_callback_s
* @param[in] msg Engine message (e.g. #VC_RESULT_MESSAGE_NONE, #VC_RESULT_MESSAGE_ERROR_TOO_LOUD)
* @param[out] user_info A user info (e.g. If ASR result is consumed, the value is 0x01. If not, the value is 0x00.)
* @param[in] user_data The user data passed from set callback function
-* @return @c 0 on success,
-* otherwise a negative error value
+* @return @c 0 on success, otherwise a negative error value
* @retval #VCE_ERROR_NONE Successful
* @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
* @param[in] event A asr result event
* @param[in] asr_result A asr result text
* @param[in] user_data The user data passed from the start
-* @return @c 0 on success,
-* otherwise a negative error value
+* @return @c 0 on success, otherwise a negative error value
* @retval #VCE_ERROR_NONE Successful
* @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
int vce_send_asr_result(vce_asr_result_event_e event, const char* asr_result, void* user_data);
/**
-* @brief Sends the nlg(natural language generation) result to the engine service user.
+* @brief Sends the NLG (Natural Language Generation) result to the engine service user.
* @since_tizen 5.0
* @param[in] nlg_result A nlg result
* @param[in] user_data The user data passed from the start
-* @return @c 0 on success,
-* otherwise a negative error value
+* @return @c 0 on success, otherwise a negative error value
* @retval #VCE_ERROR_NONE Successful
* @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
/**
* @brief Sends the error to the engine service user.
-* @details The following error codes can be delivered.
-* #VCE_ERROR_NONE,
-* #VCE_ERROR_OUT_OF_MEMORY,
-* #VCE_ERROR_IO_ERROR,
-* #VCE_ERROR_INVALID_PARAMETER,
-* #VCE_ERROR_OUT_OF_NETWORK,
-* #VCE_ERROR_RECORDER_BUSY,
-* #VCE_ERROR_INVALID_STATE,
-* #VCE_ERROR_INVALID_LANGUAGE,
-* #VCE_ERROR_OPERATION_FAILED,
-* #VCE_ERROR_PERMISSION_DENIED,
-* #VCE_ERROR_NOT_SUPPORTED_FEATURE.
+* @details The following error codes can be delivered. \n
+* #VCE_ERROR_NONE, \n
+* #VCE_ERROR_OUT_OF_MEMORY, \n
+* #VCE_ERROR_IO_ERROR, \n
+* #VCE_ERROR_INVALID_PARAMETER, \n
+* #VCE_ERROR_OUT_OF_NETWORK, \n
+* #VCE_ERROR_RECORDER_BUSY, \n
+* #VCE_ERROR_NOT_SUPPORTED, \n
+* #VCE_ERROR_INVALID_STATE, \n
+* #VCE_ERROR_INVALID_LANGUAGE, \n
+* #VCE_ERROR_OPERATION_FAILED, \n
+* #VCE_ERROR_PERMISSION_DENIED, \n
+* #VCE_ERROR_NOT_SUPPORTED_FEATURE.
* @since_tizen 5.0
* @param[in] error Error type
* @param[in] msg Error message
* @param[in] user_data The user data passed from set callback function
-* @return @c 0 on success,
-* otherwise a negative error value
+* @return @c 0 on success, otherwise a negative error value
* @retval #VCE_ERROR_NONE Successful
* @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #VCE_ERROR_OUT_OF_MEMORY Out of Memory
* @privilege %http://tizen.org/privilege/recorder
* @remarks The vce_private_data_set_cb() function is called when the engine service user sets the private data to the engine service.
* @param[in] callback_func vce_private_data_set event callback function
-* @return @c 0 on success,
-* otherwise a negative error value
+* @return @c 0 on success, otherwise a negative error value
* @retval #VCE_ERROR_NONE Successful
* @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
* @retval #VCE_ERROR_NOT_SUPPORTED Not supported
* @retval #VCE_ERROR_OPERATION_FAILED Operation failure
+* @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
* @pre The vce_main() function should be invoked before this function is called.
* @see vce_private_data_set_cb()
*/
* @privilege %http://tizen.org/privilege/recorder
* @remarks The vce_private_data_requested_cb() function is called when the engine service user requests the private data to the engine service.
* @param[in] callback_func vce_private_data_requested event callback function
-* @return @c 0 on success,
-* otherwise a negative error value
+* @return @c 0 on success, otherwise a negative error value
* @retval #VCE_ERROR_NONE Successful
* @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
* @since_tizen 5.0
* @remarks The vce_nlu_base_info_requested_cb() function is called when the engine service user requests the NLU base information to the engine service.
* @param[in] callback_func vce_nlu_base_info_requested event callback function
-* @return @c 0 on success,
-* otherwise a negative error value
+* @return @c 0 on success, otherwise a negative error value
* @retval #VCE_ERROR_NONE Successful
* @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #VCE_ERROR_OPERATION_FAILED Operation failure
+* @retval #VCE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
* @see vce_nlu_base_info_requested_cb()
*/
int vce_set_nlu_base_info_requested_cb(vce_nlu_base_info_requested_cb callback_func);
* @brief Gets command length.
* @since_tizen 5.0
* @param[in] vce_command The handle to be passed to the vce_set_commands() function
-* @return the value greater than 0 on success
+* @param[out] count The command count value
+* @return 0 on success, otherwise a negative error value.
+* @retval #VCE_ERROR_NONE Successful
+* @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
+* @retval #VCE_ERROR_OPERATION_FAILED Operation failure
* @see vce_set_commands()
*/
-int vce_get_command_count(vce_cmd_h vce_command);
+int vce_get_command_count(vce_cmd_h vce_command, int* count);
/**
* @brief Gets current audio type.
* @since_tizen 5.0
+* @privlevel public
+* @privilege %http://tizen.org/privilege/recorder
* @remarks audio_type must be released using free() when it is no longer required.
-* @param[in] audio_type Current audio type (e.g. #VCE_AUDIO_ID_BLUETOOTH or VCE_AUDIO_ID_WIFI)
+* @param[in] audio_type Current audio type (e.g. #VCE_AUDIO_ID_BLUETOOTH or #VCE_AUDIO_ID_WIFI)
* @return the value greater than 0 on success, otherwise a negative error value
* @retval #VCE_ERROR_NONE Successful
* @retval #VCE_ERROR_INVALID_PARAMETER Invalid parameter
+* @retval #VCE_ERROR_PERMISSION_DENIED Permission denied
+* @retval #VCE_ERROR_NOT_SUPPORTED Not supported
*/
int vce_get_audio_type(char** audio_type);
/**
-* @brief Sets private data to Manager client.
+* @brief Sets private data to a voice manager client.
* @since_tizen 5.0
* @privlevel public
* @privilege %http://tizen.org/privilege/recorder
int vce_set_private_data(const char* key, const char* data);
/**
-* @brief Gets private data from Manager client.
+* @brief Gets private data from a voice manager client.
* @since_tizen 5.0
* @privlevel public
* @privilege %http://tizen.org/privilege/recorder
+* @remarks The @a data should not be released.
* @param[in] key Private key
* @param[out] data Private data
* @return 0 on success, otherwise a negative error value.
int vce_get_private_data(const char* key, char** data);
/**
-* @brief Request start recording.
+* @brief Starts recording voice.
* @since_tizen 5.0
* @privlevel public
* @privilege %http://tizen.org/privilege/recorder
int vce_start_recording(void);
/**
-* @brief Request stop recording.
+* @brief Stops recording voice.
* @since_tizen 5.0
* @privlevel public
* @privilege %http://tizen.org/privilege/recorder
projects / platform / core / uifw / voice-control.git / commitdiff