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