From 4d9738a5878cda6130fd059479aa3cedabaead3b Mon Sep 17 00:00:00 2001 From: "pr.jung" Date: Fri, 6 Jan 2017 17:32:42 +0900 Subject: [PATCH] Modify api document Change-Id: I7558be0134bd6b8c098d9c69205691ed22455586 Signed-off-by: pr.jung --- include/feedback-ids.h | 105 ++++++++++++------------ include/feedback.h | 213 ++++++++++++++++++++++--------------------------- 2 files changed, 152 insertions(+), 166 deletions(-) diff --git a/include/feedback-ids.h b/include/feedback-ids.h index 179948e..0caaea8 100644 --- a/include/feedback-ids.h +++ b/include/feedback-ids.h @@ -19,89 +19,94 @@ #ifndef __FEEDBACK_IDS_H__ #define __FEEDBACK_IDS_H__ + #ifdef __cplusplus extern "C" { #endif + /** * @addtogroup CAPI_SYSTEM_FEEDBACK_MODULE * @{ */ + /** - * @brief Enumerations of the type for feedback interface + * @brief Enumeration for feedback interface type. * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif */ typedef enum { - FEEDBACK_TYPE_NONE, /**< Feedback type none */ - FEEDBACK_TYPE_SOUND, /**< Feedback type for sound */ - FEEDBACK_TYPE_VIBRATION, /**< Feedback type for vibration */ + FEEDBACK_TYPE_NONE, /**< Feedback type none */ + FEEDBACK_TYPE_SOUND, /**< Feedback type for sound */ + FEEDBACK_TYPE_VIBRATION, /**< Feedback type for vibration */ FEEDBACK_TYPE_END, } feedback_type_e; + /** - * @brief Enumerations of the system pre-defined patterns for feedback interface - * @details - * Each feedback pattern can have separate media files of each types. - * But Depending on vendor design, pattern may not have any type of file. - * + * @brief Enumeration for feedback interface of the system pre-defined patterns. + * @details Each feedback pattern can have separate media files of each types. + * But depending on vendor design, pattern may not have any type of file. * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif */ typedef enum { FEEDBACK_PATTERN_NONE = -1, - FEEDBACK_PATTERN_TAP = 0, /**< Feedback pattern when general touch */ - FEEDBACK_PATTERN_SIP, /**< Feedback pattern when touch text key */ - FEEDBACK_PATTERN_KEY0 = 6, /**< Feedback pattern when touch numeric 0 key */ - FEEDBACK_PATTERN_KEY1, /**< Feedback pattern when touch numeric 1 key */ - FEEDBACK_PATTERN_KEY2, /**< Feedback pattern when touch numeric 2 key */ - FEEDBACK_PATTERN_KEY3, /**< Feedback pattern when touch numeric 3 key */ - FEEDBACK_PATTERN_KEY4, /**< Feedback pattern when touch numeric 4 key */ - FEEDBACK_PATTERN_KEY5, /**< Feedback pattern when touch numeric 5 key */ - FEEDBACK_PATTERN_KEY6, /**< Feedback pattern when touch numeric 6 key */ - FEEDBACK_PATTERN_KEY7, /**< Feedback pattern when touch numeric 7 key */ - FEEDBACK_PATTERN_KEY8, /**< Feedback pattern when touch numeric 8 key */ - FEEDBACK_PATTERN_KEY9, /**< Feedback pattern when touch numeric 9 key */ - FEEDBACK_PATTERN_KEY_STAR, /**< Feedback pattern when touch star key */ - FEEDBACK_PATTERN_KEY_SHARP, /**< Feedback pattern when touch sharp key */ - FEEDBACK_PATTERN_KEY_BACK, /**< Feedback pattern when touch backspace key */ - FEEDBACK_PATTERN_HOLD, /**< Feedback pattern when touch hold */ - FEEDBACK_PATTERN_HW_TAP = 21, /**< Feedback pattern when press hardware key */ - FEEDBACK_PATTERN_HW_HOLD, /**< Feedback pattern when holding press hardware key */ - - FEEDBACK_PATTERN_MESSAGE, /**< Feedback pattern when incoming a message */ - FEEDBACK_PATTERN_EMAIL = 25, /**< Feedback pattern when incoming an email */ - FEEDBACK_PATTERN_WAKEUP = 27, /**< Feedback pattern when alert wake up call */ - FEEDBACK_PATTERN_SCHEDULE = 29, /**< Feedback pattern when alert schedule alarm */ - FEEDBACK_PATTERN_TIMER = 31, /**< Feedback pattern when alert timer */ - FEEDBACK_PATTERN_GENERAL = 33, /**< Feedback pattern when alert general event */ - - FEEDBACK_PATTERN_POWERON = 36, /**< Feedback pattern when power on */ - FEEDBACK_PATTERN_POWEROFF, /**< Feedback pattern when power off */ - FEEDBACK_PATTERN_CHARGERCONN, /**< Feedback pattern when connecting charger */ - FEEDBACK_PATTERN_CHARGING_ERROR = 40, /**< Feedback pattern when occuring charging error */ - FEEDBACK_PATTERN_FULLCHARGED = 42, /**< Feedback pattern when full charged */ - FEEDBACK_PATTERN_LOWBATT = 44, /**< Feedback pattern when low battery */ - FEEDBACK_PATTERN_LOCK = 46, /**< Feedback pattern when lock */ - FEEDBACK_PATTERN_UNLOCK, /**< Feedback pattern when unlock */ - FEEDBACK_PATTERN_VIBRATION_ON = 55, /**< Feedback pattern when turn on vibration mode */ - FEEDBACK_PATTERN_SILENT_OFF, /**< Feedback pattern when turn off silent mode */ - FEEDBACK_PATTERN_BT_CONNECTED, /**< Feedback pattern when connecting with bluetooth */ - FEEDBACK_PATTERN_BT_DISCONNECTED, /**< Feedback pattern when disconnecting with bluetooth */ - FEEDBACK_PATTERN_LIST_REORDER = 62, /**< Feedback pattern when list reorder */ - FEEDBACK_PATTERN_LIST_SLIDER, /**< Feedback pattern when list slider sweep */ - FEEDBACK_PATTERN_VOLUME_KEY, /**< Feedback pattern when pressed volume key */ + FEEDBACK_PATTERN_TAP = 0, /**< Feedback pattern when general touch */ + FEEDBACK_PATTERN_SIP, /**< Feedback pattern when touch text key */ + FEEDBACK_PATTERN_KEY0 = 6, /**< Feedback pattern when touch numeric 0 key */ + FEEDBACK_PATTERN_KEY1, /**< Feedback pattern when touch numeric 1 key */ + FEEDBACK_PATTERN_KEY2, /**< Feedback pattern when touch numeric 2 key */ + FEEDBACK_PATTERN_KEY3, /**< Feedback pattern when touch numeric 3 key */ + FEEDBACK_PATTERN_KEY4, /**< Feedback pattern when touch numeric 4 key */ + FEEDBACK_PATTERN_KEY5, /**< Feedback pattern when touch numeric 5 key */ + FEEDBACK_PATTERN_KEY6, /**< Feedback pattern when touch numeric 6 key */ + FEEDBACK_PATTERN_KEY7, /**< Feedback pattern when touch numeric 7 key */ + FEEDBACK_PATTERN_KEY8, /**< Feedback pattern when touch numeric 8 key */ + FEEDBACK_PATTERN_KEY9, /**< Feedback pattern when touch numeric 9 key */ + FEEDBACK_PATTERN_KEY_STAR, /**< Feedback pattern when touch star key */ + FEEDBACK_PATTERN_KEY_SHARP, /**< Feedback pattern when touch sharp key */ + FEEDBACK_PATTERN_KEY_BACK, /**< Feedback pattern when touch backspace key */ + FEEDBACK_PATTERN_HOLD, /**< Feedback pattern when touch hold */ + FEEDBACK_PATTERN_HW_TAP = 21, /**< Feedback pattern when press hardware key */ + FEEDBACK_PATTERN_HW_HOLD, /**< Feedback pattern when holding press hardware key */ + + FEEDBACK_PATTERN_MESSAGE, /**< Feedback pattern when incoming a message */ + FEEDBACK_PATTERN_EMAIL = 25, /**< Feedback pattern when incoming an email */ + FEEDBACK_PATTERN_WAKEUP = 27, /**< Feedback pattern when alert wake up call */ + FEEDBACK_PATTERN_SCHEDULE = 29, /**< Feedback pattern when alert schedule alarm */ + FEEDBACK_PATTERN_TIMER = 31, /**< Feedback pattern when alert timer */ + FEEDBACK_PATTERN_GENERAL = 33, /**< Feedback pattern when alert general event */ + + FEEDBACK_PATTERN_POWERON = 36, /**< Feedback pattern when power on */ + FEEDBACK_PATTERN_POWEROFF, /**< Feedback pattern when power off */ + FEEDBACK_PATTERN_CHARGERCONN, /**< Feedback pattern when connecting charger */ + FEEDBACK_PATTERN_CHARGING_ERROR = 40, /**< Feedback pattern when occuring charging error */ + FEEDBACK_PATTERN_FULLCHARGED = 42, /**< Feedback pattern when full charged */ + FEEDBACK_PATTERN_LOWBATT = 44, /**< Feedback pattern when low battery */ + FEEDBACK_PATTERN_LOCK = 46, /**< Feedback pattern when lock */ + FEEDBACK_PATTERN_UNLOCK, /**< Feedback pattern when unlock */ + FEEDBACK_PATTERN_VIBRATION_ON = 55, /**< Feedback pattern when turn on vibration mode */ + FEEDBACK_PATTERN_SILENT_OFF, /**< Feedback pattern when turn off silent mode */ + FEEDBACK_PATTERN_BT_CONNECTED, /**< Feedback pattern when connecting with bluetooth */ + FEEDBACK_PATTERN_BT_DISCONNECTED, /**< Feedback pattern when disconnecting with bluetooth */ + FEEDBACK_PATTERN_LIST_REORDER = 62, /**< Feedback pattern when list reorder */ + FEEDBACK_PATTERN_LIST_SLIDER, /**< Feedback pattern when list slider sweep */ + FEEDBACK_PATTERN_VOLUME_KEY, /**< Feedback pattern when pressed volume key */ FEEDBACK_PATTERN_END = 74, } feedback_pattern_e; + /** * @} */ + #ifdef __cplusplus } #endif + #endif //__FEEDBACK_IDS_H__ diff --git a/include/feedback.h b/include/feedback.h index dba4f45..3fcff64 100644 --- a/include/feedback.h +++ b/include/feedback.h @@ -19,194 +19,175 @@ #ifndef __FEEDBACK_H__ #define __FEEDBACK_H__ + #include #include #include "feedback-ids.h" + #ifdef __cplusplus extern "C" { #endif + /** * @file feedback.h - * @brief This file contains the feedback API + * @brief This file contains the feedback API. */ + /** * @addtogroup CAPI_SYSTEM_FEEDBACK_MODULE * @{ */ + /** - * @brief Enumerations of error codes for the Feedback API. + * @brief Enumeration for the Feedback API error codes. * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif */ typedef enum { - FEEDBACK_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ - FEEDBACK_ERROR_OPERATION_FAILED = TIZEN_ERROR_NOT_PERMITTED, /**< Operation failed */ - FEEDBACK_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ - FEEDBACK_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported in this device */ - FEEDBACK_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */ - FEEDBACK_ERROR_NOT_INITIALIZED = TIZEN_ERROR_FEEDBACK | 0x01, /**< Not initialized */ + FEEDBACK_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ + FEEDBACK_ERROR_OPERATION_FAILED = TIZEN_ERROR_NOT_PERMITTED, /**< Operation failed */ + FEEDBACK_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ + FEEDBACK_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported in this device */ + FEEDBACK_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */ + FEEDBACK_ERROR_NOT_INITIALIZED = TIZEN_ERROR_FEEDBACK | 0x01, /**< Not initialized */ } feedback_error_e; + /** * @brief Initializes feedback API. - * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * - * @remarks - * If this function is not called in advance, other function will return #FEEDBACK_ERROR_NOT_INITIALIZED. - * And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic. - * If you don't have the haptic privilege, this function initializes only sound. - * It does not return any error in this case. - * - * @return 0 on success, otherwise a negative error value. - * @retval #FEEDBACK_ERROR_NONE Successful - * + * @remarks If this function is not called in advance, other function will return #FEEDBACK_ERROR_NOT_INITIALIZED. + * And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic. + * If you don't have the haptic privilege, this function initializes only sound. + * It does not return any error in this case. + * @return @c 0 on success, + * otherwise a negative error value + * @retval #FEEDBACK_ERROR_NONE Successful * @post feedback_deinitialize() - * * @see feedback_deinitialize() */ int feedback_initialize(void); + /** * @brief Deinitializes feedback API. * @details This function must be called when feedback functions are no longer needed. - * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * - * @remarks - * If you don't want to use feedback anymore, you need to deinitialize with this function. - * And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic. - * If you don't have the haptic privilege, this function deinitializes only sound. - * It does not return any error in this case. - * - * @return 0 on success, otherwise a negative error value. - * @retval #FEEDBACK_ERROR_NONE Successful - * @retval #FEEDBACK_ERROR_NOT_INITIALIZED Not initialized - * + * @remarks If you don't want to use feedback anymore, you need to deinitialize with this function. + * And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic. + * If you don't have the haptic privilege, this function deinitializes only sound. + * It does not return any error in this case. + * @return @c 0 on success, + * otherwise a negative error value + * @retval #FEEDBACK_ERROR_NONE Successful + * @retval #FEEDBACK_ERROR_NOT_INITIALIZED Not initialized * @pre feedback_initialize() - * * @see feedback_initialize() */ int feedback_deinitialize(void); + /** * @brief Plays various types of reactions that are pre-defined. - * @details - * This functon can be used to react to pre-defined actions. \n - * It play various types of system pre-defined media or vibration patterns. - * + * @details This function can be used to react to pre-defined actions. \n + * It play various types of system pre-defined media or vibration patterns. * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * - * @remarks - * Currently, there are two types of reactions: sound and vibration. \n - * Depending on the settings, some types cannot operate. - * For example, when set to silent mode, the device doesn't produce any sound. - * If to play one of devices is successful, this function regards as success. - * And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic. - * If you don't have the haptic privilege, it only works sound operation. - * It does not return any error in this case. - * - * @param[in] pattern The pre-defined pattern - * - * @return 0 on success, otherwise a negative error value. - * @retval #FEEDBACK_ERROR_NONE Successful - * @retval #FEEDBACK_ERROR_OPERATION_FAILED Operation not permitted - * @retval #FEEDBACK_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #FEEDBACK_ERROR_NOT_SUPPORTED Not supported device - * @retval #FEEDBACK_ERROR_NOT_INITIALIZED Not initialized - * + * @remarks Currently, there are two types of reactions: sound and vibration. \n + * Depending on the settings, some types cannot operate. + * For example, when set to silent mode, the device doesn't produce any sound. + * If to play one of the devices is successful, this function regards as success. + * And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic. + * If you don't have the haptic privilege, it only works sound operation. + * It does not return any error in this case. + * @param[in] pattern The pre-defined pattern + * @return @c 0 on success, + * otherwise a negative error value + * @retval #FEEDBACK_ERROR_NONE Successful + * @retval #FEEDBACK_ERROR_OPERATION_FAILED Operation not permitted + * @retval #FEEDBACK_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #FEEDBACK_ERROR_NOT_SUPPORTED Not supported device + * @retval #FEEDBACK_ERROR_NOT_INITIALIZED Not initialized * @pre feedback_initialize() */ int feedback_play(feedback_pattern_e pattern); /** - * * @brief Plays specific type of reactions that are pre-defined. - * @details - * This function can be used to react to pre-defined actions. \n - * It play specific type of system pre-defined pattern. - * + * @details This function can be used to react to pre-defined actions. \n + * It play specific type of system pre-defined pattern. * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * - * @remarks - * Currently, there are two types of reactions: sound and vibration. \n - * Depending on the settings, some types cannot operate. - * For example, when set to silent mode, the device doesn't produce any sound. - * And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic. - * If you don't have the haptic privilege, it returns FEEDBACK_ERROR_PERMISSION_DENIED error. - * - * @param[in] type The pattern type - * @param[in] pattern The pre-defined pattern - * - * @return 0 on success, otherwise a negative error value. - * @retval #FEEDBACK_ERROR_NONE Successful - * @retval #FEEDBACK_ERROR_OPERATION_FAILED Operation not permitted - * @retval #FEEDBACK_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #FEEDBACK_ERROR_NOT_SUPPORTED Not supported device - * @retval #FEEDBACK_ERROR_PERMISSION_DENIED Permission denied - * @retval #FEEDBACK_ERROR_NOT_INITIALIZED Not initialized - * + * @remarks Currently, there are two types of reactions: sound and vibration. \n + * Depending on the settings, some types cannot operate. + * For example, when set to silent mode, the device doesn't produce any sound. + * And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic. + * If you don't have the haptic privilege, it returns FEEDBACK_ERROR_PERMISSION_DENIED error. + * @param[in] type The pattern type + * @param[in] pattern The pre-defined pattern + * @return @c 0 on success, + * otherwise a negative error value + * @retval #FEEDBACK_ERROR_NONE Successful + * @retval #FEEDBACK_ERROR_OPERATION_FAILED Operation not permitted + * @retval #FEEDBACK_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #FEEDBACK_ERROR_NOT_SUPPORTED Not supported device + * @retval #FEEDBACK_ERROR_PERMISSION_DENIED Permission denied + * @retval #FEEDBACK_ERROR_NOT_INITIALIZED Not initialized * @pre feedback_initialize() */ int feedback_play_type(feedback_type_e type, feedback_pattern_e pattern); /** - * @brief Stop various types of reactions - * @details - * This functon can be used to stop react to pre-defined actions. \n - * It stops system pre-defined vibration patterns. - * + * @brief Stops various types of reactions. + * @details This function can be used to stop reaction to pre-defined actions. \n + * It stops system pre-defined vibration patterns. * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * - * @remarks - * This function does not support to stop media sound actions. \n - * In this case, it will return FEEDBACK_ERROR_NOT_SUPPORTED error. - * And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic. - * If you don't have the haptic privilege, it only works sound operation. - * It does not return any error in this case. - * - * @return 0 on success, otherwise a negative error value. - * @retval #FEEDBACK_ERROR_NONE Successful - * @retval #FEEDBACK_ERROR_OPERATION_FAILED Operation not permitted - * @retval #FEEDBACK_ERROR_NOT_SUPPORTED Not supported device - * @retval #FEEDBACK_ERROR_PERMISSION_DENIED Permission denied - * @retval #FEEDBACK_ERROR_NOT_INITIALIZED Not initialized - * + * @remarks This function does not support to stop media sound actions. \n + * In this case, it will return FEEDBACK_ERROR_NOT_SUPPORTED error. + * And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic. + * If you don't have the haptic privilege, it only works sound operation. + * It does not return any error in this case. + * @return @c 0 on success, + * otherwise a negative error value + * @retval #FEEDBACK_ERROR_NONE Successful + * @retval #FEEDBACK_ERROR_OPERATION_FAILED Operation not permitted + * @retval #FEEDBACK_ERROR_NOT_SUPPORTED Not supported device + * @retval #FEEDBACK_ERROR_PERMISSION_DENIED Permission denied + * @retval #FEEDBACK_ERROR_NOT_INITIALIZED Not initialized * @pre feedback_initialize() */ int feedback_stop(void); + /** - * @brief Checks if the pattern is supported - * @details - * This functon can be used to check if a specific pattern is supported. - * + * @brief Checks if the pattern is supported. + * @details This function can be used to check if a specific pattern is supported. * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * - * @param[in] type The pattern type - * @param[in] pattern The pre-defined pattern - * @param[out] status True means the pattern is supported, otherwise not supported. - * - * @return 0 on success, otherwise a negative error value. - * @retval #FEEDBACK_ERROR_NONE Successful - * @retval #FEEDBACK_ERROR_OPERATION_FAILED Operation not permitted - * @retval #FEEDBACK_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #FEEDBACK_ERROR_NOT_SUPPORTED Not supported device - * @retval #FEEDBACK_ERROR_NOT_INITIALIZED Not initialized - * + * @param[in] type The pattern type + * @param[in] pattern The pre-defined pattern + * @param[out] status True means the pattern is supported, + * otherwise not supported + * @return @c 0 on success, + * otherwise a negative error value + * @retval #FEEDBACK_ERROR_NONE Successful + * @retval #FEEDBACK_ERROR_OPERATION_FAILED Operation not permitted + * @retval #FEEDBACK_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #FEEDBACK_ERROR_NOT_SUPPORTED Not supported device + * @retval #FEEDBACK_ERROR_NOT_INITIALIZED Not initialized * @pre feedback_initialize() */ int feedback_is_supported_pattern(feedback_type_e type, feedback_pattern_e pattern, bool *status); + /** * @} */ + #ifdef __cplusplus } #endif + #endif //__FEEDBACK_H__ -- 2.7.4