devman_haptic.h

   1 /*
   2  *  devman
   3  *
   4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: DongGi Jang <dg0402.jang@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20 */
  21
  22
  23 #ifndef __DEVMAN_HAPTIC_H__
  24 #define __DEVMAN_HAPTIC_H__
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /**
  31  * @file        devman_haptic.h
  32  * @ingroup     DEVICE_MANAGER
  33  * @brief       This file contains the prototypes of the haptic API
  34  * @author      SLP2.0
  35  * @date        2010-01-24
  36  * @version     0.1
  37  */
  38
  39 /**
  40  * @addtogroup DEVICE_MANAGER
  41  * @{
  42  */
  43
  44
  45 /**
  46  * @par Description:
  47  *      The pattern list for haptic.\n
  48  *      Note: The patterns will be removed except the patterns which are used for BEAT UX after 9. Dec. 2011.
  49  */
  50         enum effectvibe_pattern_list {
  51                 EFFCTVIBE_TOUCH = 0,            /**< for BeatUX */
  52                 EFFCTVIBE_HW_TOUCH,             /**< for BeatUX */
  53                 EFFCTVIBE_NOTIFICATION,         /**< for BeatUX */
  54                 EFFCTVIBE_INCOMING_CALL01,      /**< for BeatUX */
  55                 EFFCTVIBE_INCOMING_CALL02,      /**< for BeatUX */
  56                 EFFCTVIBE_INCOMING_CALL03,      /**< for BeatUX */
  57                 EFFCTVIBE_ALERTS_CALL,          /**< for BeatUX */
  58                 EFFCTVIBE_OPERATION,            /**< for BeatUX */
  59                 EFFCTVIBE_SILENT_MODE,          /**< for BeatUX */
  60
  61                 EFFCTVIBE_PATTERN_END
  62         };
  63
  64 /**
  65  * @par Description:
  66  *      feedback level for haptic.
  67  */
  68         enum haptic_feedback_level {
  69                 HAPTIC_FEEDBACK_LEVEL_AUTO = -1,                /**< auto feedback level */
  70                 HAPTIC_FEEDBACK_LEVEL_1 = 1,                    /**< feedback level 1 */
  71                 HAPTIC_FEEDBACK_LEVEL_2 = 2,                    /**< feedback level 2 */
  72                 HAPTIC_FEEDBACK_LEVEL_3 = 3,                    /**< feedback level 3 */
  73                 HAPTIC_FEEDBACK_LEVEL_4 = 4,                    /**< feedback level 4 */
  74                 HAPTIC_FEEDBACK_LEVEL_5 = 5,                    /**< feedback level 5 */
  75         };
  76
  77 /**
  78  * @par Description:
  79  *      infinite iteration count
  80  */
  81 #define HAPTIC_INFINITE_ITERATION       256
  82
  83 /**
  84  * @par Description:
  85  *      Return Values
  86  */
  87 #define HAPTIC_SUCCESS                  0
  88 #define HAPTIC_NOT_OPENED               -2
  89 #define HAPTIC_FAIL                     -4
  90 #define HAPTIC_NOT_SUPPORTED            -13
  91
  92 /**
  93  * @par Description:
  94  * Motor device index. We support two motors now.
  95  */
  96         typedef enum haptic_dev_idx_t {
  97                 DEV_IDX_0 = 0x01,               /**< 1st motor */
  98                 DEV_IDX_1 = 0x02,               /**< 2nd motor */
  99                 DEV_IDX_ALL = 0x04,             /**< both of them */
 100         } haptic_dev_idx;
 101
 102 /**
 103  * @fn int device_haptic_open(haptic_dev_idx dev_idx, unsigned int mode)
 104  * @par Description:
 105  *      This API opens a Haptic-vibration device. \n
 106  *      On success it returns a dev_handle value. In case of failure it returns a negative value. \n
 107  *      If the device is already open it returns (-1).\n
 108  *      The first in parameter dev_idx should be from a predefined haptic-device-index which is available in the typedef enum haptic_dev_idx.\n
 109  *      The DEV_IDX_0 means first haptic-device-index of target , the DEV_IDX_1 means second haptic-device-index of target \n
 110  *      and the DEV_IDX_ALL means both of them. \n
 111  *      The availability of the dev_idx value is dependent on the real target. Normally, set a DEV_IDX_0 value to the first haptic-device.\n
 112  *      The second in parameter mode is reserved for future so just set a 0 value\n
 113  *      Note: The device_haptic_open() must be called before all other haptic APIs are called. \n
 114  *      The device_haptic_open() should have a matching call to device_haptic_close().\n
 115  *      Applications call the device_haptic_open() only once if possible during application startup and call the device_haptic_close() during application shutdown.
 116  * @param[in] dev_idx set a device index (predefined enum value by haptic_dev_idx)
 117  * @param[in] mode just set a "0" value (not support current , reserved for future)
 118  * @return if it succeed, it return dev_handle value , otherwise negative value return
 119  * @see device_haptic_close()
 120  * @par Example:
 121  * @code
 122  *      ...
 123  *      int ret_val=0;
 124  *      int dev_handle;
 125  *
 126  *      //Open the haptic device
 127  *      dev_handle = device_haptic_open(DEV_IDX_0,0);
 128  *      if(dev_handle < 0)
 129  *              return -1;
 130  *      ...
 131  * @endcode
 132  */
 133
 134         int device_haptic_open(haptic_dev_idx dev_idx, unsigned int mode);
 135
 136 /**
 137  * @fn int device_haptic_close(int dev_handle)
 138  * @par Description:
 139  *      This API closes a Haptic-vibration device. \n
 140  *      On success it returns a zero value. In case of failure it returns a negative value. \n
 141  *      If the device is already closed it returns (-1).  \n
 142  *      The first in parameter dev_handle should be from the return value of device_haptic_open().
 143  * hatic device close
 144  * @param[in] dev_handle set recived  dev_handle value from device_haptic_open()
 145  * @return if it succeed, it return zero value , otherwise negative value return
 146  * @see device_haptic_open()
 147  * @par Example:
 148  * @code
 149  *      ...
 150  *      //Close the device
 151  *      ret_val = device_haptic_close(dev_handle);
 152  *      if(ret_val != 0)
 153  *               return -1
 154  *      ...
 155  * @endcode
 156  */
 157
 158         int device_haptic_close(int dev_handle);
 159
 160 /**
 161  * @fn int device_haptic_play_pattern(int dev_handle, int pattern , int iteration , int feedback_level )
 162  * @par Description:
 163  *      This API plays a predefined rhythmic haptic-vibration pattern. \n
 164  *      The first in parameter dev_handle should be from the return value of device_haptic_open().\n
 165  *      The second in parameter pattern should be from a predefined pattern list which is available in an enumeration (effectvibe_pattern_list).
 166  *      These patterns are rhythmic vibration patterns. \n
 167  *      The third in parameter iteration sets the number of iterations to be played.
 168  *      This should be less than the maximum iteration range set for the device (currently its 255).  \n
 169  *      The fourth in parameter is the vibration feedback intensity level.
 170  *      This level is already predefined by enumeration type value from HAPTIC_FEEDBACK_LEVEL_1 to HAPTIC_FEEDBACK_LEVEL_5.
 171  *      If you want to use the value selected by the user in the Setting application menu, just set -1 value.\n
 172  *      On success it returns a zero value. In case of failure it returns a negative value. \n
 173  *      Note: The actual behavior of the feedback play pattern and the intensity depends on the target hardware.
 174  * @param[in] dev_handle set recived  dev_handle value from device_haptic_open()
 175  * @param[in] pattern set predefined pattern enum value from effectvibe_pattern_list
 176  * @param[in] iteration set iteration count
 177  * @param[in] feedback_level set feed_back level value ( it is dependent on target's hardware )
 178  * @return if it succeed, it return zero value , otherwise negative value return
 179  * @see device_haptic_play_file(), device_haptic_play_monoton(), device_haptic_stop_play()
 180  * @par Example
 181  * @code
 182  *      ...
 183  *      //Play a rhythmic pattern
 184  *      ret_val = device_haptic_play_pattern(dev_handle, EFFCTVIBE_POPUP, HAPTIC_TEST_ITERATION , HAPTIC_FEEDBACK_LEVEL_3);
 185  *      if(ret_val !=0)
 186  *              return -1;
 187  *      ...
 188  * @endcode
 189  */
 190
 191         int device_haptic_play_pattern(int dev_handle, int pattern,
 192                                        int iteration, int feedback_level);
 193
 194 /**
 195  * @fn int device_haptic_play_file(int dev_handle, const char *file_name , int iteration , int feedback_level  )
 196  * @par Description:
 197  *      This API plays a predefined rhythmic haptic-vibration pattern file (only supports .ivt type file, Immersion VibeTonz).\n
 198  *      The first in parameter dev_handle should be from the return value of device_haptic_open().\n
 199  *      The second in parameter file_name sets rhythmic vibration pattern file with path.
 200  *      It only supports *.ivt type pattern file. \n
 201  *      The third in parameter iteration sets the number of iterations to be played.
 202  *      This should be less than the maximum iteration range set for the device (currently its 255).
 203  *      If you want to play indefinitely, use HAPTIC_INFINITE_ITERATION defined value. But it depends on the target hardware.\n
 204  *      The fourth in parameter is the vibration feedback intensity level.
 205  *      This level is already predefined by enumeration type value from HAPTIC _FEEDBACK_LEVEL_1 to HAPTIC _FEEDBACK_LEVEL_5.
 206  *      If you want to use the value selected by the user in the Setting application menu, just set HAPTIC_FEEDBACK_LEVEL_AUTO value.
 207  *      (But the application must have a main loop to use the HAPTIC_FEEDBACK_LEVEL_AUTO value ) \n
 208  *      On success it returns a zero value. In case of failure it returns a negative value. \n
 209  *      Note: The actual behavior of the feedback play pattern and the intensity depends on the target hardware.
 210  * @param[in] dev_handle set recived  dev_handle value from device_haptic_open()
 211  * @param[in] file_name set file name with path
 212  * @param[in] iteration set iteration count
 213  * @param[in] feedback_level set feed_back level value ( it is dependent on target's hardware )
 214  * @return if it succeed, it return zero value , otherwise negative value return
 215  * @see device_haptic_play_pattern(), device_haptic_play_monotone(), device_haptic_stop_play()
 216  * @par Example
 217  * @code
 218  *      ...
 219  *      ret_val = device_haptic_play_file(dev_handle, "test.ivt", HAPTIC_TEST_ITERATION , HAPTIC_FEEDBACK_LEVEL_3);
 220  *      if(ret_val !=0)
 221  *              return -1;
 222  *      ...
 223  * @endcode
 224  */
 225
 226         int device_haptic_play_file(int dev_handle, const char *file_name,
 227                                     int iteration, int feedback_level);
 228
 229 /**
 230  * @fn int device_haptic_play_buffer(int dev_handle, const unsigned char *vibe_buffer, int iteration , int feedback_level  )
 231  * @par Description:
 232  *      This API plays a predefined rhythmic haptic-vibration pattern file (only supports .ivt type file, Immersion VibeTonz).\n
 233  *      The first in parameter dev_handle should be from the return value of device_haptic_open().\n
 234  *      The second in parameter vibe_buffer sets rhythmic vibration pattern buffer.
 235  *      The third in parameter iteration sets the number of iterations to be played.
 236  *      This should be less than the maximum iteration range set for the device (currently its 255).
 237  *      If you want to play indefinitely, use HAPTIC_INFINITE_ITERATION defined value. But it depends on the target hardware.\n
 238  *      The fourth in parameter is the vibration feedback intensity level.
 239  *      This level is already predefined by enumeration type value from HAPTIC _FEEDBACK_LEVEL_1 to HAPTIC _FEEDBACK_LEVEL_5.
 240  *      If you want to use the value selected by the user in the Setting application menu, just set HAPTIC_FEEDBACK_LEVEL_AUTO value.
 241  *      (But the application must have a main loop to use the HAPTIC_FEEDBACK_LEVEL_AUTO value ) \n
 242  *      On success it returns a zero value. In case of failure it returns a negative value. \n
 243  *      Note: The actual behavior of the feedback play pattern and the intensity depends on the target hardware.
 244  * @param[in] dev_handle set recived dev_handle value from device_haptic_open()
 245  * @param[in] buffer set buffer to be played
 246  * @param[in] iteration set iteration count
 247  * @param[in] feedback_level set feed_back level value ( it is dependent on target's hardware )
 248  * @return if it succeed, it return zero value , otherwise negative value return
 249  * @see device_haptic_play_pattern(), device_haptic_play_monotone(), device_haptic_stop_play()
 250  * @par Example
 251  * @code
 252  *      ...
 253  *      ret_val = device_haptic_play_buffer(dev_handle, buffer, HAPTIC_TEST_ITERATION , HAPTIC_FEEDBACK_LEVEL_3);
 254  *      if(ret_val !=0)
 255  *              return -1;
 256  *      ...
 257  * @endcode
 258  */
 259
 260         int device_haptic_play_buffer(int dev_handle, const unsigned char *vibe_buffer,
 261                                     int iteration, int feedback_level);
 262
 263 /**
 264  * @fn int device_haptic_play_monotone(int dev_handle, int duration)
 265  * @par Description:
 266  *      This API plays a monotonous haptic-vibration pattern with a constant intensity. \n
 267  *      In this monotone play, the intensity used is the value that the user has selected in the Setting application menu.\n
 268  *      The first in parameter dev_handle should be from the return value of device_haptic_open().\n
 269  *      The second in parameter duration defines the length of time this vibration should be played.
 270  *      This duration is in milliseconds.  \n
 271  *      On success it returns a zero value. In case of failure it returns a negative value. \n
 272  *      Note: The actual behavior of the feedback played and the intensity depends on the target hardware.
 273  * @param[in] dev_handle set recived  dev_handle value from device_haptic_open()
 274  * @param[in] duration set duration times (ms)
 275  * @return if it succeed, it return zero value, otherwise negative value return
 276  * @see device_haptic_play_pattern(), device_haptic_play_file(), device_haptic_stop_play()
 277  * @par Example
 278  * @code
 279  *      ...
 280  *      //Play a monotone pattern for 1s == 1000ms
 281  *      ret_val = device_haptic_play_monotone(dev_handle, 1000);
 282  *      if(ret_val !=0)
 283  *              return -1;
 284  *      ...
 285  * @endcode
 286  */
 287
 288         int device_haptic_play_monotone(int dev_handle, int duration);
 289
 290 /**
 291  * @fn int device_haptic_play_monotone_with_feedback_level(int dev_handle, int duration, int feedback_level)
 292  * @par Description:
 293  *      This API plays a monotonous haptic-vibration pattern with a given feedback intensity. \n
 294  *      The first in parameter dev_handle should be from the return value of device_haptic_open().\n
 295  *      The second in parameter duration defines the length of time this vibration should be played.
 296  *      This duration is in milliseconds.  \n
 297  *      The fourth in parameter is the vibration feedback intensity level.
 298  *      This level is already predefined by enumeration type value from HAPTIC _FEEDBACK_LEVEL_1 to HAPTIC _FEEDBACK_LEVEL_5.
 299  *      If you want to use the value selected by the user in the Setting application menu, just set HAPTIC_FEEDBACK_LEVEL_AUTO value.
 300  *      (But the application must have a main loop to use the HAPTIC_FEEDBACK_LEVEL_AUTO value ) \n
 301  *      The third in paramater feedback_level defines the strenth of vibration.
 302  *      On success it returns a zero value. In case of failure it returns a negative value. \n
 303  *      Note: The actual behavior of the feedback played and the intensity depends on the target hardware.
 304  * @param[in] dev_handle set recived  dev_handle value from device_haptic_open()
 305  * @param[in] duration set duration times (ms)
 306  * @param[in] feedback_level set feedback level
 307  * @return if it succeed, it return zero value, otherwise negative value return
 308  * @see device_haptic_play_pattern(), device_haptic_play_file(), device_haptic_stop_play()
 309  * @par Example
 310  * @code
 311  *      ...
 312  *      //Play a monotone pattern for 1s == 1000ms
 313  *      ret_val = device_haptic_play_monotone_with_feedback_level(dev_handle, 1000, HAPTIC_FEEDBACK_LEVEL_3);
 314  *      if(ret_val !=0)
 315  *              return -1;
 316  *      ...
 317  * @endcode
 318  */
 319
 320         int device_haptic_play_monotone_with_feedback_level(int dev_handle, int duration, int feedback_level);
 321
 322 /**
 323  * @fn int device_haptic_play_monotone_with_detail_feedback_level(int dev_handle, int duration, int detail_feedback_level)
 324  * @par Description:
 325  *  This API plays a monotonous haptic-vibration pattern with a given feedback intensity. \n
 326  *  The first in parameter dev_handle should be from the return value of device_haptic_open().\n
 327  *  The second in parameter duration defines the length of time this vibration should be played.
 328  *  This duration is in milliseconds.  \n
 329  *  The fourth in parameter is the vibration feedback intensity level.
 330  *  This level is integer type value from 0 to 100.
 331  *  If you want to use the value selected by the user in the Setting application menu, just set 0 value.
 332  *  On success it returns a zero value. In case of failure it returns a negative value. \n
 333  *  Note: The actual behavior of the feedback played and the intensity depends on the target hardware.
 334  * @param[in] dev_handle set recived  dev_handle value from device_haptic_open()
 335  * @param[in] duration set duration times (ms)
 336  * @param[in] detail_feedback_level set feedback level (0 - 100)
 337  * @return if it succeed, it return zero value, otherwise negative value return
 338  * @see device_haptic_play_pattern(), device_haptic_play_file(), device_haptic_stop_play()
 339  * @par Example
 340  * @code
 341  *      ...
 342  *      //Play a monotone pattern for 1s == 1000ms
 343  *      ret_val = device_haptic_play_monotone_with_detail_feedback_level(dev_handle, 1000, 100);
 344  *      if(ret_val !=0)
 345  *              return -1;
 346  *      ...
 347  * @endcode
 348  */
 349
 350         int device_haptic_play_monotone_with_detail_feedback_level(int dev_handle, int duration, int detail_feedback_level);
 351
 352 /**
 353  * @fn int device_haptic_stop_play(int dev_handle)
 354  * @par Description:
 355  *      This API stops the current vibration being played.\n
 356  *      The first in parameter dev_handle should be from the return value of device_haptic_open().\n
 357  *      On success it returns a zero value. In case of failure it returns a negative value.
 358  * @param[in] dev_handle set recived  dev_handle value from device_haptic_open()
 359  * @return if it succeed, it return zero value , otherwise negative value return
 360  * @see device_haptic_play_pattern(), device_haptic_play_file(), device_haptic_play_monotone()
 361  * @par Example
 362  * @code
 363  *      ...
 364  *      //Stop the pattern immediately
 365  *      ret_val = device_haptic_stop_play(dev_handle);
 366  *      if(ret_val !=0)
 367  *              return -1;
 368  *      ...
 369  * @endcode
 370  */
 371
 372         int device_haptic_stop_play(int dev_handle);
 373
 374 /**
 375  * @fn int device_haptic_get_buffer_duration(int dev_handle, const unsigned char* vibe_buffer , int* duration)
 376  * @par Description:
 377  *      This API gets a duration time value from a predefined rhythmic vibration pattern.\n
 378  *      The first in parameter dev_handle should be from the return value of device_haptic_open().\n
 379  *      The second in parameter vibe_buffer sets rhythmic vibration pattern buffer.
 380  *      The application can get a duration time value from the third out parameter duration when this API succeeds.
 381  *      The unit of duration is ms (millisecond) \n
 382  *      On success it returns a zero value. In case of failure it returns a negative value. \n
 383  *      Note: The actual behavior of the feedback played and the intensity depends on the target hardware.
 384  * @param[in] dev_handle set recived dev_handle value from device_haptic_open()
 385  * @param[in] vibe_buffer set vibe pattern buffer to get duration
 386  * @param[out] duration get duration times (ms)
 387  * @return if it succeed, it return zero value , otherwise negative value return
 388  * @see device_haptic_get_file_duration()
 389  */
 390
 391         int device_haptic_get_buffer_duration(int dev_handle, const unsigned char *vibe_buffer,
 392                                                int *duration);
 393
 394 /**
 395  * @fn int device_haptic_get_pattern_duration(int dev_handle, int pattern , int* duration)
 396  * @par Description:
 397  *      This API gets a duration time value from a predefined rhythmic vibration pattern.\n
 398  *      The first in parameter dev_handle should be from the return value of device_haptic_open().\n
 399  *      The second in parameter pattern should be from a predefined pattern list
 400  *      which is available in an enumeration (effectvibe_pattern_list). \n
 401  *      The application can get a duration time value from the third out parameter duration when this API succeeds.
 402  *      The unit of duration is ms (millisecond) \n
 403  *      On success it returns a zero value. In case of failure it returns a negative value. \n
 404  *      Note: The actual behavior of the feedback played and the intensity depends on the target hardware.
 405  * @param[in] dev_handle set recived  dev_handle value from device_haptic_open()
 406  * @param[in] pattern set predefined pattern enum value from <effectvibe_pattern_list>
 407  * @param[out] duration get duration times (ms)
 408  * @return if it succeed, it return zero value , otherwise negative value return
 409  * @see device_haptic_get_file_duration()
 410  */
 411
 412         int device_haptic_get_pattern_duration(int dev_handle, int pattern,
 413                                                int *duration);
 414
 415 /**
 416  * @fn int device_haptic_get_file_duration(int dev_handle, const char *file_name , int* duration)
 417  * @par Description:
 418  *      This API gets a duration time value from a predefined rhythmic vibration pattern file (only supports .ivt type file).\n
 419  *      The first in parameter ?dev_handle? should be from the return value of device_haptic_open().\n
 420  *      The second in parameter ?file_name? sets rhythmic vibration pattern file with path. It only supports *.ivt type pattern file.\n
 421  *      The application can get a duration time value from the third out parameter duration when this API succeeds.
 422  *      The unit of duration is ms (millisecond)\n
 423  *      On success it returns a zero value. In case of failure it returns a negative value. \n
 424  *      Note: The actual behavior of the feedback played and the intensity depends on the target hardware.
 425  * @param[in] dev_handle set recived  dev_handle value from device_haptic_open()
 426  * @param[in] file_name set file name with path
 427  * @param[out] duration get duration times (ms)
 428  * @return if it succeed, it return zero value , otherwise negative value return
 429  * @see device_haptic_get_pattern_duration()
 430  */
 431
 432         int device_haptic_get_file_duration(int dev_handle,
 433                                             const char *file_name,
 434                                             int *duration);
 435
 436 /**
 437  * @fn int device_haptic_get_device_count(void)
 438  * @par Description:
 439  *      This API gets a numer of devices.\n
 440  *      The application can get a number of devices from the return value this API succeeds.
 441  *      On success it returns a number of devices. In case of failure it returns a negative value. \n
 442  * @return if it succeed, it return number of devices, otherwise negative value return
 443  */
 444         int device_haptic_get_device_count(void);
 445
 446 /**
 447  * @}
 448  */
 449
 450 #ifdef __cplusplus
 451 }
 452 #endif
 453 #endif          /* __DEVMAN_HAPTIC_H__ */