1/* 2 * Copyright (c) 2025 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 get vibrator ability or 23 * set the vibrator effect using the functions provided by the driver object or agent. 24 * 25 * @since 5.1 26 * @version 2.0 27 */ 28 29/** 30 * @file IVibratorInterface.idl 31 * 32 * @brief Declares common APIs in the vibrator module. The APIs canObtains information about all the vibrator 33 * that support setting intensity and Start the vibrator according to the incoming vibration effect. 34 * 35 * @since 5.1 36 * @version 2.0 37 */ 38 39package ohos.hdi.vibrator.v2_0; 40 41import ohos.hdi.vibrator.v2_0.VibratorTypes; 42import ohos.hdi.vibrator.v2_0.IVibratorPlugCallback; 43 44interface IVibratorInterface { 45 /** 46 * @brief Controls the vibrator to perform a one-shot vibration that lasts for a given duration. 47 * 48 * One-shot vibration is mutually exclusive with periodic vibration. Before using one-shot vibration, 49 * exit periodic vibration. 50 * 51 * @param duration Indicates the duration that the one-shot vibration lasts, in milliseconds. 52 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 53 * 54 * @since 2.2 55 * @version 1.0 56 */ 57 StartOnce([in] DeviceVibratorInfo deviceVibratorInfo, [in] unsigned int duration); 58 59 /** 60 * @brief Controls the vibrator to perform a periodic vibration with the preset effect. 61 * 62 * One-shot vibration is mutually exclusive with periodic vibration. Before using periodic vibration, 63 * exit one-shot vibration. 64 * 65 * @param effectType Indicates the pointer to the preset effect type. It is recommended that the 66 * maximum length be 64 bytes. 67 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 68 * 69 * @since 2.2 70 * @version 1.0 71 */ 72 Start([in] DeviceVibratorInfo deviceVibratorInfo, [in] String effectType); 73 74 /** 75 * @brief Stops the vibration. 76 * 77 * Before the vibrator starts, it must stop vibrating in any mode. This function can be used during 78 * and after the vibrating process. 79 * 80 * @param mode Indicates the vibration mode, which can be one-shot or periodic. For details, 81 * see {@link HdfVibratorMode}. 82 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 83 * 84 * @since 2.2 85 * @version 1.0 86 */ 87 Stop([in] DeviceVibratorInfo deviceVibratorInfo, [in] enum HdfVibratorMode mode); 88 89 /** 90 * @brief Obtains information about all the vibrator that support setting intensity and frequency in the system. 91 * 92 * @param vibratorInfo Indicates the pointer to the vibration effect, For details, see {@link HdfVibratorInfo}. 93 * 94 * @return Returns <b>0</b> if the operation is successful. 95 * @return Returns negative value if the get failed. 96 * 97 * @since 3.2 98 * @version 1.1 99 */ 100 GetVibratorInfo([out] struct HdfVibratorInfo[] vibratorInfo); 101 102 /** 103 * @brief Obtains information about all the vibrator that support setting intensity and frequency in the system. 104 * 105 * @param vibratorInfo Indicates the pointer to the vibration effect, For details, see {@link HdfVibratorInfo}. 106 * 107 * @return Returns <b>0</b> if the operation is successful. 108 * @return Returns negative value if the get failed. 109 * 110 * @since 5.1 111 * @version 1.0 112 */ 113 GetDeviceVibratorInfo([in] DeviceVibratorInfo deviceVibratorInfo, [out] struct HdfVibratorInfo[] vibratorInfo); 114 115 /** 116 * @brief Obtains information about this device contains vibrator that support setting intensity and frequency in the system. 117 * 118 * @param vibratorInfo Indicates the pointer to the vibration effect, For details, see {@link HdfVibratorInfo}. 119 * 120 * @return Returns <b>0</b> if the operation is successful. 121 * @return Returns negative value if the get failed. 122 * 123 * @since 3.2 124 * @version 1.1 125 */ 126 GetVibratorIdSingle([in] DeviceVibratorInfo deviceVibratorInfo, [out] struct HdfVibratorInfo[] vibratorInfo); 127 128 /** 129 * @brief Start the vibrator according to the incoming vibration effect. 130 * 131 * @param duration Indicates the duration that the vibration lasts, in milliseconds. 132 * 133 * @param intensity Indicates vibrator intensity in a vibration period. 134 * 135 * @param frequency Indicates vibrator frequency in a vibration period. 136 * 137 * @return Returns <b>0</b> if the operation is successful. 138 * @return Returns <b>-1</b> if the vibrationPeriod setting is not supported. 139 * @return Returns <b>-2</b> if the intensity setting is not supported. 140 * @return Returns <b>-3</b> if the frequency setting is not supported. 141 * 142 * @since 3.2 143 * @version 1.1 144 */ 145 EnableVibratorModulation([in] DeviceVibratorInfo deviceVibratorInfo, [in] unsigned int duration, 146 [in] unsigned short intensity, [in] short frequency); 147 148 /** 149 * @brief Controls the vibrator to perform a periodic vibration with the custom composite effect. 150 * 151 * @param effect Indicates the pointer to the custom composite effect type. For details, 152 * see {@link HdfCompositeEffect}. 153 * 154 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 155 * 156 * @since 3.2 157 * @version 1.1 158 */ 159 EnableCompositeEffect([in] DeviceVibratorInfo deviceVibratorInfo, [in] struct HdfCompositeEffect effect); 160 161 /** 162 * @brief Obtains the vibration effect information with the specified effect type. 163 * 164 * @param effectType Indicates the pointer to the preset effect type. It is recommended that the 165 * maximum length be 64 bytes. 166 * 167 * @param effectInfo Indicates the pointer to the vibration effect information. For details, 168 * see {@link HdfEffectInfo}. 169 * 170 * @return Returns <b>0</b> if the operation is successful. 171 * @return Returns negative value if the get failed. 172 * 173 * @since 3.2 174 * @version 1.1 175 */ 176 GetEffectInfo([in] DeviceVibratorInfo deviceVibratorInfo, [in] String effectType, 177 [out] struct HdfEffectInfo effectInfo); 178 179 /** 180 * @brief Obtains whether the vibrator is currently vibrating. 181 * 182 * @param state Indicates current vibration state of the vibrator. 183 * 184 * @return Returns <b>0</b> if the operation is successful. 185 * @return Returns negative value if the get failed. 186 * 187 * @since 3.2 188 * @version 1.1 189 */ 190 IsVibratorRunning([in] DeviceVibratorInfo deviceVibratorInfo, [out] boolean state); 191 192 /** 193 * @brief HD vibration data packet delivery. 194 * 195 * @param Indecates the Hd vibration data packet. 196 * 197 * @return Returns <b>0</b> if the operation is successful. 198 * @return Returns negative value if the get failed. 199 * 200 * @since 4.1 201 * @version 1.2 202 */ 203 PlayHapticPattern([in] DeviceVibratorInfo deviceVibratorInfo, [in] struct HapticPaket pkg); 204 205 /** 206 * @brief Obtains the vibration capability of the motor. 207 * 208 * @param Indecates the vibration capability of the motor. 209 * 210 * @return Returns <b>0</b> if the operation is successful. 211 * @return Returns negative value if the get failed. 212 * 213 * @since 4.1 214 * @version 1.2 215 */ 216 GetHapticCapacity([in] DeviceVibratorInfo deviceVibratorInfo, [out] struct HapticCapacity HapticCapacity); 217 218 /** 219 * @brief Obtains the start_up time of the motor. 220 * 221 * @param Indicates the time from command is issued to the time the motor starts. 222 * 223 * @return Returns <b>0</b> if the operation is successful. 224 * @return Returns negative value if the get failed. 225 * 226 * @since 4.1 227 * @version 1.2 228 */ 229 GetHapticStartUpTime([in] DeviceVibratorInfo deviceVibratorInfo, [in] int mode, [out] int startUpTime); 230 231 /** 232 * @brief Controls the vibrator to perform a periodic vibration with the preset effect. 233 * 234 * One-shot vibration is mutually exclusive with periodic vibration. Before using periodic vibration, 235 * exit one-shot vibration. 236 * 237 * @param effectType Indicates the pointer to the preset effect type. It is recommended that the 238 * maximum length be 64 bytes. 239 * @param intensity Indicates amplitude intensity, ranging from 1 to 100. 240 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 241 * 242 * @since 5.0 243 * @version 1.3 244 */ 245 StartByIntensity([in] DeviceVibratorInfo deviceVibratorInfo, [in] String effectType, [in] unsigned short intensity); 246 247 /** 248 * @brief Obtains the vibration wave information. 249 * 250 * @param vibratorId Indicates the vibration index. 251 * @param info Indicates the information. 252 * 253 * @return Returns <b>0</b> if the operation is successful. 254 * @return Returns negative value if the get failed. 255 * 256 * @since 5.0 257 * @version 1.3 258 */ 259 GetAllWaveInfo([in] DeviceVibratorInfo deviceVibratorInfo, [out] struct HdfWaveInformation[] info); 260 261 /** 262 * @brief Registers the callback for reporting vibrator plug state. 263 * 264 * The deviceId means which pluged in this device. 265 * the vibratorCnt means device contains vibrator count. 266 * The HapticCapacity means vibrator ability. 267 * is subscribed, and the subscription is successful once. 268 * @param callbackObj Indicates the callback to register. For details, see {@link IVibratorPlugCallback}. 269 * @return Returns <b>0</b> if the callback is successfully registered; returns a negative value otherwise. 270 * 271 * @since 5.1 272 * @version 2.0 273 */ 274 RegVibratorPlugCallback([in] IVibratorPlugCallback callbackObj); 275 276 /** 277 * @brief UnRegisters the callback for reporting vibrator plug state. 278 * 279 * The deviceId means which pluged in this device. 280 * the vibratorCnt means device contains vibrator count. 281 * The HapticCapacity means vibrator ability. 282 * is subscribed, and the subscription is successful once. 283 * @param callbackObj Indicates the callback to register. For details, see {@link IVibratorPlugCallback}. 284 * @return Returns <b>0</b> if the callback is successfully registered; returns a negative value otherwise. 285 * 286 * @since 5.1 287 * @version 2.0 288 */ 289 UnRegVibratorPlugCallback([in] IVibratorPlugCallback callbackObj); 290 291/** 292* @brief HD vibration data packet delivery. 293* Indecates the Hd vibration data packet. 294* @param deviceVibratorInfo, The default value of deviceId is -1, vibratorId is accumulated according to the number of motors. 295* see {@link DeviceVibratorInfo}. 296* @param The sessionId is sent by the audio framework. 297* @param HapticPaket data is sent from the upper layer 298* @return Returns <b>0</b> if the operation is successful. 299* @return Returns negative value if the get failed. 300* 301* @since 6.0 302* @version 1.0 303*/ 304 PlayPatternBySessionId([in] DeviceVibratorInfo deviceVibratorInfo, [in] unsigned int sessionId, [in] struct HapticPaket hapticPaket); 305 306/** 307* @brief HD vibration data packet delivery. 308* Indecates the Hd vibration data packet. 309* @param deviceVibratorInfo, The default value of deviceId is -1, vibratorId is accumulated according to the number of motors. 310* see {@link DeviceVibratorInfo}. 311* @param The sessionId is sent by the audio framework. 312* @param VibratorPackage data is sent from the upper layer 313* @return Returns <b>0</b> if the operation is successful. 314* @return Returns negative value if the get failed. 315* 316* @since 6.0 317* @version 1.0 318*/ 319 PlayPackageBySession([in] DeviceVibratorInfo deviceVibratorInfo, [in] unsigned int sessionId, [in] struct VibratorPackage vibratorPackage); 320/** 321* @brief Stops the vibration. 322* 323* Before the vibrator starts, it must stop vibrating in any mode. This function can be used during 324* and after the vibrating process. 325* @param deviceVibratorInfo, The default value of deviceId is -1, vibratorId is accumulated according to the number of motors. 326* see {@link DeviceVibratorInfo}. 327* @param The sessionId is sent by the audio framework. 328* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 329* 330* @since 6.0 331* @version 1.0 332*/ 333 StopVibrateBySessionId([in] DeviceVibratorInfo deviceVibratorInfo, [in] unsigned int sessionId); 334}