/*
 * Copyright (C) 2006 The Android Open Source Project
 *
 * 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.
 */

package android.os;

import android.annotation.CallbackExecutor;
import android.annotation.FlaggedApi;
import android.annotation.IntDef;
import android.annotation.NonNull;
import android.annotation.Nullable;
import android.annotation.RequiresPermission;
import android.annotation.SuppressLint;
import android.annotation.SystemApi;
import android.annotation.SystemService;
import android.annotation.TestApi;
import android.app.ActivityThread;
import android.compat.annotation.UnsupportedAppUsage;
import android.content.Context;
import android.content.res.Resources;
import android.hardware.vibrator.IVibrator;
import android.media.AudioAttributes;
import android.os.vibrator.Flags;
import android.os.vibrator.HapticGeneratorChannelStream;
import android.os.vibrator.HapticGeneratorSession;
import android.os.vibrator.VendorVibrationSession;
import android.os.vibrator.VibrationConfig;
import android.os.vibrator.VibratorEnvelopeEffectInfo;
import android.os.vibrator.VibratorFrequencyProfile;
import android.os.vibrator.VibratorFrequencyProfileLegacy;
import android.util.Log;
import android.view.HapticFeedbackConstants;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.util.concurrent.Executor;

/**
 * Class that operates the vibrator on the device.
 * <p>
 * If your process exits, any vibration you started will stop.
 * </p>
 */
@SystemService(Context.VIBRATOR_SERVICE)
@android.ravenwood.annotation.RavenwoodKeepPartialClass
public abstract class Vibrator {
    private static final String TAG = "Vibrator";

    /**
     * Vibration intensity: no vibrations.
     *
     * @hide
     */
    @TestApi
    public static final int VIBRATION_INTENSITY_OFF = 0;

    /**
     * Vibration intensity: low.
     *
     * @hide
     */
    @TestApi
    public static final int VIBRATION_INTENSITY_LOW = 1;

    /**
     * Vibration intensity: medium.
     *
     * @hide
     */
    @TestApi
    public static final int VIBRATION_INTENSITY_MEDIUM = 2;

    /**
     * Vibration intensity: high.
     *
     * @hide
     */
    @TestApi
    public static final int VIBRATION_INTENSITY_HIGH = 3;

    /**
     * Vibration effect support: unknown
     *
     * <p>The hardware doesn't report its supported effects, so we can't determine whether the
     * effect is supported or not.
     */
    public static final int VIBRATION_EFFECT_SUPPORT_UNKNOWN = 0;

    /**
     * Vibration effect support: supported
     *
     * <p>This effect is supported by the underlying hardware.
     */
    public static final int VIBRATION_EFFECT_SUPPORT_YES = 1;

    /**
     * Vibration effect support: unsupported
     *
     * <p>This effect is <b>not</b> natively supported by the underlying hardware, although
     * the system may still play a fallback vibration.
     */
    public static final int VIBRATION_EFFECT_SUPPORT_NO = 2;

    /** @hide */
    @Retention(RetentionPolicy.SOURCE)
    @IntDef(prefix = {"VIBRATION_EFFECT_SUPPORT_"}, value = {
            VIBRATION_EFFECT_SUPPORT_UNKNOWN,
            VIBRATION_EFFECT_SUPPORT_YES,
            VIBRATION_EFFECT_SUPPORT_NO,
    })
    public @interface VibrationEffectSupport {}

    /** @hide */
    @Retention(RetentionPolicy.SOURCE)
    @IntDef(prefix = {"VIBRATION_INTENSITY_"}, value = {
            VIBRATION_INTENSITY_OFF,
            VIBRATION_INTENSITY_LOW,
            VIBRATION_INTENSITY_MEDIUM,
            VIBRATION_INTENSITY_HIGH
    })
    public @interface VibrationIntensity {
    }

    private final String mPackageName;
    @Nullable
    private final Resources mResources;

    // This is lazily loaded only for the few clients that need this (e. Settings app).
    @Nullable
    private volatile VibrationConfig mVibrationConfig;

    private VibratorFrequencyProfile mVibratorFrequencyProfile;
    private VibratorEnvelopeEffectInfo mVibratorEnvelopeEffectInfo;

    /**
     * @hide to prevent subclassing from outside of the framework
     */
    @UnsupportedAppUsage
    @android.ravenwood.annotation.RavenwoodKeep
    public Vibrator() {
        mPackageName = ActivityThread.currentPackageName();
        mResources = null;
    }

    /**
     * @hide to prevent subclassing from outside of the framework
     */
    protected Vibrator(Context context) {
        mPackageName = context.getOpPackageName();
        mResources = context.getResources();
    }

    /**
     * Get the info describing this vibrator.
     *
     * @hide
     */
    public VibratorInfo getInfo() {
        return VibratorInfo.EMPTY_VIBRATOR_INFO;
    }

