1 /* 2 * Copyright (C) 2020 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.os; 18 19 import android.annotation.NonNull; 20 import android.annotation.Nullable; 21 import android.annotation.RequiresPermission; 22 import android.annotation.SystemService; 23 import android.app.ActivityThread; 24 import android.content.Context; 25 import android.util.Log; 26 27 /** 28 * Provides access to all vibrators from the device, as well as the ability to run them 29 * in a synchronized fashion. 30 * <p> 31 * If your process exits, any vibration you started will stop. 32 * </p> 33 */ 34 @SystemService(Context.VIBRATOR_MANAGER_SERVICE) 35 public abstract class VibratorManager { 36 private static final String TAG = "VibratorManager"; 37 38 private final String mPackageName; 39 40 /** 41 * @hide to prevent subclassing from outside of the framework 42 */ VibratorManager()43 public VibratorManager() { 44 mPackageName = ActivityThread.currentPackageName(); 45 } 46 47 /** 48 * @hide to prevent subclassing from outside of the framework 49 */ VibratorManager(Context context)50 protected VibratorManager(Context context) { 51 mPackageName = context.getOpPackageName(); 52 } 53 54 /** 55 * List all available vibrator ids, returning a possible empty list. 56 * 57 * @return An array containing the ids of the vibrators available on the device. 58 */ 59 @NonNull getVibratorIds()60 public abstract int[] getVibratorIds(); 61 62 /** 63 * Retrieve a single vibrator by id. 64 * 65 * @param vibratorId The id of the vibrator to be retrieved. 66 * @return The vibrator with given {@code vibratorId}, never null. 67 */ 68 @NonNull getVibrator(int vibratorId)69 public abstract Vibrator getVibrator(int vibratorId); 70 71 /** 72 * Returns the default Vibrator for the device. 73 */ 74 @NonNull getDefaultVibrator()75 public abstract Vibrator getDefaultVibrator(); 76 77 /** 78 * Configure an always-on haptics effect. 79 * 80 * @hide 81 */ 82 @RequiresPermission(android.Manifest.permission.VIBRATE_ALWAYS_ON) setAlwaysOnEffect(int uid, String opPkg, int alwaysOnId, @Nullable CombinedVibration effect, @Nullable VibrationAttributes attributes)83 public boolean setAlwaysOnEffect(int uid, String opPkg, int alwaysOnId, 84 @Nullable CombinedVibration effect, @Nullable VibrationAttributes attributes) { 85 Log.w(TAG, "Always-on effects aren't supported"); 86 return false; 87 } 88 89 /** 90 * Vibrate with a given combination of effects. 91 * 92 * <p> 93 * Pass in a {@link CombinedVibration} representing a combination of {@link 94 * VibrationEffect VibrationEffects} to be played on one or more vibrators. 95 * </p> 96 * 97 * <p>The app should be in foreground for the vibration to happen.</p> 98 * 99 * @param effect a combination of effects to be performed by one or more vibrators. 100 */ 101 @RequiresPermission(android.Manifest.permission.VIBRATE) vibrate(@onNull CombinedVibration effect)102 public final void vibrate(@NonNull CombinedVibration effect) { 103 vibrate(effect, null); 104 } 105 106 /** 107 * Vibrate with a given combination of effects. 108 * 109 * <p> 110 * Pass in a {@link CombinedVibration} representing a combination of {@link 111 * VibrationEffect} to be played on one or more vibrators. 112 * </p> 113 * 114 * <p>The app should be in foreground for the vibration to happen. Background apps should 115 * specify a ringtone, notification or alarm usage in order to vibrate.</p> 116 * 117 * @param effect a combination of effects to be performed by one or more vibrators. 118 * @param attributes {@link VibrationAttributes} corresponding to the vibration. For example, 119 * specify {@link VibrationAttributes#USAGE_ALARM} for alarm vibrations or 120 * {@link VibrationAttributes#USAGE_RINGTONE} for vibrations associated with 121 * incoming calls. 122 */ 123 @RequiresPermission(android.Manifest.permission.VIBRATE) vibrate(@onNull CombinedVibration effect, @Nullable VibrationAttributes attributes)124 public final void vibrate(@NonNull CombinedVibration effect, 125 @Nullable VibrationAttributes attributes) { 126 vibrate(Process.myUid(), mPackageName, effect, null, attributes); 127 } 128 129 /** 130 * Like {@link #vibrate(CombinedVibration, VibrationAttributes)}, but allows the 131 * caller to specify the vibration is owned by someone else and set reason for vibration. 132 * 133 * @hide 134 */ 135 @RequiresPermission(android.Manifest.permission.VIBRATE) vibrate(int uid, String opPkg, @NonNull CombinedVibration effect, String reason, @Nullable VibrationAttributes attributes)136 public abstract void vibrate(int uid, String opPkg, @NonNull CombinedVibration effect, 137 String reason, @Nullable VibrationAttributes attributes); 138 139 /** 140 * Turn all the vibrators off. 141 */ 142 @RequiresPermission(android.Manifest.permission.VIBRATE) cancel()143 public abstract void cancel(); 144 145 /** 146 * Cancel specific types of ongoing vibrations. 147 * 148 * @param usageFilter The type of vibration to be cancelled, represented as a bitwise 149 * combination of {@link VibrationAttributes.Usage} values. 150 * @hide 151 */ 152 @RequiresPermission(android.Manifest.permission.VIBRATE) cancel(int usageFilter)153 public abstract void cancel(int usageFilter); 154 } 155