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 #include <tizen.h>
  23 #include <tizen_error.h>
  24 #include "feedback-ids.h"
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /**
  31  * @file feedback.h
  32  * @brief This file contains the feedback API
  33  */
  34
  35 /**
  36  * @addtogroup CAPI_SYSTEM_FEEDBACK_MODULE
  37  * @{
  38  */
  39
  40 /**
  41  * @brief Enumerations of error codes for the Feedback API.
  42  * @since_tizen 2.4
  43  */
  44 typedef enum
  45 {
  46     FEEDBACK_ERROR_NONE                = TIZEN_ERROR_NONE,                /**< Successful */
  47     FEEDBACK_ERROR_OPERATION_FAILED    = TIZEN_ERROR_NOT_PERMITTED,       /**< Operation failed */
  48     FEEDBACK_ERROR_INVALID_PARAMETER   = TIZEN_ERROR_INVALID_PARAMETER,   /**< Invalid parameter */
  49     FEEDBACK_ERROR_NOT_SUPPORTED       = TIZEN_ERROR_NOT_SUPPORTED,       /**< Not supported in this device */
  50     FEEDBACK_ERROR_PERMISSION_DENIED   = TIZEN_ERROR_PERMISSION_DENIED,   /**< Permission denied */
  51     FEEDBACK_ERROR_NOT_INITIALIZED     = TIZEN_ERROR_FEEDBACK | 0x01,     /**< Not initialized */
  52 } feedback_error_e;
  53
  54 /**
  55  * @brief Initializes feedback API.
  56  *
  57  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  58  *
  59  * @remarks
  60  * If this function is not called in advance, other function will return #FEEDBACK_ERROR_NOT_INITIALIZED.
  61  * And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic.
  62  * If you don't have the haptic privilege, this function initializes only sound.
  63  * It does not return any error in this case.
  64  *
  65  * @return 0 on success, otherwise a negative error value.
  66  * @retval #FEEDBACK_ERROR_NONE               Successful
  67  *
  68  * @post feedback_deinitialize()
  69  *
  70  * @see feedback_deinitialize()
  71  */
  72 int feedback_initialize(void);
  73
  74 /**
  75  * @brief Deinitializes feedback API.
  76  * @details This function must be called when feedback functions are no longer needed.
  77  *
  78  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  79  *
  80  * @remarks
  81  * If you don't want to use feedback anymore, you need to deinitialize with this function.
  82  * And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic.
  83  * If you don't have the haptic privilege, this function deinitializes only sound.
  84  * It does not return any error in this case.
  85  *
  86  * @return 0 on success, otherwise a negative error value.
  87  * @retval #FEEDBACK_ERROR_NONE                 Successful
  88  * @retval #FEEDBACK_ERROR_NOT_INITIALIZED      Not initialized
  89  *
  90  * @pre feedback_initialize()
  91  *
  92  * @see feedback_initialize()
  93  */
  94 int feedback_deinitialize(void);
  95
  96 /**
  97  * @brief Plays various types of reactions that are pre-defined.
  98  * @details
  99  * This functon can be used to react to pre-defined actions. \n
 100  * It play various types of system pre-defined media or vibration patterns.
 101  *
 102  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 103  *
 104  * @remarks
 105  * Currently, there are two types of reactions: sound and vibration. \n
 106  * Depending on the settings, some types cannot operate.
 107  * For example, when set to silent mode, the device doesn't produce any sound.
 108  * If to play one of devices is successful, this function regards as success.
 109  * And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic.
 110  * If you don't have the haptic privilege, it only works sound operation.
 111  * It does not return any error in this case.
 112  *
 113  * @param[in] pattern   The pre-defined pattern
 114  *
 115  * @return 0 on success, otherwise a negative error value.
 116  * @retval #FEEDBACK_ERROR_NONE                 Successful
 117  * @retval #FEEDBACK_ERROR_OPERATION_FAILED     Operation not permitted
 118  * @retval #FEEDBACK_ERROR_INVALID_PARAMETER    Invalid parameter
 119  * @retval #FEEDBACK_ERROR_NOT_SUPPORTED        Not supported device
 120  * @retval #FEEDBACK_ERROR_NOT_INITIALIZED      Not initialized
 121  *
 122  * @pre feedback_initialize()
 123  */
 124 int feedback_play(feedback_pattern_e pattern);
 125
 126 /**
 127  *
 128  * @brief Plays specific type of reactions that are pre-defined.
 129  * @details
 130  * This function can be used to react to pre-defined actions. \n
 131  * It play specific type of system pre-defined pattern.
 132  *
 133  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 134  *
 135  * @remarks
 136  * Currently, there are two types of reactions: sound and vibration. \n
 137  * Depending on the settings, some types cannot operate.
 138  * For example, when set to silent mode, the device doesn't produce any sound.
 139  * And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic.
 140  * If you don't have the haptic privilege, it returns FEEDBACK_ERROR_PERMISSION_DENIED error.
 141  *
 142  * @param[in] type      The pattern type
 143  * @param[in] pattern   The pre-defined pattern
 144  *
 145  * @return 0 on success, otherwise a negative error value.
 146  * @retval #FEEDBACK_ERROR_NONE                 Successful
 147  * @retval #FEEDBACK_ERROR_OPERATION_FAILED     Operation not permitted
 148  * @retval #FEEDBACK_ERROR_INVALID_PARAMETER    Invalid parameter
 149  * @retval #FEEDBACK_ERROR_NOT_SUPPORTED        Not supported device
 150  * @retval #FEEDBACK_ERROR_PERMISSION_DENIED    Permission denied
 151  * @retval #FEEDBACK_ERROR_NOT_INITIALIZED      Not initialized
 152  *
 153  * @pre feedback_initialize()
 154  */
 155 int feedback_play_type(feedback_type_e type, feedback_pattern_e pattern);
 156
 157 /**
 158  * @brief Stop various types of reactions
 159  * @details
 160  * This functon can be used to stop react to pre-defined actions. \n
 161  * It stops system pre-defined vibration patterns.
 162  *
 163  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 164  *
 165  * @remarks
 166  * This function does not support to stop media sound actions. \n
 167  * In this case, it will return FEEDBACK_ERROR_NOT_SUPPORTED error.
 168  * And for controlling haptic device, the privilege should be set to, %http://tizen.org/privilege/haptic.
 169  * If you don't have the haptic privilege, it only works sound operation.
 170  * It does not return any error in this case.
 171  *
 172  * @return 0 on success, otherwise a negative error value.
 173  * @retval #FEEDBACK_ERROR_NONE                 Successful
 174  * @retval #FEEDBACK_ERROR_OPERATION_FAILED     Operation not permitted
 175  * @retval #FEEDBACK_ERROR_NOT_SUPPORTED        Not supported device
 176  * @retval #FEEDBACK_ERROR_PERMISSION_DENIED    Permission denied
 177  * @retval #FEEDBACK_ERROR_NOT_INITIALIZED      Not initialized
 178  *
 179  * @pre feedback_initialize()
 180  */
 181 int feedback_stop(void);
 182
 183 /**
 184  * @brief Checks if the pattern is supported
 185  * @details
 186  * This functon can be used to check if a specific pattern is supported.
 187  *
 188  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 189  *
 190  * @param[in] type      The pattern type
 191  * @param[in] pattern   The pre-defined pattern
 192  * @param[out] status   True means the pattern is supported, otherwise not supported.
 193  *
 194  * @return 0 on success, otherwise a negative error value.
 195  * @retval #FEEDBACK_ERROR_NONE                 Successful
 196  * @retval #FEEDBACK_ERROR_OPERATION_FAILED     Operation not permitted
 197  * @retval #FEEDBACK_ERROR_INVALID_PARAMETER    Invalid parameter
 198  * @retval #FEEDBACK_ERROR_NOT_SUPPORTED        Not supported device
 199  * @retval #FEEDBACK_ERROR_NOT_INITIALIZED      Not initialized
 200  *
 201  * @pre feedback_initialize()
 202  */
 203 int feedback_is_supported_pattern(feedback_type_e type, feedback_pattern_e pattern, bool *status);
 204
 205 /**
 206  * @}
 207  */
 208
 209 #ifdef __cplusplus
 210 }
 211 #endif
 212
 213 #endif //__FEEDBACK_H__