    /** Get the static vibrator configuration from config.xml. */
    private VibrationConfig getConfig() {
        if (mVibrationConfig == null) {
            Resources resources = mResources;
            if (resources == null) {
                final Context ctx = ActivityThread.currentActivityThread().getSystemContext();
                resources = ctx != null ? ctx.getResources() : null;
            }
            // This might be constructed more than once, but it only loads static config data from a
            // xml file, so it would be ok.
            mVibrationConfig = new VibrationConfig(resources);
        }
        return mVibrationConfig;
    }

    /**
     * Get the default vibration intensity for given usage.
     *
     * @hide
     */
    @TestApi
    @VibrationIntensity
    public int getDefaultVibrationIntensity(@VibrationAttributes.Usage int usage) {
        return getConfig().getDefaultVibrationIntensity(usage);
    }

    /**
     * Return the ID of this vibrator.
     *
     * @return A non-negative integer representing the id of the vibrator controlled by this
     * service, or -1 this service is not attached to any physical vibrator.
     */
    public int getId() {
        return getInfo().getId();
    }

    /**
     * Check whether the hardware has a vibrator.
     *
     * @return True if the hardware has a vibrator, else false.
     */
    public abstract boolean hasVibrator();

    /**
     * Check whether the vibrator has amplitude control.
     *
     * @return True if the hardware can control the amplitude of the vibrations, otherwise false.
     */
    public abstract boolean hasAmplitudeControl();

    /**
     * Check whether the vibrator has independent frequency control.
     *
     * @return True if the hardware can control the frequency of the vibrations independently of
     * the vibration amplitude, false otherwise.
     * @hide
     */
    @TestApi
    public boolean hasFrequencyControl() {
        return getInfo().hasFrequencyControl();
    }

    /**
     * Checks whether or not the vibrator supports all components of a given {@link VibrationEffect}
     * (i.e. the vibrator can play the given effect as intended).
     *
     * <p>If this method returns {@code true}, then the VibrationEffect should play as expected.
     * If {@code false}, playing the VibrationEffect might still make a vibration, but the vibration
     * may be significantly degraded from the intention.
     *
     * <p>This method aggregates the results of feature check methods such as
     * {@link #hasAmplitudeControl}, {@link #areAllPrimitivesSupported(int...)}, etc, depending
     * on the features that are actually used by the VibrationEffect.
     *
     * @param effect the {@link VibrationEffect} to check if it is supported
     * @return {@code true} if the vibrator can play the given {@code effect} as intended,
     *         {@code false} otherwise.
     *
     * @hide
     */
    public boolean areVibrationFeaturesSupported(@NonNull VibrationEffect effect) {
        return getInfo().areVibrationFeaturesSupported(effect);
    }

    /**
     * Check whether the vibrator has support for vendor-specific effects.
     *
     * <p>Vendor vibration effects can be created via {@link VibrationEffect#createVendorEffect}.
     *
     * @return True if the hardware can play vendor-specific vibration effects, false otherwise.
     * @hide
     */
    @SystemApi
    public boolean areVendorEffectsSupported() {
        return getInfo().hasCapability(IVibrator.CAP_PERFORM_VENDOR_EFFECTS);
    }

    /**
     * Check whether the vibrator has support for vendor-specific vibration sessions.
     *
     * <p>Vendor vibration sessions can be started via {@link #startVendorSession}.
     *
     * @return True if the hardware can play vendor-specific vibration sessions, false otherwise.
     * @hide
     */
    @SystemApi
    public boolean areVendorSessionsSupported() {
        return false;
    }

    /**
     * Check whether the vibrator can be controlled by an external service with the
     * {@link IExternalVibratorService}.
     *
     * @return True if the hardware can be controlled by an external service, otherwise false.
     * @hide
     */
    public boolean hasExternalControl() {
        return getInfo().hasCapability(IVibrator.CAP_EXTERNAL_CONTROL);
    }

    /**
     * Gets the resonant frequency of the vibrator, if applicable.
     *
     * @return the resonant frequency of the vibrator, or {@link Float#NaN NaN} if it's unknown, not
     * applicable, or if this vibrator is a composite of multiple physical devices with different
     * frequencies.
     */
    public float getResonantFrequency() {
        return getInfo().getResonantFrequencyHz();
    }

    /**
     * Gets the <a href="https://en.wikipedia.org/wiki/Q_factor">Q factor</a> of the vibrator.
     *
     * @return the Q factor of the vibrator, or {@link Float#NaN NaN} if it's unknown, not
     * applicable, or if this vibrator is a composite of multiple physical devices with different
     * Q factors.
     */
    public float getQFactor() {
        return getInfo().getQFactor();
    }

