1 /* 2 * Copyright (c) 2021-2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup Vibrator 18 * @{ 19 * 20 * @brief Provides a driver for upper-layer vibrator services. 21 * 22 * After obtaining a driver object or agent, a vibrator service starts or stops the vibrator 23 * using the functions provided by the driver object or agent. 24 * 25 * @since 2.2 26 */ 27 28 /** 29 * @file vibrator_if.h 30 * 31 * @brief Declares common APIs in the vibrator module. The APIs can be used to control 32 * the vibrator to perform a one-shot or periodic vibration. 33 * 34 * @since 2.2 35 * @version 1.0 36 */ 37 38 #ifndef VIBRATOR_IF_H 39 #define VIBRATOR_IF_H 40 41 #include <stdint.h> 42 #include "vibrator_type.h" 43 44 #ifdef __cplusplus 45 #if __cplusplus 46 extern "C" { 47 #endif 48 #endif /* __cplusplus */ 49 50 struct VibratorInterface { 51 /** 52 * @brief Controls the vibrator to perform a one-shot vibration that lasts for a given duration. 53 * 54 * One-shot vibration is mutually exclusive with periodic vibration. Before using one-shot vibration, 55 * exit periodic vibration. 56 * 57 * @param duration Indicates the duration that the one-shot vibration lasts, in milliseconds. 58 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 59 * 60 * @since 2.2 61 * @version 1.0 62 */ 63 int32_t (*StartOnce)(uint32_t duration); 64 /** 65 * @brief Controls the vibrator to perform a periodic vibration with the preset effect. 66 * 67 * One-shot vibration is mutually exclusive with periodic vibration. Before using periodic vibration, 68 * exit one-shot vibration. 69 * 70 * @param effectType Indicates the pointer to the preset effect type. It is recommended that the 71 * maximum length be 64 bytes. 72 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 73 * 74 * @since 2.2 75 * @version 1.0 76 */ 77 int32_t (*Start)(const char *effectType); 78 /** 79 * @brief Stops the vibration. 80 * 81 * Before the vibrator starts, it must stop vibrating in any mode. This function can be used during 82 * and after the vibrating process. 83 * 84 * @param mode Indicates the vibration mode, which can be one-shot or periodic. For details, 85 * see {@link VibratorMode}. 86 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 87 * 88 * @since 2.2 89 * @version 1.0 90 */ 91 int32_t (*Stop)(enum VibratorMode mode); 92 /** 93 * @brief Obtains information about all the vibrator that support setting intensity and frequency in the system. 94 * 95 * @param vibratorInfo Indicates the pointer to the vibration effect, For details, see {@link VibratorInfo}. 96 * 97 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 98 * 99 * @since 3.2 100 * @version 1.1 101 */ 102 int32_t (*GetVibratorInfo)(struct VibratorInfo **vibratorInfo); 103 /** 104 * @brief Start the vibrator according to the incoming vibration effect. 105 * 106 * @param duration Indicates the duration that the vibration lasts, in milliseconds. 107 * 108 * @param intensity indicates vibrator intensity in a vibration period. 109 * 110 * @param frequency indicates vibrator frequency in a vibration period. 111 * 112 * @return Returns <b>0</b> if the operation is successful. 113 * @return Returns <b>-1</b> if the vibrationPeriod setting is not supported. 114 * @return Returns <b>-2</b> if the intensity setting is not supported. 115 * @return Returns <b>-3</b> if the frequency setting is not supported. 116 * 117 * @since 3.2 118 * @version 1.1 119 */ 120 int32_t (*EnableVibratorModulation)(uint32_t duration, uint16_t intensity, int16_t frequency); 121 /** 122 * @brief Controls the vibrator to perform a periodic vibration with the custom composite effect. 123 * 124 * @param effect Indicates the pointer to the custom composite effect type. For details, 125 * see {@link CompositeEffect}. 126 * 127 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 128 * 129 * @since 3.2 130 * @version 1.1 131 */ 132 int32_t (*EnableCompositeEffect)(struct CompositeEffect *effect); 133 /** 134 * @brief Obtains the vibration effect information with the specified effect type. 135 * 136 * @param effectType Indicates the pointer to the preset effect type. It is recommended that the 137 * maximum length be 64 bytes. 138 * 139 * @param effectInfo Indicates the pointer to the vibration effect information. For details, 140 * see {@link EffectInfo}. 141 * 142 * @return Returns <b>0</b> if the operation is successful. 143 * @return Returns negative value if the get failed. 144 * 145 * @since 3.2 146 * @version 1.1 147 */ 148 int32_t (*GetEffectInfo)(const char *effectType, struct EffectInfo *effectInfo); 149 /** 150 * @brief Obtains whether the vibrator is currently vibrating. 151 * 152 * @param state Indicates current vibration state of the vibrator. 153 * 154 * @return Returns <b>0</b> if the operation is successful. 155 * @return Returns negative value if the get failed. 156 * 157 * @since 3.2 158 * @version 1.1 159 */ 160 int32_t (*IsVibratorRunning)(bool state); 161 /** 162 * @brief HD vibration data packet delivery. 163 * 164 * @param Indecates the Hd vibration data packet. 165 * 166 * @return Returns <b>0</b> if the operation is successful. 167 * @return Returns negative value if the get failed. 168 * 169 * @since 4.1 170 * @version 1.2 171 */ 172 int32_t (*PlayHapticPattern)(struct HapticPaket *pkg); 173 /** 174 * @brief Obtains the vibration capability of the motor. 175 * 176 * @param Indecates the vibration capability of the motor. 177 * 178 * @return Returns <b>0</b> if the operation is successful. 179 * @return Returns negative value if the get failed. 180 * 181 * @since 4.1 182 * @version 1.2 183 */ 184 int32_t (*GetHapticCapacity)(struct HapticCapacity *hapticCapacity); 185 /** 186 * @brief Obtains the start_up time of the motor. 187 * 188 * @param Indicates the time from command is issued to the time the motor starts. 189 * 190 * @return Returns <b>0</b> if the operation is successful. 191 * @return Returns negative value if the get failed. 192 * 193 * @since 4.1 194 * @version 1.2 195 */ 196 int32_t (*GetHapticStartUpTime)(int32_t mode, int32_t *startUpTime); 197 }; 198 199 /** 200 * @brief Creates a <b>VibratorInterface</b> instance. 201 * 202 * The obtained <b>VibratorInterface</b> instance can be used to control the vibrator to vibrate as configured. 203 * 204 * @return Returns <b>0</b> if the operation is successful. 205 * @return Returns negative value if the get failed. 206 * 207 * @since 2.2 208 * @version 1.0 209 */ 210 const struct VibratorInterface *NewVibratorInterfaceInstance(void); 211 212 /** 213 * @brief Releases this <b>VibratorInterface</b> instance to free up related resources. 214 * 215 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 216 * 217 * @since 2.2 218 * @version 1.0 219 */ 220 int32_t FreeVibratorInterfaceInstance(void); 221 222 #ifdef __cplusplus 223 #if __cplusplus 224 } 225 #endif 226 #endif /* __cplusplus */ 227 228 #endif /* VIBRATOR_IF_H */ 229 /** @} */ 230