4 * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
6 * Contact: DongGi Jang <dg0402.jang@samsung.com>
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
12 * http://www.apache.org/licenses/LICENSE-2.0
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.
23 #ifndef __DEVMAN_HAPTIC_H__
24 #define __DEVMAN_HAPTIC_H__
31 * @file devman_haptic.h
32 * @ingroup DEVICE_MANAGER
33 * @brief This file contains the prototypes of the haptic API
40 * @addtogroup DEVICE_MANAGER
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.
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 */
66 * priority level for haptic.
68 enum haptic_priority_level {
69 HAPTIC_PRIORITY_LEVEL_MIN = 0, /**< Minimum effect priority for developers */
70 HAPTIC_PRIORITY_LEVEL_MAX_DEV, /**< Maximum effect priority for developers */
71 HAPTIC_PRIORITY_LEVEL_MAX_OEM, /**< Maximum effect priority for OEMs */
76 * feedback level for haptic.
78 enum haptic_feedback_level {
79 HAPTIC_FEEDBACK_LEVEL_AUTO = -1, /**< auto feedback level */
80 HAPTIC_FEEDBACK_LEVEL_0, /**< feedback level 0 */
81 HAPTIC_FEEDBACK_LEVEL_1, /**< feedback level 1 */
82 HAPTIC_FEEDBACK_LEVEL_2, /**< feedback level 2 */
83 HAPTIC_FEEDBACK_LEVEL_3, /**< feedback level 3 */
84 HAPTIC_FEEDBACK_LEVEL_4, /**< feedback level 4 */
85 HAPTIC_FEEDBACK_LEVEL_5, /**< feedback level 5 */
87 HAPTIC_FEEDBACK_LEVEL_END,
92 * infinite iteration count
94 #define HAPTIC_INFINITE_ITERATION 256
100 #define HAPTIC_SUCCESS 0
101 #define HAPTIC_ALREADY_INITIALIZED -1
102 #define HAPTIC_NOT_OPENED -2
103 #define HAPTIC_INVALID_ARGUMENT -3
104 #define HAPTIC_FAIL -4
105 #define HAPTIC_NOT_SUPPORTED -13
106 #define HAPTIC_ALREADY_EXIST -14
110 * Motor device index. We support two motors now.
112 typedef enum haptic_dev_idx_t {
113 DEV_IDX_0 = 0x01, /**< 1st motor */
114 DEV_IDX_1 = 0x02, /**< 2nd motor */
115 DEV_IDX_ALL = 0x04, /**< both of them */
119 * @fn int device_haptic_open(haptic_dev_idx dev_idx, unsigned int mode)
121 * This API opens a Haptic-vibration device. \n
122 * On success it returns a dev_handle value. In case of failure it returns a negative value. \n
123 * If the device is already open it returns (-1).\n
124 * 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
125 * The DEV_IDX_0 means first haptic-device-index of target , the DEV_IDX_1 means second haptic-device-index of target \n
126 * and the DEV_IDX_ALL means both of them. \n
127 * 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
128 * The second in parameter mode is reserved for future so just set a 0 value\n
129 * Note: The device_haptic_open() must be called before all other haptic APIs are called. \n
130 * The device_haptic_open() should have a matching call to device_haptic_close().\n
131 * Applications call the device_haptic_open() only once if possible during application startup and call the device_haptic_close() during application shutdown.
132 * @param[in] dev_idx set a device index (predefined enum value by haptic_dev_idx)
133 * @param[in] mode just set a "0" value (not support current , reserved for future)
134 * @return if it succeed, it return dev_handle value , otherwise negative value return
135 * @see device_haptic_close()
142 * //Open the haptic device
143 * dev_handle = device_haptic_open(DEV_IDX_0,0);
150 int device_haptic_open(haptic_dev_idx dev_idx, unsigned int mode);
153 * @fn int device_haptic_close(int dev_handle)
155 * This API closes a Haptic-vibration device. \n
156 * On success it returns a zero value. In case of failure it returns a negative value. \n
157 * If the device is already closed it returns (-1). \n
158 * The first in parameter dev_handle should be from the return value of device_haptic_open().
160 * @param[in] dev_handle set recived dev_handle value from device_haptic_open()
161 * @return if it succeed, it return zero value , otherwise negative value return
162 * @see device_haptic_open()
167 * ret_val = device_haptic_close(dev_handle);
174 int device_haptic_close(int dev_handle);
177 * @fn int device_haptic_play_pattern(int dev_handle, int pattern , int iteration , int feedback_level )
179 * This API plays a predefined rhythmic haptic-vibration pattern. \n
180 * The first in parameter dev_handle should be from the return value of device_haptic_open().\n
181 * The second in parameter pattern should be from a predefined pattern list which is available in an enumeration (effectvibe_pattern_list).
182 * These patterns are rhythmic vibration patterns. \n
183 * The third in parameter iteration sets the number of iterations to be played.
184 * This should be less than the maximum iteration range set for the device (currently its 255). \n
185 * The fourth in parameter is the vibration feedback intensity level.
186 * This level is already predefined by enumeration type value from HAPTIC_FEEDBACK_LEVEL_1 to HAPTIC_FEEDBACK_LEVEL_5.
187 * If you want to use the value selected by the user in the Setting application menu, just set -1 value.\n
188 * On success it returns a zero value. In case of failure it returns a negative value. \n
189 * Note: The actual behavior of the feedback play pattern and the intensity depends on the target hardware.
190 * @param[in] dev_handle set recived dev_handle value from device_haptic_open()
191 * @param[in] pattern set predefined pattern enum value from effectvibe_pattern_list
192 * @param[in] iteration set iteration count
193 * @param[in] feedback_level set feed_back level value ( it is dependent on target's hardware )
194 * @return if it succeed, it return zero value , otherwise negative value return
195 * @see device_haptic_play_file(), device_haptic_play_monoton(), device_haptic_stop_play()
199 * //Play a rhythmic pattern
200 * ret_val = device_haptic_play_pattern(dev_handle, EFFCTVIBE_POPUP, HAPTIC_TEST_ITERATION , HAPTIC_FEEDBACK_LEVEL_3);
207 int device_haptic_play_pattern(int dev_handle, int pattern,
208 int iteration, int feedback_level);
211 * @fn int device_haptic_play_file(int dev_handle, const char *file_name , int iteration , int feedback_level )
213 * This API plays a predefined rhythmic haptic-vibration pattern file (only supports .ivt type file, Immersion VibeTonz).\n
214 * The first in parameter dev_handle should be from the return value of device_haptic_open().\n
215 * The second in parameter file_name sets rhythmic vibration pattern file with path.
216 * It only supports *.ivt type pattern file. \n
217 * The third in parameter iteration sets the number of iterations to be played.
218 * This should be less than the maximum iteration range set for the device (currently its 255).
219 * If you want to play indefinitely, use HAPTIC_INFINITE_ITERATION defined value. But it depends on the target hardware.\n
220 * The fourth in parameter is the vibration feedback intensity level.
221 * This level is already predefined by enumeration type value from HAPTIC _FEEDBACK_LEVEL_1 to HAPTIC _FEEDBACK_LEVEL_5.
222 * If you want to use the value selected by the user in the Setting application menu, just set HAPTIC_FEEDBACK_LEVEL_AUTO value.
223 * (But the application must have a main loop to use the HAPTIC_FEEDBACK_LEVEL_AUTO value ) \n
224 * On success it returns a zero value. In case of failure it returns a negative value. \n
225 * Note: The actual behavior of the feedback play pattern and the intensity depends on the target hardware.
226 * @param[in] dev_handle set recived dev_handle value from device_haptic_open()
227 * @param[in] file_name set file name with path
228 * @param[in] iteration set iteration count
229 * @param[in] feedback_level set feed_back level value ( it is dependent on target's hardware )
230 * @return if it succeed, it return zero value , otherwise negative value return
231 * @see device_haptic_play_pattern(), device_haptic_play_monotone(), device_haptic_stop_play()
235 * ret_val = device_haptic_play_file(dev_handle, "test.ivt", HAPTIC_TEST_ITERATION , HAPTIC_FEEDBACK_LEVEL_3);
242 int device_haptic_play_file(int dev_handle, const char *file_name,
243 int iteration, int feedback_level);
246 * @fn int device_haptic_play_file_with_priority(int device_handle, const char *file_name, int priority_level, int iteration, int feedback_level)
248 * This API plays a predefined rhythmic haptic-vibration pattern file with priority(only supports .ivt type file, Immersion VibeTonz).\n
249 * The first in parameter dev_handle should be from the return value of device_haptic_open().\n
250 * The second in parameter file_name sets rhythmic vibration pattern file with path.
251 * It only supports *.ivt type pattern file. \n
252 * The third in parameter prioritizes between the different effect. \n
253 * This level is already predefined by enumeration type value from hantpic_priority_level.
254 * This value must be between HAPTIC_PRIORITY_LEVEL_MIN and HAPTIC_PRIORITY_LEVEL_MAX_OEM.
255 * The fourth in parameter iteration sets the number of iterations to be played.
256 * This should be less than the maximum iteration range set for the device (currently its 255).
257 * If you want to play indefinitely, use HAPTIC_INFINITE_ITERATION defined value. But it depends on the target hardware.\n
258 * The fifth in parameter is the vibration feedback intensity level.
259 * This level is already predefined by enumeration type value from HAPTIC _FEEDBACK_LEVEL_1 to HAPTIC _FEEDBACK_LEVEL_5.
260 * If you want to use the value selected by the user in the Setting application menu, just set HAPTIC_FEEDBACK_LEVEL_AUTO value.
261 * (But the application must have a main loop to use the HAPTIC_FEEDBACK_LEVEL_AUTO value ) \n
262 * On success it returns a zero value. In case of failure it returns a negative value. \n
263 * Note: The actual behavior of the feedback play pattern and the intensity depends on the target hardware.
264 * @param[in] dev_handle set received dev_handle value from device_haptic_open()
265 * @param[in] file_name set file name with path
266 * @param[in] priority_level set priority value
267 * @param[in] iteration set iteration count
268 * @param[in] feedback_level set feed_back level value ( it is dependent on target's hardware )
269 * @return if it succeed, it return zero value , otherwise negative value return
270 * @see device_haptic_play_file(), device_haptic_play_monotone(), device_haptic_stop_play()
274 * ret_val = device_haptic_play_file_with_priority(dev_handle, "test.ivt", HAPTIC_PRIORITY_LEVEL_MAX_DEV, HAPTIC_TEST_ITERATION , HAPTIC_FEEDBACK_LEVEL_3);
281 int device_haptic_play_file_with_priority(int device_handle, const char *file_name,
282 int priority, int iteration, int feedback_level);
285 * @fn int device_haptic_play_buffer(int dev_handle, const unsigned char *vibe_buffer, int iteration , int feedback_level )
287 * This API plays a predefined rhythmic haptic-vibration pattern file (only supports .ivt type file, Immersion VibeTonz).\n
288 * The first in parameter dev_handle should be from the return value of device_haptic_open().\n
289 * The second in parameter vibe_buffer sets rhythmic vibration pattern buffer.
290 * The third in parameter iteration sets the number of iterations to be played.
291 * This should be less than the maximum iteration range set for the device (currently its 255).
292 * If you want to play indefinitely, use HAPTIC_INFINITE_ITERATION defined value. But it depends on the target hardware.\n
293 * The fourth in parameter is the vibration feedback intensity level.
294 * This level is already predefined by enumeration type value from HAPTIC _FEEDBACK_LEVEL_1 to HAPTIC _FEEDBACK_LEVEL_5.
295 * If you want to use the value selected by the user in the Setting application menu, just set HAPTIC_FEEDBACK_LEVEL_AUTO value.
296 * (But the application must have a main loop to use the HAPTIC_FEEDBACK_LEVEL_AUTO value ) \n
297 * On success it returns a zero value. In case of failure it returns a negative value. \n
298 * Note: The actual behavior of the feedback play pattern and the intensity depends on the target hardware.
299 * @param[in] dev_handle set recived dev_handle value from device_haptic_open()
300 * @param[in] buffer set buffer to be played
301 * @param[in] iteration set iteration count
302 * @param[in] feedback_level set feed_back level value ( it is dependent on target's hardware )
303 * @return if it succeed, it return zero value , otherwise negative value return
304 * @see device_haptic_play_pattern(), device_haptic_play_monotone(), device_haptic_stop_play()
308 * ret_val = device_haptic_play_buffer(dev_handle, buffer, HAPTIC_TEST_ITERATION , HAPTIC_FEEDBACK_LEVEL_3);
315 int device_haptic_play_buffer(int dev_handle, const unsigned char *vibe_buffer,
316 int iteration, int feedback_level);
319 * @fn int device_haptic_play_monotone(int dev_handle, int duration)
321 * This API plays a monotonous haptic-vibration pattern with a constant intensity. \n
322 * In this monotone play, the intensity used is the value that the user has selected in the Setting application menu.\n
323 * The first in parameter dev_handle should be from the return value of device_haptic_open().\n
324 * The second in parameter duration defines the length of time this vibration should be played.
325 * This duration is in milliseconds. \n
326 * On success it returns a zero value. In case of failure it returns a negative value. \n
327 * Note: The actual behavior of the feedback played and the intensity depends on the target hardware.
328 * @param[in] dev_handle set recived dev_handle value from device_haptic_open()
329 * @param[in] duration set duration times (ms)
330 * @return if it succeed, it return zero value, otherwise negative value return
331 * @see device_haptic_play_pattern(), device_haptic_play_file(), device_haptic_stop_play()
335 * //Play a monotone pattern for 1s == 1000ms
336 * ret_val = device_haptic_play_monotone(dev_handle, 1000);
343 int device_haptic_play_monotone(int dev_handle, int duration);
346 * @fn int device_haptic_play_monotone_with_feedback_level(int dev_handle, int duration, int feedback_level)
348 * This API plays a monotonous haptic-vibration pattern with a given feedback intensity. \n
349 * The first in parameter dev_handle should be from the return value of device_haptic_open().\n
350 * The second in parameter duration defines the length of time this vibration should be played.
351 * This duration is in milliseconds. \n
352 * The fourth in parameter is the vibration feedback intensity level.
353 * This level is already predefined by enumeration type value from HAPTIC _FEEDBACK_LEVEL_1 to HAPTIC _FEEDBACK_LEVEL_5.
354 * If you want to use the value selected by the user in the Setting application menu, just set HAPTIC_FEEDBACK_LEVEL_AUTO value.
355 * (But the application must have a main loop to use the HAPTIC_FEEDBACK_LEVEL_AUTO value ) \n
356 * The third in paramater feedback_level defines the strenth of vibration.
357 * On success it returns a zero value. In case of failure it returns a negative value. \n
358 * Note: The actual behavior of the feedback played and the intensity depends on the target hardware.
359 * @param[in] dev_handle set recived dev_handle value from device_haptic_open()
360 * @param[in] duration set duration times (ms)
361 * @param[in] feedback_level set feedback level
362 * @return if it succeed, it return zero value, otherwise negative value return
363 * @see device_haptic_play_pattern(), device_haptic_play_file(), device_haptic_stop_play()
367 * //Play a monotone pattern for 1s == 1000ms
368 * ret_val = device_haptic_play_monotone_with_feedback_level(dev_handle, 1000, HAPTIC_FEEDBACK_LEVEL_3);
375 int device_haptic_play_monotone_with_feedback_level(int dev_handle, int duration, int feedback_level);
378 * @fn int device_haptic_play_monotone_with_detail_feedback_level(int dev_handle, int duration, int detail_feedback_level)
380 * This API plays a monotonous haptic-vibration pattern with a given feedback intensity. \n
381 * The first in parameter dev_handle should be from the return value of device_haptic_open().\n
382 * The second in parameter duration defines the length of time this vibration should be played.
383 * This duration is in milliseconds. \n
384 * The fourth in parameter is the vibration feedback intensity level.
385 * This level is integer type value from 0 to 100.
386 * If you want to use the value selected by the user in the Setting application menu, just set 0 value.
387 * On success it returns a zero value. In case of failure it returns a negative value. \n
388 * Note: The actual behavior of the feedback played and the intensity depends on the target hardware.
389 * @param[in] dev_handle set recived dev_handle value from device_haptic_open()
390 * @param[in] duration set duration times (ms)
391 * @param[in] detail_feedback_level set feedback level (0 - 100)
392 * @return if it succeed, it return zero value, otherwise negative value return
393 * @see device_haptic_play_pattern(), device_haptic_play_file(), device_haptic_stop_play()
397 * //Play a monotone pattern for 1s == 1000ms
398 * ret_val = device_haptic_play_monotone_with_detail_feedback_level(dev_handle, 1000, 100);
405 int device_haptic_play_monotone_with_detail_feedback_level(int dev_handle, int duration, int detail_feedback_level);
408 * @fn int device_haptic_stop_play(int dev_handle)
410 * This API stops the current vibration being played.\n
411 * The first in parameter dev_handle should be from the return value of device_haptic_open().\n
412 * On success it returns a zero value. In case of failure it returns a negative value.
413 * @param[in] dev_handle set recived dev_handle value from device_haptic_open()
414 * @return if it succeed, it return zero value , otherwise negative value return
415 * @see device_haptic_play_pattern(), device_haptic_play_file(), device_haptic_play_monotone()
419 * //Stop the pattern immediately
420 * ret_val = device_haptic_stop_play(dev_handle);
427 int device_haptic_stop_play(int dev_handle);
430 * @fn int device_haptic_get_buffer_duration(int dev_handle, const unsigned char* vibe_buffer , int* duration)
432 * This API gets a duration time value from a predefined rhythmic vibration pattern.\n
433 * The first in parameter dev_handle should be from the return value of device_haptic_open().\n
434 * The second in parameter vibe_buffer sets rhythmic vibration pattern buffer.
435 * The application can get a duration time value from the third out parameter duration when this API succeeds.
436 * The unit of duration is ms (millisecond) \n
437 * On success it returns a zero value. In case of failure it returns a negative value. \n
438 * Note: The actual behavior of the feedback played and the intensity depends on the target hardware.
439 * @param[in] dev_handle set recived dev_handle value from device_haptic_open()
440 * @param[in] vibe_buffer set vibe pattern buffer to get duration
441 * @param[out] duration get duration times (ms)
442 * @return if it succeed, it return zero value , otherwise negative value return
443 * @see device_haptic_get_file_duration()
446 int device_haptic_get_buffer_duration(int dev_handle, const unsigned char *vibe_buffer,
450 * @fn int device_haptic_get_pattern_duration(int dev_handle, int pattern , int* duration)
452 * This API gets a duration time value from a predefined rhythmic vibration pattern.\n
453 * The first in parameter dev_handle should be from the return value of device_haptic_open().\n
454 * The second in parameter pattern should be from a predefined pattern list
455 * which is available in an enumeration (effectvibe_pattern_list). \n
456 * The application can get a duration time value from the third out parameter duration when this API succeeds.
457 * The unit of duration is ms (millisecond) \n
458 * On success it returns a zero value. In case of failure it returns a negative value. \n
459 * Note: The actual behavior of the feedback played and the intensity depends on the target hardware.
460 * @param[in] dev_handle set recived dev_handle value from device_haptic_open()
461 * @param[in] pattern set predefined pattern enum value from <effectvibe_pattern_list>
462 * @param[out] duration get duration times (ms)
463 * @return if it succeed, it return zero value , otherwise negative value return
464 * @see device_haptic_get_file_duration()
467 int device_haptic_get_pattern_duration(int dev_handle, int pattern,
471 * @fn int device_haptic_get_file_duration(int dev_handle, const char *file_name , int* duration)
473 * This API gets a duration time value from a predefined rhythmic vibration pattern file (only supports .ivt type file).\n
474 * The first in parameter ?dev_handle? should be from the return value of device_haptic_open().\n
475 * The second in parameter ?file_name? sets rhythmic vibration pattern file with path. It only supports *.ivt type pattern file.\n
476 * The application can get a duration time value from the third out parameter duration when this API succeeds.
477 * The unit of duration is ms (millisecond)\n
478 * On success it returns a zero value. In case of failure it returns a negative value. \n
479 * Note: The actual behavior of the feedback played and the intensity depends on the target hardware.
480 * @param[in] dev_handle set recived dev_handle value from device_haptic_open()
481 * @param[in] file_name set file name with path
482 * @param[out] duration get duration times (ms)
483 * @return if it succeed, it return zero value , otherwise negative value return
484 * @see device_haptic_get_pattern_duration()
487 int device_haptic_get_file_duration(int dev_handle,
488 const char *file_name,
492 * @fn int device_haptic_get_device_count(void)
494 * This API gets a numer of devices.\n
495 * The application can get a number of devices from the return value this API succeeds.
496 * On success it returns a number of devices. In case of failure it returns a negative value. \n
497 * @return if it succeed, it return number of devices, otherwise negative value return
499 int device_haptic_get_device_count(void);
502 * @fn int device_haptic_convert_to_binary(const char *haptic_name)
504 * This API convert ivt file to binary file.\n
505 * If the haptic file is not located predefined position, this api can't work and returns a negative value.\n
506 * And also binary file is located predefined position and name according to rules.\n
507 * The first in parameter sets source file name which should be ".ivt" file.\n
508 * On success it returns 0. In case of failure it returns a negative value.\n
509 * @return if it succeed, it return 0, otherwise negative value return
511 int device_haptic_convert_to_binary(const char *haptic_name);
520 #endif /* __DEVMAN_HAPTIC_H__ */