    /**
     * Gets the profile that describes the vibrator output across the supported frequency range.
     *
     * <p>The profile describes the relative output acceleration that the device can reach when it
     * vibrates at different frequencies.
     *
     * @return The frequency profile for this vibrator, or null if the vibrator does not have
     * frequency control. If this vibrator is a composite of multiple physical devices then this
     * will return a profile supported in all devices, or null if the intersection is empty or not
     * available.
     * @hide
     */
    @TestApi
    @SuppressLint("UnflaggedApi")
    @Nullable
    public VibratorFrequencyProfileLegacy getFrequencyProfileLegacy() {
        VibratorInfo.FrequencyProfileLegacy frequencyProfile =
                getInfo().getFrequencyProfileLegacy();
        if (frequencyProfile.isEmpty()) {
            return null;
        }
        return new VibratorFrequencyProfileLegacy(frequencyProfile);
    }

    /**
     * Gets the profile that describes the vibrator output across the supported frequency range.
     *
     * <p>The profile describes the output acceleration that the device can reach when it
     * vibrates at different frequencies.
     *
     * @return The frequency profile for this vibrator, or null if the vibrator does not have
     * frequency control. If this vibrator is a composite of multiple physical devices then this
     * will return a profile supported in all devices, or null if the intersection is empty or not
     * available.
     */
    @FlaggedApi(Flags.FLAG_NORMALIZED_PWLE_EFFECTS)
    @Nullable
    public VibratorFrequencyProfile getFrequencyProfile() {
        VibratorInfo.FrequencyProfile frequencyProfile = getInfo().getFrequencyProfile();
        if (frequencyProfile.isEmpty()) {
            return null;
        }

        if (mVibratorFrequencyProfile == null) {
            mVibratorFrequencyProfile = new VibratorFrequencyProfile(frequencyProfile);
        }

        return mVibratorFrequencyProfile;
    }

    /**
     * Return the maximum amplitude the vibrator can play using the audio haptic channels.
     *
     * <p>This is a positive value, or {@link Float#NaN NaN} if it's unknown. If this returns a
     * positive value <code>maxAmplitude</code>, then the signals from the haptic channels of audio
     * tracks should be in the range <code>[-maxAmplitude, maxAmplitude]</code>.
     *
     * @return a positive value representing the maximum absolute value the device can play signals
     * from audio haptic channels, or {@link Float#NaN NaN} if it's unknown.
     * @hide
     */
    public float getHapticChannelMaximumAmplitude() {
        return getConfig().getHapticChannelMaximumAmplitude();
    }

    /**
     * Checks whether the vibrator supports the creation of envelope effects.
     *
     * Envelope effects are defined by a series of frequency-amplitude pairs with specified
     * transition times, allowing the creation of more complex vibration patterns.
     *
     * @return True if the hardware supports creating envelope effects, false otherwise.
     */
    @FlaggedApi(Flags.FLAG_NORMALIZED_PWLE_EFFECTS)
    public boolean areEnvelopeEffectsSupported() {
        return getInfo().areEnvelopeEffectsSupported();
    }

    /**
     * Retrieves the vibrator's capabilities and limitations for envelope effects.
     *
     * <p>These parameters can be used with {@link VibrationEffect.WaveformEnvelopeBuilder}
     * to create custom envelope effects.
     *
     * @return The vibrator's envelope effect information, or null if not supported. If this
     * vibrator is a composite of multiple physical devices then this will return a profile
     * supported in all devices, or null if the intersection is empty or not available.
     *
     * @see VibrationEffect.WaveformEnvelopeBuilder
     */
    @FlaggedApi(Flags.FLAG_NORMALIZED_PWLE_EFFECTS)
    @NonNull
    public VibratorEnvelopeEffectInfo getEnvelopeEffectInfo() {
        if (mVibratorEnvelopeEffectInfo == null) {
            mVibratorEnvelopeEffectInfo = new VibratorEnvelopeEffectInfo(
                    getInfo().getMaxEnvelopeEffectSize(),
                    getInfo().getMinEnvelopeEffectControlPointDurationMillis(),
                    getInfo().getMaxEnvelopeEffectControlPointDurationMillis());
        }

        return mVibratorEnvelopeEffectInfo;
    }

    /**
     * Configure an always-on haptics effect.
     *
     * @param alwaysOnId The board-specific always-on ID to configure.
     * @param effect     Vibration effect to assign to always-on id. Passing null will disable it.
     * @param attributes {@link VibrationAttributes} corresponding to the vibration. For example,
     *                   specify {@link VibrationAttributes#USAGE_ALARM} for alarm vibrations or
     *                   {@link VibrationAttributes#USAGE_RINGTONE} for vibrations associated with
     *                   incoming calls. May only be null when effect is null.
     * @hide
     */
    @RequiresPermission(android.Manifest.permission.VIBRATE_ALWAYS_ON)
    public boolean setAlwaysOnEffect(int alwaysOnId, @Nullable VibrationEffect effect,
            @Nullable VibrationAttributes attributes) {
        return setAlwaysOnEffect(Process.myUid(), mPackageName, alwaysOnId, effect, attributes);
    }

