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 16/** 17 * @file 18 * @kit SensorServiceKit 19 */ 20 21import { AsyncCallback } from './@ohos.base'; 22 23/** 24 * This module provides the capability to control motor vibration. 25 * 26 * @namespace vibrator 27 * @syscap SystemCapability.Sensors.MiscDevice 28 * @since 8 29 */ 30/** 31 * This module provides the capability to control motor vibration. 32 * 33 * @namespace vibrator 34 * @syscap SystemCapability.Sensors.MiscDevice 35 * @atomicservice 36 * @since 11 37 */ 38declare namespace vibrator { 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 * @param { AsyncCallback<void> } callback The callback of vibrate. 45 * @syscap SystemCapability.Sensors.MiscDevice 46 * @since 8 47 * @deprecated since 9 48 * @useinstead vibrator#startVibration 49 */ 50 function vibrate(duration: number, callback?: AsyncCallback<void>): void; 51 52 /** 53 * The trigger motor vibrates for a specified length of time. 54 * 55 * @permission ohos.permission.VIBRATE 56 * @param { number } duration Indicate the duration of the motor vibration. 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(duration: number): 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 * @returns { Promise<void> } Promise used to return the result. 71 * @syscap SystemCapability.Sensors.MiscDevice 72 * @since 8 73 * @deprecated since 9 74 * @useinstead vibrator#startVibration 75 */ 76 function vibrate(effectId: EffectId): Promise<void>; 77 78 /** 79 * The trigger motor vibrates for the specified effect of the preset. 80 * 81 * @permission ohos.permission.VIBRATE 82 * @param { EffectId } effectId Indicate the specified effect of the preset, {@code EffectId}. 83 * @param { AsyncCallback<void> } callback The callback of vibrate. 84 * @syscap SystemCapability.Sensors.MiscDevice 85 * @since 8 86 * @deprecated since 9 87 * @useinstead vibrator#startVibration 88 */ 89 function vibrate(effectId: EffectId, callback?: AsyncCallback<void>): void; 90 91 /** 92 * Trigger vibrator vibration. 93 * 94 * @permission ohos.permission.VIBRATE 95 * @param { VibrateEffect } effect - Indicate vibrate effect, {@code VibrateEffect}. 96 * @param { VibrateAttribute } attribute - Indicate vibrate attribute, {@code VibrateAttribute}. 97 * @param { AsyncCallback<void> } callback - The callback of startVibration. 98 * @throws { BusinessError } 201 - Permission denied. 99 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 100 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 101 * @throws { BusinessError } 801 - Capability not supported. 102 * @throws { BusinessError } 14600101 - Device operation failed. 103 * @syscap SystemCapability.Sensors.MiscDevice 104 * @since 9 105 */ 106 /** 107 * Trigger vibrator vibration. 108 * 109 * @permission ohos.permission.VIBRATE 110 * @param { VibrateEffect } effect - Indicate vibrate effect, {@code VibrateEffect} 111 * @param { VibrateAttribute } attribute - Indicate vibrate attribute, {@code VibrateAttribute} 112 * @param { AsyncCallback<void> } callback - The callback of startVibration 113 * @throws { BusinessError } 201 - Permission denied 114 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 115 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 116 * @throws { BusinessError } 801 - Capability not supported 117 * @throws { BusinessError } 14600101 - Device operation failed 118 * @syscap SystemCapability.Sensors.MiscDevice 119 * @atomicservice 120 * @since 11 121 */ 122 function startVibration(effect: VibrateEffect, attribute: VibrateAttribute, callback: AsyncCallback<void>): void; 123 124 /** 125 * Trigger vibrator vibration. 126 * 127 * @permission ohos.permission.VIBRATE 128 * @param { VibrateEffect } effect - Indicate vibrate effect, {@code VibrateEffect}. 129 * @param { VibrateAttribute } attribute - Indicate vibrate attribute, {@code VibrateAttribute}. 130 * @returns { Promise<void> } Promise used to return the result. 131 * @throws { BusinessError } 201 - Permission denied. 132 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 133 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 134 * @throws { BusinessError } 801 - Capability not supported. 135 * @throws { BusinessError } 14600101 - Device operation failed. 136 * @syscap SystemCapability.Sensors.MiscDevice 137 * @since 9 138 */ 139 /** 140 * Trigger vibrator vibration. 141 * 142 * @permission ohos.permission.VIBRATE 143 * @param { VibrateEffect } effect - Indicate vibrate effect, {@code VibrateEffect}. 144 * @param { VibrateAttribute } attribute - Indicate vibrate attribute, {@code VibrateAttribute}. 145 * @returns { Promise<void> } Promise used to return the result. 146 * @throws { BusinessError } 201 - Permission denied. 147 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 148 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 149 * @throws { BusinessError } 801 - Capability not supported. 150 * @throws { BusinessError } 14600101 - Device operation failed. 151 * @syscap SystemCapability.Sensors.MiscDevice 152 * @atomicservice 153 * @since 11 154 */ 155 function startVibration(effect: VibrateEffect, attribute: VibrateAttribute): Promise<void>; 156 157 /** 158 * Stop the vibrator from vibrating. 159 * 160 * @permission ohos.permission.VIBRATE 161 * @param { VibratorStopMode } stopMode - Indicate the stop mode in which the motor vibrates, {@code VibratorStopMode}. 162 * @returns { Promise<void> } Promise used to return the result. 163 * @throws { BusinessError } 201 - Permission denied. 164 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 165 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 166 * @syscap SystemCapability.Sensors.MiscDevice 167 * @since 9 168 */ 169 function stopVibration(stopMode: VibratorStopMode): Promise<void>; 170 171 /** 172 * Stop the vibrator from vibrating. 173 * 174 * @permission ohos.permission.VIBRATE 175 * @param { VibratorStopMode } stopMode - Indicate the stop mode in which the motor vibrates, {@code VibratorStopMode}. 176 * @param { AsyncCallback<void> } callback - The callback of stopVibration. 177 * @throws { BusinessError } 201 - Permission denied. 178 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 179 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 180 * @syscap SystemCapability.Sensors.MiscDevice 181 * @since 9 182 */ 183 function stopVibration(stopMode: VibratorStopMode, callback: AsyncCallback<void>): void; 184 185 /** 186 * Stop any type of vibration. 187 * 188 * @permission ohos.permission.VIBRATE 189 * @param { AsyncCallback<void> } callback - The callback of stopVibration. 190 * @throws { BusinessError } 201 - Permission denied. 191 * @syscap SystemCapability.Sensors.MiscDevice 192 * @since 10 193 */ 194 /** 195 * Stop any type of vibration. 196 * 197 * @permission ohos.permission.VIBRATE 198 * @param { AsyncCallback<void> } callback - The callback of stopVibration. 199 * @throws { BusinessError } 201 - Permission denied. 200 * @syscap SystemCapability.Sensors.MiscDevice 201 * @atomicservice 202 * @since 11 203 */ 204 function stopVibration(callback: AsyncCallback<void>): void; 205 206 /** 207 * Stop any type of vibration. 208 * 209 * @permission ohos.permission.VIBRATE 210 * @returns { Promise<void> } Promise used to return the result. 211 * @throws { BusinessError } 201 - Permission denied. 212 * @syscap SystemCapability.Sensors.MiscDevice 213 * @since 10 214 */ 215 /** 216 * Stop any type of vibration. 217 * 218 * @permission ohos.permission.VIBRATE 219 * @returns { Promise<void> } Promise used to return the result. 220 * @throws { BusinessError } 201 - Permission denied. 221 * @syscap SystemCapability.Sensors.MiscDevice 222 * @atomicservice 223 * @since 11 224 */ 225 function stopVibration(): Promise<void>; 226 227 /** 228 * Stop any type of vibration. 229 * 230 * @permission ohos.permission.VIBRATE 231 * @throws { BusinessError } 201 - Permission denied. 232 * @throws { BusinessError } 14600101 - Device operation failed. 233 * @syscap SystemCapability.Sensors.MiscDevice 234 * @atomicservice 235 * @since 12 236 */ 237 function stopVibrationSync(): void; 238 239 /** 240 * Whether the preset vibration effect is supported. 241 * 242 * @param { string } effectId Indicate the specified effect of the preset, {@code EffectId}. 243 * @param { AsyncCallback<boolean> } callback The callback of isSupportEffect. 244 * @throws { BusinessError } 201 - Permission denied. 245 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 246 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 247 * @syscap SystemCapability.Sensors.MiscDevice 248 * @since 10 249 */ 250 function isSupportEffect(effectId: string, callback: AsyncCallback<boolean>): void; 251 252 /** 253 * Whether the preset vibration effect is supported. 254 * 255 * @param { string } effectId Indicate the specified effect of the preset, {@code EffectId}. 256 * @returns { Promise<boolean> } Promise used to return the result. 257 * @throws { BusinessError } 201 - Permission denied. 258 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 259 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 260 * @syscap SystemCapability.Sensors.MiscDevice 261 * @since 10 262 */ 263 function isSupportEffect(effectId: string): Promise<boolean>; 264 265 /** 266 * Whether the preset vibration effect is supported. 267 * 268 * @param { string } effectId Indicate the specified effect of the preset, {@code EffectId}. 269 * @returns { boolean } Returns whether the effect is supported. 270 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 271 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 272 * @throws { BusinessError } 14600101 - Device operation failed. 273 * @syscap SystemCapability.Sensors.MiscDevice 274 * @since 12 275 */ 276 function isSupportEffectSync(effectId: string): boolean; 277 278 /** 279 * Stop the motor from vibrating. 280 * 281 * @permission ohos.permission.VIBRATE 282 * @param { VibratorStopMode } stopMode Indicate the stop mode in which the motor vibrates, {@code VibratorStopMode}. 283 * @returns { Promise<void> } Promise used to return the result. 284 * @syscap SystemCapability.Sensors.MiscDevice 285 * @since 8 286 * @deprecated since 9 287 * @useinstead vibrator#stopVibration 288 */ 289 function stop(stopMode: VibratorStopMode): Promise<void>; 290 291 /** 292 * Stop the motor from vibrating. 293 * 294 * @permission ohos.permission.VIBRATE 295 * @param { VibratorStopMode } stopMode Indicate the stop mode in which the motor vibrates, {@code VibratorStopMode}. 296 * @param { AsyncCallback<void> } callback The callback of stop. 297 * @syscap SystemCapability.Sensors.MiscDevice 298 * @since 8 299 * @deprecated since 9 300 * @useinstead vibrator#stopVibration 301 */ 302 function stop(stopMode: VibratorStopMode, callback?: AsyncCallback<void>): void; 303 304 /** 305 * Whether the high-definition haptic is supported. 306 * 307 * @returns { boolean } Returns whether the high-definition haptic is supported. 308 * @throws { BusinessError } 14600101 - Device operation failed. 309 * @syscap SystemCapability.Sensors.MiscDevice 310 * @since 12 311 */ 312 function isHdHapticSupported(): boolean; 313 314 /** 315 * Preset vibration effect string. 316 * 317 * @enum { string } 318 * @syscap SystemCapability.Sensors.MiscDevice 319 * @since 8 320 */ 321 enum EffectId { 322 /** 323 * Describes the vibration effect of the vibrator when a user adjusts the timer. 324 * 325 * @syscap SystemCapability.Sensors.MiscDevice 326 * @since 8 327 */ 328 EFFECT_CLOCK_TIMER = 'haptic.clock.timer' 329 } 330 331 /** 332 * Simple and universal vibration effects. 333 * 334 * @enum { string } 335 * @syscap SystemCapability.Sensors.MiscDevice 336 * @since 12 337 */ 338 enum HapticFeedback { 339 /** 340 * Describes the soft vibration effect of the vibrator. 341 * 342 * @syscap SystemCapability.Sensors.MiscDevice 343 * @since 12 344 */ 345 EFFECT_SOFT = 'haptic.effect.soft', 346 347 /** 348 * Describes the hard vibration effect of the vibrator. 349 * 350 * @syscap SystemCapability.Sensors.MiscDevice 351 * @since 12 352 */ 353 EFFECT_HARD = 'haptic.effect.hard', 354 355 /** 356 * Describes the sharp vibration effect of the vibrator. 357 * 358 * @syscap SystemCapability.Sensors.MiscDevice 359 * @since 12 360 */ 361 EFFECT_SHARP = 'haptic.effect.sharp' 362 } 363 364 /** 365 * Vibrator vibration stop mode. 366 * 367 * @enum { string } 368 * @syscap SystemCapability.Sensors.MiscDevice 369 * @since 8 370 */ 371 enum VibratorStopMode { 372 /** 373 * Indicates the mode of stopping a one-shot vibration effect. 374 * 375 * @syscap SystemCapability.Sensors.MiscDevice 376 * @since 8 377 */ 378 VIBRATOR_STOP_MODE_TIME = 'time', 379 380 /** 381 * Indicates the mode of stopping a preset vibration effect. 382 * 383 * @syscap SystemCapability.Sensors.MiscDevice 384 * @since 8 385 */ 386 VIBRATOR_STOP_MODE_PRESET = 'preset' 387 } 388 389 /** 390 * The use of vibration. 391 * 392 * @typedef {'unknown' | 'alarm' | 'ring' | 'notification' | 'communication' | 393 * 'touch' | 'media' | 'physicalFeedback' | 'simulateReality'} 394 * @syscap SystemCapability.Sensors.MiscDevice 395 * @since 9 396 */ 397 /** 398 * The use of vibration. 399 * 400 * @typedef {'unknown' | 'alarm' | 'ring' | 'notification' | 'communication' | 401 * 'touch' | 'media' | 'physicalFeedback' | 'simulateReality'} 402 * @syscap SystemCapability.Sensors.MiscDevice 403 * @atomicservice 404 * @since 11 405 */ 406 type Usage = 'unknown' | 'alarm' | 'ring' | 'notification' | 'communication' | 407 'touch' | 'media' | 'physicalFeedback' | 'simulateReality'; 408 409 /** 410 * The attribute of vibration. 411 * 412 * @interface VibrateAttribute 413 * @syscap SystemCapability.Sensors.MiscDevice 414 * @since 9 415 */ 416 /** 417 * The attribute of vibration. 418 * 419 * @interface VibrateAttribute 420 * @syscap SystemCapability.Sensors.MiscDevice 421 * @atomicservice 422 * @since 11 423 */ 424 interface VibrateAttribute { 425 /** 426 * Vibrator id, default is 0. 427 * 428 * @syscap SystemCapability.Sensors.MiscDevice 429 * @since 9 430 */ 431 /** 432 * Vibrator id, default is 0. 433 * 434 * @syscap SystemCapability.Sensors.MiscDevice 435 * @atomicservice 436 * @since 11 437 */ 438 id?: number; 439 440 /** 441 * The use of vibration. 442 * 443 * @syscap SystemCapability.Sensors.MiscDevice 444 * @since 9 445 */ 446 /** 447 * The use of vibration. 448 * 449 * @syscap SystemCapability.Sensors.MiscDevice 450 * @atomicservice 451 * @since 11 452 */ 453 usage: Usage; 454 } 455 456 /** 457 * Describes the effect of vibration. 458 * 459 * @typedef { VibrateTime | VibratePreset } 460 * @syscap SystemCapability.Sensors.MiscDevice 461 * @since 9 462 */ 463 /** 464 * Describes the effect of vibration. 465 * 466 * @typedef { VibrateTime | VibratePreset | VibrateFromFile } 467 * @syscap SystemCapability.Sensors.MiscDevice 468 * @since 10 469 */ 470 /** 471 * Describes the effect of vibration. 472 * 473 * @typedef { VibrateTime | VibratePreset | VibrateFromFile } 474 * @syscap SystemCapability.Sensors.MiscDevice 475 * @atomicservice 476 * @since 11 477 */ 478 type VibrateEffect = VibrateTime | VibratePreset | VibrateFromFile; 479 480 /** 481 * Vibrate continuously for a period of time at the default intensity of the system. 482 * 483 * @interface VibrateTime 484 * @syscap SystemCapability.Sensors.MiscDevice 485 * @since 9 486 */ 487 /** 488 * Vibrate continuously for a period of time at the default intensity of the system. 489 * 490 * @interface VibrateTime 491 * @syscap SystemCapability.Sensors.MiscDevice 492 * @atomicservice 493 * @since 11 494 */ 495 interface VibrateTime { 496 /** 497 * The value is "time", which triggers the motor vibration according to the specified duration. 498 * 499 * @syscap SystemCapability.Sensors.MiscDevice 500 * @since 9 501 */ 502 /** 503 * The value is "time", which triggers the motor vibration according to the specified duration. 504 * 505 * @syscap SystemCapability.Sensors.MiscDevice 506 * @atomicservice 507 * @since 11 508 */ 509 type: 'time'; 510 511 /** 512 * The duration of the vibration, in ms. 513 * 514 * @syscap SystemCapability.Sensors.MiscDevice 515 * @since 9 516 */ 517 /** 518 * The duration of the vibration, in ms. 519 * 520 * @syscap SystemCapability.Sensors.MiscDevice 521 * @atomicservice 522 * @since 11 523 */ 524 duration: number; /** The duration of the vibration, in ms */ 525 } 526 527 /** 528 * Preset vibration type vibration effect. 529 * 530 * @interface VibratePreset 531 * @syscap SystemCapability.Sensors.MiscDevice 532 * @since 9 533 */ 534 interface VibratePreset { 535 /** 536 * The value is "preset", which triggers motor vibration according to preset vibration effect. 537 * 538 * @syscap SystemCapability.Sensors.MiscDevice 539 * @since 9 540 */ 541 type: 'preset'; 542 543 /** 544 * Preset type vibration. 545 * 546 * @syscap SystemCapability.Sensors.MiscDevice 547 * @since 9 548 */ 549 effectId: string; 550 551 /** 552 * The number of vibration repetitions. 553 * 554 * @syscap SystemCapability.Sensors.MiscDevice 555 * @since 9 556 */ 557 /** 558 * The number of vibration repetitions. 559 * 560 * @type { ?number } 561 * @syscap SystemCapability.Sensors.MiscDevice 562 * @since 12 563 */ 564 count?: number; 565 566 /** 567 * The intensity of vibration effect. 568 * 569 * @type { ?number } 570 * @syscap SystemCapability.Sensors.MiscDevice 571 * @since 12 572 */ 573 intensity?: number; 574 } 575 576 /** 577 * Custom vibration, vibrate the effect from a haptic file. 578 * 579 * @interface VibrateFromFile 580 * @syscap SystemCapability.Sensors.MiscDevice 581 * @since 10 582 */ 583 interface VibrateFromFile { 584 /** 585 * The value is "file", which triggers motor vibration according to the vibration profile. 586 * 587 * @syscap SystemCapability.Sensors.MiscDevice 588 * @since 10 589 */ 590 type: 'file'; 591 592 /** 593 * Haptic file descriptor, some formats are supported. 594 * 595 * @syscap SystemCapability.Sensors.MiscDevice 596 * @since 10 597 */ 598 hapticFd: HapticFileDescriptor; 599 } 600 601 /** 602 * Haptic file descriptor. The caller needs to ensure that the fd is valid and 603 * the offset and length are correct. 604 * 605 * @interface HapticFileDescriptor 606 * @syscap SystemCapability.Sensors.MiscDevice 607 * @since 10 608 */ 609 interface HapticFileDescriptor { 610 /** 611 * The file descriptor of haptic effect source from file system. The caller 612 * is responsible to close the file descriptor. 613 * 614 * @syscap SystemCapability.Sensors.MiscDevice 615 * @since 10 616 */ 617 fd: number; 618 619 /** 620 * The offset into the file where the data to be read, in bytes. By default, 621 * the offset is zero. 622 * 623 * @syscap SystemCapability.Sensors.MiscDevice 624 * @since 10 625 */ 626 offset?: number; 627 628 /** 629 * The length in bytes of the data to be read. By default, the length is the 630 * rest of bytes in the file from the offset. 631 * 632 * @syscap SystemCapability.Sensors.MiscDevice 633 * @since 10 634 */ 635 length?: number; 636 } 637} 638 639export default vibrator; 640