From fbd8e0a9497afe3e375000d973035bc4c7d31a19 Mon Sep 17 00:00:00 2001 From: "sooyeon.kim" Date: Tue, 11 Oct 2016 14:40:30 +0900 Subject: [PATCH] Fix documentation for ACR Change-Id: Iea6ee606b333e855aefae0c67bc0713a290866df Signed-off-by: sooyeon.kim --- client/vc.c | 1 + common/vc_cmd_db.h | 2 +- common/vc_command.c | 6 +- include/CMakeLists.txt | 1 + include/voice_control.h | 1004 ++++++++++++++++---------------- include/voice_control_command.h | 738 ++++++++++++----------- include/voice_control_command_expand.h | 46 +- include/voice_control_common.h | 204 +++---- include/voice_control_internal.h | 65 +++ packaging/voice-control.spec | 1 + server/vcd_recorder.c | 2 + 11 files changed, 1044 insertions(+), 1026 deletions(-) create mode 100644 include/voice_control_internal.h diff --git a/client/vc.c b/client/vc.c index e6b4de9..46ef551 100644 --- a/client/vc.c +++ b/client/vc.c @@ -33,6 +33,7 @@ #include "vc_json_parser.h" #include "vc_main.h" #include "voice_control.h" +#include "voice_control_internal.h" #include "voice_control_authority.h" #include "voice_control_command.h" #include "voice_control_command_expand.h" diff --git a/common/vc_cmd_db.h b/common/vc_cmd_db.h index c0028b6..c580ce2 100644 --- a/common/vc_cmd_db.h +++ b/common/vc_cmd_db.h @@ -40,7 +40,7 @@ typedef enum { VC_DB_ERROR_OPERATION_REJECTED = TIZEN_ERROR_VOICE_CONTROL | 0x015, /**< Operation rejected */ VC_DB_ERROR_ITERATION_END = TIZEN_ERROR_VOICE_CONTROL | 0x016, /**< List reached end */ VC_DB_ERROR_EMPTY = TIZEN_ERROR_VOICE_CONTROL | 0x017, /**< List empty */ - VC_DB_ERROR_SERVICE_RESET = TIZEN_ERROR_VOICE_CONTROL | 0x018 /**< Service Damon reset */ + VC_DB_ERROR_SERVICE_RESET = TIZEN_ERROR_VOICE_CONTROL | 0x018 /**< Service daemon reset @if MOBILE (Since 3.0) @endif */ } vc_db_error_e; typedef struct _deactivated_app_s { diff --git a/common/vc_command.c b/common/vc_command.c index 3252b90..c37287e 100755 --- a/common/vc_command.c +++ b/common/vc_command.c @@ -1103,7 +1103,7 @@ int vc_cmd_get_type(vc_cmd_h vc_command, int* type) return 0; } -int vc_cmd_set_format(vc_cmd_h vc_command, vc_cmd_format_e format) +int vc_cmd_set_format(vc_cmd_h vc_command, int format) { if (0 != __vc_cmd_get_feature_enabled()) { return VC_ERROR_NOT_SUPPORTED; @@ -1127,7 +1127,7 @@ int vc_cmd_set_format(vc_cmd_h vc_command, vc_cmd_format_e format) return 0; } -int vc_cmd_get_format(vc_cmd_h vc_command, vc_cmd_format_e* format) +int vc_cmd_get_format(vc_cmd_h vc_command, int* format) { if (0 != __vc_cmd_get_feature_enabled()) { return VC_ERROR_NOT_SUPPORTED; @@ -2269,4 +2269,4 @@ int vc_cmd_get_datetime(const char *text, time_t *result, char **remain) SLOG(LOG_DEBUG, TAG_VCCMD, ""); return VC_ERROR_NONE; -} \ No newline at end of file +} diff --git a/include/CMakeLists.txt b/include/CMakeLists.txt index d40a4de..7d0db51 100644 --- a/include/CMakeLists.txt +++ b/include/CMakeLists.txt @@ -14,6 +14,7 @@ INSTALL(FILES ${CMAKE_BINARY_DIR}/include/voice-control-engine.pc DESTINATION ${ ## Install header files ## INSTALL(FILES ${CMAKE_BINARY_DIR}/include/voice_control.h DESTINATION ${INCLUDEDIR}) +INSTALL(FILES ${CMAKE_BINARY_DIR}/include/voice_control_internal.h DESTINATION ${INCLUDEDIR}) INSTALL(FILES ${CMAKE_BINARY_DIR}/include/voice_control_authority.h DESTINATION ${INCLUDEDIR}) INSTALL(FILES ${CMAKE_BINARY_DIR}/include/voice_control_command.h DESTINATION ${INCLUDEDIR}) INSTALL(FILES ${CMAKE_BINARY_DIR}/include/voice_control_command_expand.h DESTINATION ${INCLUDEDIR}) diff --git a/include/voice_control.h b/include/voice_control.h index 205a39a..4d9c51a 100644 --- a/include/voice_control.h +++ b/include/voice_control.h @@ -1,18 +1,18 @@ -/* -* Copyright (c) 2011-2015 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. -*/ +/** + * Copyright (c) 2011-2016 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 __VOICE_CONTROL_H__ @@ -22,9 +22,9 @@ #include /** -* @addtogroup CAPI_UIX_VOICE_CONTROL_MODULE -* @{ -*/ + * @addtogroup CAPI_UIX_VOICE_CONTROL_MODULE + * @{ + */ #ifdef __cplusplus extern "C" @@ -32,583 +32,567 @@ extern "C" #endif /** -* @file voice_control.h -* @brief This file contains the voice control client API and related callback definitions and enums. -*/ + * @file voice_control.h + * @brief This file contains the voice control client API and related callback definitions and enums. + */ /** -* @file voice_control_command.h -* @brief This file contains the command list and command API and related handle definitions and enums. -*/ + * @file voice_control_command.h + * @brief This file contains the command list and command API and related handle definitions and enums. + */ /** -* @file voice_control_common.h -* @brief This file contains the callback function definitions and enums. -*/ + * @file voice_control_common.h + * @brief This file contains the callback function definitions and enums. + */ /** -* @brief Definitions for foreground command type. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -*/ + * @brief Definitions for foreground command type. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + */ #define VC_COMMAND_TYPE_FOREGROUND 1 /** -* @brief Definitions for background command type. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -*/ + * @brief Definitions for background command type. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + */ #define VC_COMMAND_TYPE_BACKGROUND 2 /** -* @brief Definitions for ended dialog. -* @since_tizen 3.0 -*/ + * @brief Definitions for ended dialog. + * @since_tizen 3.0 + */ #define VC_DIALOG_END 0 /** -* @brief Definitions for continued dialog. -* @since_tizen 3.0 -*/ + * @brief Definitions for continued dialog. + * @since_tizen 3.0 + */ #define VC_DIALOG_CONTINUE 1 /** -* @brief Initializes voice control. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @remarks If the function succeeds, @a vc must be released with vc_deinitialize(). -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_OUT_OF_MEMORY Out of memory -* @retval #VC_ERROR_OPERATION_FAILED Operation failure -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @post If this function is called, the state will be #VC_STATE_INITIALIZED. -* -* @see vc_deinitialize() -*/ + * @brief Initializes voice control. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @remarks If the function succeeds, @a vc must be released with vc_deinitialize(). + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory + * @retval #VC_ERROR_OPERATION_FAILED Operation failure + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @post If this function is called, the state will be #VC_STATE_INITIALIZED. + * + * @see vc_deinitialize() + */ int vc_initialize(void); /** -* @brief Deinitializes voice control. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_OPERATION_FAILED Operation failure -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @see vc_deinitialize() -*/ + * @brief Deinitializes voice control. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_OPERATION_FAILED Operation failure + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @see vc_deinitialize() + */ int vc_deinitialize(void); /** -* @brief Connects the voice control service. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_OPERATION_FAILED Operation failure -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_INITIALIZED. -* @post If this function is called, the state will be #VC_STATE_READY. -* -* @see vc_unprepare() -*/ + * @brief Connects the voice control service. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_OPERATION_FAILED Operation failure + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_INITIALIZED. + * @post If this function is called, the state will be #VC_STATE_READY. + * + * @see vc_unprepare() + */ int vc_prepare(void); /** -* @brief Disconnects the voice control service. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_READY. -* @post If this function is called, the state will be #VC_STATE_INITIALIZED. -* -* @see vc_prepare() -*/ + * @brief Disconnects the voice control service. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_READY. + * @post If this function is called, the state will be #VC_STATE_INITIALIZED. + * + * @see vc_prepare() + */ int vc_unprepare(void); /** -* @brief Retrieves all supported languages using callback function. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @param[in] callback Callback function to invoke -* @param[in] user_data The user data to be passed to the callback function -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_OPERATION_FAILED Operation failure -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_INITIALIZED or #VC_STATE_READY. -* @post This function invokes vc_supported_language_cb() repeatedly for getting languages. -* -* @see vc_supported_language_cb() -* @see vc_get_current_language() -*/ + * @brief Retrieves all supported languages using callback function. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @param[in] callback Callback function to invoke + * @param[in] user_data The user data to be passed to the callback function + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_OPERATION_FAILED Operation failure + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_INITIALIZED or #VC_STATE_READY. + * @post This function invokes vc_supported_language_cb() repeatedly for getting languages. + * + * @see vc_supported_language_cb() + * @see vc_get_current_language() + */ int vc_foreach_supported_languages(vc_supported_language_cb callback, void* user_data); /** -* @brief Gets current language. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @remark If the function succeeds, @a language must be released with free() by you when you no longer need it. -* -* @param[out] language A language is specified as an ISO 3166 alpha-2 two letter country-code \n -* followed by ISO 639-1 for the two-letter language code. \n -* For example, "ko_KR" for Korean, "en_US" for American English. -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_OUT_OF_MEMORY Out of memory -* @retval #VC_ERROR_OPERATION_FAILED Operation failure -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_INITIALIZED or #VC_STATE_READY. -* -* @see vc_foreach_supported_languages() -*/ + * @brief Gets current language. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @remark If the function succeeds, @a language must be released with free() by you when you no longer need it. + * + * @param[out] language A language is specified as an ISO 3166 alpha-2 two letter country-code \n + * followed by ISO 639-1 for the two-letter language code. \n + * For example, "ko_KR" for Korean, "en_US" for American English. + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory + * @retval #VC_ERROR_OPERATION_FAILED Operation failure + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_INITIALIZED or #VC_STATE_READY. + * + * @see vc_foreach_supported_languages() + */ int vc_get_current_language(char** language); /** -* @brief Gets current state of voice control client. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @param[out] state The current state -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @see vc_state_changed_cb() -* @see vc_set_state_changed_cb() -*/ + * @brief Gets current state of voice control client. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @param[out] state The current state + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @see vc_state_changed_cb() + * @see vc_set_state_changed_cb() + */ int vc_get_state(vc_state_e* state); /** -* @brief Gets current state of voice control service. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @param[out] state The current state -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_READY. -* -* @see vc_request_start() -* @see vc_request_stop() -* @see vc_request_cancel() -* @see vc_set_service_state_changed_cb() -* @see vc_unset_service_state_changed_cb() -*/ + * @brief Gets current state of voice control service. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @param[out] state The current state + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_READY. + * + * @see vc_request_start() + * @see vc_request_stop() + * @see vc_request_cancel() + * @see vc_set_service_state_changed_cb() + * @see vc_unset_service_state_changed_cb() + */ int vc_get_service_state(vc_service_state_e* state); /** -* @brief Get system command list. -* @since_tizen 3.0 -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @remarks If system command is set by system voice app, the system command list can be retreived. -* -* @param[out] vc_sys_cmd_list System command list handle -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The service state should be #VC_SERVICE_STATE_READY. -* -* @see vc_unset_command_list() -*/ + * @brief Gets the system command list. + * @since_tizen 3.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @remarks In the system command list, there are system commands predefined by product manufacturers. Those commands have the highest priority. + * Therefore, the user can not set any commands same with the system commands. \n + * The @a vc_sys_cmd_list must be released using free() when it is no longer required. + * + * @param[out] vc_sys_cmd_list System command list handle + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The service state should be #VC_SERVICE_STATE_READY. + * + * @see vc_unset_command_list() + */ int vc_get_system_command_list(vc_cmd_list_h* vc_sys_cmd_list); /** -* @brief Sets invocation name. -* @since_tizen 3.0 -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @remarks The invocation name will be combined with background command. -* This function should be called before vc_set_command_list() or vc_set_command_list_from_file(). -* -* @param[in] name App name that wants to be invoked -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_READY. -* -* @see vc_set_command_list() -* @see vc_set_command_list_from_file() -*/ + * @brief Sets invocation name. + * @since_tizen 3.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @remarks Invocation name is used to activate background commands. The invocation name can be set as the application name or some words. + * For example, an application "Tizen Sample" has a background command, "Play music", and the invocation name of the application is set as "Tizen Sample". + * In order to activate the background command, users can say "Tizen Sample, Play music". + * The invocation name is dependent on the setting language. For example, if the setting language is "en_US"(English), the invocation name is also "en_US". + * If the setting language is "ja_JP"(Japanese) and the invocation name is "en_US", the invocation name will not be recognized. + * This function should be called before vc_set_command_list(). + * + * @param[in] name Invocation name that an application wants to be invoked by + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_READY. + * + * @see vc_set_command_list() + */ int vc_set_invocation_name(const char* name); /** -* @brief Request to display text and to speak text what app want. -* @since_tizen 3.0 -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @remarks If continue is true, the recognition will start again. In this case, 4 times can be restarted. -* -* @param[in] disp_text Text hat wants to be displayed -* @param[in] utt_text Text that wants to be spoken -* @param[in] continue Continue dialog session -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The service state should be #VC_SERVICE_STATE_READY. -*/ -int vc_dialog(const char* disp_text, const char* utt_text, bool auto_start); - -/** -* @brief Sets command list. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @remarks The command type is valid for #VC_COMMAND_TYPE_FOREGROUND or #VC_COMMAND_TYPE_BACKGROUND. \n -* The matched commands of command list should be set and they should include type and command text at least. -* -* @param[in] vc_cmd_list Command list handle -* @param[in] type Command type -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_READY. -* -* @see vc_unset_command_list() -*/ + * @brief Requests to start the dialogue. + * @details Using this function, the developer can transfer texts, for starting the dialogue, to the framework. + * There are two types of texts. One is a text for displaying, and the other is that for uttering. + * For example, if @a disp_text is "October 10th" and @a utt_text is "Today is October 10th.", "October 10th" will be displayed on the screen and "Today is October 10th." will be spoken. + * Also, the developer can set whether the dialogue restarts automatically or not, using @a auto_start. + * + * @since_tizen 3.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @remarks If @a auto_start is @c true, the recognition will start again. In this case, 4 times can be restarted. + * + * @param[in] disp_text Text to be displayed on the screen + * @param[in] utt_text Text to be spoken + * @param[in] auto_start A variable for setting whether the dialog session will be restarted automatically or not + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The service state should be #VC_SERVICE_STATE_READY. + */ +int vc_request_dialog(const char* disp_text, const char* utt_text, bool auto_start); + +/** + * @brief Sets command list. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @remarks The command type is valid for #VC_COMMAND_TYPE_FOREGROUND or #VC_COMMAND_TYPE_BACKGROUND. \n + * The matched commands of command list should be set and they should include type and command text at least. + * + * @param[in] vc_cmd_list Command list handle + * @param[in] type Command type + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_READY. + * + * @see vc_unset_command_list() + */ int vc_set_command_list(vc_cmd_list_h vc_cmd_list, int type); /** -* @brief Sets command list from file. -* @since_tizen 3.0 -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @remarks The command type is valid for #VC_COMMAND_TYPE_FOREGROUND or #VC_COMMAND_TYPE_BACKGROUND. \n -* The matched commands of command list should be set and they should include type and command text at least. -* -* @param[in] file_path The file path including commands -* @param[in] type Command type -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_READY. -* -* @see vc_unset_command_list() -*/ -int vc_set_command_list_from_file(const char* file_path, int type); - -/** -* @brief Unsets command list. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @param[in] type Command type -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_READY. -* -* @see vc_set_command_list() -* @see vc_set_command_list_from_file -*/ + * @brief Unsets command list. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @param[in] type Command type + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_READY. + * + * @see vc_set_command_list() + */ int vc_unset_command_list(int type); /** -* @brief Get recognition result using a callback function. -* @since_tizen 3.0 -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @param[in] callback Callback function to get recognition result -* @param[in] user_data The user data to be passed to the callback function -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_READY. -* -* @see vc_result_cb() -*/ + * @brief Gets the recognition result. + * @since_tizen 3.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @param[in] callback Callback function to get recognition result + * @param[in] user_data The user data to be passed to the callback function + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_READY. + * + * @see vc_result_cb() + */ int vc_get_result(vc_result_cb callback, void* user_data); /** -* @brief Registers a callback function for getting recognition result. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @param[in] callback Callback function to register -* @param[in] user_data The user data to be passed to the callback function -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_INITIALIZED. -* -* @see vc_result_cb() -* @see vc_unset_result_cb() -*/ + * @brief Registers a callback function for getting recognition result. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @param[in] callback Callback function to register + * @param[in] user_data The user data to be passed to the callback function + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_INITIALIZED. + * + * @see vc_result_cb() + * @see vc_unset_result_cb() + */ int vc_set_result_cb(vc_result_cb callback, void* user_data); /** -* @brief Unregisters the callback function. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_INITIALIZED. -* -* @see vc_set_result_cb() -*/ + * @brief Unregisters the callback function. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_INITIALIZED. + * + * @see vc_set_result_cb() + */ int vc_unset_result_cb(void); /** -* @brief Registers a callback function to be called when state is changed. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @param[in] callback Callback function to register -* @param[in] user_data The user data to be passed to the callback function -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_INITIALIZED. -* -* @see vc_service_state_changed_cb() -* @see vc_unset_service_state_changed_cb() -*/ + * @brief Registers a callback function to be called when state is changed. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @param[in] callback Callback function to register + * @param[in] user_data The user data to be passed to the callback function + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_INITIALIZED. + * + * @see vc_service_state_changed_cb() + * @see vc_unset_service_state_changed_cb() + */ int vc_set_service_state_changed_cb(vc_service_state_changed_cb callback, void* user_data); /** -* @brief Unregisters the callback function. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_INITIALIZED. -* -* @see vc_set_service_state_changed_cb() -*/ + * @brief Unregisters the callback function. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_INITIALIZED. + * + * @see vc_set_service_state_changed_cb() + */ int vc_unset_service_state_changed_cb(void); /** -* @brief Registers a callback function to be called when state is changed. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @param[in] callback Callback function to register -* @param[in] user_data The user data to be passed to the callback function -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_INITIALIZED. -* -* @see vc_state_changed_cb() -* @see vc_unset_state_changed_cb() -*/ + * @brief Registers a callback function to be called when state is changed. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @param[in] callback Callback function to register + * @param[in] user_data The user data to be passed to the callback function + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_INITIALIZED. + * + * @see vc_state_changed_cb() + * @see vc_unset_state_changed_cb() + */ int vc_set_state_changed_cb(vc_state_changed_cb callback, void* user_data); /** -* @brief Unregisters the callback function. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_INITIALIZED. -* -* @see vc_set_state_changed_cb() -*/ + * @brief Unregisters the callback function. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_INITIALIZED. + * + * @see vc_set_state_changed_cb() + */ int vc_unset_state_changed_cb(void); /** -* @brief Registers a callback function to be called when current language is changed. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @param[in] callback Callback function to register -* @param[in] user_data The user data to be passed to the callback function -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_INITIALIZED. -* -* @see vc_current_language_changed_cb() -* @see vc_unset_current_language_changed_cb() -*/ + * @brief Registers a callback function to be called when current language is changed. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @param[in] callback Callback function to register + * @param[in] user_data The user data to be passed to the callback function + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_INITIALIZED. + * + * @see vc_current_language_changed_cb() + * @see vc_unset_current_language_changed_cb() + */ int vc_set_current_language_changed_cb(vc_current_language_changed_cb callback, void* user_data); /** -* @brief Unregisters the callback function. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_INITIALIZED. -* -* @see vc_set_current_language_changed_cb() -*/ + * @brief Unregisters the callback function. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_INITIALIZED. + * + * @see vc_set_current_language_changed_cb() + */ int vc_unset_current_language_changed_cb(void); /** -* @brief Registers a callback function to be called when an error occurred. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @param[in] callback Callback function to register -* @param[in] user_data The user data to be passed to the callback function -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_INITIALIZED. -* -* @see vc_error_cb() -* @see vc_unset_error_cb() -*/ + * @brief Registers a callback function to be called when an error occurred. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @param[in] callback Callback function to register + * @param[in] user_data The user data to be passed to the callback function + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_INITIALIZED. + * + * @see vc_error_cb() + * @see vc_unset_error_cb() + */ int vc_set_error_cb(vc_error_cb callback, void* user_data); /** -* @brief Unregisters the callback function. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* @privlevel public -* @privilege %http://tizen.org/privilege/recorder -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_STATE Invalid state -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @pre The state should be #VC_STATE_INITIALIZED. -* -* @see vc_set_error_cb() -*/ + * @brief Unregisters the callback function. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_INITIALIZED. + * + * @see vc_set_error_cb() + */ int vc_unset_error_cb(void); diff --git a/include/voice_control_command.h b/include/voice_control_command.h index f913caa..8a7ee52 100644 --- a/include/voice_control_command.h +++ b/include/voice_control_command.h @@ -1,18 +1,18 @@ -/* -* Copyright (c) 2011-2015 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. -*/ +/** + * Copyright (c) 2011-2016 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 __VOICE_CONTROL_COMMAND_H__ @@ -20,14 +20,13 @@ #include - /** -* @defgroup CAPI_UIX_VOICE_CONTROL_COMMAND_MODULE Voice control command -* @ingroup CAPI_UIX_VOICE_CONTROL_MODULE -* -* @brief The @ref CAPI_UIX_VOICE_CONTROL_COMMAND_MODULE API provides functions for creating/destroying command list and add/remove/retrieve commands of list. -* @{ -*/ + * @defgroup CAPI_UIX_VOICE_CONTROL_COMMAND_MODULE Voice control command + * @ingroup CAPI_UIX_VOICE_CONTROL_MODULE + * + * @brief The @ref CAPI_UIX_VOICE_CONTROL_COMMAND_MODULE API provides functions for creating/destroying command list and add/remove/retrieve commands of list. + * @{ + */ #ifdef __cplusplus extern "C" @@ -36,428 +35,415 @@ extern "C" /** -* @brief The voice command handle. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -*/ + * @brief The voice command handle. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + */ typedef struct vc_cmd_s* vc_cmd_h; /** -* @brief The voice command list handle. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -*/ + * @brief The voice command list handle. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + */ typedef struct vc_cmd_list_s* vc_cmd_list_h; /** -* @brief Enumerations of command format. -* @since_tizen 3.0 -*/ -typedef enum { - VC_CMD_FORMAT_FIXED = 0, /**< fixed command only */ - VC_CMD_FORMAT_FIXED_AND_VFIXED, /**< Fixed + variable fixed command */ - VC_CMD_FORMAT_VFIXED_AND_FIXED, /**< Variable fixed + fixed command */ - VC_CMD_FORMAT_FIXED_AND_NONFIXED, /**< Fixed + non fixed command */ - VC_CMD_FORMAT_NONFIXED_AND_FIXED, /**< Non fixed + fixed command */ - VC_CMD_FORMAT_ACTION, /**< Action command */ - VC_CMD_FORMAT_PARTIAL /**< Partial matched command */ -} vc_cmd_format_e; - -/** -* @brief Called to retrieve The commands in list. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] vc_command The command handle -* @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 vc_cmd_list_foreach_commands() will invoke this callback. -* -* @see vc_cmd_list_foreach_commands() -*/ + * @brief Called to retrieve The commands in list. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] vc_command The command handle + * @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 vc_cmd_list_foreach_commands() will invoke this callback. + * + * @see vc_cmd_list_foreach_commands() + */ typedef bool (*vc_cmd_list_cb)(vc_cmd_h vc_command, void* user_data); /** -* @brief Creates a handle for command list. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @remarks If the function succeeds, @a The list handle must be released with vc_cmd_list_destroy(). -* -* @param[out] vc_cmd_list The command list handle -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_OUT_OF_MEMORY Out of memory -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @see vc_cmd_list_destroy() -*/ + * @brief Creates a handle for command list. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @remarks If the function succeeds, @a The list handle must be released with vc_cmd_list_destroy(). + * + * @param[out] vc_cmd_list The command list handle + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @see vc_cmd_list_destroy() + */ int vc_cmd_list_create(vc_cmd_list_h* vc_cmd_list); /** -* @brief Destroys the handle for command list. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] vc_cmd_list The command list handle -* @param[in] free_command The command free option @c true = release each commands in list, -* @c false = remove command from list -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @see vc_cmd_list_create() -*/ + * @brief Destroys the handle for command list. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] vc_cmd_list The command list handle + * @param[in] free_command The command free option @c true = release each commands in list, + * @c false = remove command from list + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @see vc_cmd_list_create() + */ int vc_cmd_list_destroy(vc_cmd_list_h vc_cmd_list, bool free_command); /** -* @brief Gets command count of list. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] vc_cmd_list The command list handle -* @param[out] count The count -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -*/ + * @brief Gets command count of list. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] vc_cmd_list The command list handle + * @param[out] count The count + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + */ int vc_cmd_list_get_count(vc_cmd_list_h vc_cmd_list, int* count); /** -* @brief Adds command to command list. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] vc_cmd_list The command list handle -* @param[in] vc_command The command handle -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @see vc_cmd_list_remove() -*/ + * @brief Adds command to command list. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] vc_cmd_list The command list handle + * @param[in] vc_command The command handle + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @see vc_cmd_list_remove() + */ int vc_cmd_list_add(vc_cmd_list_h vc_cmd_list, vc_cmd_h vc_command); /** -* @brief Removes command from command list. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] vc_cmd_list The command list handle -* @param[in] vc_command The command handle -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @see vc_cmd_list_add() -*/ + * @brief Removes command from command list. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] vc_cmd_list The command list handle + * @param[in] vc_command The command handle + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @see vc_cmd_list_add() + */ int vc_cmd_list_remove(vc_cmd_list_h vc_cmd_list, vc_cmd_h vc_command); /** -* @brief Retrieves all commands of command list using callback function. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] vc_cmd_list The command list handle -* @param[in] callback Callback function to invoke -* @param[in] user_data The user data to be passed to the callback function -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @post This function invokes vc_cmd_list_cb() repeatedly for getting commands. -* -* @see vc_cmd_list_cb() -*/ + * @brief Retrieves all commands of command list using callback function. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] vc_cmd_list The command list handle + * @param[in] callback Callback function to invoke + * @param[in] user_data The user data to be passed to the callback function + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @post This function invokes vc_cmd_list_cb() repeatedly for getting commands. + * + * @see vc_cmd_list_cb() + */ int vc_cmd_list_foreach_commands(vc_cmd_list_h vc_cmd_list, vc_cmd_list_cb callback, void* user_data); /** -* @brief Retrieves all commands of system command list using callback function. -* @since_tizen 3.0 -* -* @param[in] callback Callback function to invoke -* @param[in] user_data The user data to be passed to the callback function -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @post This function invokes vc_cmd_list_cb() repeatedly for getting commands. -* -* @see vc_cmd_list_cb() -*/ -int vc_cmd_list_foreach_system_commands(vc_cmd_list_cb callback, void* user_data); + * @brief Retrieves all commands on the system command list using callback function. + * @since_tizen 3.0 + * + * @param[in] callback Callback function to invoke + * @param[in] user_data The user data to be passed to the callback function + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @post This function invokes vc_cmd_list_cb() for each command. + * + * @see vc_cmd_list_cb() + */ +int vc_cmd_list_foreach_system_command(vc_cmd_list_cb callback, void* user_data); /** -* @brief Moves index to first command. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] vc_cmd_list The command list handle -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_EMPTY List empty -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @see vc_cmd_list_last() -*/ + * @brief Moves index to first command. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] vc_cmd_list The command list handle + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_EMPTY List empty + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @see vc_cmd_list_last() + */ int vc_cmd_list_first(vc_cmd_list_h vc_cmd_list); /** -* @brief Moves index to last command. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] vc_cmd_list The command list handle -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_EMPTY List empty -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @see vc_cmd_list_first() -*/ + * @brief Moves index to last command. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] vc_cmd_list The command list handle + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_EMPTY List empty + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @see vc_cmd_list_first() + */ int vc_cmd_list_last(vc_cmd_list_h vc_cmd_list); /** -* @brief Moves index to next command. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] vc_cmd_list The command list handle -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_EMPTY List empty -* @retval #VC_ERROR_ITERATION_END List reached end -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @see vc_cmd_list_prev() -*/ + * @brief Moves index to next command. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] vc_cmd_list The command list handle + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_EMPTY List empty + * @retval #VC_ERROR_ITERATION_END List reached end + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @see vc_cmd_list_prev() + */ int vc_cmd_list_next(vc_cmd_list_h vc_cmd_list); /** -* @brief Moves index to previous command. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] vc_cmd_list The command list handle -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_EMPTY List empty -* @retval #VC_ERROR_ITERATION_END List reached end -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @see vc_cmd_list_next() -*/ + * @brief Moves index to previous command. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] vc_cmd_list The command list handle + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_EMPTY List empty + * @retval #VC_ERROR_ITERATION_END List reached end + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @see vc_cmd_list_next() + */ int vc_cmd_list_prev(vc_cmd_list_h vc_cmd_list); /** -* @brief Get current command from command list by index. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] vc_cmd_list The command list handle -* @param[out] vc_command The command handle -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_EMPTY List empty -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @see vc_cmd_list_first() -* @see vc_cmd_list_last() -* @see vc_cmd_list_prev() -* @see vc_cmd_list_next() -*/ + * @brief Get current command from command list by index. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] vc_cmd_list The command list handle + * @param[out] vc_command The command handle + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_EMPTY List empty + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @see vc_cmd_list_first() + * @see vc_cmd_list_last() + * @see vc_cmd_list_prev() + * @see vc_cmd_list_next() + */ int vc_cmd_list_get_current(vc_cmd_list_h vc_cmd_list, vc_cmd_h* vc_command); - /** -* @brief Creates a handle for command. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @remarks If the function succeeds, @a The command handle must be released -* with vc_cmd_destroy() or vc_cmd_list_destroy(). -* You should set command and type if command is valid -* -* @param[out] vc_command The command handle -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_OUT_OF_MEMORY Out of memory -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @see vc_cmd_destroy() -*/ + * @brief Creates a handle for command. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @remarks If the function succeeds, @a The command handle must be released + * with vc_cmd_destroy() or vc_cmd_list_destroy(). + * You should set command and type if command is valid. + * The command format is set to #VC_CMD_FORMAT_FIXED by default and can be changed with vc_cmd_set_format(). + * + * @param[out] vc_command The command handle + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @see vc_cmd_destroy() + */ int vc_cmd_create(vc_cmd_h* vc_command); /** -* @brief Destroys the handle. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] vc_command The command handle -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @see vc_cmd_create() -*/ + * @brief Destroys the handle. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] vc_command The command handle + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @see vc_cmd_create() + */ int vc_cmd_destroy(vc_cmd_h vc_command); /** -* @brief Sets command or action. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] vc_command The command handle -* @param[in] command The command or action text -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @see vc_cmd_get_command() -*/ + * @brief Sets command or action. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] vc_command The command handle + * @param[in] command The command or action text + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @see vc_cmd_get_command() + */ int vc_cmd_set_command(vc_cmd_h vc_command, const char* command); /** -* @brief Gets command. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @remark If the function succeeds, @a command must be released with free() by you if they are not NULL. -* -* @param[in] vc_command The command handle -* @param[out] command The command text -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @see vc_cmd_set_command() -*/ + * @brief Gets command. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @remark If the function succeeds, @a command must be released with free() by you if they are not NULL. + * + * @param[in] vc_command The command handle + * @param[out] command The command text + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @see vc_cmd_set_command() + */ int vc_cmd_get_command(vc_cmd_h vc_command, char** command); /** -* @brief Gets extra unfixed command. -* @since_tizen 3.0 -* -* @remark If the function succeeds, @a The command must be released with free() by you if they are not NULL. -* If you get the result command list in result callback and the command type of commands has non-fixed format, -* you should check non-fixed result using this function. -* -* @param[in] vc_command The command handle -* @param[out] command The unfixed command text -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported feature -*/ + * @brief Gets the unfixed command. + * @since_tizen 3.0 + * + * @remark After this function is successfully conducted, the @a command must be released with free() if it is not NULL. + * If the command in @a vc_command is NULL, @a command will be also NULL. + * This function should be used for commands which have non-fixed format. + * + * @param[in] vc_command The command handle + * @param[out] command The unfixed command text + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported feature + */ int vc_cmd_get_unfixed_command(vc_cmd_h vc_command, char** command); /** -* @brief Sets command type. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @remark If you do not set the command type, the default value is -1. -* You should set type if command is valid -* -* @param[in] vc_command The command handle -* @param[in] type The command type -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @see vc_cmd_get_type() -*/ + * @brief Sets command type. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @remark If you do not set the command type, the default value is -1. + * You should set type if command is valid + * + * @param[in] vc_command The command handle + * @param[in] type The command type + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @see vc_cmd_get_type() + */ int vc_cmd_set_type(vc_cmd_h vc_command, int type); /** -* @brief Gets command type. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] vc_command The command handle -* @param[out] type The command type -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported -* -* @see vc_cmd_set_type() -*/ + * @brief Gets command type. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] vc_command The command handle + * @param[out] type The command type + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @see vc_cmd_set_type() + */ int vc_cmd_get_type(vc_cmd_h vc_command, int* type); - /** -* @brief Sets command format. -* @since_tizen 3.0 -* -* @param[in] vc_command The command handle -* @param[in] format The command format -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported feature -* -* @see vc_cmd_get_format() -*/ -int vc_cmd_set_format(vc_cmd_h vc_command, vc_cmd_format_e format); + * @brief Sets the command format. + * @since_tizen 3.0 + * + * @remark The default format is #VC_CMD_FORMAT_FIXED. + * + * @param[in] vc_command The command handle + * @param[in] format The command format + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported feature + * + * @see vc_cmd_get_format() + */ +int vc_cmd_set_format(vc_cmd_h vc_command, int format); /** -* @brief Gets command format. -* @since_tizen 3.0 -* -* @remark If you do not set the format, the default format is #VC_CMD_FORMAT_FIXED. -* -* @param[in] vc_command The command handle -* @param[out] format The command format -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported feature -* -* @see vc_cmd_set_format() -*/ -int vc_cmd_get_format(vc_cmd_h vc_command, vc_cmd_format_e* format); + * @brief Gets the command format. + * @since_tizen 3.0 + * + * @remark The default format is #VC_CMD_FORMAT_FIXED. + * + * @param[in] vc_command The command handle + * @param[out] format The command format + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported feature + * + * @see vc_cmd_set_format() + */ +int vc_cmd_get_format(vc_cmd_h vc_command, int* format); #ifdef __cplusplus diff --git a/include/voice_control_command_expand.h b/include/voice_control_command_expand.h index fdb4101..2714301 100755 --- a/include/voice_control_command_expand.h +++ b/include/voice_control_command_expand.h @@ -29,40 +29,18 @@ extern "C" #endif /** -* @brief Sets command format. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] vc_command The command handle -* @param[in] format The command format -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported feature -* -* @see vc_cmd_get_format() -*/ -int vc_cmd_set_format(vc_cmd_h vc_command, vc_cmd_format_e format); - -/** -* @brief Gets command format. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @remark If you do not set the format, the default format is #VC_CMD_FORMAT_FIXED. -* -* @param[in] vc_command The command handle -* @param[out] format The command format -* -* @return 0 on success, otherwise a negative error value -* @retval #VC_ERROR_NONE Successful -* @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter -* @retval #VC_ERROR_PERMISSION_DENIED Permission denied -* @retval #VC_ERROR_NOT_SUPPORTED Not supported feature -* -* @see vc_cmd_set_format() -*/ -int vc_cmd_get_format(vc_cmd_h vc_command, vc_cmd_format_e* format); + * @brief Enumerations of command format. + * @since_tizen 3.0 + */ +typedef enum { + VC_CMD_FORMAT_FIXED = 0, /**< fixed command only */ + VC_CMD_FORMAT_FIXED_AND_VFIXED, /**< Fixed + variable fixed command */ + VC_CMD_FORMAT_VFIXED_AND_FIXED, /**< Variable fixed + fixed command */ + VC_CMD_FORMAT_FIXED_AND_NONFIXED, /**< Fixed + non fixed command */ + VC_CMD_FORMAT_NONFIXED_AND_FIXED, /**< Non fixed + fixed command */ + VC_CMD_FORMAT_ACTION, /**< Action command */ + VC_CMD_FORMAT_PARTIAL /**< Partial matched command */ +} vc_cmd_format_e; /** * @brief Sets command domain diff --git a/include/voice_control_common.h b/include/voice_control_common.h index b491719..d8d4043 100644 --- a/include/voice_control_common.h +++ b/include/voice_control_common.h @@ -1,18 +1,18 @@ -/* -* Copyright (c) 2011-2015 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. -*/ +/** + * Copyright (c) 2011-2016 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 __VOICE_CONTROL_COMMON_H__ @@ -21,9 +21,9 @@ #include /** -* @addtogroup CAPI_UIX_VOICE_CONTROL_MODULE -* @{ -*/ + * @addtogroup CAPI_UIX_VOICE_CONTROL_MODULE + * @{ + */ #ifdef __cplusplus extern "C" @@ -31,9 +31,9 @@ extern "C" #endif /** -* @brief Enumerations of error codes. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -*/ + * @brief Enumerations of error codes. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + */ typedef enum { VC_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ VC_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of Memory */ @@ -50,25 +50,25 @@ typedef enum { VC_ERROR_OPERATION_REJECTED = TIZEN_ERROR_VOICE_CONTROL | 0x015, /**< Operation rejected */ VC_ERROR_ITERATION_END = TIZEN_ERROR_VOICE_CONTROL | 0x016, /**< List reached end */ VC_ERROR_EMPTY = TIZEN_ERROR_VOICE_CONTROL | 0x017, /**< List empty */ - VC_ERROR_SERVICE_RESET = TIZEN_ERROR_VOICE_CONTROL | 0x018, /**< Service Damon reset */ + VC_ERROR_SERVICE_RESET = TIZEN_ERROR_VOICE_CONTROL | 0x018, /**< Service daemon reset @if MOBILE (Since 3.0) @endif */ VC_ERROR_IN_PROGRESS_TO_READY = TIZEN_ERROR_VOICE_CONTROL | 0x019, VC_ERROR_IN_PROGRESS_TO_RECORDING = TIZEN_ERROR_VOICE_CONTROL | 0x020, VC_ERROR_IN_PROGRESS_TO_PROCESSING = TIZEN_ERROR_VOICE_CONTROL | 0x021 } vc_error_e; /** -* @brief Enumerations of result event. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -*/ + * @brief Enumerations of result event. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + */ typedef enum { VC_RESULT_EVENT_RESULT_SUCCESS = 0, /**< Normal result */ VC_RESULT_EVENT_REJECTED = 1 /**< Rejected result */ } vc_result_event_e; /** -* @brief Enumerations of service state. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -*/ + * @brief Enumerations of service state. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + */ typedef enum { VC_SERVICE_STATE_NONE = 0, /**< 'None' state */ VC_SERVICE_STATE_READY = 1, /**< 'Ready' state */ @@ -77,9 +77,9 @@ typedef enum { } vc_service_state_e; /** -* @brief Enumerations of client state. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -*/ + * @brief Enumerations of client state. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + */ typedef enum { VC_STATE_NONE = 0, /**< 'None' state */ VC_STATE_INITIALIZED = 1, /**< 'Initialized' state */ @@ -88,92 +88,92 @@ typedef enum { /** -* @brief Called when client gets the recognition result. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @remarks If the duplicated commands are recognized, the event(e.g. #VC_RESULT_EVENT_REJECTED) of command may be rejected \n -* for selecting command as priority. If you set similar or same commands or the recognized results are multi-results, -* vc_cmd_list has the multi commands. -* -* @param[in] event The result event (e.g. #VC_RESULT_EVENT_RESULT_SUCCESS, #VC_RESULT_EVENT_REJECTED) -* @param[in] vc_cmd_list The recognized command list -* @param[in] result The spoken text -* @param[in] user_data The user data passed from the callback registration function -* -* @pre An application registers callback function. -* -* @see vc_set_result_cb() -*/ + * @brief Called when client gets the recognition result. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @remarks If the duplicated commands are recognized, the event(e.g. #VC_RESULT_EVENT_REJECTED) of command may be rejected \n + * for selecting command as priority. If you set similar or same commands or the recognized results are multi-results, + * vc_cmd_list has the multi commands. + * + * @param[in] event The result event (e.g. #VC_RESULT_EVENT_RESULT_SUCCESS, #VC_RESULT_EVENT_REJECTED) + * @param[in] vc_cmd_list The recognized command list + * @param[in] result The spoken text + * @param[in] user_data The user data passed from the callback registration function + * + * @pre An application registers callback function. + * + * @see vc_set_result_cb() + */ typedef void (*vc_result_cb)(vc_result_event_e event, vc_cmd_list_h vc_cmd_list, const char* result, void *user_data); /** -* @brief Called when default language is changed. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] previous Previous language -* @param[in] current Current language -* @param[in] user_data The user data passed from the callback registration function -* -* @pre An application registers this callback to detect changing mode. -* -* @see vc_set_current_language_changed_cb() -*/ + * @brief Called when default language is changed. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] previous Previous language + * @param[in] current Current language + * @param[in] user_data The user data passed from the callback registration function + * + * @pre An application registers this callback to detect changing mode. + * + * @see vc_set_current_language_changed_cb() + */ typedef void (*vc_current_language_changed_cb)(const char* previous, const char* current, void* user_data); /** -* @brief Called to retrieve supported language. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code \n -* 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 The function will invoke this callback. -*/ + * @brief Called to retrieve supported language. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code \n + * 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 The function will invoke this callback. + */ typedef bool (*vc_supported_language_cb)(const char* language, void* user_data); /** -* @brief Called when the state of voice control client is changed. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] previous A previous state -* @param[in] current A current state -* @param[in] user_data The user data passed from the callback registration function -* -* @pre An application registers this callback to detect changing state. -* -* @see vc_set_state_changed_cb() -*/ + * @brief Called when the state of voice control client is changed. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] previous A previous state + * @param[in] current A current state + * @param[in] user_data The user data passed from the callback registration function + * + * @pre An application registers this callback to detect changing state. + * + * @see vc_set_state_changed_cb() + */ typedef void (*vc_state_changed_cb)(vc_state_e previous, vc_state_e current, void* user_data); /** -* @brief Called when the state of voice control service is changed. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] previous A previous state -* @param[in] current A current state -* @param[in] user_data The user data passed from the callback registration function -* -* @pre An application registers this callback to detect changing service state. -* -* @see vc_set_service_state_changed_cb() -*/ + * @brief Called when the state of voice control service is changed. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] previous A previous state + * @param[in] current A current state + * @param[in] user_data The user data passed from the callback registration function + * + * @pre An application registers this callback to detect changing service state. + * + * @see vc_set_service_state_changed_cb() + */ typedef void (*vc_service_state_changed_cb)(vc_service_state_e previous, vc_service_state_e current, void* user_data); /** -* @brief Called when error occurred. -* @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif -* -* @param[in] reason The error type (e.g. #VC_ERROR_OUT_OF_MEMORY, #VC_ERROR_TIMED_OUT) -* @param[in] user_data The user data passed from the callback registration function -* -* @pre An application registers this callback to detect error. -* -* @see vc_set_error_cb() -*/ + * @brief Called when error occurred. + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif + * + * @param[in] reason The error type (e.g. #VC_ERROR_OUT_OF_MEMORY, #VC_ERROR_TIMED_OUT) + * @param[in] user_data The user data passed from the callback registration function + * + * @pre An application registers this callback to detect error. + * + * @see vc_set_error_cb() + */ typedef void (*vc_error_cb)(vc_error_e reason, void *user_data); diff --git a/include/voice_control_internal.h b/include/voice_control_internal.h new file mode 100644 index 0000000..4935a91 --- /dev/null +++ b/include/voice_control_internal.h @@ -0,0 +1,65 @@ +/* + * Copyright (c) 2011-2016 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 __VOICE_CONTROL_INTERNAL_H__ +#define __VOICE_CONTROL_INTERNAL_H__ + +#include +#include + + +#ifdef __cplusplus +extern "C" +{ +#endif + +/** + * @brief Sets command list from file. + * @since_tizen 3.0 + * @privlevel public + * @privilege %http://tizen.org/privilege/recorder + * + * @remarks The command type is valid for #VC_COMMAND_TYPE_FOREGROUND and #VC_COMMAND_TYPE_BACKGROUND. + * Therefore, @a type is either #VC_COMMAND_TYPE_FOREGROUND or #VC_COMMAND_TYPE_BACKGROUND. \n + * In the file corresponding to @a file_path, there must be commands and command types. + * + * @param[in] file_path The command file path (absolute or relative) + * @param[in] type Command type + * + * @return 0 on success, otherwise a negative error value + * @retval #VC_ERROR_NONE Successful + * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #VC_ERROR_INVALID_STATE Invalid state + * @retval #VC_ERROR_PERMISSION_DENIED Permission denied + * @retval #VC_ERROR_NOT_SUPPORTED Not supported + * + * @pre The state should be #VC_STATE_READY. + * + * @see vc_unset_command_list() + */ +int vc_set_command_list_from_file(const char* file_path, int type); + + +#ifdef __cplusplus +} +#endif + +/** + * @}@} + */ + +#endif /* __VOICE_CONTROL_INTERNAL_H__ */ diff --git a/packaging/voice-control.spec b/packaging/voice-control.spec index f724a9e..8e185dd 100644 --- a/packaging/voice-control.spec +++ b/packaging/voice-control.spec @@ -132,6 +132,7 @@ mkdir -p %{_libdir}/voice/vc %defattr(-,root,root,-) %{_libdir}/pkgconfig/voice-control.pc %{_includedir}/voice_control.h +%{_includedir}/voice_control_internal.h %{_includedir}/voice_control_authority.h %{_includedir}/voice_control_command.h %{_includedir}/voice_control_common.h diff --git a/server/vcd_recorder.c b/server/vcd_recorder.c index f7e7313..9ffb34c 100644 --- a/server/vcd_recorder.c +++ b/server/vcd_recorder.c @@ -50,7 +50,9 @@ static vcd_recorder_interrupt_cb g_interrupt_cb = NULL; static audio_in_h g_audio_h; +#if 0 static sound_stream_info_h g_stream_info_h; +#endif static vcp_audio_type_e g_audio_type; -- 2.7.4