include/feedback.h

   1 /*
   2  * libfeedback
   3  * Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the License);
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17
  18
  19 #ifndef __FEEDBACK_H__
  20 #define __FEEDBACK_H__
  21
  22
  23 #include <tizen.h>
  24 #include <tizen_error.h>
  25 #include "feedback-ids.h"
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31
  32 /**
  33  * @file feedback.h
  34  * @brief This file contains the feedback API.
  35  */
  36
  37
  38 /**
  39  * @addtogroup CAPI_SYSTEM_FEEDBACK_MODULE
  40  * @{
  41  */
  42
  43
  44 /**
  45  * @brief Enumeration for the Feedback API error codes.
  46  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  47  */
  48 typedef enum {
  49         FEEDBACK_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  50         FEEDBACK_ERROR_OPERATION_FAILED = TIZEN_ERROR_NOT_PERMITTED, /**< Operation failed */
  51         FEEDBACK_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  52         FEEDBACK_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported in this device */
  53         FEEDBACK_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
  54         FEEDBACK_ERROR_NOT_INITIALIZED = TIZEN_ERROR_FEEDBACK | 0x01, /**< Not initialized */
  55 } feedback_error_e;
  56
  57
  58 /**
  59  * @brief Initializes feedback API.
  60  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  61  * @remarks If this function is not called in advance, other function will return #FEEDBACK_ERROR_NOT_INITIALIZED.
  62  *          And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic.
  63  *          If you don't have the haptic privilege, this function initializes only sound.
  64  *          It does not return any error in this case.
  65  * @return @c 0 on success,
  66  *         otherwise a negative error value
  67  * @retval #FEEDBACK_ERROR_NONE Successful
  68  * @post feedback_deinitialize()
  69  * @see feedback_deinitialize()
  70  */
  71 int feedback_initialize(void);
  72
  73
  74 /**
  75  * @brief Deinitializes feedback API.
  76  * @details This function must be called when feedback functions are no longer needed.
  77  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  78  * @remarks If you don't want to use feedback anymore, you need to deinitialize with this function.
  79  *          And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic.
  80  *          If you don't have the haptic privilege, this function deinitializes only sound.
  81  *          It does not return any error in this case.
  82  * @return @c 0 on success,
  83  *         otherwise a negative error value
  84  * @retval #FEEDBACK_ERROR_NONE Successful
  85  * @retval #FEEDBACK_ERROR_NOT_INITIALIZED Not initialized
  86  * @pre feedback_initialize()
  87  * @see feedback_initialize()
  88  */
  89 int feedback_deinitialize(void);
  90
  91
  92 /**
  93  * @brief Plays various types of reactions that are pre-defined.
  94  * @details This function can be used to react to pre-defined actions. \n
  95  *          It play various types of system pre-defined media or vibration patterns.
  96  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  97  * @remarks Currently, there are two types of reactions: sound and vibration. \n
  98  *          Depending on the settings, some types cannot operate.
  99  *          For example, when set to silent mode, the device doesn't produce any sound.
 100  *          If to play one of the devices is successful, this function regards as success.
 101  *          And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic.
 102  *          If you don't have the haptic privilege, it only works sound operation.
 103  *          It does not return any error in this case.
 104  * @param[in] pattern The pre-defined pattern
 105  * @return @c 0 on success,
 106  *         otherwise a negative error value
 107  * @retval #FEEDBACK_ERROR_NONE Successful
 108  * @retval #FEEDBACK_ERROR_OPERATION_FAILED Operation not permitted
 109  * @retval #FEEDBACK_ERROR_INVALID_PARAMETER Invalid parameter
 110  * @retval #FEEDBACK_ERROR_NOT_SUPPORTED Not supported device
 111  * @retval #FEEDBACK_ERROR_NOT_INITIALIZED Not initialized
 112  * @pre feedback_initialize()
 113  */
 114 int feedback_play(feedback_pattern_e pattern);
 115
 116 /**
 117  * @brief Plays specific type of reactions that are pre-defined.
 118  * @details This function can be used to react to pre-defined actions. \n
 119  *          It play specific type of system pre-defined pattern.
 120  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 121  * @remarks Currently, there are two types of reactions: sound and vibration. \n
 122  *          Depending on the settings, some types cannot operate.
 123  *          For example, when set to silent mode, the device doesn't produce any sound.
 124  *          And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic.
 125  *          If you don't have the haptic privilege, it returns FEEDBACK_ERROR_PERMISSION_DENIED error.
 126  * @param[in] type The pattern type
 127  * @param[in] pattern The pre-defined pattern
 128  * @return @c 0 on success,
 129  *         otherwise a negative error value
 130  * @retval #FEEDBACK_ERROR_NONE Successful
 131  * @retval #FEEDBACK_ERROR_OPERATION_FAILED Operation not permitted
 132  * @retval #FEEDBACK_ERROR_INVALID_PARAMETER Invalid parameter
 133  * @retval #FEEDBACK_ERROR_NOT_SUPPORTED Not supported device
 134  * @retval #FEEDBACK_ERROR_PERMISSION_DENIED Permission denied
 135  * @retval #FEEDBACK_ERROR_NOT_INITIALIZED Not initialized
 136  * @pre feedback_initialize()
 137  */
 138 int feedback_play_type(feedback_type_e type, feedback_pattern_e pattern);
 139
 140 /**
 141  * @brief Stops various types of reactions.
 142  * @details This function can be used to stop reaction to pre-defined actions. \n
 143  *          It stops system pre-defined vibration patterns.
 144  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 145  * @remarks This function does not support to stop media sound actions. \n
 146  *          In this case, it will return FEEDBACK_ERROR_NOT_SUPPORTED error.
 147  *          And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic.
 148  *          If you don't have the haptic privilege, it only works sound operation.
 149  *          It does not return any error in this case.
 150  * @return @c 0 on success,
 151  *         otherwise a negative error value
 152  * @retval #FEEDBACK_ERROR_NONE Successful
 153  * @retval #FEEDBACK_ERROR_OPERATION_FAILED Operation not permitted
 154  * @retval #FEEDBACK_ERROR_NOT_SUPPORTED Not supported device
 155  * @retval #FEEDBACK_ERROR_PERMISSION_DENIED Permission denied
 156  * @retval #FEEDBACK_ERROR_NOT_INITIALIZED Not initialized
 157  * @pre feedback_initialize()
 158  */
 159 int feedback_stop(void);
 160
 161
 162 /**
 163  * @brief Checks if the pattern is supported.
 164  * @details This function can be used to check if a specific pattern is supported.
 165  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 166  * @param[in] type The pattern type
 167  * @param[in] pattern The pre-defined pattern
 168  * @param[out] status True means the pattern is supported,
 169  *                    otherwise not supported
 170  * @return @c 0 on success,
 171  *         otherwise a negative error value
 172  * @retval #FEEDBACK_ERROR_NONE Successful
 173  * @retval #FEEDBACK_ERROR_OPERATION_FAILED Operation not permitted
 174  * @retval #FEEDBACK_ERROR_INVALID_PARAMETER Invalid parameter
 175  * @retval #FEEDBACK_ERROR_NOT_SUPPORTED Not supported device
 176  * @retval #FEEDBACK_ERROR_NOT_INITIALIZED Not initialized
 177  * @pre feedback_initialize()
 178  */
 179 int feedback_is_supported_pattern(feedback_type_e type, feedback_pattern_e pattern, bool *status);
 180
 181
 182 /**
 183  * @}
 184  */
 185
 186
 187 #ifdef __cplusplus
 188 }
 189 #endif
 190
 191
 192 #endif //__FEEDBACK_H__