    /**
     * @hide
     */
    @RequiresPermission(android.Manifest.permission.VIBRATE_ALWAYS_ON)
    public boolean setAlwaysOnEffect(int uid, String opPkg, int alwaysOnId,
            @Nullable VibrationEffect effect, @Nullable VibrationAttributes attributes) {
        Log.w(TAG, "Always-on effects aren't supported");
        return false;
    }

    /**
     * Vibrate constantly for the specified period of time.
     *
     * <p>The app should be in the foreground for the vibration to happen.</p>
     *
     * @param milliseconds The number of milliseconds to vibrate.
     * @deprecated Use {@link #vibrate(VibrationEffect)} instead.
     */
    @Deprecated
    @RequiresPermission(android.Manifest.permission.VIBRATE)
    public void vibrate(long milliseconds) {
        vibrate(milliseconds, null);
    }

    /**
     * Vibrate constantly for the specified period of time.
     *
     * <p>The app should be in the foreground for the vibration to happen. Background apps should
     * specify a ringtone, notification or alarm usage in order to vibrate.</p>
     *
     * @param milliseconds The number of milliseconds to vibrate.
     * @param attributes   {@link AudioAttributes} corresponding to the vibration. For example,
     *                     specify {@link AudioAttributes#USAGE_ALARM} for alarm vibrations or
     *                     {@link AudioAttributes#USAGE_NOTIFICATION_RINGTONE} for
     *                     vibrations associated with incoming calls.
     * @deprecated Use {@link #vibrate(VibrationEffect, VibrationAttributes)} instead.
     */
    @Deprecated
    @RequiresPermission(android.Manifest.permission.VIBRATE)
    public void vibrate(long milliseconds, AudioAttributes attributes) {
        try {
            // This ignores all exceptions to stay compatible with pre-O implementations.
            VibrationEffect effect =
                    VibrationEffect.createOneShot(milliseconds, VibrationEffect.DEFAULT_AMPLITUDE);
            vibrate(effect, attributes);
        } catch (IllegalArgumentException iae) {
            Log.e(TAG, "Failed to create VibrationEffect", iae);
        }
    }

    /**
     * Vibrate with a given pattern.
     *
     * <p>
     * Pass in an array of ints that are the durations for which to turn on or off
     * the vibrator in milliseconds.  The first value indicates the number of milliseconds
     * to wait before turning the vibrator on.  The next value indicates the number of milliseconds
     * for which to keep the vibrator on before turning it off.  Subsequent values alternate
     * between durations in milliseconds to turn the vibrator off or to turn the vibrator on.
     * </p><p>
     * To cause the pattern to repeat, pass the index into the pattern array at which
     * to start the repeat, or -1 to disable repeating.
     * </p>
     *
     * <p>The app should be in the foreground for the vibration to happen.</p>
     *
     * @param pattern an array of longs of times for which to turn the vibrator on or off.
     * @param repeat  the index into pattern at which to repeat, or -1 if
     *                you don't want to repeat.
     * @deprecated Use {@link #vibrate(VibrationEffect)} instead.
     */
    @Deprecated
    @RequiresPermission(android.Manifest.permission.VIBRATE)
    public void vibrate(long[] pattern, int repeat) {
        vibrate(pattern, repeat, null);
    }

    /**
     * Vibrate with a given pattern.
     *
     * <p>
     * Pass in an array of ints that are the durations for which to turn on or off
     * the vibrator in milliseconds.  The first value indicates the number of milliseconds
     * to wait before turning the vibrator on.  The next value indicates the number of milliseconds
     * for which to keep the vibrator on before turning it off.  Subsequent values alternate
     * between durations in milliseconds to turn the vibrator off or to turn the vibrator on.
     * </p><p>
     * To cause the pattern to repeat, pass the index into the pattern array at which
     * to start the repeat, or -1 to disable repeating.
     * </p>
     *
     * <p>The app should be in the foreground for the vibration to happen. Background apps should
     * specify a ringtone, notification or alarm usage in order to vibrate.</p>
     *
     * @param pattern    an array of longs of times for which to turn the vibrator on or off.
     * @param repeat     the index into pattern at which to repeat, or -1 if
     *                   you don't want to repeat.
     * @param attributes {@link AudioAttributes} corresponding to the vibration. For example,
     *                   specify {@link AudioAttributes#USAGE_ALARM} for alarm vibrations or
     *                   {@link AudioAttributes#USAGE_NOTIFICATION_RINGTONE} for
     *                   vibrations associated with incoming calls.
     * @deprecated Use {@link #vibrate(VibrationEffect, VibrationAttributes)} instead.
     */
    @Deprecated
    @RequiresPermission(android.Manifest.permission.VIBRATE)
    public void vibrate(long[] pattern, int repeat, AudioAttributes attributes) {
        // This call needs to continue throwing ArrayIndexOutOfBoundsException but ignore all other
        // exceptions for compatibility purposes
        if (repeat < -1 || repeat >= pattern.length) {
            Log.e(TAG, "vibrate called with repeat index out of bounds" +
                    " (pattern.length=" + pattern.length + ", index=" + repeat + ")");
            throw new ArrayIndexOutOfBoundsException();
        }

        try {
            vibrate(VibrationEffect.createWaveform(pattern, repeat), attributes);
        } catch (IllegalArgumentException iae) {
            Log.e(TAG, "Failed to create VibrationEffect", iae);
        }
    }

