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 * @type { ?number } 435 * @syscap SystemCapability.Sensors.MiscDevice 436 * @atomicservice 437 * @since 11 438 */ 439 id?: number; 440 441 /** 442 * The use of vibration. 443 * 444 * @syscap SystemCapability.Sensors.MiscDevice 445 * @since 9 446 */ 447 /** 448 * The use of vibration. 449 * 450 * @type { Usage } 451 * @syscap SystemCapability.Sensors.MiscDevice 452 * @atomicservice 453 * @since 11 454 */ 455 usage: Usage; 456 457 /** 458 * Indicates whether to bypass system management switches. 459 * 460 * @type { ?boolean } 461 * @syscap SystemCapability.Sensors.MiscDevice 462 * @systemapi 463 * @since 12 464 */ 465 systemUsage?: boolean; 466 } 467 468 /** 469 * Describes the effect of vibration. 470 * 471 * @typedef { VibrateTime | VibratePreset } 472 * @syscap SystemCapability.Sensors.MiscDevice 473 * @since 9 474 */ 475 /** 476 * Describes the effect of vibration. 477 * 478 * @typedef { VibrateTime | VibratePreset | VibrateFromFile } 479 * @syscap SystemCapability.Sensors.MiscDevice 480 * @since 10 481 */ 482 /** 483 * Describes the effect of vibration. 484 * 485 * @typedef { VibrateTime | VibratePreset | VibrateFromFile } 486 * @syscap SystemCapability.Sensors.MiscDevice 487 * @atomicservice 488 * @since 11 489 */ 490 type VibrateEffect = VibrateTime | VibratePreset | VibrateFromFile; 491 492 /** 493 * Vibrate continuously for a period of time at the default intensity of the system. 494 * 495 * @interface VibrateTime 496 * @syscap SystemCapability.Sensors.MiscDevice 497 * @since 9 498 */ 499 /** 500 * Vibrate continuously for a period of time at the default intensity of the system. 501 * 502 * @interface VibrateTime 503 * @syscap SystemCapability.Sensors.MiscDevice 504 * @atomicservice 505 * @since 11 506 */ 507 interface VibrateTime { 508 /** 509 * The value is "time", which triggers the motor vibration according to the specified duration. 510 * 511 * @syscap SystemCapability.Sensors.MiscDevice 512 * @since 9 513 */ 514 /** 515 * The value is "time", which triggers the motor vibration according to the specified duration. 516 * 517 * @type { 'time' } 518 * @syscap SystemCapability.Sensors.MiscDevice 519 * @atomicservice 520 * @since 11 521 */ 522 type: 'time'; 523 524 /** 525 * The duration of the vibration, in ms. 526 * 527 * @syscap SystemCapability.Sensors.MiscDevice 528 * @since 9 529 */ 530 /** 531 * The duration of the vibration, in ms. 532 * 533 * @type { number } 534 * @syscap SystemCapability.Sensors.MiscDevice 535 * @atomicservice 536 * @since 11 537 */ 538 duration: number; /** The duration of the vibration, in ms */ 539 } 540 541 /** 542 * Preset vibration type vibration effect. 543 * 544 * @interface VibratePreset 545 * @syscap SystemCapability.Sensors.MiscDevice 546 * @since 9 547 */ 548 interface VibratePreset { 549 /** 550 * The value is "preset", which triggers motor vibration according to preset vibration effect. 551 * 552 * @type { 'preset' } 553 * @syscap SystemCapability.Sensors.MiscDevice 554 * @since 9 555 */ 556 type: 'preset'; 557 558 /** 559 * Preset type vibration. 560 * 561 * @type { string } 562 * @syscap SystemCapability.Sensors.MiscDevice 563 * @since 9 564 */ 565 effectId: string; 566 567 /** 568 * The number of vibration repetitions. 569 * 570 * @syscap SystemCapability.Sensors.MiscDevice 571 * @since 9 572 */ 573 /** 574 * The number of vibration repetitions. 575 * 576 * @type { ?number } 577 * @syscap SystemCapability.Sensors.MiscDevice 578 * @since 12 579 */ 580 count?: number; 581 582 /** 583 * The intensity of vibration effect. 584 * 585 * @type { ?number } 586 * @syscap SystemCapability.Sensors.MiscDevice 587 * @since 12 588 */ 589 intensity?: number; 590 } 591 592 /** 593 * Custom vibration, vibrate the effect from a haptic file. 594 * 595 * @interface VibrateFromFile 596 * @syscap SystemCapability.Sensors.MiscDevice 597 * @since 10 598 */ 599 interface VibrateFromFile { 600 /** 601 * The value is "file", which triggers motor vibration according to the vibration profile. 602 * 603 * @type { 'file' } 604 * @syscap SystemCapability.Sensors.MiscDevice 605 * @since 10 606 */ 607 type: 'file'; 608 609 /** 610 * Haptic file descriptor, some formats are supported. 611 * 612 * @type { HapticFileDescriptor } 613 * @syscap SystemCapability.Sensors.MiscDevice 614 * @since 10 615 */ 616 hapticFd: HapticFileDescriptor; 617 } 618 619 /** 620 * Haptic file descriptor. The caller needs to ensure that the fd is valid and 621 * the offset and length are correct. 622 * 623 * @interface HapticFileDescriptor 624 * @syscap SystemCapability.Sensors.MiscDevice 625 * @since 10 626 */ 627 interface HapticFileDescriptor { 628 /** 629 * The file descriptor of haptic effect source from file system. The caller 630 * is responsible to close the file descriptor. 631 * 632 * @type { number } 633 * @syscap SystemCapability.Sensors.MiscDevice 634 * @since 10 635 */ 636 fd: number; 637 638 /** 639 * The offset into the file where the data to be read, in bytes. By default, 640 * the offset is zero. 641 * 642 * @type { ?number } 643 * @syscap SystemCapability.Sensors.MiscDevice 644 * @since 10 645 */ 646 offset?: number; 647 648 /** 649 * The length in bytes of the data to be read. By default, the length is the 650 * rest of bytes in the file from the offset. 651 * 652 * @type { ?number } 653 * @syscap SystemCapability.Sensors.MiscDevice 654 * @since 10 655 */ 656 length?: number; 657 } 658} 659 660export default vibrator; 661