include/haptic.h

   1 /*
   2  * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18
  19
  20 #ifndef __TIZEN_SYSTEM_HAPTIC_H__
  21 #define __TIZEN_SYSTEM_HAPTIC_H__
  22
  23 #include <tizen_error.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /**
  30  * @addtogroup CAPI_SYSTEM_HAPTIC_MODULE
  31  * @{
  32  * @brief
  33  * This is a Haptic API of the System Service.
  34  * @}
  35  */
  36
  37 /**
  38  * @addtogroup CAPI_SYSTEM_HAPTIC_MODULE
  39  * @{
  40  */
  41
  42 /**
  43  * @brief Enumerations of feedback level for haptic.
  44  * @details Haptic level means vibration power (intensity).
  45  */
  46 typedef enum
  47 {
  48         HAPTIC_LEVEL_AUTO = -1,     /**< vibration level from settings */
  49         HAPTIC_LEVEL_0 = 0,         /**< vibration level 0 (silence) */
  50         HAPTIC_LEVEL_1 = 20,        /**< vibration level 1 (the lowest) */
  51         HAPTIC_LEVEL_2 = 40,        /**< vibration level 2 (low)*/
  52         HAPTIC_LEVEL_3 = 60,        /**< vibration level 3 (middle) */
  53         HAPTIC_LEVEL_4 = 80,        /**< vibration level 4 (high) */
  54         HAPTIC_LEVEL_5 = 100,       /**< vibration level 5 (the highest) */
  55 } haptic_level_e;
  56
  57 /**
  58  * @brief Enumerations of error codes for the Haptic API.
  59  */
  60 typedef enum
  61 {
  62         HAPTIC_ERROR_NONE                  = TIZEN_ERROR_NONE,                     /**< Successful */
  63         HAPTIC_ERROR_INVALID_PARAMETER     = TIZEN_ERROR_INVALID_PARAMETER,      /**< Invalid parameter */
  64     HAPTIC_ERROR_NO_SUCH_FILE          = TIZEN_ERROR_NO_SUCH_FILE,           /**< No such file */
  65     HAPTIC_ERROR_NOT_SUPPORTED_FORMAT  = TIZEN_ERROR_SYSTEM_CLASS | 0x23,    /**< Not supported file format */
  66     HAPTIC_ERROR_NOT_INITIALIZED       = TIZEN_ERROR_SYSTEM_CLASS | 0x26,    /**< Not initialized */
  67     HAPTIC_ERROR_OPERATION_FAILED      = TIZEN_ERROR_SYSTEM_CLASS | 0x28,    /**< Operation failed  */
  68 } haptic_error_e;
  69
  70
  71 /**
  72  * @brief The structure type to contain the set of vibration data
  73  *        that used for generate a iteration of vibration.
  74  *
  75  * @see haptic_play_pattern()
  76  */
  77 typedef struct
  78 {
  79     int vibrator_index;           /**< Index of the vibrator */
  80     int time;              /**< Duration of the vibration in a iteration */
  81 } haptic_vibration_iter_s;
  82
  83 /**
  84  * @brief Gets the number of the vibrators.
  85  *
  86  * @remarks The index zero is reserved meaning for all vibrators at a time.
  87  *
  88  * @param[out] vibrator_number A number of vibrators
  89  *
  90  * @return 0 on success, otherwise a negative error value.
  91  * @retval #HAPTIC_ERROR_OPERATION_FAILED   Operation failed
  92  */
  93 int haptic_get_count(int* vibrator_number);
  94
  95 /**
  96  * @brief Initializes haptic API.
  97  *
  98  * @details Internally, it makes a connection to the vibrator.
  99  *
 100  * @remarks If this function is not called in advance, other functions will return #HAPTIC_ERROR_NOT_INITIALIZED.
 101  * @remarks Haptic API must be deinitialized by haptic_deinitialize().
 102  *
 103  * @return 0 on success, otherwise a negative error value.
 104  * @retval #HAPTIC_ERROR_NONE               Successful
 105  * @retval #HAPTIC_ERROR_OPERATION_FAILED   Operation failed
 106  *
 107  * @see haptic_deinitialize()
 108  */
 109 int haptic_initialize(void);
 110
 111 /**
 112  * @brief Deinitializes haptic API.
 113  *
 114  * @details Internally, it disconnects the connection to vibrator.
 115  *
 116  * @return 0 on success, otherwise a negative error value.
 117  * @retval #HAPTIC_ERROR_NONE               Successful
 118  * @retval #HAPTIC_ERROR_OPERATION_FAILED   Operation failed
 119  *
 120  * @see haptic_initialize()
 121  */
 122 int haptic_deinitialize(void);
 123
 124 /**
 125  * @brief Vibrates during the specified time with a constant intensity.
 126  * @details
 127  * This function can be used to start monotonous vibration for specified time.\n
 128  * Default value of intensity is used.\n
 129  *
 130  * @remark
 131  * level is intensity variation of vibration. it has a value from 0 to 100.\n
 132  * level -1 is reserved for auto changing to saved variable in the settings.
 133  *
 134  * @param[in] vibrator_index    The index of the vibrator.\n
 135  *                                                      The index of the first vibrator is 1.\n
 136  *                                                      0 is reserved for every vibrators at once.
 137  * @param[in] duration_ms       The play duration in milliseconds
 138  * @param[in] level         The amount of the intensity variation
 139  *
 140  * @return 0 on success, otherwise a negative error value.
 141  * @retval #HAPTIC_ERROR_NONE               Successful
 142  * @retval #HAPTIC_ERROR_INVALID_PARAMETER  Invalid parameter
 143  * @retval #HAPTIC_ERROR_OPERATION_FAILED   Operation failed
 144  * @retval #HAPTIC_ERROR_NOT_INITIALIZED    Not initialized
 145  *
 146  * @see haptic_stop_device()
 147  * @see haptic_vibrate_file()
 148  * @see haptic_get_count()
 149  */
 150 int haptic_vibrate_monotone(int vibrator_index, int duration_ms, int level);
 151
 152 /**
 153  * @brief Stops the current vibration which is being played.
 154  * @details This function can be used to stop vibration started by haptic_vibrate_file(), or haptic_vibrate_monotone().
 155  *
 156  * @remarks You must use haptic_stop_pattern() to stop the vibration pattern from haptic_play_pattern();
 157  *
 158  * @param[in] vibrator_index    The index of the vibrator.\n
 159  *                                                      The index of the first vibrator is 1.\n
 160  *                                                      0 is reserved for every vibrators at once.
 161  *
 162  * @return 0 on success, otherwise a negative error value.
 163  * @retval #HAPTIC_ERROR_NONE               Successful
 164  * @retval #HAPTIC_ERROR_INVALID_PARAMETER  Invalid parameter
 165  * @retval #HAPTIC_ERROR_OPERATION_FAILED   Operation failed
 166  * @retval #HAPTIC_ERROR_NOT_INITIALIZED    Not initialized
 167  *
 168  * @see haptic_vibrate_file()
 169  * @see haptic_vibrate_monotone()
 170  * @see haptic_get_count()
 171  */
 172 int haptic_stop_device(int vibrator_index);
 173
 174 /**
 175  * @brief Starts playing the pattern of continuous vibration data.
 176  * @details
 177  * Each vibration data has index of vibrator and duration time. \n
 178  * Vibration data plays continuously in order of specific array. \n
 179  * This function returns the ID of playing session if it succeeds.
 180  * This ID can be used to stop playing iterations.
 181  *
 182  * @remark
 183  * level is intensity variation of vibration. it has a value from 0 to 100.\n
 184  * level -1 is reserved for auto changing to saved variable in the settings.
 185  *
 186  * @param[in]   pattern         The array of the vibration data
 187  * @param[in]   pattern_size    The number of the vibration data
 188  * @param[in]   count           The number of the Iteration that include playing every vibrations
 189  * @param[in]   level           The amount of the intensity variation in every vibrations
 190  * @param[out]  id              The ID of the vibration pattern
 191  *
 192  * @return 0 on success, otherwise a negative error value.
 193  * @retval #HAPTIC_ERROR_NONE               Successful
 194  * @retval #HAPTIC_ERROR_INVALID_PARAMETER  Invalid parameter
 195  * @retval #HAPTIC_ERROR_OPERATION_FAILED   Operation failed
 196  * @retval #HAPTIC_ERROR_NOT_INITIALIZED    Not initialized
 197  *
 198  * @see haptic_stop_pattern()
 199  */
 200 int haptic_play_pattern(haptic_vibration_iter_s* pattern, int pattern_size, int count, int level, int* id);
 201
 202 /**
 203  * @brief Stops playing the pattern which is being played.
 204  *
 205  * @remarks haptic_stop_device() can not stop pattern,
 206  * because playing process calls the vibration procedure in each vibration data.
 207  *
 208  * @param[in] id    The ID of playing session from haptic_play_pattern()
 209  *
 210  * @return 0 on success, otherwise a negative error value.
 211  * @retval #HAPTIC_ERROR_NONE               Successful
 212  * @retval #HAPTIC_ERROR_INVALID_PARAMETER  Invalid parameter
 213  *
 214  * @see haptic_play_pattern()
 215  */
 216 int haptic_stop_pattern(int id);
 217 /**
 218  * @}
 219  */
 220
 221 #ifdef __cplusplus
 222 }
 223 #endif
 224
 225 #endif  // __TIZEN_SYSTEM_HAPTIC_H__
 226