1/* 2 * Copyright (c) 2021 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 16import { AsyncCallback } from './@ohos.base'; 17 18/** 19 * This module provides the capability to control motor vibration. 20 * 21 * @namespace vibrator 22 * @syscap SystemCapability.Sensors.MiscDevice 23 * @since 8 24 */ 25declare namespace vibrator { 26 /** 27 * The trigger motor vibrates for a specified length of time. 28 * 29 * @permission ohos.permission.VIBRATE 30 * @param { number } duration Indicate the duration of the motor vibration. 31 * @param { AsyncCallback<void> } callback The callback of vibrate. 32 * @syscap SystemCapability.Sensors.MiscDevice 33 * @since 8 34 * @deprecated since 9 35 * @useinstead vibrator#startVibration 36 */ 37 function vibrate(duration: number, callback?: AsyncCallback<void>): void; 38 39 /** 40 * The trigger motor vibrates for a specified length of time. 41 * 42 * @permission ohos.permission.VIBRATE 43 * @param { number } duration Indicate the duration of the motor vibration. 44 * @returns { Promise<void> } Promise used to return the result. 45 * @syscap SystemCapability.Sensors.MiscDevice 46 * @since 8 47 * @deprecated since 9 48 * @useinstead vibrator#startVibration 49 */ 50 function vibrate(duration: number): Promise<void>; 51 52 /** 53 * The trigger motor vibrates for the specified effect of the preset. 54 * 55 * @permission ohos.permission.VIBRATE 56 * @param { EffectId } effectId Indicate the specified effect of the preset, {@code EffectId}. 57 * @returns { Promise<void> } Promise used to return the result. 58 * @syscap SystemCapability.Sensors.MiscDevice 59 * @since 8 60 * @deprecated since 9 61 * @useinstead vibrator#startVibration 62 */ 63 function vibrate(effectId: EffectId): Promise<void>; 64 65 /** 66 * The trigger motor vibrates for the specified effect of the preset. 67 * 68 * @permission ohos.permission.VIBRATE 69 * @param { EffectId } effectId Indicate the specified effect of the preset, {@code EffectId}. 70 * @param { AsyncCallback<void> } callback The callback of vibrate. 71 * @syscap SystemCapability.Sensors.MiscDevice 72 * @since 8 73 * @deprecated since 9 74 * @useinstead vibrator#startVibration 75 */ 76 function vibrate(effectId: EffectId, callback?: AsyncCallback<void>): void; 77 78 /** 79 * Trigger vibrator vibration. 80 * 81 * @permission ohos.permission.VIBRATE 82 * @param { VibrateEffect } effect - Indicate vibrate effect, {@code VibrateEffect}. 83 * @param { VibrateAttribute } attribute - Indicate vibrate attribute, {@code VibrateAttribute}. 84 * @param { AsyncCallback<void> } callback - The callback of startVibration. 85 * @throws { BusinessError } 201 - Permission denied. 86 * @throws { BusinessError } 401 - Parameter error. 87 * @throws { BusinessError } 801 - Capability not supported. 88 * @throws { BusinessError } 14600101 - Device operation failed. 89 * @syscap SystemCapability.Sensors.MiscDevice 90 * @since 9 91 */ 92 function startVibration(effect: VibrateEffect, attribute: VibrateAttribute, callback: AsyncCallback<void>): void; 93 94 /** 95 * Trigger vibrator vibration. 96 * 97 * @permission ohos.permission.VIBRATE 98 * @param { VibrateEffect } effect - Indicate vibrate effect, {@code VibrateEffect}. 99 * @param { VibrateAttribute } attribute - Indicate vibrate attribute, {@code VibrateAttribute}. 100 * @returns { Promise<void> } Promise used to return the result. 101 * @throws { BusinessError } 201 - Permission denied. 102 * @throws { BusinessError } 401 - Parameter error. 103 * @throws { BusinessError } 801 - Capability not supported. 104 * @throws { BusinessError } 14600101 - Device operation failed. 105 * @syscap SystemCapability.Sensors.MiscDevice 106 * @since 9 107 */ 108 function startVibration(effect: VibrateEffect, attribute: VibrateAttribute): Promise<void>; 109 110 /** 111 * Stop the vibrator from vibrating. 112 * 113 * @permission ohos.permission.VIBRATE 114 * @param { VibratorStopMode } stopMode - Indicate the stop mode in which the motor vibrates, {@code VibratorStopMode}. 115 * @returns { Promise<void> } Promise used to return the result. 116 * @throws { BusinessError } 201 - Permission denied. 117 * @throws { BusinessError } 401 - Parameter error. 118 * @syscap SystemCapability.Sensors.MiscDevice 119 * @since 9 120 */ 121 function stopVibration(stopMode: VibratorStopMode): Promise<void>; 122 123 /** 124 * Stop the vibrator from vibrating. 125 * 126 * @permission ohos.permission.VIBRATE 127 * @param { VibratorStopMode } stopMode - Indicate the stop mode in which the motor vibrates, {@code VibratorStopMode}. 128 * @param { AsyncCallback<void> } callback - The callback of stopVibration. 129 * @throws { BusinessError } 201 - Permission denied. 130 * @throws { BusinessError } 401 - Parameter error. 131 * @syscap SystemCapability.Sensors.MiscDevice 132 * @since 9 133 */ 134 function stopVibration(stopMode: VibratorStopMode, callback: AsyncCallback<void>): void; 135 136 /** 137 * Stop any type of vibration. 138 * 139 * @permission ohos.permission.VIBRATE 140 * @param { AsyncCallback<void> } callback - The callback of stopVibration. 141 * @throws { BusinessError } 201 - Permission denied. 142 * @syscap SystemCapability.Sensors.MiscDevice 143 * @since 10 144 */ 145 function stopVibration(callback: AsyncCallback<void>): void; 146 147 /** 148 * Stop any type of vibration. 149 * 150 * @permission ohos.permission.VIBRATE 151 * @returns { Promise<void> } Promise used to return the result. 152 * @throws { BusinessError } 201 - Permission denied. 153 * @syscap SystemCapability.Sensors.MiscDevice 154 * @since 10 155 */ 156 function stopVibration(): Promise<void>; 157 158 /** 159 * Whether the preset vibration effect is supported. 160 * 161 * @param { string } effectId Indicate the specified effect of the preset, {@code EffectId}. 162 * @param { AsyncCallback<boolean> } callback The callback of isSupportEffect. 163 * @throws { BusinessError } 201 - Permission denied. 164 * @throws { BusinessError } 401 - Parameter error. 165 * @syscap SystemCapability.Sensors.MiscDevice 166 * @since 10 167 */ 168 function isSupportEffect(effectId: string, callback: AsyncCallback<boolean>): void; 169 170 /** 171 * Whether the preset vibration effect is supported. 172 * 173 * @param { string } effectId Indicate the specified effect of the preset, {@code EffectId}. 174 * @returns { Promise<boolean> } Promise used to return the result. 175 * @throws { BusinessError } 201 - Permission denied. 176 * @throws { BusinessError } 401 - Parameter error. 177 * @syscap SystemCapability.Sensors.MiscDevice 178 * @since 10 179 */ 180 function isSupportEffect(effectId: string): Promise<boolean>; 181 182 /** 183 * Stop the motor from vibrating. 184 * 185 * @permission ohos.permission.VIBRATE 186 * @param { VibratorStopMode } stopMode Indicate the stop mode in which the motor vibrates, {@code VibratorStopMode}. 187 * @returns { Promise<void> } Promise used to return the result. 188 * @syscap SystemCapability.Sensors.MiscDevice 189 * @since 8 190 * @deprecated since 9 191 * @useinstead vibrator#stopVibration 192 */ 193 function stop(stopMode: VibratorStopMode): Promise<void>; 194 195 /** 196 * Stop the motor from vibrating. 197 * 198 * @permission ohos.permission.VIBRATE 199 * @param { VibratorStopMode } stopMode Indicate the stop mode in which the motor vibrates, {@code VibratorStopMode}. 200 * @param { AsyncCallback<void> } callback The callback of stop. 201 * @syscap SystemCapability.Sensors.MiscDevice 202 * @since 8 203 * @deprecated since 9 204 * @useinstead vibrator#stopVibration 205 */ 206 function stop(stopMode: VibratorStopMode, callback?: AsyncCallback<void>): void; 207 208 /** 209 * Preset vibration effect string. 210 * 211 * @enum { string } 212 * @syscap SystemCapability.Sensors.MiscDevice 213 * @since 8 214 */ 215 enum EffectId { 216 /* Describes the vibration effect of the vibrator when a user adjusts the timer.*/ 217 EFFECT_CLOCK_TIMER = 'haptic.clock.timer' 218 } 219 220 /** 221 * Vibrator vibration stop mode. 222 * 223 * @enum { string } 224 * @syscap SystemCapability.Sensors.MiscDevice 225 * @since 8 226 */ 227 enum VibratorStopMode { 228 /* Indicates the mode of stopping a one-shot vibration effect.*/ 229 VIBRATOR_STOP_MODE_TIME = 'time', 230 /* Indicates the mode of stopping a preset vibration effect.*/ 231 VIBRATOR_STOP_MODE_PRESET = 'preset' 232 } 233 234 /** 235 * The use of vibration. 236 * 237 * @syscap SystemCapability.Sensors.MiscDevice 238 * @since 9 239 */ 240 type Usage = 'unknown' | 'alarm' | 'ring' | 'notification' | 'communication' | 241 'touch' | 'media' | 'physicalFeedback' | 'simulateReality'; 242 243 /** 244 * The attribute of vibration. 245 * 246 * @interface VibrateAttribute 247 * @syscap SystemCapability.Sensors.MiscDevice 248 * @since 9 249 */ 250 interface VibrateAttribute { 251 id?: number; /** Vibrator id, default is 0. */ 252 usage: Usage; /** The use of vibration. */ 253 } 254 255 /** 256 * Describes the effect of vibration. 257 * 258 * @type { VibrateTime | VibratePreset } 259 * @syscap SystemCapability.Sensors.MiscDevice 260 * @since 9 261 */ 262 /** 263 * Describes the effect of vibration. 264 * 265 * @type { VibrateTime | VibratePreset | VibrateFromFile } 266 * @syscap SystemCapability.Sensors.MiscDevice 267 * @since 10 268 */ 269 type VibrateEffect = VibrateTime | VibratePreset | VibrateFromFile; 270 271 /** 272 * Vibrate continuously for a period of time at the default intensity of the system. 273 * 274 * @interface VibrateTime 275 * @syscap SystemCapability.Sensors.MiscDevice 276 * @since 9 277 */ 278 interface VibrateTime { 279 type: 'time'; 280 duration: number; /** The duration of the vibration, in ms */ 281 } 282 283 /** 284 * Preset vibration type vibration effect. 285 * 286 * @interface VibratePreset 287 * @syscap SystemCapability.Sensors.MiscDevice 288 * @since 9 289 */ 290 interface VibratePreset { 291 type: 'preset'; 292 effectId: string; /** Preset type vibration */ 293 count: number; /** The number of vibration repetitions */ 294 } 295 296 /** 297 * Custom vibration, vibrate the effect from a haptic file. 298 * 299 * @interface VibrateFromFile 300 * @syscap SystemCapability.Sensors.MiscDevice 301 * @since 10 302 */ 303 interface VibrateFromFile { 304 type: 'file'; 305 hapticFd: HapticFileDescriptor; /** Haptic file descriptor, some formats are supported. */ 306 } 307 308 /** 309 * Haptic file descriptor. The caller needs to ensure that the fd is valid and 310 * the offset and length are correct. 311 * 312 * @interface HapticFileDescriptor 313 * @syscap SystemCapability.Sensors.MiscDevice 314 * @since 10 315 */ 316 interface HapticFileDescriptor { 317 /** 318 * The file descriptor of haptic effect source from file system. The caller 319 * is responsible to close the file descriptor. 320 * 321 * @syscap SystemCapability.Sensors.MiscDevice 322 * @since 10 323 */ 324 fd: number; 325 326 /** 327 * The offset into the file where the data to be read, in bytes. By default, 328 * the offset is zero. 329 * 330 * @syscap SystemCapability.Sensors.MiscDevice 331 * @since 10 332 */ 333 offset?: number; 334 335 /** 336 * The length in bytes of the data to be read. By default, the length is the 337 * rest of bytes in the file from the offset. 338 * 339 * @syscap SystemCapability.Sensors.MiscDevice 340 * @since 10 341 */ 342 length?: number; 343 } 344} 345 346export default vibrator; 347