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 17package android.os; 18 19import android.app.ActivityThread; 20import android.content.Context; 21import android.media.AudioAttributes; 22 23/** 24 * Class that operates the vibrator on the device. 25 * <p> 26 * If your process exits, any vibration you started will stop. 27 * </p> 28 * 29 * To obtain an instance of the system vibrator, call 30 * {@link Context#getSystemService} with {@link Context#VIBRATOR_SERVICE} as the argument. 31 */ 32public abstract class Vibrator { 33 34 private final String mPackageName; 35 36 /** 37 * @hide to prevent subclassing from outside of the framework 38 */ 39 public Vibrator() { 40 mPackageName = ActivityThread.currentPackageName(); 41 } 42 43 /** 44 * @hide to prevent subclassing from outside of the framework 45 */ 46 protected Vibrator(Context context) { 47 mPackageName = context.getOpPackageName(); 48 } 49 50 /** 51 * Check whether the hardware has a vibrator. 52 * 53 * @return True if the hardware has a vibrator, else false. 54 */ 55 public abstract boolean hasVibrator(); 56 57 /** 58 * Vibrate constantly for the specified period of time. 59 * <p>This method requires the caller to hold the permission 60 * {@link android.Manifest.permission#VIBRATE}. 61 * 62 * @param milliseconds The number of milliseconds to vibrate. 63 */ 64 public void vibrate(long milliseconds) { 65 vibrate(milliseconds, null); 66 } 67 68 /** 69 * Vibrate constantly for the specified period of time. 70 * <p>This method requires the caller to hold the permission 71 * {@link android.Manifest.permission#VIBRATE}. 72 * 73 * @param milliseconds The number of milliseconds to vibrate. 74 * @param attributes {@link AudioAttributes} corresponding to the vibration. For example, 75 * specify {@link AudioAttributes#USAGE_ALARM} for alarm vibrations or 76 * {@link AudioAttributes#USAGE_NOTIFICATION_RINGTONE} for 77 * vibrations associated with incoming calls. 78 */ 79 public void vibrate(long milliseconds, AudioAttributes attributes) { 80 vibrate(Process.myUid(), mPackageName, milliseconds, attributes); 81 } 82 83 /** 84 * Vibrate with a given pattern. 85 * 86 * <p> 87 * Pass in an array of ints that are the durations for which to turn on or off 88 * the vibrator in milliseconds. The first value indicates the number of milliseconds 89 * to wait before turning the vibrator on. The next value indicates the number of milliseconds 90 * for which to keep the vibrator on before turning it off. Subsequent values alternate 91 * between durations in milliseconds to turn the vibrator off or to turn the vibrator on. 92 * </p><p> 93 * To cause the pattern to repeat, pass the index into the pattern array at which 94 * to start the repeat, or -1 to disable repeating. 95 * </p> 96 * <p>This method requires the caller to hold the permission 97 * {@link android.Manifest.permission#VIBRATE}. 98 * 99 * @param pattern an array of longs of times for which to turn the vibrator on or off. 100 * @param repeat the index into pattern at which to repeat, or -1 if 101 * you don't want to repeat. 102 */ 103 public void vibrate(long[] pattern, int repeat) { 104 vibrate(pattern, repeat, null); 105 } 106 107 /** 108 * Vibrate with a given pattern. 109 * 110 * <p> 111 * Pass in an array of ints that are the durations for which to turn on or off 112 * the vibrator in milliseconds. The first value indicates the number of milliseconds 113 * to wait before turning the vibrator on. The next value indicates the number of milliseconds 114 * for which to keep the vibrator on before turning it off. Subsequent values alternate 115 * between durations in milliseconds to turn the vibrator off or to turn the vibrator on. 116 * </p><p> 117 * To cause the pattern to repeat, pass the index into the pattern array at which 118 * to start the repeat, or -1 to disable repeating. 119 * </p> 120 * <p>This method requires the caller to hold the permission 121 * {@link android.Manifest.permission#VIBRATE}. 122 * 123 * @param pattern an array of longs of times for which to turn the vibrator on or off. 124 * @param repeat the index into pattern at which to repeat, or -1 if 125 * you don't want to repeat. 126 * @param attributes {@link AudioAttributes} corresponding to the vibration. For example, 127 * specify {@link AudioAttributes#USAGE_ALARM} for alarm vibrations or 128 * {@link AudioAttributes#USAGE_NOTIFICATION_RINGTONE} for 129 * vibrations associated with incoming calls. 130 */ 131 public void vibrate(long[] pattern, int repeat, AudioAttributes attributes) { 132 vibrate(Process.myUid(), mPackageName, pattern, repeat, attributes); 133 } 134 135 /** 136 * @hide 137 * Like {@link #vibrate(long, AudioAttributes)}, but allowing the caller to specify that 138 * the vibration is owned by someone else. 139 */ 140 public abstract void vibrate(int uid, String opPkg, long milliseconds, 141 AudioAttributes attributes); 142 143 /** 144 * @hide 145 * Like {@link #vibrate(long[], int, AudioAttributes)}, but allowing the caller to specify that 146 * the vibration is owned by someone else. 147 */ 148 public abstract void vibrate(int uid, String opPkg, long[] pattern, int repeat, 149 AudioAttributes attributes); 150 151 /** 152 * Turn the vibrator off. 153 * <p>This method requires the caller to hold the permission 154 * {@link android.Manifest.permission#VIBRATE}. 155 */ 156 public abstract void cancel(); 157} 158