From fd3e9c29b0477e5ce924973e9dff813b6421c1f5 Mon Sep 17 00:00:00 2001 From: Ji-hoon Lee Date: Tue, 24 Sep 2019 14:30:04 +0900 Subject: [PATCH] Update API header for review Change-Id: Id6467576ebc30f538d8e6a45d1fdee80169aa9d7 --- include/multi_assistant.h | 50 ++++++++++++-------------------- include/multi_assistant_common.h | 6 +++- 2 files changed, 23 insertions(+), 33 deletions(-) diff --git a/include/multi_assistant.h b/include/multi_assistant.h index afe8587..6f6d894 100644 --- a/include/multi_assistant.h +++ b/include/multi_assistant.h @@ -118,8 +118,8 @@ int ma_unprepare(void); * @retval #MA_ERROR_NONE Successful * @retval #MA_ERROR_NOT_SUPPORTED Not supported * @retval #MA_ERROR_PERMISSION_DENIED Permission denied - * @retval #MA_ERROR_INVALID_STATE Invalid state * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MA_ERROR_INVALID_STATE Invalid state */ int ma_get_state(ma_state_e* state); @@ -154,8 +154,8 @@ int ma_get_current_language(char** language); * @retval #MA_ERROR_NONE Successful * @retval #MA_ERROR_NOT_SUPPORTED Not supported * @retval #MA_ERROR_PERMISSION_DENIED Permission denied - * @retval #MA_ERROR_INVALID_STATE Invalid state * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MA_ERROR_INVALID_STATE Invalid state * @retval #MA_ERROR_OPERATION_FAILED Operation failed * * @pre The state should be #MA_STATE_READY. @@ -172,8 +172,8 @@ int ma_get_recording_audio_format(int* rate, ma_audio_channel_e* channel, ma_aud * @return @c 0 on success, otherwise a negative error value * @retval #MA_ERROR_NONE Successful * @retval #MA_ERROR_NOT_SUPPORTED Not supported - * @retval #MA_ERROR_INVALID_STATE Invalid state * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MA_ERROR_INVALID_STATE Invalid state * * @pre The state should be #MA_STATE_INITIALIZED. * @see ma_state_changed_cb() @@ -206,8 +206,8 @@ int ma_unset_state_changed_cb(void); * @return @c 0 on success, otherwise a negative error value * @retval #MA_ERROR_NONE Successful * @retval #MA_ERROR_NOT_SUPPORTED Not supported - * @retval #MA_ERROR_INVALID_STATE Invalid state * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MA_ERROR_INVALID_STATE Invalid state * * @pre The state should be #MA_STATE_INITIALIZED. * @see ma_error_cb() @@ -240,8 +240,8 @@ int ma_unset_error_cb(void); * @return @c 0 on success, otherwise a negative error value * @retval #MA_ERROR_NONE Successful * @retval #MA_ERROR_NOT_SUPPORTED Not supported - * @retval #MA_ERROR_INVALID_STATE Invalid state * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MA_ERROR_INVALID_STATE Invalid state * * @pre The state should be #MA_STATE_INITIALIZED. * @see ma_language_changed_cb() @@ -274,8 +274,8 @@ int ma_unset_language_changed_cb(void); * @return @c 0 on success, otherwise a negative error value * @retval #MA_ERROR_NONE Successful * @retval #MA_ERROR_NOT_SUPPORTED Not supported - * @retval #MA_ERROR_INVALID_STATE Invalid state * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MA_ERROR_INVALID_STATE Invalid state * * @pre The state should be #MA_STATE_INITIALIZED. * @see ma_audio_streaming_cb() @@ -359,8 +359,8 @@ int ma_send_recognition_result(ma_recognition_result_event_e result); * @return @c 0 on success, otherwise a negative error value * @retval #MA_ERROR_NONE Successful * @retval #MA_ERROR_NOT_SUPPORTED Not supported - * @retval #MA_ERROR_INVALID_STATE Invalid state * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MA_ERROR_INVALID_STATE Invalid state * * @pre The state should be #MA_STATE_INITIALIZED. * @see ma_active_state_changed_cb() @@ -457,8 +457,8 @@ int ma_send_assistant_specific_command(const char* command); * @return @c 0 on success, otherwise a negative error value * @retval #MA_ERROR_NONE Successful * @retval #MA_ERROR_NOT_SUPPORTED Not supported - * @retval #MA_ERROR_INVALID_STATE Invalid state * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MA_ERROR_INVALID_STATE Invalid state * * @pre The state should be #MA_STATE_INITIALIZED. * @see ma_wakeup_engine_command_cb() @@ -482,7 +482,7 @@ int ma_set_wakeup_engine_command_cb(ma_wakeup_engine_command_cb callback, void* int ma_unset_wakeup_engine_command_cb(void); /** - * @brief Retrieves all installed voice assistant applications information. + * @brief Retrieves the information about all installed voice assistant applications. * @since_tizen 5.5 * * @param[in] callback A callback for getting the information of the installed assistants. @@ -491,20 +491,20 @@ int ma_unset_wakeup_engine_command_cb(void); * @return @c 0 on success, otherwise a negative error value * @retval #MA_ERROR_NONE Successful * @retval #MA_ERROR_NOT_SUPPORTED Not supported - * @retval #MA_ERROR_INVALID_STATE Invalid state * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MA_ERROR_INVALID_STATE Invalid state * * @see ma_voice_assistant_list_cb() */ int ma_assistant_info_foreach_assistants(ma_assistant_info_list_cb callback, void* user_data); /** - * @brief Gets the app id of the specific handle. + * @brief Gets the app id of the specified handle. * @since_tizen 5.5 * * @remarks You must not release @a app_id using free(). * @param[in] handle The handle to the assistant's information - * @param[in] app_id The application ID of the given assistant handle + * @param[out] app_id The application ID of the given assistant handle * * @return @c 0 on success, otherwise a negative error value * @retval #MA_ERROR_NONE Successful @@ -514,7 +514,7 @@ int ma_assistant_info_foreach_assistants(ma_assistant_info_list_cb callback, voi int ma_assistant_info_get_app_id(ma_assistant_info_h handle, char** app_id); /** - * @brief Gets the enabled status of the specific handle. + * @brief Gets the enabled status of the specified handle. * @since_tizen 5.5 * * @param[in] handle The handle to the assistant's information @@ -528,21 +528,7 @@ int ma_assistant_info_get_app_id(ma_assistant_info_h handle, char** app_id); int ma_assistant_info_get_enabled_status(ma_assistant_info_h handle, bool* status); /** - * @brief Gets the name of the specific handle. - * @since_tizen 5.5 - * - * @param[in] handle The handle to the assistant's information - * @param[in] name The application name of the given assistant handle - * - * @return @c 0 on success, otherwise a negative error value - * @retval #MA_ERROR_NONE Successful - * @retval #MA_ERROR_NOT_SUPPORTED Not supported - * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter - */ -int ma_assistant_info_get_name(ma_assistant_info_h handle, char** name); - -/** - * @brief Gets the type information of recording audio source. + * @brief Gets the recording audio source type. * @since_tizen 5.5 * @privlevel public * @privilege %http://tizen.org/privilege/recorder @@ -554,8 +540,8 @@ int ma_assistant_info_get_name(ma_assistant_info_h handle, char** name); * @retval #MA_ERROR_NONE Successful * @retval #MA_ERROR_NOT_SUPPORTED Not supported * @retval #MA_ERROR_PERMISSION_DENIED Permission denied - * @retval #MA_ERROR_INVALID_STATE Invalid state * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MA_ERROR_INVALID_STATE Invalid state * @retval #MA_ERROR_OPERATION_FAILED Operation failed * * @pre The state should be #MA_STATE_READY. @@ -568,15 +554,15 @@ int ma_get_recording_audio_source_type(char** type); * @privlevel public * @privilege %http://tizen.org/privilege/recorder * - * @remarks The @a ratio must be in 0.0~1.0 . + * @remarks The @a ratio must be a value between 0.0 and 1.0 (inclusive). * @param[in] ratio The volume ratio to be set * * @return @c 0 on success, otherwise a negative error value * @retval #MA_ERROR_NONE Successful * @retval #MA_ERROR_NOT_SUPPORTED Not supported * @retval #MA_ERROR_PERMISSION_DENIED Permission denied - * @retval #MA_ERROR_INVALID_STATE Invalid state * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MA_ERROR_INVALID_STATE Invalid state * @retval #MA_ERROR_OPERATION_FAILED Operation failed * * @pre The state should be #MA_STATE_READY. @@ -614,8 +600,8 @@ int ma_set_preprocessing_allow_mode(ma_preprocessing_allow_mode_e mode, const ch * @return @c 0 on success, otherwise a negative error value * @retval #MA_ERROR_NONE Successful * @retval #MA_ERROR_NOT_SUPPORTED Not supported - * @retval #MA_ERROR_INVALID_STATE Invalid state * @retval #MA_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #MA_ERROR_INVALID_STATE Invalid state * * @pre The state should be #MA_STATE_INITIALIZED. * @see ma_preprocessing_information_changed_cb() diff --git a/include/multi_assistant_common.h b/include/multi_assistant_common.h index a80e319..caa7553 100644 --- a/include/multi_assistant_common.h +++ b/include/multi_assistant_common.h @@ -237,7 +237,8 @@ typedef void (*ma_active_state_changed_cb)(ma_active_state_e previous, ma_active typedef void (*ma_wakeup_engine_command_cb)(const char *command, void* user_data); /** - * @brief A handle to get assistant information + * @brief A handle to get assistant information. + * @since_tizen 5.5 */ typedef void *ma_assistant_info_h; @@ -246,6 +247,8 @@ typedef void *ma_assistant_info_h; * @brief Called to get the assistant information once for each installed assistant. * @since_tizen 5.5 * + * @remarks The @a handle should not be released. + * @remarks The @a handle is managed by the platform and will be released when application exits. * @param[in] handle The handle of the assistant * @param[in] user_data The user data passed from the callback registration function */ @@ -258,6 +261,7 @@ typedef int (*ma_assistant_info_list_cb)(ma_assistant_info_h handle, void* user_ * @remarks The @a app_id should not be released and can be used only in the callback. To use outside, make a copy. * @remarks If the @a app_id is NULL, it means there is no preprocessing voice assistant available. * @param[in] app_id The application id of current preprocessing voice assistant + * @param[in] user_data The user data passed from the callback registration function */ typedef void (*ma_preprocessing_information_changed_cb)(const char* app_id, void* user_data); -- 2.34.1