    /**
     * Vibrate with a given effect.
     *
     * <p>The app should be in the foreground for the vibration to happen.</p>
     *
     * @param vibe {@link VibrationEffect} describing the vibration to be performed.
     */
    @RequiresPermission(android.Manifest.permission.VIBRATE)
    public void vibrate(VibrationEffect vibe) {
        vibrate(vibe, new VibrationAttributes.Builder().build());
    }

    /**
     * Vibrate with a given effect.
     *
     * <p>The app should be in the foreground for the vibration to happen. Background apps should
     * specify a ringtone, notification or alarm usage in order to vibrate.</p>
     *
     * @param vibe       {@link VibrationEffect} describing the vibration to be performed.
     * @param attributes {@link AudioAttributes} corresponding to the vibration. For example,
     *                   specify {@link AudioAttributes#USAGE_ALARM} for alarm vibrations or
     *                   {@link AudioAttributes#USAGE_NOTIFICATION_RINGTONE} for
     *                   vibrations associated with incoming calls.
     * @deprecated Use {@link #vibrate(VibrationEffect, VibrationAttributes)} instead.
     */
    @RequiresPermission(android.Manifest.permission.VIBRATE)
    public void vibrate(VibrationEffect vibe, AudioAttributes attributes) {
        vibrate(vibe,
                attributes == null
                        ? new VibrationAttributes.Builder().build()
                        : new VibrationAttributes.Builder(attributes).build());
    }

    /**
     * Vibrate with a given effect.
     *
     * <p>The app should be in the foreground for the vibration to happen. Background apps should
     * specify a ringtone, notification or alarm usage in order to vibrate.</p>
     *
     * @param vibe       {@link VibrationEffect} describing the vibration to be performed.
     * @param attributes {@link VibrationAttributes} corresponding to the vibration. For example,
     *                   specify {@link VibrationAttributes#USAGE_ALARM} for alarm vibrations or
     *                   {@link VibrationAttributes#USAGE_RINGTONE} for vibrations associated with
     *                   incoming calls.
     */
    @RequiresPermission(android.Manifest.permission.VIBRATE)
    public void vibrate(@NonNull VibrationEffect vibe, @NonNull VibrationAttributes attributes) {
        vibrate(vibe, attributes, null);
    }

    /**
     * Vibrate with a given effect.
     *
     * <p>The app should be in the foreground for the vibration to happen. Background apps should
     * specify a ringtone, notification or alarm usage in order to vibrate.</p>
     *
     * @param vibe       {@link VibrationEffect} describing the vibration to be performed.
     * @param attributes {@link VibrationAttributes} corresponding to the vibration. For example,
     *                   specify {@link VibrationAttributes#USAGE_ALARM} for alarm vibrations or
     *                   {@link VibrationAttributes#USAGE_RINGTONE} for vibrations associated with
     *                   incoming calls.
     * @param reason     the reason for this vibration, used for debugging purposes.
     * @hide
     */
    @RequiresPermission(android.Manifest.permission.VIBRATE)
    public void vibrate(@NonNull VibrationEffect vibe,
            @NonNull VibrationAttributes attributes, String reason) {
        vibrate(Process.myUid(), mPackageName, vibe, reason, attributes);
    }

    /**
     * Like {@link #vibrate(VibrationEffect, VibrationAttributes)}, but allows the
     * caller to specify the vibration is owned by someone else and set a reason for vibration.
     *
     * @hide
     */
    @RequiresPermission(android.Manifest.permission.VIBRATE)
    public abstract void vibrate(int uid, String opPkg, @NonNull VibrationEffect vibe,
            String reason, @NonNull VibrationAttributes attributes);

