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.os.vibrator.VendorVibrationSession; 26 import android.util.Log; 27 import android.view.HapticFeedbackConstants; 28 29 import java.util.concurrent.Executor; 30 31 /** 32 * Provides access to all vibrators from the device, as well as the ability to run them 33 * in a synchronized fashion. 34 * <p> 35 * If your process exits, any vibration you started will stop. 36 * </p> 37 */ 38 @SystemService(Context.VIBRATOR_MANAGER_SERVICE) 39 public abstract class VibratorManager { 40 private static final String TAG = "VibratorManager"; 41 42 /** @hide */ 43 protected final String mPackageName; 44 45 /** 46 * @hide to prevent subclassing from outside of the framework 47 */ VibratorManager()48 public VibratorManager() { 49 mPackageName = ActivityThread.currentPackageName(); 50 } 51 52 /** 53 * @hide to prevent subclassing from outside of the framework 54 */ VibratorManager(Context context)55 protected VibratorManager(Context context) { 56 mPackageName = context.getOpPackageName(); 57 } 58 59 /** 60 * List all available vibrator ids, returning a possible empty list. 61 * 62 * @return An array containing the ids of the vibrators available on the device. 63 */ 64 @NonNull getVibratorIds()65 public abstract int[] getVibratorIds(); 66 67 /** 68 * Return true if the vibrator manager has all capabilities, false otherwise. 69 * @hide 70 */ hasCapabilities(int capabilities)71 public boolean hasCapabilities(int capabilities) { 72 return false; 73 } 74 75 /** 76 * Retrieve a single vibrator by id. 77 * 78 * @param vibratorId The id of the vibrator to be retrieved. 79 * @return The vibrator with given {@code vibratorId}, never null. 80 */ 81 @NonNull getVibrator(int vibratorId)82 public abstract Vibrator getVibrator(int vibratorId); 83 84 /** 85 * Returns the default Vibrator for the device. 86 */ 87 @NonNull getDefaultVibrator()88 public abstract Vibrator getDefaultVibrator(); 89 90 /** 91 * Configure an always-on haptics effect. 92 * 93 * @hide 94 */ 95 @RequiresPermission(android.Manifest.permission.VIBRATE_ALWAYS_ON) setAlwaysOnEffect(int uid, String opPkg, int alwaysOnId, @Nullable CombinedVibration effect, @Nullable VibrationAttributes attributes)96 public boolean setAlwaysOnEffect(int uid, String opPkg, int alwaysOnId, 97 @Nullable CombinedVibration effect, @Nullable VibrationAttributes attributes) { 98 Log.w(TAG, "Always-on effects aren't supported"); 99 return false; 100 } 101 102 /** 103 * Vibrate with a given combination of effects. 104 * 105 * <p> 106 * Pass in a {@link CombinedVibration} representing a combination of {@link 107 * VibrationEffect VibrationEffects} to be played on one or more vibrators. 108 * </p> 109 * 110 * <p>The app should be in foreground for the vibration to happen.</p> 111 * 112 * @param effect a combination of effects to be performed by one or more vibrators. 113 */ 114 @RequiresPermission(android.Manifest.permission.VIBRATE) vibrate(@onNull CombinedVibration effect)115 public final void vibrate(@NonNull CombinedVibration effect) { 116 vibrate(effect, null); 117 } 118 119 /** 120 * Vibrate with a given combination of effects. 121 * 122 * <p> 123 * Pass in a {@link CombinedVibration} representing a combination of {@link 124 * VibrationEffect} to be played on one or more vibrators. 125 * </p> 126 * 127 * <p>The app should be in foreground for the vibration to happen. Background apps should 128 * specify a ringtone, notification or alarm usage in order to vibrate.</p> 129 * 130 * @param effect a combination of effects to be performed by one or more vibrators. 131 * @param attributes {@link VibrationAttributes} corresponding to the vibration. For example, 132 * specify {@link VibrationAttributes#USAGE_ALARM} for alarm vibrations or 133 * {@link VibrationAttributes#USAGE_RINGTONE} for vibrations associated with 134 * incoming calls. 135 */ 136 @RequiresPermission(android.Manifest.permission.VIBRATE) vibrate(@onNull CombinedVibration effect, @Nullable VibrationAttributes attributes)137 public final void vibrate(@NonNull CombinedVibration effect, 138 @Nullable VibrationAttributes attributes) { 139 vibrate(Process.myUid(), mPackageName, effect, null, attributes); 140 } 141 142 /** 143 * Like {@link #vibrate(CombinedVibration, VibrationAttributes)}, but allows the 144 * caller to specify the vibration is owned by someone else and set reason for vibration. 145 * 146 * @hide 147 */ 148 @RequiresPermission(android.Manifest.permission.VIBRATE) vibrate(int uid, String opPkg, @NonNull CombinedVibration effect, String reason, @Nullable VibrationAttributes attributes)149 public abstract void vibrate(int uid, String opPkg, @NonNull CombinedVibration effect, 150 String reason, @Nullable VibrationAttributes attributes); 151 152 /** 153 * Performs a haptic feedback. 154 * 155 * @param constant the ID of the requested haptic feedback. Should be one of the constants 156 * defined in {@link HapticFeedbackConstants}. 157 * @param reason the reason for this haptic feedback. 158 * @param flags Additional flags as per {@link HapticFeedbackConstants}. 159 * @param privFlags Additional private flags as per {@link HapticFeedbackConstants}. 160 * @hide 161 */ performHapticFeedback(int constant, String reason, @HapticFeedbackConstants.Flags int flags, @HapticFeedbackConstants.PrivateFlags int privFlags)162 public void performHapticFeedback(int constant, String reason, 163 @HapticFeedbackConstants.Flags int flags, 164 @HapticFeedbackConstants.PrivateFlags int privFlags) { 165 Log.w(TAG, "performHapticFeedback is not supported"); 166 } 167 168 /** 169 * Performs a haptic feedback. Similar to {@link #performHapticFeedback} but also take input 170 * into consideration. 171 * 172 * @param constant the ID of the requested haptic feedback. Should be one of the constants 173 * defined in {@link HapticFeedbackConstants}. 174 * @param inputDeviceId the integer id of the input device that customizes the haptic feedback 175 * corresponding to the {@code constant}. 176 * @param inputSource the {@link InputDevice.Source} that customizes the haptic feedback 177 * corresponding to the {@code constant}. 178 * @param reason the reason for this haptic feedback. 179 * @param flags Additional flags as per {@link HapticFeedbackConstants}. 180 * @param privFlags Additional private flags as per {@link HapticFeedbackConstants}. 181 * @hide 182 */ performHapticFeedbackForInputDevice(int constant, int inputDeviceId, int inputSource, String reason, @HapticFeedbackConstants.Flags int flags, @HapticFeedbackConstants.PrivateFlags int privFlags)183 public void performHapticFeedbackForInputDevice(int constant, int inputDeviceId, 184 int inputSource, String reason, @HapticFeedbackConstants.Flags int flags, 185 @HapticFeedbackConstants.PrivateFlags int privFlags) { 186 Log.w(TAG, "performHapticFeedbackForInputDevice is not supported"); 187 } 188 189 /** 190 * Turn all the vibrators off. 191 */ 192 @RequiresPermission(android.Manifest.permission.VIBRATE) cancel()193 public abstract void cancel(); 194 195 /** 196 * Cancel specific types of ongoing vibrations. 197 * 198 * @param usageFilter The type of vibration to be cancelled, represented as a bitwise 199 * combination of {@link VibrationAttributes.Usage} values. 200 * @hide 201 */ 202 @RequiresPermission(android.Manifest.permission.VIBRATE) cancel(int usageFilter)203 public abstract void cancel(int usageFilter); 204 205 206 /** 207 * Starts a vibration session on given vibrators. 208 * 209 * @param vibratorIds The vibrators that will be controlled by this session. 210 * @param attrs The {@link VibrationAttributes} corresponding to the vibrations that will 211 * be performed in the session. This will be used to decide the priority of 212 * this session against other system vibrations. 213 * @param reason The description for this session, used for debugging purposes. 214 * @param cancellationSignal A signal to cancel the session before it starts. 215 * @param executor The executor for the session callbacks. 216 * @param callback The {@link VendorVibrationSession.Callback} for the started session. 217 * @see Vibrator#startVendorSession 218 * @hide 219 */ 220 @RequiresPermission(allOf = { 221 android.Manifest.permission.VIBRATE, 222 android.Manifest.permission.VIBRATE_VENDOR_EFFECTS, 223 android.Manifest.permission.START_VIBRATION_SESSIONS, 224 }) startVendorSession(@onNull int[] vibratorIds, @NonNull VibrationAttributes attrs, @Nullable String reason, @Nullable CancellationSignal cancellationSignal, @NonNull Executor executor, @NonNull VendorVibrationSession.Callback callback)225 public void startVendorSession(@NonNull int[] vibratorIds, @NonNull VibrationAttributes attrs, 226 @Nullable String reason, @Nullable CancellationSignal cancellationSignal, 227 @NonNull Executor executor, @NonNull VendorVibrationSession.Callback callback) { 228 Log.w(TAG, "startVendorSession is not supported"); 229 } 230 } 231