2 * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 #ifndef __TIZEN_SYSTEM_HAPTIC_H__
19 #define __TIZEN_SYSTEM_HAPTIC_H__
22 #include "device-error.h"
31 * @addtogroup CAPI_SYSTEM_DEVICE_HAPTIC_MODULE
37 * @brief The haptic device handle.
40 typedef void* haptic_device_h;
44 * @brief The haptic effect handle.
47 typedef void* haptic_effect_h;
51 * @brief Gets the number of vibrators.
54 * @privilege %http://tizen.org/privilege/haptic
55 * @param[in] device_number The number of vibrators
56 * @return @c 0 on success,
57 * otherwise a negative error value
58 * @retval #DEVICE_ERROR_NONE Successful
59 * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
60 * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
61 * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
62 * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
64 int device_haptic_get_count(int *device_number);
68 * @brief Opens a haptic-vibration device.
69 * @details Internally, it makes a connection to the vibrator.
72 * @privilege %http://tizen.org/privilege/haptic
73 * @remarks You must close the Haptic API using device_haptic_close().
74 * @param[in] device_index The index of device what you want to vibrate \n
75 * The index starts from @c 0
76 * @param[out] device_handle The handle of vibrator
77 * @return @c 0 on success,
78 * otherwise a negative error value
79 * @retval #DEVICE_ERROR_NONE Successful
80 * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
81 * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
82 * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
83 * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
84 * @see device_haptic_close()
86 int device_haptic_open(int device_index, haptic_device_h *device_handle);
90 * @brief Closes a haptic-vibration device.
91 * @details Internally, it disconnects the connection to the vibrator.
94 * @privilege %http://tizen.org/privilege/haptic
95 * @param[in] device_handle The device handle from device_haptic_open()
96 * @return @c 0 on success,
97 * otherwise a negative error value
98 * @retval #DEVICE_ERROR_NONE Successful
99 * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
100 * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
101 * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
102 * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
103 * @see device_haptic_open()
105 int device_haptic_close(haptic_device_h device_handle);
109 * @brief Vibrates during the specified time with a constant intensity.
110 * @details This function can be used to start monotonous vibration for the specified time.
113 * @privilege %http://tizen.org/privilege/haptic
114 * @remarks @a feedback level is reserved for auto changing to save variable in the settings.
115 * @remarks @a effect_handle effect_handle value can be @c 0(zero).
116 * @remarks To prevent unexpected sleep (suspend) during vibration, please use @ref CAPI_SYSTEM_DEVICE_POWER_MODULE.
117 * @param[in] device_handle The device handle from device_haptic_open()
118 * @param[in] duration The play duration in milliseconds
119 * @param[in] feedback The amount of the intensity variation (@c 0 ~ @c 100)
120 * @param[out] effect_handle The pointer to the variable that will receive a handle to the playing effect
121 * @return @c 0 on success,
122 * otherwise a negative error value
123 * @retval #DEVICE_ERROR_NONE Successful
124 * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
125 * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
126 * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
127 * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
128 * @see device_haptic_stop()
130 int device_haptic_vibrate(haptic_device_h device_handle, int duration, int feedback, haptic_effect_h *effect_handle);
134 * @brief Stops all vibration effects which are being played.
135 * @details This function can be used to stop all effects started by device_haptic_vibrate().
138 * @privilege %http://tizen.org/privilege/haptic
139 * @param[in] device_handle The device handle from device_haptic_open()
140 * @param[in] effect_handle The effect handle from device_haptic_vibrate()
141 * @return @c 0 on success,
142 * otherwise a negative error value
143 * @retval #DEVICE_ERROR_NONE Successful
144 * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
145 * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
146 * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
147 * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
148 * @see device_haptic_vibrate()
150 int device_haptic_stop(haptic_device_h device_handle, haptic_effect_h effect_handle);
163 #endif // __TIZEN_SYSTEM_HAPTIC_H__