NotificationManager.java revision 69ddab4575ff684c533c995e07ca15fe18543fc0
1/* 2 * Copyright (C) 2007 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.app; 18 19import android.content.Context; 20import android.os.Handler; 21import android.os.IBinder; 22import android.os.RemoteException; 23import android.os.ServiceManager; 24import android.util.Log; 25 26/** 27 * Class to notify the user of events that happen. This is how you tell 28 * the user that something has happened in the background. {@more} 29 * 30 * Notifications can take different forms: 31 * <ul> 32 * <li>A persistent icon that goes in the status bar and is accessible 33 * through the launcher, (when the user selects it, a designated Intent 34 * can be launched),</li> 35 * <li>Turning on or flashing LEDs on the device, or</li> 36 * <li>Alerting the user by flashing the backlight, playing a sound, 37 * or vibrating.</li> 38 * </ul> 39 * 40 * <p> 41 * Each of the notify methods takes an int id parameter and optionally a 42 * {@link String} tag parameter, which may be {@code null}. These parameters 43 * are used to form a pair (tag, id), or ({@code null}, id) if tag is 44 * unspecified. This pair identifies this notification from your app to the 45 * system, so that pair should be unique within your app. If you call one 46 * of the notify methods with a (tag, id) pair that is currently active and 47 * a new set of notification parameters, it will be updated. For example, 48 * if you pass a new status bar icon, the old icon in the status bar will 49 * be replaced with the new one. This is also the same tag and id you pass 50 * to the {@link #cancel(int)} or {@link #cancel(String, int)} method to clear 51 * this notification. 52 * 53 * <p> 54 * You do not instantiate this class directly; instead, retrieve it through 55 * {@link android.content.Context#getSystemService}. 56 * 57 * <div class="special reference"> 58 * <h3>Developer Guides</h3> 59 * <p>For a guide to creating notifications, read the 60 * <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Status Bar Notifications</a> 61 * developer guide.</p> 62 * </div> 63 * 64 * @see android.app.Notification 65 * @see android.content.Context#getSystemService 66 */ 67public class NotificationManager 68{ 69 private static String TAG = "NotificationManager"; 70 private static boolean localLOGV = false; 71 72 private static INotificationManager sService; 73 74 /** @hide */ 75 static public INotificationManager getService() 76 { 77 if (sService != null) { 78 return sService; 79 } 80 IBinder b = ServiceManager.getService("notification"); 81 sService = INotificationManager.Stub.asInterface(b); 82 return sService; 83 } 84 85 /*package*/ NotificationManager(Context context, Handler handler) 86 { 87 mContext = context; 88 } 89 90 /** {@hide} */ 91 public static NotificationManager from(Context context) { 92 return (NotificationManager) context.getSystemService(Context.NOTIFICATION_SERVICE); 93 } 94 95 /** 96 * Post a notification to be shown in the status bar. If a notification with 97 * the same id has already been posted by your application and has not yet been canceled, it 98 * will be replaced by the updated information. 99 * 100 * @param id An identifier for this notification unique within your 101 * application. 102 * @param notification A {@link Notification} object describing what to show the user. Must not 103 * be null. 104 */ 105 public void notify(int id, Notification notification) 106 { 107 notify(null, id, notification); 108 } 109 110 /** 111 * Post a notification to be shown in the status bar. If a notification with 112 * the same tag and id has already been posted by your application and has not yet been 113 * canceled, it will be replaced by the updated information. 114 * 115 * @param tag A string identifier for this notification. May be {@code null}. 116 * @param id An identifier for this notification. The pair (tag, id) must be unique 117 * within your application. 118 * @param notification A {@link Notification} object describing what to 119 * show the user. Must not be null. 120 */ 121 public void notify(String tag, int id, Notification notification) 122 { 123 int[] idOut = new int[1]; 124 INotificationManager service = getService(); 125 String pkg = mContext.getPackageName(); 126 if (localLOGV) Log.v(TAG, pkg + ": notify(" + id + ", " + notification + ")"); 127 try { 128 service.enqueueNotificationWithTag(pkg, tag, id, notification, idOut); 129 if (id != idOut[0]) { 130 Log.w(TAG, "notify: id corrupted: sent " + id + ", got back " + idOut[0]); 131 } 132 } catch (RemoteException e) { 133 } 134 } 135 136 /** 137 * Cancel a previously shown notification. If it's transient, the view 138 * will be hidden. If it's persistent, it will be removed from the status 139 * bar. 140 */ 141 public void cancel(int id) 142 { 143 cancel(null, id); 144 } 145 146 /** 147 * Cancel a previously shown notification. If it's transient, the view 148 * will be hidden. If it's persistent, it will be removed from the status 149 * bar. 150 */ 151 public void cancel(String tag, int id) 152 { 153 INotificationManager service = getService(); 154 String pkg = mContext.getPackageName(); 155 if (localLOGV) Log.v(TAG, pkg + ": cancel(" + id + ")"); 156 try { 157 service.cancelNotificationWithTag(pkg, tag, id); 158 } catch (RemoteException e) { 159 } 160 } 161 162 /** 163 * Cancel all previously shown notifications. See {@link #cancel} for the 164 * detailed behavior. 165 */ 166 public void cancelAll() 167 { 168 INotificationManager service = getService(); 169 String pkg = mContext.getPackageName(); 170 if (localLOGV) Log.v(TAG, pkg + ": cancelAll()"); 171 try { 172 service.cancelAllNotifications(pkg); 173 } catch (RemoteException e) { 174 } 175 } 176 177 private Context mContext; 178} 179