| /* |
| * Copyright (C) 2019 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.IntDef; |
| import android.annotation.NonNull; |
| import android.annotation.Nullable; |
| import android.annotation.TestApi; |
| import android.media.AudioAttributes; |
| |
| import java.lang.annotation.Retention; |
| import java.lang.annotation.RetentionPolicy; |
| import java.util.Objects; |
| |
| /** |
| * Encapsulates a collection of attributes describing information about a vibration. |
| */ |
| @android.ravenwood.annotation.RavenwoodKeepWholeClass |
| public final class VibrationAttributes implements Parcelable { |
| private static final String TAG = "VibrationAttributes"; |
| |
| /** @hide */ |
| @IntDef(prefix = { "USAGE_CLASS_" }, value = { |
| USAGE_CLASS_UNKNOWN, |
| USAGE_CLASS_ALARM, |
| USAGE_CLASS_FEEDBACK, |
| USAGE_CLASS_MEDIA, |
| }) |
| @Retention(RetentionPolicy.SOURCE) |
| public @interface UsageClass {} |
| |
| /** @hide */ |
| @IntDef(prefix = { "USAGE_" }, value = { |
| USAGE_UNKNOWN, |
| USAGE_ACCESSIBILITY, |
| USAGE_ALARM, |
| USAGE_COMMUNICATION_REQUEST, |
| USAGE_HARDWARE_FEEDBACK, |
| USAGE_MEDIA, |
| USAGE_NOTIFICATION, |
| USAGE_PHYSICAL_EMULATION, |
| USAGE_RINGTONE, |
| USAGE_TOUCH, |
| }) |
| @Retention(RetentionPolicy.SOURCE) |
| public @interface Usage {} |
| |
| /** |
| * Vibration usage filter value to match all usages. |
| * @hide |
| */ |
| public static final int USAGE_FILTER_MATCH_ALL = -1; |
| /** |
| * Vibration usage class value to use when the vibration usage class is unknown. |
| */ |
| public static final int USAGE_CLASS_UNKNOWN = 0x0; |
| /** |
| * Vibration usage class value to use when the vibration is initiated to catch user's |
| * attention, such as alarm, ringtone, and notification vibrations. |
| */ |
| public static final int USAGE_CLASS_ALARM = 0x1; |
| /** |
| * Vibration usage class value to use when the vibration is initiated as a response to user's |
| * actions, such as emulation of physical effects, and texting feedback vibration. |
| */ |
| public static final int USAGE_CLASS_FEEDBACK = 0x2; |
| /** |
| * Vibration usage class value to use when the vibration is part of media, such as music, movie, |
| * soundtrack, game or animations. |
| */ |
| public static final int USAGE_CLASS_MEDIA = 0x3; |
| |
| /** |
| * Mask for vibration usage class value. |
| */ |
| public static final int USAGE_CLASS_MASK = 0xF; |
| |
| /** |
| * Usage value to use when usage is unknown. |
| */ |
| public static final int USAGE_UNKNOWN = 0x0 | USAGE_CLASS_UNKNOWN; |
| /** |
| * Usage value to use for alarm vibrations. |
| */ |
| public static final int USAGE_ALARM = 0x10 | USAGE_CLASS_ALARM; |
| /** |
| * Usage value to use for ringtone vibrations. |
| */ |
| public static final int USAGE_RINGTONE = 0x20 | USAGE_CLASS_ALARM; |
| /** |
| * Usage value to use for notification vibrations. |
| */ |
| public static final int USAGE_NOTIFICATION = 0x30 | USAGE_CLASS_ALARM; |
| /** |
| * Usage value to use for vibrations which mean a request to enter/end a |
| * communication with the user, such as a voice prompt. |
| */ |
| public static final int USAGE_COMMUNICATION_REQUEST = 0x40 | USAGE_CLASS_ALARM; |
| /** |
| * Usage value to use for touch vibrations. |
| * |
| * <p>Most typical haptic feedback should be classed as <em>touch</em> feedback. Examples |
| * include vibrations for tap, long press, drag and scroll. |
| */ |
| public static final int USAGE_TOUCH = 0x10 | USAGE_CLASS_FEEDBACK; |
| /** |
| * Usage value to use for vibrations which emulate physical hardware reactions, |
| * such as edge squeeze. |
| * |
| * <p>Note that normal screen-touch feedback "click" effects would typically be |
| * classed as {@link #USAGE_TOUCH}, and that on-screen "physical" animations |
| * like bouncing would be {@link #USAGE_MEDIA}. |
| */ |
| public static final int USAGE_PHYSICAL_EMULATION = 0x20 | USAGE_CLASS_FEEDBACK; |
| /** |
| * Usage value to use for vibrations which provide a feedback for hardware |
| * component interaction, such as a fingerprint sensor. |
| */ |
| public static final int USAGE_HARDWARE_FEEDBACK = 0x30 | USAGE_CLASS_FEEDBACK; |
| /** |
| * Usage value to use for accessibility vibrations, such as with a screen reader. |
| */ |
| public static final int USAGE_ACCESSIBILITY = 0x40 | USAGE_CLASS_FEEDBACK; |
| /** |
| * Usage value to use for media vibrations, such as music, movie, soundtrack, animations, games, |
| * or any interactive media that isn't for touch feedback specifically. |
| */ |
| public static final int USAGE_MEDIA = 0x10 | USAGE_CLASS_MEDIA; |
| |
| /** @hide */ |
| @IntDef(prefix = { "CATEGORY_" }, value = { |
| CATEGORY_UNKNOWN, |
| CATEGORY_KEYBOARD, |
| }) |
| @Retention(RetentionPolicy.SOURCE) |
| public @interface Category {} |
| |
| /** |
| * Category value when the vibration category is unknown. |
| * |
| * @hide |
| */ |
| public static final int CATEGORY_UNKNOWN = 0x0; |
| |
| /** |
| * Category value for keyboard vibrations. |
| * |
| * <p>Most typical keyboard vibrations are haptic feedback for virtual keyboard key |
| * press/release, for example. |
| * |
| * @hide |
| */ |
| public static final int CATEGORY_KEYBOARD = 1; |
| |
| /** |
| * @hide |
| */ |
| @IntDef(prefix = { "FLAG_" }, flag = true, value = { |
| FLAG_BYPASS_INTERRUPTION_POLICY, |
| FLAG_BYPASS_USER_VIBRATION_INTENSITY_OFF, |
| FLAG_INVALIDATE_SETTINGS_CACHE, |
| FLAG_PIPELINED_EFFECT, |
| FLAG_BYPASS_USER_VIBRATION_INTENSITY_SCALE |
| }) |
| @Retention(RetentionPolicy.SOURCE) |
| public @interface Flag{} |
| |
| /** |
| * Flag requesting vibration effect to be played even under limited interruptions. |
| * |
| * <p>Only privileged apps can ignore user settings that limit interruptions, and this |
| * flag will be ignored otherwise. |
| */ |
| public static final int FLAG_BYPASS_INTERRUPTION_POLICY = 1; |
| |
| /** |
| * Flag requesting vibration effect to be played even when user settings are disabling it. |
| * |
| * <p>Flag introduced to represent |
| * {@link android.view.HapticFeedbackConstants#FLAG_IGNORE_GLOBAL_SETTING} and |
| * {@link AudioAttributes#FLAG_BYPASS_MUTE}. |
| * |
| * <p>Only privileged apps can ignore user settings, and this flag will be ignored otherwise. |
| * |
| * @hide |
| */ |
| public static final int FLAG_BYPASS_USER_VIBRATION_INTENSITY_OFF = 1 << 1; |
| |
| /** |
| * Flag requesting vibration effect to be played with fresh user settings values. |
| * |
| * <p>This flag is not protected by any permission, but vibrations that use it require an extra |
| * query of user vibration intensity settings, ringer mode and other controls that affect the |
| * vibration effect playback, which can increase the latency for the overall request. |
| * |
| * <p>This is intended to be used on scenarios where the user settings might have changed |
| * recently, and needs to be applied to this vibration, like settings controllers that preview |
| * newly set intensities to the user. |
| * |
| * @hide |
| */ |
| public static final int FLAG_INVALIDATE_SETTINGS_CACHE = 1 << 2; |
| |
| /** |
| * Flag requesting that this vibration effect be pipelined with other vibration effects from the |
| * same package that also carry this flag. |
| * |
| * <p>Pipelined effects won't cancel a running pipelined effect, but will instead play after |
| * it completes. However, only one pipelined effect can be waiting at a time - so if an effect |
| * is already waiting (but not running), it will be cancelled in favor of a newer one. |
| * |
| * @hide |
| */ |
| public static final int FLAG_PIPELINED_EFFECT = 1 << 3; |
| |
| /** |
| * Flag requesting that this vibration effect to be played without applying the user |
| * intensity setting to scale the vibration. |
| * |
| * <p>The user setting is still applied to enable/disable the vibration, but the vibration |
| * effect strength will not be scaled based on the enabled setting value. |
| * |
| * <p>This is intended to be used on scenarios where the system needs to enforce a specific |
| * strength for the vibration effect, regardless of the user preference. Only privileged apps |
| * can ignore user settings, and this flag will be ignored otherwise. |
| * |
| * <p>If you need to bypass the user setting when it's disabling vibrations then this also |
| * needs the flag {@link #FLAG_BYPASS_USER_VIBRATION_INTENSITY_OFF} to be set. |
| * |
| * @hide |
| */ |
| public static final int FLAG_BYPASS_USER_VIBRATION_INTENSITY_SCALE = 1 << 4; |
| |
| /** |
| * All flags supported by vibrator service, update it when adding new flag. |
| * @hide |
| */ |
| public static final int FLAG_ALL_SUPPORTED = |
| FLAG_BYPASS_INTERRUPTION_POLICY | FLAG_BYPASS_USER_VIBRATION_INTENSITY_OFF |
| | FLAG_INVALIDATE_SETTINGS_CACHE | FLAG_PIPELINED_EFFECT |
| | FLAG_BYPASS_USER_VIBRATION_INTENSITY_SCALE; |
| |
| /** Creates a new {@link VibrationAttributes} instance with given usage. */ |
| public static @NonNull VibrationAttributes createForUsage(@Usage int usage) { |
| return new VibrationAttributes.Builder().setUsage(usage).build(); |
| } |
| |
| private final int mUsage; |
| private final int mFlags; |
| private final int mOriginalAudioUsage; |
| private final int mCategory; |
| |
| private VibrationAttributes(@Usage int usage, @AudioAttributes.AttributeUsage int audioUsage, |
| @Flag int flags, @Category int category) { |
| mUsage = usage; |
| mOriginalAudioUsage = audioUsage; |
| mFlags = flags & FLAG_ALL_SUPPORTED; |
| mCategory = category; |
| } |
| |
| /** |
| * Return the vibration usage class. |
| */ |
| @UsageClass |
| public int getUsageClass() { |
| return mUsage & USAGE_CLASS_MASK; |
| } |
| |
| /** |
| * Return the vibration usage. |
| */ |
| @Usage |
| public int getUsage() { |
| return mUsage; |
| } |
| |
| /** |
| * Return the original {@link AudioAttributes} used to create the vibration attributes. |
| * @hide |
| */ |
| @AudioAttributes.AttributeUsage |
| public int getOriginalAudioUsage() { |
| return mOriginalAudioUsage; |
| } |
| |
| /** |
| * Return the flags. |
| * @return a combined mask of all flags |
| */ |
| @Flag |
| public int getFlags() { |
| return mFlags; |
| } |
| |
| /** |
| * Return the vibration category. |
| * |
| * <p>Vibration categories describe the source of the vibration, and it can be combined with |
| * the vibration usage to best match to a user setting, e.g. a vibration with usage touch and |
| * category keyboard can be used to control keyboard haptic feedback independently. |
| * |
| * @hide |
| */ |
| @Category |
| public int getCategory() { |
| return mCategory; |
| } |
| |
| /** |
| * Check whether a flag is set |
| * @return true if a flag is set and false otherwise |
| */ |
| public boolean isFlagSet(@Flag int flag) { |
| return (mFlags & flag) > 0; |
| } |
| |
| /** |
| * Return {@link AudioAttributes} usage equivalent to {@link #getUsage()}. |
| * @return one of {@link AudioAttributes#SDK_USAGES} that represents {@link #getUsage()} |
| * @hide |
| */ |
| @TestApi |
| @AudioAttributes.AttributeUsage |
| public int getAudioUsage() { |
| if (mOriginalAudioUsage != AudioAttributes.USAGE_UNKNOWN) { |
| // Return same audio usage set in the Builder. |
| return mOriginalAudioUsage; |
| } |
| // Return correct audio usage based on the vibration usage set in the Builder. |
| switch (mUsage) { |
| case USAGE_NOTIFICATION: |
| return AudioAttributes.USAGE_NOTIFICATION; |
| case USAGE_COMMUNICATION_REQUEST: |
| return AudioAttributes.USAGE_VOICE_COMMUNICATION; |
| case USAGE_RINGTONE: |
| return AudioAttributes.USAGE_NOTIFICATION_RINGTONE; |
| case USAGE_TOUCH: |
| return AudioAttributes.USAGE_ASSISTANCE_SONIFICATION; |
| case USAGE_ALARM: |
| return AudioAttributes.USAGE_ALARM; |
| case USAGE_ACCESSIBILITY: |
| return AudioAttributes.USAGE_ASSISTANCE_ACCESSIBILITY; |
| case USAGE_MEDIA: |
| return AudioAttributes.USAGE_MEDIA; |
| default: |
| return AudioAttributes.USAGE_UNKNOWN; |
| } |
| } |
| |
| @Override |
| public int describeContents() { |
| return 0; |
| } |
| |
| @Override |
| public void writeToParcel(@NonNull Parcel dest, int flags) { |
| dest.writeInt(mUsage); |
| dest.writeInt(mOriginalAudioUsage); |
| dest.writeInt(mFlags); |
| dest.writeInt(mCategory); |
| } |
| |
| private VibrationAttributes(Parcel src) { |
| mUsage = src.readInt(); |
| mOriginalAudioUsage = src.readInt(); |
| mFlags = src.readInt(); |
| mCategory = src.readInt(); |
| } |
| |
| public static final @NonNull Parcelable.Creator<VibrationAttributes> |
| CREATOR = new Parcelable.Creator<VibrationAttributes>() { |
| public VibrationAttributes createFromParcel(Parcel p) { |
| return new VibrationAttributes(p); |
| } |
| public VibrationAttributes[] newArray(int size) { |
| return new VibrationAttributes[size]; |
| } |
| }; |
| |
| @Override |
| public boolean equals(@Nullable Object o) { |
| if (this == o) { |
| return true; |
| } |
| if (o == null || getClass() != o.getClass()) { |
| return false; |
| } |
| VibrationAttributes rhs = (VibrationAttributes) o; |
| return mUsage == rhs.mUsage && mOriginalAudioUsage == rhs.mOriginalAudioUsage |
| && mFlags == rhs.mFlags && mCategory == rhs.mCategory; |
| } |
| |
| @Override |
| public int hashCode() { |
| return Objects.hash(mUsage, mOriginalAudioUsage, mFlags, mCategory); |
| } |
| |
| @Override |
| public String toString() { |
| return "VibrationAttributes{" |
| + "mUsage=" + usageToString() |
| + ", mAudioUsage= " + AudioAttributes.usageToString(mOriginalAudioUsage) |
| + ", mCategory=" + categoryToString() |
| + ", mFlags=" + mFlags |
| + '}'; |
| } |
| |
| /** @hide */ |
| public String usageToString() { |
| return usageToString(mUsage); |
| } |
| |
| /** @hide */ |
| public static String usageToString(@Usage int usage) { |
| switch (usage) { |
| case USAGE_UNKNOWN: |
| return "UNKNOWN"; |
| case USAGE_ALARM: |
| return "ALARM"; |
| case USAGE_ACCESSIBILITY: |
| return "ACCESSIBILITY"; |
| case USAGE_RINGTONE: |
| return "RINGTONE"; |
| case USAGE_NOTIFICATION: |
| return "NOTIFICATION"; |
| case USAGE_COMMUNICATION_REQUEST: |
| return "COMMUNICATION_REQUEST"; |
| case USAGE_MEDIA: |
| return "MEDIA"; |
| case USAGE_TOUCH: |
| return "TOUCH"; |
| case USAGE_PHYSICAL_EMULATION: |
| return "PHYSICAL_EMULATION"; |
| case USAGE_HARDWARE_FEEDBACK: |
| return "HARDWARE_FEEDBACK"; |
| default: |
| return "unknown usage " + usage; |
| } |
| } |
| |
| /** @hide */ |
| public String categoryToString() { |
| return categoryToString(mCategory); |
| } |
| |
| /** @hide */ |
| public static String categoryToString(@Category int category) { |
| switch (category) { |
| case CATEGORY_UNKNOWN: |
| return "UNKNOWN"; |
| case CATEGORY_KEYBOARD: |
| return "KEYBOARD"; |
| default: |
| return "unknown category " + category; |
| } |
| } |
| |
| /** |
| * Builder class for {@link VibrationAttributes} objects. |
| * By default, all information is set to UNKNOWN. |
| */ |
| @android.ravenwood.annotation.RavenwoodKeepWholeClass |
| public static final class Builder { |
| private int mUsage = USAGE_UNKNOWN; |
| private int mOriginalAudioUsage = AudioAttributes.USAGE_UNKNOWN; |
| private int mFlags = 0x0; |
| private int mCategory = CATEGORY_UNKNOWN; |
| |
| /** |
| * Constructs a new Builder with the defaults. |
| */ |
| public Builder() { |
| } |
| |
| /** |
| * Constructs a new Builder from a given VibrationAttributes. |
| */ |
| public Builder(@Nullable VibrationAttributes vib) { |
| if (vib != null) { |
| mUsage = vib.mUsage; |
| mOriginalAudioUsage = vib.mOriginalAudioUsage; |
| mFlags = vib.mFlags; |
| mCategory = vib.mCategory; |
| } |
| } |
| |
| /** |
| * Constructs a new Builder from AudioAttributes. |
| */ |
| public Builder(@NonNull AudioAttributes audio) { |
| setUsage(audio); |
| setFlags(audio); |
| } |
| |
| private void setUsage(@NonNull AudioAttributes audio) { |
| mOriginalAudioUsage = audio.getUsage(); |
| switch (audio.getUsage()) { |
| case AudioAttributes.USAGE_NOTIFICATION: |
| case AudioAttributes.USAGE_NOTIFICATION_EVENT: |
| case AudioAttributes.USAGE_NOTIFICATION_COMMUNICATION_DELAYED: |
| case AudioAttributes.USAGE_NOTIFICATION_COMMUNICATION_INSTANT: |
| case AudioAttributes.USAGE_NOTIFICATION_COMMUNICATION_REQUEST: |
| mUsage = USAGE_NOTIFICATION; |
| break; |
| case AudioAttributes.USAGE_VOICE_COMMUNICATION: |
| case AudioAttributes.USAGE_VOICE_COMMUNICATION_SIGNALLING: |
| case AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE: |
| case AudioAttributes.USAGE_ASSISTANT: |
| mUsage = USAGE_COMMUNICATION_REQUEST; |
| break; |
| case AudioAttributes.USAGE_NOTIFICATION_RINGTONE: |
| mUsage = USAGE_RINGTONE; |
| break; |
| case AudioAttributes.USAGE_ASSISTANCE_ACCESSIBILITY: |
| mUsage = USAGE_ACCESSIBILITY; |
| break; |
| case AudioAttributes.USAGE_ASSISTANCE_SONIFICATION: |
| mUsage = USAGE_TOUCH; |
| break; |
| case AudioAttributes.USAGE_ALARM: |
| mUsage = USAGE_ALARM; |
| break; |
| case AudioAttributes.USAGE_MEDIA: |
| case AudioAttributes.USAGE_GAME: |
| mUsage = USAGE_MEDIA; |
| break; |
| default: |
| mUsage = USAGE_UNKNOWN; |
| } |
| } |
| |
| private void setFlags(@NonNull AudioAttributes audio) { |
| if ((audio.getAllFlags() & AudioAttributes.FLAG_BYPASS_INTERRUPTION_POLICY) != 0) { |
| mFlags |= FLAG_BYPASS_INTERRUPTION_POLICY; |
| } |
| if ((audio.getAllFlags() & AudioAttributes.FLAG_BYPASS_MUTE) != 0) { |
| // Muted audio stream translates to vibration usage having the value |
| // Vibrator.VIBRATION_INTENSITY_OFF set in the user setting. |
| mFlags |= FLAG_BYPASS_USER_VIBRATION_INTENSITY_OFF; |
| } |
| } |
| |
| /** |
| * Combines all of the attributes that have been set and returns a new |
| * {@link VibrationAttributes} object. |
| * @return a new {@link VibrationAttributes} object |
| */ |
| public @NonNull VibrationAttributes build() { |
| VibrationAttributes ans = new VibrationAttributes( |
| mUsage, mOriginalAudioUsage, mFlags, mCategory); |
| return ans; |
| } |
| |
| /** |
| * Sets the attribute describing the type of the corresponding vibration. |
| * @param usage The type of usage for the vibration |
| * @return the same Builder instance. |
| */ |
| public @NonNull Builder setUsage(@Usage int usage) { |
| mOriginalAudioUsage = AudioAttributes.USAGE_UNKNOWN; |
| mUsage = usage; |
| return this; |
| } |
| |
| /** |
| * Sets the attribute describing the category of the corresponding vibration. |
| * |
| * @param category The category for the vibration |
| * @return the same Builder instance. |
| * |
| * @hide |
| */ |
| public @NonNull Builder setCategory(@Category int category) { |
| mCategory = category; |
| return this; |
| } |
| |
| /** |
| * Sets only the flags specified in the bitmask, leaving the other supported flag values |
| * unchanged in the builder. |
| * |
| * @param flags Combination of flags to be set. |
| * @param mask Bit range that should be changed. |
| * @return the same Builder instance. |
| */ |
| public @NonNull Builder setFlags(@Flag int flags, int mask) { |
| mask &= FLAG_ALL_SUPPORTED; |
| mFlags = (mFlags & ~mask) | (flags & mask); |
| return this; |
| } |
| |
| /** |
| * Set all supported flags with given combination of flags, overriding any previous values |
| * set to this builder. |
| * |
| * @param flags combination of flags to be set. |
| * @return the same Builder instance. |
| * |
| * @hide |
| */ |
| public @NonNull Builder setFlags(@Flag int flags) { |
| return setFlags(flags, FLAG_ALL_SUPPORTED); |
| } |
| } |
| } |