    /**
     * Performs a haptic feedback.
     *
     * <p>A haptic feedback is a short vibration feedback. The type of feedback is identified via
     * the {@code constant}, which should be one of the effect constants provided in
     * {@link HapticFeedbackConstants}. The haptic feedback provided for a given effect ID is
     * consistent across all usages on the same device.
     *
     * @param constant the ID for the haptic feedback. This should be one of the constants defined
     *          in {@link HapticFeedbackConstants}.
     * @param usage one of the {@link VibrationAttributes} usages with the class
     *      {@link USAGE_CLASS_FEEDBACK}. Use {@link USAGE_UNKNOWN} if you are not sure about which
     *      usage to use, and the system will assign a default usage.
     * @param reason the reason for this haptic feedback.
     * @param flags Additional flags as per {@link HapticFeedbackConstants}.
     * @param privFlags Additional private flags as per {@link HapticFeedbackConstants}.
     *
     * @hide
     */
    public void performHapticFeedback(int constant, @VibrationAttributes.Usage int usage,
            String reason, @HapticFeedbackConstants.Flags int flags,
            @HapticFeedbackConstants.PrivateFlags int privFlags) {
        Log.w(TAG, "performHapticFeedback is not supported");
    }

    /**
     * Performs a haptic feedback. Similar to {@link #performHapticFeedback} but also take into the
     * consideration the {@link InputDevice} that triggered the haptic
     *
     * <p>A haptic feedback is a short vibration feedback. The type of feedback is identified via
     * the {@code constant}, which should be one of the effect constants provided in
     * {@link HapticFeedbackConstants}. The haptic feedback provided for a given effect ID is
     * consistent across all usages on the same device.
     *
     * @param constant      the ID for the haptic feedback. This should be one of the constants
     *                      defined in {@link HapticFeedbackConstants}.
     * @param inputDeviceId the integer id of the input device that triggered the haptic feedback.
     * @param inputSource   the {@link InputDevice.Source} that triggered the haptic feedback.
     * @param reason        the reason for this haptic feedback.
     * @param flags         Additional flags as per {@link HapticFeedbackConstants}.
     * @param privFlags     Additional private flags as per {@link HapticFeedbackConstants}.
     * @hide
     */
    public void performHapticFeedbackForInputDevice(
            int constant, int inputDeviceId, int inputSource, String reason,
            @HapticFeedbackConstants.Flags int flags,
            @HapticFeedbackConstants.PrivateFlags int privFlags) {
        Log.w(TAG, "performHapticFeedbackForInputDevice is not supported");
    }

    /**
     * Query whether the vibrator natively supports the given effects.
     *
     * <p>If an effect is not supported, the system may still automatically fall back to playing
     * a simpler vibration instead, which is not optimised for the specific device. This includes
     * the unknown case, which can't be determined in advance, that will dynamically attempt to
     * fall back if the optimised effect fails to play.
     *
     * <p>The returned array will be the same length as the query array and the value at a given
     * index will contain {@link #VIBRATION_EFFECT_SUPPORT_YES} if the effect at that same index
     * in the querying array is supported, {@link #VIBRATION_EFFECT_SUPPORT_NO} if it isn't
     * supported, or {@link #VIBRATION_EFFECT_SUPPORT_UNKNOWN} if the system can't determine whether
     * it's supported or not, as some hardware doesn't report its effect capabilities.
     *
     * <p>Use {@link #areAllEffectsSupported(int...)} to get a single combined result,
     * or for convenience when querying exactly one effect.
     *
     * @param effectIds Which effects to query for.
     * @return An array containing the systems current knowledge about whether the given effects
     * are natively supported by the device, or not.
     */
    @NonNull
    @VibrationEffectSupport
    public int[] areEffectsSupported(
            @NonNull @VibrationEffect.EffectType int... effectIds) {
        VibratorInfo info = getInfo();
        int[] supported = new int[effectIds.length];
        for (int i = 0; i < effectIds.length; i++) {
            supported[i] = info.isEffectSupported(effectIds[i]);
        }
        return supported;
    }

    /**
     * Query whether the vibrator supports all the given effects. If no argument is provided this
     * method will always return {@link #VIBRATION_EFFECT_SUPPORT_YES}.
     *
     * <p>If an effect is not supported, the system may still automatically fall back to a simpler
     * vibration instead, which is not optimised for the specific device, however vibration isn't
     * guaranteed in this case.
     *
     * <p>If the result is {@link #VIBRATION_EFFECT_SUPPORT_YES}, all effects in the query are
     * supported by the hardware.
     *
     * <p>If the result is {@link #VIBRATION_EFFECT_SUPPORT_NO}, at least one of the effects in the
     * query is not supported, and using them may fall back to an un-optimized vibration or no
     * vibration.
     *
     * <p>If the result is {@link #VIBRATION_EFFECT_SUPPORT_UNKNOWN}, the system doesn't know
     * whether all the effects are supported. It may support any or all of the queried effects,
     * but there's no way to programmatically know whether a {@link #vibrate} call will successfully
     * cause a vibration. It's guaranteed, however, that none of the queried effects are
     * definitively unsupported by the hardware.
     *
     * <p>Use {@link #areEffectsSupported(int...)} to get individual results for each effect.
     *
     * @param effectIds Which effects to query for.
     * @return Whether all specified effects are natively supported by the device. Empty query
     * defaults to {@link #VIBRATION_EFFECT_SUPPORT_YES}.
     */
    @VibrationEffectSupport
    public final int areAllEffectsSupported(
            @NonNull @VibrationEffect.EffectType int... effectIds) {
        VibratorInfo info = getInfo();
        int allSupported = VIBRATION_EFFECT_SUPPORT_YES;
        for (int effectId : effectIds) {
            switch (info.isEffectSupported(effectId)) {
                case VIBRATION_EFFECT_SUPPORT_NO:
                    return VIBRATION_EFFECT_SUPPORT_NO;
                case VIBRATION_EFFECT_SUPPORT_YES:
                    continue;
                default: // VIBRATION_EFFECT_SUPPORT_UNKNOWN
                    allSupported = VIBRATION_EFFECT_SUPPORT_UNKNOWN;
                    break;
            }
        }
        return allSupported;
    }

