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_error.h>
  23 #include "feedback-ids.h"
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /**
  30  * @file feedback.h
  31  * @brief This file contains the feedback API
  32  */
  33
  34 /**
  35  * @addtogroup CAPI_SYSTEM_FEEDBACK_MODULE
  36  * @{
  37  */
  38
  39 /**
  40  * @brief Enumerations of error codes for the Feedback API.
  41  * @since_tizen 2.3
  42  */
  43 typedef enum
  44 {
  45     FEEDBACK_ERROR_NONE                = TIZEN_ERROR_NONE,                /**< Successful */
  46     FEEDBACK_ERROR_OPERATION_FAILED    = TIZEN_ERROR_NOT_PERMITTED,       /**< Operation not permitted */
  47     FEEDBACK_ERROR_INVALID_PARAMETER   = TIZEN_ERROR_INVALID_PARAMETER,   /**< Invalid parameter */
  48     FEEDBACK_ERROR_NOT_SUPPORTED       = TIZEN_ERROR_NOT_SUPPORTED,       /**< Not supported in this device */
  49     FEEDBACK_ERROR_NOT_INITIALIZED     = TIZEN_ERROR_SYSTEM_CLASS | 0x52, /**< Has not yet been Initialized */
  50 } feedback_error_e;
  51
  52 #define FEEDBACK_SUCCEEDED(n)                ((n) == FEEDBACK_ERROR_NONE)
  53 #define FEEDBACK_FAILED(n)                   ((n) != FEEDBACK_ERROR_NONE)
  54
  55 /**
  56  * @brief Initializes feedback API.
  57  *
  58  * @since_tizen 2.3
  59  *
  60  * @remarks
  61  * If this function is not called in advance, other function will return #FEEDBACK_ERROR_NOT_INITIALIZED.
  62  *
  63  * @return 0 on success, otherwise a negative error value.
  64  * @retval #FEEDBACK_ERROR_NONE               Successful
  65  * @retval #FEEDBACK_ERROR_OPERATION_FAILED   Operation failed
  66  * @retval #FEEDBACK_ERROR_NOT_SUPPORTED      Not supported device
  67  *
  68  * @see feedback_deinitialize()
  69  */
  70 int feedback_initialize(void);
  71
  72 /**
  73  * @brief Deinitializes feedback API.
  74  * @details This function must be called when feedback functions are no longer needed.
  75  *
  76  * @since_tizen 2.3
  77  *
  78  * @return 0 on success, otherwise a negative error value.
  79  * @retval #FEEDBACK_ERROR_NONE                 Successful
  80  * @retval #FEEDBACK_ERROR_OPERATION_FAILED     Operation failed
  81  * @retval #FEEDBACK_ERROR_NOT_SUPPORTED      Not supported device
  82  *
  83  * @see feedback_initialize()
  84  */
  85 int feedback_deinitialize(void);
  86
  87 /**
  88  * @brief Plays various types of reactions that are pre-defined.
  89  * @details
  90  * This functon can be used to react to pre-defined actions. \n
  91  * It play various types of system pre-defined media or vibration patterns.
  92  *
  93  * @since_tizen 2.3
  94  *
  95  * @remarks
  96  * Currently, there are two types of reactions: sound and vibration. \n
  97  * Depending on the settings, some types cannot operate.
  98  * For example, when set to silent mode, the device doesn't produce any sound.
  99  *
 100  * @param[in] pattern   The pre-defined pattern
 101  *
 102  * @return 0 on success, otherwise a negative error value.
 103  * @retval #FEEDBACK_ERROR_NONE               Successful
 104  * @retval #FEEDBACK_ERROR_INVALID_PARAMETER  Invalid parameter
 105  * @retval #FEEDBACK_ERROR_NOT_SUPPORTED      Not supported device
 106  */
 107 int feedback_play(feedback_pattern_e pattern);
 108
 109 /**
 110  *
 111  * @brief Plays specific type of reactions that are pre-defined.
 112  * @details
 113  * This function can be used to react to pre-defined actions. \n
 114  * It play specific type of system pre-defined pattern.
 115  *
 116  * @since_tizen 2.3
 117  *
 118  * @remarks
 119  * Currently, there are two types of reactions: sound and vibration.
 120  *
 121  * @param[in] type      The pattern type
 122  * @param[in] pattern   The pre-defined pattern
 123  *
 124  * @return 0 on success, otherwise a negative error value.
 125  * @retval #FEEDBACK_ERROR_NONE               Successful
 126  * @retval #FEEDBACK_ERROR_INVALID_PARAMETER  Invalid parameter
 127  * @retval #FEEDBACK_ERROR_NOT_SUPPORTED      Not supported device
 128  */
 129 int feedback_play_type(feedback_type_e type, feedback_pattern_e pattern);
 130
 131 /**
 132  *
 133  * @brief Plays specific type of reactions that are pre-defined.
 134  * @details
 135  * This function can be used to react to pre-defined actions. \n
 136  * It play specific type of system pre-defined pattern.
 137  *
 138  * @since_tizen 2.3
 139  *
 140  * @remarks
 141  * Currently, there are two types of reactions: sound and vibration.
 142  *
 143  * @param[in] type string      The pattern type
 144  * @param[in] pattern string   The pre-defined pattern
 145  *
 146  * @return 0 on success, otherwise a negative error value.
 147  * @retval #FEEDBACK_ERROR_NONE               Successful
 148  * @retval #FEEDBACK_ERROR_INVALID_PARAMETER  Invalid parameter
 149  * @retval #FEEDBACK_ERROR_NOT_SUPPORTED      Not supported device
 150  */
 151 int feedback_play_type_by_name(char *type, char *pattern);
 152
 153 /**
 154  * @brief Stop various types of reactions
 155  * @details
 156  * This functon can be used to stop react to pre-defined actions. \n
 157  * It stops various types of system pre-defined media or vibration patterns.
 158  *
 159  * @since_tizen 2.3
 160  *
 161  * @return 0 on success, otherwise a negative error value.
 162  * @retval #FEEDBACK_ERROR_NONE               Successful
 163  * @retval #FEEDBACK_ERROR_NOT_SUPPORTED      Not supported device
 164  */
 165 int feedback_stop(void);
 166
 167 /**
 168  * @brief Gets the file path of resource for the given feedback type and pattern.
 169  * @details
 170  * Depending on the type of each pattern resouorce has a different format. \n
 171  * Currently, System supports two pattern types. \n
 172  * #FEEDBACK_TYPE_SOUND type uses .wav format. \n
 173  * #FEEDBACK_TYPE_VIBRATION type uses .ivt format. \n
 174  * If the given pattern doesn't have a file for the type, @a path will return NULL.
 175  *
 176  * @since_tizen 2.3
 177  *
 178  * @remarks @a path must be released with free() by you.
 179  *
 180  * @param[in]  type      The pattern type
 181  * @param[in]  pattern   The pre-defined pattern
 182  * @param[out] path      The file path of resource for feedback type and pattern
 183  *
 184  * @return 0 on success, otherwise a negative error value.
 185  * @retval #FEEDBACK_ERROR_NONE               Successful
 186  * @retval #FEEDBACK_ERROR_INVALID_PARAMETER  Invalid parameter
 187  * @retval #FEEDBACK_ERROR_OPERATION_FAILED   Operation failed
 188  * @retval #FEEDBACK_ERROR_NOT_SUPPORTED      Not supported device
 189  */
 190 int feedback_get_resource_path(feedback_type_e type, feedback_pattern_e pattern, char **path);
 191
 192 /**
 193  * @brief Sets the new file path of resource for the given feedback type and pattern.
 194  * @details
 195  * Depending on the type of each pattern resouorce has a different format. \n
 196  * Currently, System supports two pattern types. \n
 197  * #FEEDBACK_TYPE_SOUND type uses .wav format. \n
 198  * #FEEDBACK_TYPE_VIBRATION type uses .ivt format. \n
 199  * If the given pattern doesn't have a file for the type, @a path will return NULL.
 200  *
 201  * @since_tizen 2.3
 202  *
 203  * @param[in]  type      The pattern type
 204  * @param[in]  pattern   The pre-defined pattern
 205  * @param[in]  path      The new file path of resource for feedback type and pattern
 206  *
 207  * @return 0 on success, otherwise a negative error value.
 208  * @retval #FEEDBACK_ERROR_NONE               Successful
 209  * @retval #FEEDBACK_ERROR_INVALID_PARAMETER  Invalid parameter
 210  * @retval #FEEDBACK_ERROR_OPERATION_FAILED   Operation failed
 211  * @retval #FEEDBACK_ERROR_NOT_SUPPORTED      Not supported device
 212  */
 213 int feedback_set_resource_path(feedback_type_e type, feedback_pattern_e pattern, char *path);
 214
 215 /**
 216  * @}
 217  */
 218
 219 #ifdef __cplusplus
 220 }
 221 #endif
 222
 223 #endif //__FEEDBACK_H__