Vibrator.java revision a1bfe65daa15fe93ecd23486cfc4a9a722ca039d
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.AudioManager; 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, AudioManager.USE_DEFAULT_STREAM_TYPE); 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 streamHint An {@link AudioManager} stream type corresponding to the vibration type. 75 * For example, specify {@link AudioManager#STREAM_ALARM} for alarm vibrations or 76 * {@link AudioManager#STREAM_RING} for vibrations associated with incoming calls. 77 */ 78 public void vibrate(long milliseconds, int streamHint) { 79 vibrate(Process.myUid(), mPackageName, milliseconds, streamHint); 80 } 81 82 /** 83 * Vibrate with a given pattern. 84 * 85 * <p> 86 * Pass in an array of ints that are the durations for which to turn on or off 87 * the vibrator in milliseconds. The first value indicates the number of milliseconds 88 * to wait before turning the vibrator on. The next value indicates the number of milliseconds 89 * for which to keep the vibrator on before turning it off. Subsequent values alternate 90 * between durations in milliseconds to turn the vibrator off or to turn the vibrator on. 91 * </p><p> 92 * To cause the pattern to repeat, pass the index into the pattern array at which 93 * to start the repeat, or -1 to disable repeating. 94 * </p> 95 * <p>This method requires the caller to hold the permission 96 * {@link android.Manifest.permission#VIBRATE}. 97 * 98 * @param pattern an array of longs of times for which to turn the vibrator on or off. 99 * @param repeat the index into pattern at which to repeat, or -1 if 100 * you don't want to repeat. 101 */ 102 public void vibrate(long[] pattern, int repeat) { 103 vibrate(pattern, repeat, AudioManager.USE_DEFAULT_STREAM_TYPE); 104 } 105 106 /** 107 * Vibrate with a given pattern. 108 * 109 * <p> 110 * Pass in an array of ints that are the durations for which to turn on or off 111 * the vibrator in milliseconds. The first value indicates the number of milliseconds 112 * to wait before turning the vibrator on. The next value indicates the number of milliseconds 113 * for which to keep the vibrator on before turning it off. Subsequent values alternate 114 * between durations in milliseconds to turn the vibrator off or to turn the vibrator on. 115 * </p><p> 116 * To cause the pattern to repeat, pass the index into the pattern array at which 117 * to start the repeat, or -1 to disable repeating. 118 * </p> 119 * <p>This method requires the caller to hold the permission 120 * {@link android.Manifest.permission#VIBRATE}. 121 * 122 * @param pattern an array of longs of times for which to turn the vibrator on or off. 123 * @param repeat the index into pattern at which to repeat, or -1 if 124 * you don't want to repeat. 125 * @param streamHint An {@link AudioManager} stream type corresponding to the vibration type. 126 * For example, specify {@link AudioManager#STREAM_ALARM} for alarm vibrations or 127 * {@link AudioManager#STREAM_RING} for vibrations associated with incoming calls. 128 */ 129 public void vibrate(long[] pattern, int repeat, int streamHint) { 130 vibrate(Process.myUid(), mPackageName, pattern, repeat, streamHint); 131 } 132 133 /** 134 * @hide 135 * Like {@link #vibrate(long, int)}, but allowing the caller to specify that 136 * the vibration is owned by someone else. 137 */ 138 public abstract void vibrate(int owningUid, String owningPackage, 139 long milliseconds, int streamHint); 140 141 /** 142 * @hide 143 * Like {@link #vibrate(long[], int, int)}, but allowing the caller to specify that 144 * the vibration is owned by someone else. 145 */ 146 public abstract void vibrate(int owningUid, String owningPackage, 147 long[] pattern, int repeat, int streamHint); 148 149 /** 150 * Turn the vibrator off. 151 * <p>This method requires the caller to hold the permission 152 * {@link android.Manifest.permission#VIBRATE}. 153 */ 154 public abstract void cancel(); 155} 156