include/haptic.h

   1 /*
   2  * Copyright (c) 2014 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 #ifndef __TIZEN_SYSTEM_HAPTIC_H__
  19 #define __TIZEN_SYSTEM_HAPTIC_H__
  20
  21
  22 #include "device-error.h"
  23
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29
  30 /**
  31  * @addtogroup CAPI_SYSTEM_DEVICE_HAPTIC_MODULE
  32  * @{
  33  */
  34
  35
  36 /**
  37  * @brief The haptic device handle.
  38  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  39  */
  40 typedef void* haptic_device_h;
  41
  42
  43 /**
  44  * @brief The haptic effect handle.
  45  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  46  */
  47 typedef void* haptic_effect_h;
  48
  49
  50 /**
  51  * @brief Gets the number of vibrators.
  52  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  53  * @privlevel public
  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
  63  */
  64 int device_haptic_get_count(int *device_number);
  65
  66
  67 /**
  68  * @brief Opens a haptic-vibration device.
  69  * @details Internally, it makes a connection to the vibrator.
  70  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  71  * @privlevel public
  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()
  85  */
  86 int device_haptic_open(int device_index, haptic_device_h *device_handle);
  87
  88
  89 /**
  90  * @brief Closes a haptic-vibration device.
  91  * @details Internally, it disconnects the connection to the vibrator.
  92  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  93  * @privlevel public
  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()
 104  */
 105 int device_haptic_close(haptic_device_h device_handle);
 106
 107
 108 /**
 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.
 111  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 112  * @privlevel public
 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()
 129  */
 130 int device_haptic_vibrate(haptic_device_h device_handle, int duration, int feedback, haptic_effect_h *effect_handle);
 131
 132
 133 /**
 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().
 136  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 137  * @privlevel public
 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()
 149  */
 150 int device_haptic_stop(haptic_device_h device_handle, haptic_effect_h effect_handle);
 151
 152
 153 /**
 154  * @}
 155  */
 156
 157
 158 #ifdef __cplusplus
 159 }
 160 #endif
 161
 162
 163 #endif  // __TIZEN_SYSTEM_HAPTIC_H__