diff --git a/api/@ohos.vibrator.d.ts b/api/@ohos.vibrator.d.ts index 8d08f4fea85f37558125120ac60086b5bf1e5889..248e72501b4d6486f423a8617b17b8a7664d0cbd 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. @@ -222,7 +222,22 @@ declare namespace vibrator { * @atomicservice * @since 11 */ - function stopVibration(): Promise; + /** + * 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. + * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Incorrect parameter types; + *
2. Parameter verification failed. + * @throws { BusinessError } 14600101 - Device operation failed. + * @syscap SystemCapability.Sensors.MiscDevice + * @atomicservice + * @since 18 + */ + function stopVibration(param?: VibratorParam): Promise; /** * Stop any type of vibration. @@ -328,6 +343,217 @@ declare namespace vibrator { EFFECT_CLOCK_TIMER = 'haptic.clock.timer' } + /** + * Retrieve the list of vibrator information about one or all devices. + * + * @param { VibratorParam } param - Indicate the device and vibrator information that needs to be controlled, + *
{@code VibratorParam}. + * @returns { Promise> } Promise used to return a list of vibrator IDs containing information + *
about the vibrator device.By default, this returns all devices and all vibrators when param is unspecified. + * @throws { BusinessError } 201 - Permission denied. + * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Incorrect parameter types; + *
2. Parameter verification failed. + * @throws { BusinessError } 14600101 - Device operation failed. + * @syscap SystemCapability.Sensors.MiscDevice + * @since 18 + */ + function getVibratorList(param?: VibratorParam): Promise>; + + /** + * Retrieve the list of vibrator information about one or all devices. + * + * @param { VibratorParam } param - Indicate the device and vibrator information that needs to be controlled, + *
{@code VibratorParam}. + * @returns { Array } Returns a list of vibrator IDs containing information + *
about the vibrator device.By default, this returns all devices and all vibrators when param is unspecified. + * @throws { BusinessError } 201 - Permission denied. + * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Incorrect parameter types; + *
2. Parameter verification failed. + * @throws { BusinessError } 14600101 - Device operation failed. + * @syscap SystemCapability.Sensors.MiscDevice + * @since 18 + */ + function getVibratorListSync(param?: VibratorParam): Array; + + /** + * Get effect information by device ID. + * + * @param { string } effectType - The effect type to query. + * @param { VibratorParam } param - Indicate the device and vibrator information that needs to be controlled, + *
{@code VibratorParam}. + * @returns { Promise } Promise used to return the result for retrieving effect information. + * @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 getEffectSupportInfo(effectType: string, param?: VibratorParam): Promise; + + /** + * Get effect information by device ID. + * + * @param { string } effectType - The effect type to query. + * @param { VibratorParam } param - Indicate the device and vibrator information that needs to be controlled, + *
{@code VibratorParam}. + * @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 getEffectSupportInfoSync(effectType: string, param?: VibratorParam): EffectInfo; + + /** + * Register a callback function to be called when a vibrator plugin or unplug event occurs. + * + * @param { 'VibratorDeviceStateChange' } type - Event of the listening + * @param { Callback } callback - The callback function to be executed when + *
the event is triggered. + * @throws { BusinessError } 401 - Parameter error. 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: 'VibratorDeviceStateChange', callback: Callback): void; + + /** + * Unregister a callback function for vibrator plugin or unplug events. + * + * @param { 'VibratorDeviceStateChange' } type - Event of the listening + * @param { Callback } callback - The callback function to be removed from the event listener. + * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Callback function is + *
not a valid function; 2. Insufficient permissions to register the callback. + * @throws { BusinessError } 14600102 - The user callback function has been deregistered. + * @syscap SystemCapability.Sensors.MiscDevice + * @since 18 + */ + function off(type: 'VibratorDeviceStateChange', callback: Callback): void; + + /** + * Interface representing the information of a vibrator device. + * + * @interface + * @syscap SystemCapability.Sensors.MiscDevice + * @since 18 + */ + 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; + } + + /** + * @brief Represents the information about a vibrator device in the system. + * + * @interface VibratorInfo + * @since 18 + */ + interface VibratorInfo { + /** + * Unique identifier for the device that contains one or multiple vibrators. + * + * @type { number } + * @since 18 + */ + deviceId: number; + + /** + * Unique identifier for the vibrator itself within the device. + * + * @type { number } + * @since 18 + */ + vibratorId: number; + + /** + * Name of the device. + * + * @type { string } + * @since 18 + */ + deviceName: string; + + /** + * Indicates if the vibrator device support HD haptic. + * + * @type { boolean } + * @since 18 + */ + isSupportHdHaptic: boolean; + + /** + * Indicates whether the vibrator is a local device or an external one. + * If the value is true, it represents a local device; if false, it represents an external device. + * + * @type { boolean } + * @since 18 + */ + isLocalVibrator: boolean; + } + + /** + * @brief Represents the parameters for querying vibrator information. + * By default, VibratorParam may default to querying or controlling the local default vibrator. + * + * @interface VibratorParam + * @since 18 + */ + interface VibratorParam { + /** + * Unique identifier for the device that contains one or multiple vibrators. + * By default, deviceId may default to querying or controlling the local default vibrator. + * + * @type { ?number } + * @since 18 + */ + deviceId?: number; + /** + * Unique identifier for the vibrator itself within the device. + * By default, vibratorId may default to querying or controlling all vibrators on the corresponding device. + * + * @type { ?number } + * @since 18 + */ + vibratorId?: number; + } + + /** + * @brief Defines the vibration effect information. + * + * The information includes Indicates whether the effect is supported. + * + * @interface EffectInfo + * @since 18 + */ + interface EffectInfo { + /** + * Indicates whether the effect is supported, true means supported, false means not supported + * + * @type { boolean } + * @since 18 + */ + isSupportEffect: boolean; + } + /** * Simple and universal vibration effects. * @@ -446,6 +672,17 @@ declare namespace vibrator { * @since 11 */ interface VibrateAttribute { + /** + * Unique identifier for the device that contains one or multiple vibrators. + * By default, deviceId represents the default device of the local device. + * + * @type { ?number } + * @syscap SystemCapability.Sensors.MiscDevice + * @atomicservice + * @since 18 + */ + deviceId?: number; + /** * Vibrator id, default is 0. *