NotificationAssistantService.java revision 9fa689f8b614d32f36b5f2de2e3065f4ad6b2358
1/* 2 * Copyright (C) 2015 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.service.notification; 18 19import android.app.Notification; 20import android.net.Uri; 21 22/** 23 * A service that helps the user manage notifications by modifying the 24 * relative importance of notifications. 25 * <p>To extend this class, you must declare the service in your manifest file with 26 * the {@link android.Manifest.permission#BIND_NOTIFICATION_ASSISTANT_SERVICE} permission 27 * and include an intent filter with the {@link #SERVICE_INTERFACE} action. For example:</p> 28 * <pre> 29 * <service android:name=".NotificationAssistant" 30 * android:label="@string/service_name" 31 * android:permission="android.permission.BIND_NOTIFICATION_ASSISTANT_SERVICE"> 32 * <intent-filter> 33 * <action android:name="android.service.notification.NotificationAssistantService" /> 34 * </intent-filter> 35 * </service></pre> 36 */ 37public abstract class NotificationAssistantService extends NotificationListenerService { 38 /** Notification was canceled by the status bar reporting a click. */ 39 public static final int REASON_DELEGATE_CLICK = 1; 40 41 /** Notification was canceled by the status bar reporting a user dismissal. */ 42 public static final int REASON_DELEGATE_CANCEL = 2; 43 44 /** Notification was canceled by the status bar reporting a user dismiss all. */ 45 public static final int REASON_DELEGATE_CANCEL_ALL = 3; 46 47 /** Notification was canceled by the status bar reporting an inflation error. */ 48 public static final int REASON_DELEGATE_ERROR = 4; 49 50 /** Notification was canceled by the package manager modifying the package. */ 51 public static final int REASON_PACKAGE_CHANGED = 5; 52 53 /** Notification was canceled by the owning user context being stopped. */ 54 public static final int REASON_USER_STOPPED = 6; 55 56 /** Notification was canceled by the user banning the package. */ 57 public static final int REASON_PACKAGE_BANNED = 7; 58 59 /** Notification was canceled by the app canceling this specific notification. */ 60 public static final int REASON_APP_CANCEL = 8; 61 62 /** Notification was canceled by the app cancelling all its notifications. */ 63 public static final int REASON_APP_CANCEL_ALL = 9; 64 65 /** Notification was canceled by a listener reporting a user dismissal. */ 66 public static final int REASON_LISTENER_CANCEL = 10; 67 68 /** Notification was canceled by a listener reporting a user dismiss all. */ 69 public static final int REASON_LISTENER_CANCEL_ALL = 11; 70 71 /** Notification was canceled because it was a member of a canceled group. */ 72 public static final int REASON_GROUP_SUMMARY_CANCELED = 12; 73 74 /** Notification was canceled because it was an invisible member of a group. */ 75 public static final int REASON_GROUP_OPTIMIZATION = 13; 76 77 public class Adjustment { 78 int mImportance; 79 CharSequence mExplanation; 80 Uri mReference; 81 82 /** 83 * Create a notification importance adjustment. 84 * 85 * @param importance The final importance of the notification. 86 * @param explanation A human-readable justification for the adjustment. 87 * @param reference A reference to an external object that augments the 88 * explanation, such as a 89 * {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI}, 90 * or null. 91 */ 92 public Adjustment(int importance, CharSequence explanation, Uri reference) { 93 mImportance = importance; 94 mExplanation = explanation; 95 mReference = reference; 96 } 97 } 98 99 /** 100 * A notification was posted by an app. Called before alert. 101 * 102 * @param sbn the new notification 103 * @param importance the initial importance of the notification. 104 * @param user true if the initial importance reflects an explicit user preference. 105 * @return an adjustment or null to take no action, within 100ms. 106 */ 107 abstract public Adjustment onNotificationEnqueued(StatusBarNotification sbn, 108 int importance, boolean user); 109 110 /** 111 * The visibility of a notification has changed. 112 * 113 * @param key the notification key 114 * @param time milliseconds since midnight, January 1, 1970 UTC. 115 * @param visible true if the notification became visible, false if hidden. 116 */ 117 public void onNotificationVisibilityChanged(String key, long time, boolean visible) 118 { 119 // Do nothing, Override this to collect visibility statistics. 120 } 121 122 /** 123 * The user clicked on a notification. 124 * 125 * @param key the notification key 126 * @param time milliseconds since midnight, January 1, 1970 UTC. 127 */ 128 public void onNotificationClick(String key, long time) 129 { 130 // Do nothing, Override this to collect click statistics 131 } 132 133 /** 134 * The user clicked on a notification action. 135 * 136 * @param key the notification key 137 * @param time milliseconds since midnight, January 1, 1970 UTC. 138 * @param actionIndex the index of the action button that was pressed. 139 */ 140 public void onNotificationActionClick(String key, long time, int actionIndex) 141 { 142 // Do nothing, Override this to collect action button click statistics 143 } 144 145 /** 146 * A notification was removed. 147 148 * @param key the notification key 149 * @param time milliseconds since midnight, January 1, 1970 UTC. 150 * @param reason see {@link #REASON_LISTENER_CANCEL}, etc. 151 */ 152 public void onNotificationRemoved(String key, long time, int reason) { 153 // Do nothing, Override this to collect dismissal statistics 154 } 155 156 /** 157 * Change the importance of an existing notification. N.B. this won’t cause 158 * an existing notification to alert, but might allow a future update to 159 * this notification to alert. 160 * 161 * @param key the notification key 162 * @param adjustment the new importance with an explanation 163 */ 164 public final void adjustImportance(String key, Adjustment adjustment) 165 { 166 // TODO: pack up the adjustment and send it to the NotificationManager. 167 } 168 169 /** 170 * Add an annotation to a an existing notification. The delete intent will 171 * be fired when the host notification is deleted, or when this annotation 172 * is removed or replaced. 173 * 174 * @param key the notification key 175 * @param annotation the new annotation object 176 */ 177 public final void setAnnotation(String key, Notification annotation) 178 { 179 // TODO: pack up the annotation and send it to the NotificationManager. 180 } 181 182 /** 183 * Remove the annotation from a notification. 184 * 185 * @param key the notification key 186 */ 187 public final void clearAnnotation(String key) 188 { 189 // TODO: ask the NotificationManager to clear the annotation. 190 } 191} 192