1 /* 2 * Copyright (C) 2006 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.RequiresPermission; 20 import android.annotation.SystemService; 21 import android.app.ActivityThread; 22 import android.content.Context; 23 import android.media.AudioAttributes; 24 import android.util.Log; 25 26 /** 27 * Class that operates the vibrator on the device. 28 * <p> 29 * If your process exits, any vibration you started will stop. 30 * </p> 31 */ 32 @SystemService(Context.VIBRATOR_SERVICE) 33 public abstract class Vibrator { 34 private static final String TAG = "Vibrator"; 35 36 private final String mPackageName; 37 38 /** 39 * @hide to prevent subclassing from outside of the framework 40 */ Vibrator()41 public Vibrator() { 42 mPackageName = ActivityThread.currentPackageName(); 43 } 44 45 /** 46 * @hide to prevent subclassing from outside of the framework 47 */ Vibrator(Context context)48 protected Vibrator(Context context) { 49 mPackageName = context.getOpPackageName(); 50 } 51 52 /** 53 * Check whether the hardware has a vibrator. 54 * 55 * @return True if the hardware has a vibrator, else false. 56 */ hasVibrator()57 public abstract boolean hasVibrator(); 58 59 /** 60 * Check whether the vibrator has amplitude control. 61 * 62 * @return True if the hardware can control the amplitude of the vibrations, otherwise false. 63 */ hasAmplitudeControl()64 public abstract boolean hasAmplitudeControl(); 65 66 /** 67 * Vibrate constantly for the specified period of time. 68 * 69 * @param milliseconds The number of milliseconds to vibrate. 70 * 71 * @deprecated Use {@link #vibrate(VibrationEffect)} instead. 72 */ 73 @Deprecated 74 @RequiresPermission(android.Manifest.permission.VIBRATE) vibrate(long milliseconds)75 public void vibrate(long milliseconds) { 76 vibrate(milliseconds, null); 77 } 78 79 /** 80 * Vibrate constantly for the specified period of time. 81 * 82 * @param milliseconds The number of milliseconds to vibrate. 83 * @param attributes {@link AudioAttributes} corresponding to the vibration. For example, 84 * specify {@link AudioAttributes#USAGE_ALARM} for alarm vibrations or 85 * {@link AudioAttributes#USAGE_NOTIFICATION_RINGTONE} for 86 * vibrations associated with incoming calls. 87 * 88 * @deprecated Use {@link #vibrate(VibrationEffect, AudioAttributes)} instead. 89 */ 90 @Deprecated 91 @RequiresPermission(android.Manifest.permission.VIBRATE) vibrate(long milliseconds, AudioAttributes attributes)92 public void vibrate(long milliseconds, AudioAttributes attributes) { 93 try { 94 // This ignores all exceptions to stay compatible with pre-O implementations. 95 VibrationEffect effect = 96 VibrationEffect.createOneShot(milliseconds, VibrationEffect.DEFAULT_AMPLITUDE); 97 vibrate(effect, attributes); 98 } catch (IllegalArgumentException iae) { 99 Log.e(TAG, "Failed to create VibrationEffect", iae); 100 } 101 } 102 103 /** 104 * Vibrate with a given pattern. 105 * 106 * <p> 107 * Pass in an array of ints that are the durations for which to turn on or off 108 * the vibrator in milliseconds. The first value indicates the number of milliseconds 109 * to wait before turning the vibrator on. The next value indicates the number of milliseconds 110 * for which to keep the vibrator on before turning it off. Subsequent values alternate 111 * between durations in milliseconds to turn the vibrator off or to turn the vibrator on. 112 * </p><p> 113 * To cause the pattern to repeat, pass the index into the pattern array at which 114 * to start the repeat, or -1 to disable repeating. 115 * </p> 116 * 117 * @param pattern an array of longs of times for which to turn the vibrator on or off. 118 * @param repeat the index into pattern at which to repeat, or -1 if 119 * you don't want to repeat. 120 * 121 * @deprecated Use {@link #vibrate(VibrationEffect)} instead. 122 */ 123 @Deprecated 124 @RequiresPermission(android.Manifest.permission.VIBRATE) vibrate(long[] pattern, int repeat)125 public void vibrate(long[] pattern, int repeat) { 126 vibrate(pattern, repeat, null); 127 } 128 129 /** 130 * Vibrate with a given pattern. 131 * 132 * <p> 133 * Pass in an array of ints that are the durations for which to turn on or off 134 * the vibrator in milliseconds. The first value indicates the number of milliseconds 135 * to wait before turning the vibrator on. The next value indicates the number of milliseconds 136 * for which to keep the vibrator on before turning it off. Subsequent values alternate 137 * between durations in milliseconds to turn the vibrator off or to turn the vibrator on. 138 * </p><p> 139 * To cause the pattern to repeat, pass the index into the pattern array at which 140 * to start the repeat, or -1 to disable repeating. 141 * </p> 142 * 143 * @param pattern an array of longs of times for which to turn the vibrator on or off. 144 * @param repeat the index into pattern at which to repeat, or -1 if 145 * you don't want to repeat. 146 * @param attributes {@link AudioAttributes} corresponding to the vibration. For example, 147 * specify {@link AudioAttributes#USAGE_ALARM} for alarm vibrations or 148 * {@link AudioAttributes#USAGE_NOTIFICATION_RINGTONE} for 149 * vibrations associated with incoming calls. 150 * 151 * @deprecated Use {@link #vibrate(VibrationEffect, AudioAttributes)} instead. 152 */ 153 @Deprecated 154 @RequiresPermission(android.Manifest.permission.VIBRATE) vibrate(long[] pattern, int repeat, AudioAttributes attributes)155 public void vibrate(long[] pattern, int repeat, AudioAttributes attributes) { 156 // This call needs to continue throwing ArrayIndexOutOfBoundsException but ignore all other 157 // exceptions for compatibility purposes 158 if (repeat < -1 || repeat >= pattern.length) { 159 Log.e(TAG, "vibrate called with repeat index out of bounds" + 160 " (pattern.length=" + pattern.length + ", index=" + repeat + ")"); 161 throw new ArrayIndexOutOfBoundsException(); 162 } 163 164 try { 165 vibrate(VibrationEffect.createWaveform(pattern, repeat), attributes); 166 } catch (IllegalArgumentException iae) { 167 Log.e(TAG, "Failed to create VibrationEffect", iae); 168 } 169 } 170 171 @RequiresPermission(android.Manifest.permission.VIBRATE) vibrate(VibrationEffect vibe)172 public void vibrate(VibrationEffect vibe) { 173 vibrate(vibe, null); 174 } 175 176 @RequiresPermission(android.Manifest.permission.VIBRATE) vibrate(VibrationEffect vibe, AudioAttributes attributes)177 public void vibrate(VibrationEffect vibe, AudioAttributes attributes) { 178 vibrate(Process.myUid(), mPackageName, vibe, attributes); 179 } 180 181 /** 182 * Like {@link #vibrate(VibrationEffect, AudioAttributes)}, but allowing the caller to specify 183 * that the vibration is owned by someone else. 184 * @hide 185 */ 186 @RequiresPermission(android.Manifest.permission.VIBRATE) vibrate(int uid, String opPkg, VibrationEffect vibe, AudioAttributes attributes)187 public abstract void vibrate(int uid, String opPkg, 188 VibrationEffect vibe, AudioAttributes attributes); 189 190 /** 191 * Turn the vibrator off. 192 */ 193 @RequiresPermission(android.Manifest.permission.VIBRATE) cancel()194 public abstract void cancel(); 195 } 196