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,      /**< vibration level from settings */
  49         HAPTIC_LEVEL_0,         /**< vibration level 0 (silence) */
  50         HAPTIC_LEVEL_1,         /**< vibration level 1 (the lowest) */
  51         HAPTIC_LEVEL_2,         /**< vibration level 2 (low)*/
  52         HAPTIC_LEVEL_3,         /**< vibration level 3 (middle) */
  53         HAPTIC_LEVEL_4,         /**< vibration level 4 (high) */
  54         HAPTIC_LEVEL_5,         /**< 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     haptic_level_e level;       /**< Intensity of the vibration in a iteration */
  81     int time;              /**< Duration of the vibration in a iteration */
  82 } haptic_vibration_iter_s;
  83
  84 /**
  85  * @brief Gets the number of the vibrators.
  86  *
  87  * @remarks The index zero is reserved meaning for all vibrators at a time.
  88  *
  89  * @param[out] vibrator_number A number of vibrators
  90  *
  91  * @return 0 on success, otherwise a negative error value.
  92  * @retval #HAPTIC_ERROR_OPERATION_FAILED   Operation failed
  93  */
  94 int haptic_get_count(int* vibrator_number);
  95
  96 /**
  97  * @brief Initializes haptic API.
  98  *
  99  * @details Internally, it makes a connection to the vibrator.
 100  *
 101  * @remarks If this function is not called in advance, other functions will return #HAPTIC_ERROR_NOT_INITIALIZED.
 102  * @remarks Haptic API must be deinitialized by haptic_deinitialize().
 103  *
 104  * @return 0 on success, otherwise a negative error value.
 105  * @retval #HAPTIC_ERROR_NONE               Successful
 106  * @retval #HAPTIC_ERROR_OPERATION_FAILED   Operation failed
 107  *
 108  * @see haptic_deinitialize()
 109  */
 110 int haptic_initialize(void);
 111
 112 /**
 113  * @brief Deinitializes haptic API.
 114  *
 115  * @details Internally, it disconnects the connection to vibrator.
 116  *
 117  * @return 0 on success, otherwise a negative error value.
 118  * @retval #HAPTIC_ERROR_NONE               Successful
 119  * @retval #HAPTIC_ERROR_OPERATION_FAILED   Operation failed
 120  *
 121  * @see haptic_initialize()
 122  */
 123 int haptic_deinitialize(void);
 124
 125 /**
 126  * @brief Plays a stored rhythmic haptic vibration pattern from a file.
 127  *
 128  * @remarks Both the actual behavior of the vibration pattern and the intensity depend on devices.
 129  *
 130  * @param[in] vibrator_index    The index of the vibrator.\n
 131  *                                                      The index of the first vibrator is 1.\n
 132  *                                                      0 is reserved for every vibrators at once.
 133  * @param[in] file_path The path of a rhythmic vibration pattern file.
 134  *                                              Only .ivt (Immersion VibeTonz) file is supported.
 135  * @param[in] count     The number of iterations to be vibrated. Must be less than the maximum\n
 136  *                                      Iteration range allowed for the device. (currently it's 255)
 137  * @param[in] level     The feedback intensity level (it is dependent on target's hardware).\n
 138  *                                      This level is already predefined by enumeration type value from\n
 139  *                                      #HAPTIC_LEVEL_1 to #HAPTIC_LEVEL_5.\n
 140  *                                      If you want to use the value selected by the user in the Setting application menu,\n
 141  *                                      #HAPTIC_LEVEL_AUTO has to be set. It is required that application\n
 142  *                                      must have a main loop to use the #HAPTIC_LEVEL_AUTO.
 143  *
 144  * @return 0 on success, otherwise a negative error value.
 145  * @retval #HAPTIC_ERROR_NONE                 Success
 146  * @retval #HAPTIC_ERROR_INVALID_PARAMETER    Invalid parameter
 147  * @retval #HAPTIC_ERROR_OPERATION_FAILED     Operation failed
 148  * @retval #HAPTIC_ERROR_NO_SUCH_FILE             No such file
 149  * @retval #HAPTIC_ERROR_NOT_SUPPORTED_FORMAT Not supported file format
 150  *
 151  * @see haptic_stop_device()
 152  * @see haptic_get_count()
 153  */
 154 int haptic_vibrate_file(int vibrator_index, const char *file_path, int count, haptic_level_e level);
 155
 156 /**
 157  * @brief Gets the duration of a rhythmic vibration pattern saved in a given file.
 158  *
 159  * @param[in] vibrator_index    The index of the vibrator.\n
 160  *                                                      The index of the first vibrator is 1.\n
 161  *                                                      0 is reserved for every vibrators at once.
 162  * @param[in] file_path The path of a rhythmic vibration pattern file.
 163  *                                              Only .ivt (Immersion VibeTonz) file is supported.
 164  * @param[out] duration_ms      The duration in milliseconds.
 165  *
 166  * @return 0 on success, otherwise a negative error value.
 167  * @retval #HAPTIC_ERROR_NONE                  Successful
 168  * @retval #HAPTIC_ERROR_INVALID_PARAMETER     Invalid parameter
 169  * @retval #HAPTIC_ERROR_OPERATION_FAILED      Operation failed
 170  * @retval #HAPTIC_ERROR_NO_SUCH_FILE              No such file
 171  * @retval #HAPTIC_ERROR_NOT_SUPPORTED_FORMAT  Not supported file format
 172  *
 173  * @see haptic_get_count()
 174  */
 175 int haptic_get_file_duration(int vibrator_index, const char *file_path, int *duration_ms);
 176
 177 /**
 178  * @brief Vibrates during the specified time with a constant intensity.
 179  * @details
 180  * This function can be used to start monotonous vibration for specified time.\n
 181  * Default value of intensity is used.\n
 182  *
 183  * @param[in] vibrator_index    The index of the vibrator.\n
 184  *                                                      The index of the first vibrator is 1.\n
 185  *                                                      0 is reserved for every vibrators at once.
 186  * @param[in] duration_ms       The play duration in milliseconds
 187  *
 188  * @return 0 on success, otherwise a negative error value.
 189  * @retval #HAPTIC_ERROR_NONE               Successful
 190  * @retval #HAPTIC_ERROR_INVALID_PARAMETER  Invalid parameter
 191  * @retval #HAPTIC_ERROR_OPERATION_FAILED   Operation failed
 192  * @retval #HAPTIC_ERROR_NOT_INITIALIZED    Not initialized
 193  *
 194  * @see haptic_stop_device()
 195  * @see haptic_vibrate_file()
 196  * @see haptic_get_count()
 197  */
 198 int haptic_vibrate_monotone(int vibrator_index, int duration_ms);
 199
 200 /**
 201  * @brief Stops the current vibration which is being played.
 202  * @details This function can be used to stop vibration started by haptic_vibrate_file(), or haptic_vibrate_monotone().
 203  *
 204  * @remarks You must use haptic_stop_pattern() to stop the vibration pattern from haptic_play_pattern();
 205  *
 206  * @param[in] vibrator_index    The index of the vibrator.\n
 207  *                                                      The index of the first vibrator is 1.\n
 208  *                                                      0 is reserved for every vibrators at once.
 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  * @retval #HAPTIC_ERROR_OPERATION_FAILED   Operation failed
 214  * @retval #HAPTIC_ERROR_NOT_INITIALIZED    Not initialized
 215  *
 216  * @see haptic_vibrate_file()
 217  * @see haptic_vibrate_monotone()
 218  * @see haptic_get_count()
 219  */
 220 int haptic_stop_device(int vibrator_index);
 221
 222 /**
 223  * @brief Starts playing the pattern of continuous vibration data.
 224  * @details
 225  * Each vibration data has index of vibrator, intensity level and duration time. \n
 226  * Vibration data plays continuously in order of specific array. \n
 227  * This function returns the ID of playing session if it succeeds.
 228  * This ID can be used to stop playing iterations.
 229  *
 230  * When played intensity in each vibration data can be changed with level_change parameter. \n
 231  * level_change parameter is quantity of intensity variation, it can be minus or plus integer number. \n
 232  * But if vibration intensity level is under #HAPTIC_LEVEL_0, it does not change. \n
 233  * And level can't be under #HAPTIC_LEVEL_0 or over #HAPTIC_LEVEL_5.
 234  *
 235  * For example, \n
 236  * Level(#HAPTIC_LEVEL_1) + level_change(2)   = #HAPTIC_LEVEL_3 \n
 237  * Level(#HAPTIC_LEVEL_2) + level_change(-2)  = #HAPTIC_LEVEL_0 \n
 238  * Level(#HAPTIC_LEVEL_5) + level_change(-10) = #HAPTIC_LEVEL_0 \n
 239  * Level(#HAPTIC_LEVEL_0) + level_change(3)   = #HAPTIC_LEVEL_0 (It does not change) \n
 240  * Level(#HAPTIC_LEVEL_2) + level_change(-3)  = #HAPTIC_LEVEL_0 (It can't be under zero) \n
 241  * Level(#HAPTIC_LEVEL_3) + level_change(10)  = #HAPTIC_LEVEL_5 (It can't be over five) \n
 242  *
 243  *
 244  * @param[in]   pattern         The array of the vibration data
 245  * @param[in]   pattern_size    The number of the vibration data
 246  * @param[in]   count           The number of the Iteration that include playing every vibrations
 247  * @param[in]   level_change    The amount of the intensity variation in each vibrations
 248  * @param[out]  id              The ID of the vibration pattern
 249  *
 250  * @return 0 on success, otherwise a negative error value.
 251  * @retval #HAPTIC_ERROR_NONE               Successful
 252  * @retval #HAPTIC_ERROR_INVALID_PARAMETER  Invalid parameter
 253  * @retval #HAPTIC_ERROR_OPERATION_FAILED   Operation failed
 254  * @retval #HAPTIC_ERROR_NOT_INITIALIZED    Not initialized
 255  *
 256  * @see haptic_stop_pattern()
 257  */
 258 int haptic_play_pattern(haptic_vibration_iter_s* pattern, int pattern_size, int count, int level_change, int* id);
 259
 260 /**
 261  * @brief Stops playing the pattern which is being played.
 262  *
 263  * @remarks haptic_stop_device() can not stop pattern,
 264  * because playing process calls the vibration procedure in each vibration data.
 265  *
 266  * @param[in] id    The ID of playing session from haptic_play_pattern()
 267  *
 268  * @return 0 on success, otherwise a negative error value.
 269  * @retval #HAPTIC_ERROR_NONE               Successful
 270  * @retval #HAPTIC_ERROR_INVALID_PARAMETER  Invalid parameter
 271  *
 272  * @see haptic_play_pattern()
 273  */
 274 int haptic_stop_pattern(int id);
 275 /**
 276  * @}
 277  */
 278
 279 #ifdef __cplusplus
 280 }
 281 #endif
 282
 283 #endif  // __TIZEN_SYSTEM_HAPTIC_H__
 284