/*
* Copyright (c) 2025 Huawei Device Co., Ltd.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @addtogroup Vibrator
* @{
*
* @brief Provides a driver for upper-layer vibrator services.
*
* After obtaining a driver object or agent, a vibrator service get vibrator ability or
* set the vibrator effect using the functions provided by the driver object or agent.
*
* @since 5.1
* @version 2.0
*/
/**
* @file IVibratorInterface.idl
*
* @brief Declares common APIs in the vibrator module. The APIs canObtains information about all the vibrator
* that support setting intensity and Start the vibrator according to the incoming vibration effect.
*
* @since 5.1
* @version 2.0
*/
package ohos.hdi.vibrator.v2_0;
import ohos.hdi.vibrator.v2_0.VibratorTypes;
import ohos.hdi.vibrator.v2_0.IVibratorPlugCallback;
interface IVibratorInterface {
/**
* @brief Controls the vibrator to perform a one-shot vibration that lasts for a given duration.
*
* One-shot vibration is mutually exclusive with periodic vibration. Before using one-shot vibration,
* exit periodic vibration.
*
* @param duration Indicates the duration that the one-shot vibration lasts, in milliseconds.
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
*
* @since 2.2
* @version 1.0
*/
StartOnce([in] DeviceVibratorInfo deviceVibratorInfo, [in] unsigned int duration);
/**
* @brief Controls the vibrator to perform a periodic vibration with the preset effect.
*
* One-shot vibration is mutually exclusive with periodic vibration. Before using periodic vibration,
* exit one-shot vibration.
*
* @param effectType Indicates the pointer to the preset effect type. It is recommended that the
* maximum length be 64 bytes.
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
*
* @since 2.2
* @version 1.0
*/
Start([in] DeviceVibratorInfo deviceVibratorInfo, [in] String effectType);
/**
* @brief Stops the vibration.
*
* Before the vibrator starts, it must stop vibrating in any mode. This function can be used during
* and after the vibrating process.
*
* @param mode Indicates the vibration mode, which can be one-shot or periodic. For details,
* see {@link HdfVibratorMode}.
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
*
* @since 2.2
* @version 1.0
*/
Stop([in] DeviceVibratorInfo deviceVibratorInfo, [in] enum HdfVibratorMode mode);
/**
* @brief Obtains information about all the vibrator that support setting intensity and frequency in the system.
*
* @param vibratorInfo Indicates the pointer to the vibration effect, For details, see {@link HdfVibratorInfo}.
*
* @return Returns <b>0</b> if the operation is successful.
* @return Returns negative value if the get failed.
*
* @since 3.2
* @version 1.1
*/
GetVibratorInfo([out] struct HdfVibratorInfo[] vibratorInfo);
/**
* @brief Obtains information about all the vibrator that support setting intensity and frequency in the system.
*
* @param vibratorInfo Indicates the pointer to the vibration effect, For details, see {@link HdfVibratorInfo}.
*
* @return Returns <b>0</b> if the operation is successful.
* @return Returns negative value if the get failed.
*
* @since 5.1
* @version 1.0
*/
GetDeviceVibratorInfo([in] DeviceVibratorInfo deviceVibratorInfo, [out] struct HdfVibratorInfo[] vibratorInfo);
/**
* @brief Obtains information about this device contains vibrator that support setting intensity and frequency in the system.
*
* @param vibratorInfo Indicates the pointer to the vibration effect, For details, see {@link HdfVibratorInfo}.
*
* @return Returns <b>0</b> if the operation is successful.
* @return Returns negative value if the get failed.
*
* @since 3.2
* @version 1.1
*/
GetVibratorIdSingle([in] DeviceVibratorInfo deviceVibratorInfo, [out] struct HdfVibratorInfo[] vibratorInfo);
/**
* @brief Start the vibrator according to the incoming vibration effect.
*
* @param duration Indicates the duration that the vibration lasts, in milliseconds.
*
* @param intensity Indicates vibrator intensity in a vibration period.
*
* @param frequency Indicates vibrator frequency in a vibration period.
*
* @return Returns <b>0</b> if the operation is successful.
* @return Returns <b>-1</b> if the vibrationPeriod setting is not supported.
* @return Returns <b>-2</b> if the intensity setting is not supported.
* @return Returns <b>-3</b> if the frequency setting is not supported.
*
* @since 3.2
* @version 1.1
*/
EnableVibratorModulation([in] DeviceVibratorInfo deviceVibratorInfo, [in] unsigned int duration,
[in] unsigned short intensity, [in] short frequency);
/**
* @brief Controls the vibrator to perform a periodic vibration with the custom composite effect.
*
* @param effect Indicates the pointer to the custom composite effect type. For details,
* see {@link HdfCompositeEffect}.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
*
* @since 3.2
* @version 1.1
*/
EnableCompositeEffect([in] DeviceVibratorInfo deviceVibratorInfo, [in] struct HdfCompositeEffect effect);
/**
* @brief Obtains the vibration effect information with the specified effect type.
*
* @param effectType Indicates the pointer to the preset effect type. It is recommended that the
* maximum length be 64 bytes.
*
* @param effectInfo Indicates the pointer to the vibration effect information. For details,
* see {@link HdfEffectInfo}.
*
* @return Returns <b>0</b> if the operation is successful.
* @return Returns negative value if the get failed.
*
* @since 3.2
* @version 1.1
*/
GetEffectInfo([in] DeviceVibratorInfo deviceVibratorInfo, [in] String effectType,
[out] struct HdfEffectInfo effectInfo);
/**
* @brief Obtains whether the vibrator is currently vibrating.
*
* @param state Indicates current vibration state of the vibrator.
*
* @return Returns <b>0</b> if the operation is successful.
* @return Returns negative value if the get failed.
*
* @since 3.2
* @version 1.1
*/
IsVibratorRunning([in] DeviceVibratorInfo deviceVibratorInfo, [out] boolean state);
/**
* @brief HD vibration data packet delivery.
*
* @param Indecates the Hd vibration data packet.
*
* @return Returns <b>0</b> if the operation is successful.
* @return Returns negative value if the get failed.
*
* @since 4.1
* @version 1.2
*/
PlayHapticPattern([in] DeviceVibratorInfo deviceVibratorInfo, [in] struct HapticPaket pkg);
/**
* @brief Obtains the vibration capability of the motor.
*
* @param Indecates the vibration capability of the motor.
*
* @return Returns <b>0</b> if the operation is successful.
* @return Returns negative value if the get failed.
*
* @since 4.1
* @version 1.2
*/
GetHapticCapacity([in] DeviceVibratorInfo deviceVibratorInfo, [out] struct HapticCapacity HapticCapacity);
/**
* @brief Obtains the start_up time of the motor.
*
* @param Indicates the time from command is issued to the time the motor starts.
*
* @return Returns <b>0</b> if the operation is successful.
* @return Returns negative value if the get failed.
*
* @since 4.1
* @version 1.2
*/
GetHapticStartUpTime([in] DeviceVibratorInfo deviceVibratorInfo, [in] int mode, [out] int startUpTime);
/**
* @brief Controls the vibrator to perform a periodic vibration with the preset effect.
*
* One-shot vibration is mutually exclusive with periodic vibration. Before using periodic vibration,
* exit one-shot vibration.
*
* @param effectType Indicates the pointer to the preset effect type. It is recommended that the
* maximum length be 64 bytes.
* @param intensity Indicates amplitude intensity, ranging from 1 to 100.
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
*
* @since 5.0
* @version 1.3
*/
StartByIntensity([in] DeviceVibratorInfo deviceVibratorInfo, [in] String effectType, [in] unsigned short intensity);
/**
* @brief Obtains the vibration wave information.
*
* @param vibratorId Indicates the vibration index.
* @param info Indicates the information.
*
* @return Returns <b>0</b> if the operation is successful.
* @return Returns negative value if the get failed.
*
* @since 5.0
* @version 1.3
*/
GetAllWaveInfo([in] DeviceVibratorInfo deviceVibratorInfo, [out] struct HdfWaveInformation[] info);
/**
* @brief Registers the callback for reporting vibrator plug state.
*
* The deviceId means which pluged in this device.
* the vibratorCnt means device contains vibrator count.
* The HapticCapacity means vibrator ability.
* is subscribed, and the subscription is successful once.
* @param callbackObj Indicates the callback to register. For details, see {@link IVibratorPlugCallback}.
* @return Returns <b>0</b> if the callback is successfully registered; returns a negative value otherwise.
*
* @since 5.1
* @version 2.0
*/
RegVibratorPlugCallback([in] IVibratorPlugCallback callbackObj);
/**
* @brief UnRegisters the callback for reporting vibrator plug state.
*
* The deviceId means which pluged in this device.
* the vibratorCnt means device contains vibrator count.
* The HapticCapacity means vibrator ability.
* is subscribed, and the subscription is successful once.
* @param callbackObj Indicates the callback to register. For details, see {@link IVibratorPlugCallback}.
* @return Returns <b>0</b> if the callback is successfully registered; returns a negative value otherwise.
*
* @since 5.1
* @version 2.0
*/
UnRegVibratorPlugCallback([in] IVibratorPlugCallback callbackObj);
/**
* @brief HD vibration data packet delivery.
* Indecates the Hd vibration data packet.
* @param deviceVibratorInfo, The default value of deviceId is -1, vibratorId is accumulated according to the number of motors.
* see {@link DeviceVibratorInfo}.
* @param The sessionId is sent by the audio framework.
* @param HapticPaket data is sent from the upper layer
* @return Returns <b>0</b> if the operation is successful.
* @return Returns negative value if the get failed.
*
* @since 6.0
* @version 1.0
*/
PlayPatternBySessionId([in] DeviceVibratorInfo deviceVibratorInfo, [in] unsigned int sessionId, [in] struct HapticPaket hapticPaket);
/**
* @brief HD vibration data packet delivery.
* Indecates the Hd vibration data packet.
* @param deviceVibratorInfo, The default value of deviceId is -1, vibratorId is accumulated according to the number of motors.
* see {@link DeviceVibratorInfo}.
* @param The sessionId is sent by the audio framework.
* @param VibratorPackage data is sent from the upper layer
* @return Returns <b>0</b> if the operation is successful.
* @return Returns negative value if the get failed.
*
* @since 6.0
* @version 1.0
*/
PlayPackageBySession([in] DeviceVibratorInfo deviceVibratorInfo, [in] unsigned int sessionId, [in] struct VibratorPackage vibratorPackage);
/**
* @brief Stops the vibration.
*
* Before the vibrator starts, it must stop vibrating in any mode. This function can be used during
* and after the vibrating process.
* @param deviceVibratorInfo, The default value of deviceId is -1, vibratorId is accumulated according to the number of motors.
* see {@link DeviceVibratorInfo}.
* @param The sessionId is sent by the audio framework.
* @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
*
* @since 6.0
* @version 1.0
*/
StopVibrateBySessionId([in] DeviceVibratorInfo deviceVibratorInfo, [in] unsigned int sessionId);
}