diff --git a/api/@ohos.vibrator.d.ts b/api/@ohos.vibrator.d.ts index 8d08f4fea85f37558125120ac60086b5bf1e5889..8e66128aa08e4e90266e2763ad2a37abde0aab00 100644 --- a/api/@ohos.vibrator.d.ts +++ b/api/@ohos.vibrator.d.ts @@ -18,7 +18,7 @@ * @kit SensorServiceKit */ -import { AsyncCallback } from './@ohos.base'; +import { AsyncCallback, Callback } from './@ohos.base'; /** * This module provides the capability to control motor vibration. @@ -328,6 +328,258 @@ declare namespace vibrator { EFFECT_CLOCK_TIMER = 'haptic.clock.timer' } + /** + * Stop any type of vibration. + * + * @permission ohos.permission.VIBRATE + * @param { VibratorParam } param - Indicate the device and vibrator information that needs to be controlled, {@code VibratorParam}. + * @throws { BusinessError } 201 - Permission denied. + * @throws { BusinessError } 14600101 - Device operation failed. + * @syscap SystemCapability.Sensors.MiscDevice + * @atomicservice + * @since 18 + */ + function stopVibrationSync(param?: VibratorParam): void; + + /** + * Stop any type of vibration. + * + * @permission ohos.permission.VIBRATE + * @param { VibratorParam } param - Indicate the device and vibrator information that needs to be controlled, {@code VibratorParam}. + * @returns { Promise } Promise used to return the result. + * @throws { BusinessError } 201 - Permission denied. + * @syscap SystemCapability.Sensors.MiscDevice + * @atomicservice + * @since 18 + */ + function stopVibration(param?: VibratorParam): Promise; + + /** + * Stop any type of vibration. + * + * @permission ohos.permission.VIBRATE + * @param { AsyncCallback } callback - The callback of stopVibration. + * @param { VibratorParam } param - Indicate the device and vibrator information that needs to be controlled, {@code VibratorParam}. + * @throws { BusinessError } 201 - Permission denied. + * @syscap SystemCapability.Sensors.MiscDevice + * @atomicservice + * @since 18 + */ + function stopVibration(callback: AsyncCallback, param?: VibratorParam): void; + + /** + * Retrieve the list of vibrator IDs. + * + * @param { AsyncCallback } callback - The callback function for retrieving vibrator ID list. + * @param { VibratorParam } Param - The parameters for the vibrator. + * @throws { BusinessError } 201 - Permission denied. + * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; + *
2. Incorrect parameter types; 3. Parameter verification failed. + * @throws { BusinessError } 14600101 - Device operation failed. + * @syscap SystemCapability.Sensors.MiscDevice + * @since 18 + */ + function GetVibratorList(callback: AsyncCallback>, Param?: VibratorParam): void; + + /** + * Retrieve the list of vibrator IDs. + * + * @param { VibratorParam } Param - The parameters for the vibrator. + * @returns { Array } Returns a list of vibrator IDs. + * @throws { BusinessError } 201 - Permission denied. + * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; + *
2. Incorrect parameter types; 3. Parameter verification failed. + * @throws { BusinessError } 14600101 - Device operation failed. + * @syscap SystemCapability.Sensors.MiscDevice + * @since 18 + */ + function GetVibratorListSync(Param?: VibratorParam): Array; + + /** + * Retrieve effect information by device ID. + * + * @param { string } effectType - The effect type to retrieve. + * @param { AsyncCallback } callback - The callback function for retrieving effect information. + * @param { VibratorParam } Param - The parameters for the vibrator. + * @throws { BusinessError } 201 - Permission denied. + * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; + *
2. Incorrect parameter types; 3. Parameter verification failed. + * @throws { BusinessError } 14600101 - Device operation failed. + * @syscap SystemCapability.Sensors.MiscDevice + * @since 18 + */ + function isSupportEffectInfo(effectType: string, callback: AsyncCallback, Param?: VibratorParam): void; + + /** + * Retrieve effect information by device ID. + * + * @param { string } effectType - Output parameter to store the effect type. + * @param { VibratorParam } Param - The parameters for the vibrator. + * @returns { EffectInfo } Returns information about the specified effect. + * @throws { BusinessError } 201 - Permission denied. + * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; + *
2. Incorrect parameter types; 3. Parameter verification failed. + * @throws { BusinessError } 14600101 - Device operation failed. + * @syscap SystemCapability.Sensors.MiscDevice + * @since 18 + */ + function isSupportEffectInfoSync(effectType: string, Param?: VibratorParam): EffectInfo; + + /** + * Registers a callback function to be called when a vibrator plung event occurs. + * + * @param { EventType.VIBRATOR_PLUGIN } type - The event type corresponding to the vibrator plugin. + * @param { Callback } callback - The callback function to be executed when the event is triggered. + * @throws { BusinessError } 201 - Permission denied. + * @throws { BusinessError } 401 - Callback registration failed. Possible causes: 1. Callback function is not a valid function; + *
2. Insufficient permissions to register the callback. + * @syscap SystemCapability.Sensors.MiscDevice + * @since 18 + */ + function on(type: EventType.VIBRATOR_PLUGIN, callback: Callback): void; + + /** + * Deregisters a callback function that listens for the vibrator unplung event. + * + * @param { EventType.VIBRATOR_UNPLUG } type - The event type corresponding to the vibrator unplug. + * @param { Callback } callback - The callback function to be removed from the event listener. + * @throws { BusinessError } 201 - Permission denied. + * @throws { BusinessError } 401 - Callback deregistration failed. Possible causes: 1. Callback function not previously registered; + *
2. Insufficient permissions to deregister the callback. + * @syscap SystemCapability.Sensors.MiscDevice + * @since 18 + */ + function off(type: EventType.VIBRATOR_UNPLUG, callback: Callback): void; + + /** + * Interface representing the information of a vibrator device. + * + * @interface + * @syscap SystemCapability.Sensors.MiscDevice + * @since 18 + * @property { number } deviceId - Unique identifier for the device that contains one or multiple vibrators. + * @property { boolean } VibratorDeviceState - Indicates the plug state of the device; true if plugged in, false if unplugged. + */ + interface VibratorDeviceInfo { + /** + * Unique identifier for the device that contains one or multiple vibrators. + * + * @type { number } + * @description A numeric value that serves as the unique identifier for the device. + * @since 18 + */ + deviceId: number; + + /** + * Indicates the plug state of the device. + * + * @type { boolean } + * @default false + * @description true if the device is plugged in; false if unplugged. + * @since 18 + */ + VibratorDeviceState: boolean; + } + + /** + * Enumeration representing various event types for vibrator operations. + * + * @enum { number } + * @syscap SystemCapability.Sensors.MiscDevice + * @since 18 + */ + enum EventType { + /** + * Event triggered when the vibrator is plugged in. + * + * @syscap SystemCapability.Sensors.MiscDevice + * @since 18 + */ + VIBRATOR_PLUGIN = 1, + + /** + * Event triggered when the vibrator is unplugged. + * + * @syscap SystemCapability.Sensors.MiscDevice + * @since 18 + */ + VIBRATOR_UNPLUG = 0, + } + + /** + * @brief Represents the information about a vibrator device in the system. + * + * @interface VibratorInfos + * @since + */ + interface VibratorInfos { + /** + * Unique identifier for the device that contains one or multiple vibrators. + * + * @type { number } + */ + deviceId: number; + + /** + * Unique identifier for the vibrator itself within the device. + * + * @type { number } + */ + vibratorId: number; + + /** + * Name of the device. + * + * @type { string } + */ + deviceName: string; + + /** + * Indicates if the vibrator device support HD haptic. + * + * @type { boolean } + */ + isSupportHdHaptic: boolean; + } + + /** + * @brief Represents the parameters for querying vibrator information. + * + * @interface VibratorParam + * @since 18 + */ + interface VibratorParam { + /** + * Unique identifier for the device that contains the vibrator. + * + * @type { number } + */ + deviceId?: number; + /** + * Unique identifier for the vibrator itself within the device. + * + * @type { number } + */ + vibratorId?: number; + } + + /** + * @brief Defines the vibration effect information. + * + * The information includes the capability to set the effect and the vibration duration of the effect. + * + * @interface EffectInfo + * @since 18 + */ + interface EffectInfo { + /** + * Setting effect capability. 1 indicates support, 0 indicates not support. + * + * @type { boolean } + */ + isSupportEffect: boolean; + } + /** * Simple and universal vibration effects. * @@ -446,6 +698,16 @@ declare namespace vibrator { * @since 11 */ interface VibrateAttribute { + /** + * Unique identifier for the device that contains one or multiple vibrators, default is 0. + * + * @type { ?number } + * @syscap SystemCapability.Sensors.MiscDevice + * @atomicservice + * @since 18 + */ + deviceId?: number; + /** * Vibrator id, default is 0. *