    /**
     * Query whether the vibrator supports the given primitives.
     *
     * The returned array will be the same length as the query array and the value at a given index
     * will contain whether the effect at that same index in the querying array is supported or
     * not.
     *
     * <p>If a primitive is not supported by the device, then <em>no vibration</em> will occur if
     * it is played.
     *
     * <p>Use {@link #areAllPrimitivesSupported(int...)} to get a single combined result,
     * or for convenience when querying exactly one primitive.
     *
     * @param primitiveIds Which primitives to query for.
     * @return Whether the primitives are supported.
     */
    @NonNull
    public boolean[] arePrimitivesSupported(
            @NonNull @VibrationEffect.Composition.PrimitiveType int... primitiveIds) {
        VibratorInfo info = getInfo();
        boolean[] supported = new boolean[primitiveIds.length];
        for (int i = 0; i < primitiveIds.length; i++) {
            supported[i] = info.isPrimitiveSupported(primitiveIds[i]);
        }
        return supported;
    }

    /**
     * Query whether the vibrator supports all of the given primitives.  If no argument is provided
     * this method will always return {@code true}.
     *
     * <p>If a primitive is not supported by the device, then <em>no vibration</em> will occur if
     * it is played.
     *
     * <p>Use {@link #arePrimitivesSupported(int...)} to get individual results for each primitive.
     *
     * @param primitiveIds Which primitives to query for.
     * @return Whether all specified primitives are supported. Empty query defaults to {@code true}.
     */
    public final boolean areAllPrimitivesSupported(
            @NonNull @VibrationEffect.Composition.PrimitiveType int... primitiveIds) {
        VibratorInfo info = getInfo();
        for (int primitiveId : primitiveIds) {
            if (!info.isPrimitiveSupported(primitiveId)) {
                return false;
            }
        }
        return true;
    }

    /**
     * Query the estimated durations of the given primitives.
     *
     * <p>The returned array will be the same length as the query array and the value at a given
     * index will contain the duration in milliseconds of the effect at the same index in the
     * querying array.
     *
     * <p>The duration will be positive for primitives that are supported and zero for the
     * unsupported ones, in correspondence with {@link #arePrimitivesSupported(int...)}.
     *
     * @param primitiveIds Which primitives to query for.
     * @return The duration of each primitive, with zeroes for primitives that are not supported.
     */
    @NonNull
    public int[] getPrimitiveDurations(
            @NonNull @VibrationEffect.Composition.PrimitiveType int... primitiveIds) {
        VibratorInfo info = getInfo();
        int[] durations = new int[primitiveIds.length];
        for (int i = 0; i < primitiveIds.length; i++) {
            durations[i] = info.getPrimitiveDuration(primitiveIds[i]);
        }
        return durations;
    }

    /**
     * Turn the vibrator off.
     */
    @RequiresPermission(android.Manifest.permission.VIBRATE)
    public abstract void cancel();

    /**
     * Cancel specific types of ongoing vibrations.
     *
     * @param usageFilter The type of vibration to be cancelled, represented as a bitwise
     *                    combination of {@link VibrationAttributes.Usage} values.
     * @hide
     */
    @RequiresPermission(android.Manifest.permission.VIBRATE)
    public abstract void cancel(int usageFilter);

    /**
     * Check whether the vibrator is vibrating.
     *
     * @return True if the hardware is vibrating, otherwise false.
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.ACCESS_VIBRATOR_STATE)
    public boolean isVibrating() {
        return false;
    }

    /**
    * Listener for when the vibrator state has changed.
    *
    * @see #addVibratorStateListener
    * @see #removeVibratorStateListener
    * @hide
    */
    @SystemApi
    public interface OnVibratorStateChangedListener  {
        /**
         * Called when the vibrator state has changed.
         *
         * @param isVibrating If true, the vibrator has started vibrating. If false,
         *                    it's stopped vibrating.
         */
        void onVibratorStateChanged(boolean isVibrating);
    }

