Home | History | Annotate | Download | only in app
      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.Binder;
     21 import android.os.RemoteException;
     22 import android.os.Handler;
     23 import android.os.IBinder;
     24 import android.os.ServiceManager;
     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 */
     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 
     86     /*package*/ NotificationManager(Context context, Handler handler)
     87     {
     88         mContext = context;
     89     }
     90 
     91     /**
     92      * Post a notification to be shown in the status bar. If a notification with
     93      * the same id has already been posted by your application and has not yet been canceled, it
     94      * will be replaced by the updated information.
     95      *
     96      * @param id An identifier for this notification unique within your
     97      *        application.
     98      * @param notification A {@link Notification} object describing what to show the user. Must not
     99      *        be null.
    100      */
    101     public void notify(int id, Notification notification)
    102     {
    103         notify(null, id, notification);
    104     }
    105 
    106     /**
    107      * Post a notification to be shown in the status bar. If a notification with
    108      * the same tag and id has already been posted by your application and has not yet been
    109      * canceled, it will be replaced by the updated information.
    110      *
    111      * @param tag A string identifier for this notification.  May be {@code null}.
    112      * @param id An identifier for this notification.  The pair (tag, id) must be unique
    113      *        within your application.
    114      * @param notification A {@link Notification} object describing what to
    115      *        show the user. Must not be null.
    116      */
    117     public void notify(String tag, int id, Notification notification)
    118     {
    119         int[] idOut = new int[1];
    120         INotificationManager service = getService();
    121         String pkg = mContext.getPackageName();
    122         if (localLOGV) Log.v(TAG, pkg + ": notify(" + id + ", " + notification + ")");
    123         try {
    124             service.enqueueNotificationWithTag(pkg, tag, id, notification, idOut);
    125             if (id != idOut[0]) {
    126                 Log.w(TAG, "notify: id corrupted: sent " + id + ", got back " + idOut[0]);
    127             }
    128         } catch (RemoteException e) {
    129         }
    130     }
    131 
    132     /**
    133      * Cancel a previously shown notification.  If it's transient, the view
    134      * will be hidden.  If it's persistent, it will be removed from the status
    135      * bar.
    136      */
    137     public void cancel(int id)
    138     {
    139         cancel(null, id);
    140     }
    141 
    142     /**
    143      * Cancel a previously shown notification.  If it's transient, the view
    144      * will be hidden.  If it's persistent, it will be removed from the status
    145      * bar.
    146      */
    147     public void cancel(String tag, int id)
    148     {
    149         INotificationManager service = getService();
    150         String pkg = mContext.getPackageName();
    151         if (localLOGV) Log.v(TAG, pkg + ": cancel(" + id + ")");
    152         try {
    153             service.cancelNotificationWithTag(pkg, tag, id);
    154         } catch (RemoteException e) {
    155         }
    156     }
    157 
    158     /**
    159      * Cancel all previously shown notifications. See {@link #cancel} for the
    160      * detailed behavior.
    161      */
    162     public void cancelAll()
    163     {
    164         INotificationManager service = getService();
    165         String pkg = mContext.getPackageName();
    166         if (localLOGV) Log.v(TAG, pkg + ": cancelAll()");
    167         try {
    168             service.cancelAllNotifications(pkg);
    169         } catch (RemoteException e) {
    170         }
    171     }
    172 
    173     private Context mContext;
    174 }
    175