    /**
     * Adds a listener for vibrator state changes. Callbacks will be executed on the main thread.
     * If the listener was previously added and not removed, this call will be ignored.
     *
     * @param listener listener to be added
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.ACCESS_VIBRATOR_STATE)
    public void addVibratorStateListener(@NonNull OnVibratorStateChangedListener listener) {
    }

    /**
     * Adds a listener for vibrator state change. If the listener was previously added and not
     * removed, this call will be ignored.
     *
     * @param listener listener to be added
     * @param executor executor of listener
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.ACCESS_VIBRATOR_STATE)
    public void addVibratorStateListener(
            @NonNull @CallbackExecutor Executor executor,
            @NonNull OnVibratorStateChangedListener listener) {
    }

    /**
     * Removes the listener for vibrator state changes. If the listener was not previously
     * registered, this call will do nothing.
     *
     * @param listener listener to be removed
     * @hide
     */
    @SystemApi
    @RequiresPermission(android.Manifest.permission.ACCESS_VIBRATOR_STATE)
    public void removeVibratorStateListener(@NonNull OnVibratorStateChangedListener listener) {
    }

    /**
     * Starts a vibration session in this vibrator.
     *
     * <p>The session will start asynchronously once the vibrator control can be acquired. Once it's
     * started the {@link VendorVibrationSession} will be provided to the callback. This session
     * should be used to play vibrations until the session is ended or canceled.
     *
     * <p>The vendor app will have exclusive control over the vibrator during this session. This
     * control can be revoked by the vibrator service, which will be notified to the same session
     * callback with the {@link VendorVibrationSession#STATUS_CANCELED}.
     *
     * <p>The {@link VibrationAttributes} will be used to decide the priority of the vendor
     * vibrations that will be performed in this session. All vibrations within this session will
     * apply the same attributes.
     *
     * @param attrs    The {@link VibrationAttributes} corresponding to the vibrations that will be
     *                 performed in the session. This will be used to decide the priority of this
     *                 session against other system vibrations.
     * @param reason   The description for this session, used for debugging purposes.
     * @param cancellationSignal A signal to cancel the session before it starts.
     * @param executor The executor for the session callbacks.
     * @param callback The {@link VendorVibrationSession.Callback} for the started session.
     *
     * @see VendorVibrationSession
     * @hide
     */
    @SystemApi
    @RequiresPermission(allOf = {
            android.Manifest.permission.VIBRATE,
            android.Manifest.permission.VIBRATE_VENDOR_EFFECTS,
            android.Manifest.permission.START_VIBRATION_SESSIONS,
    })
    public void startVendorSession(@NonNull VibrationAttributes attrs, @Nullable String reason,
            @Nullable CancellationSignal cancellationSignal, @NonNull Executor executor,
            @NonNull VendorVibrationSession.Callback callback) {
        Log.w(TAG, "startVendorSession is not supported");
        executor.execute(() -> callback.onFinished(VendorVibrationSession.STATUS_UNSUPPORTED));
    }

    /**
     * Asynchronously starts a new haptic generator session.
     *
     * <p>A haptic generator session allows an application to convert a {@link VibrationEffect}
     * into a stream of haptic PCM data. This is useful for creating precisely synchronized
     * audio-coupled haptic experiences.
     *
     * <p>On success, the {@code callback} receives a {@link HapticGeneratorSession} instance.
     * This session object can then be used to generate one or more
     * {@link HapticGeneratorChannelStream}s by calling
     * {@link HapticGeneratorSession#generateHapticChannelStream(VibrationEffect)}.
     *
     * <p>The session holds system resources and <strong>must</strong> be closed by calling
     * {@link HapticGeneratorSession#close()} when it is no longer needed to release these
     * resources.
     *
     * @param config   The configuration for the haptic generator session.
     * @param executor The executor on which to invoke the callback.
     * @param callback The callback that will receive the {@link HapticGeneratorSession} on success,
     *                 or an {@link Exception} on failure.
     * @hide
     */
    @SystemApi
    @FlaggedApi(Flags.FLAG_HAPTIC_PCM_GENERATION)
    @RequiresPermission(android.Manifest.permission.USE_VIBRATOR_HAPTIC_GENERATOR)
    public void startHapticGeneratorSession(
            @NonNull HapticGeneratorSession.Config config,
            @NonNull Executor executor,
            @NonNull OutcomeReceiver<HapticGeneratorSession, Exception> callback) {
        Log.w(TAG, "startHapticGeneratorSession is not supported");
        executor.execute(() -> {
            callback.onError(new UnsupportedOperationException());
        });
    }

    /**
     * Checks whether the vibrator supports creating haptic generator sessions.
     *
     * @return {@code true} if the haptic generator is supported, {@code false} otherwise.
     * @hide
     */
    @SystemApi
    @FlaggedApi(Flags.FLAG_HAPTIC_PCM_GENERATION)
    public boolean isHapticGeneratorSupported() {
        return false;
    }
}
