1 /*
2  * Copyright (C) 2020 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 com.android.systemui.statusbar.notification.collection.notifcollection;
18 
19 import android.annotation.NonNull;
20 import android.service.notification.NotificationListenerService;
21 import android.service.notification.StatusBarNotification;
22 
23 import com.android.systemui.statusbar.notification.collection.NotifCollection.CancellationReason;
24 import com.android.systemui.statusbar.notification.collection.NotificationEntry;
25 
26 /**
27  * Listener interface for {@link NotificationEntry} events.
28  */
29 public interface NotifCollectionListener {
30 
31     /**
32      * Called when the entry is having a new status bar notification bound to it. This should
33      * be used to initialize any derivative state on the entry that needs to update when the
34      * notification is updated.
35      */
onEntryBind(NotificationEntry entry, StatusBarNotification sbn)36     default void onEntryBind(NotificationEntry entry, StatusBarNotification sbn) {
37     }
38 
39     /**
40      * Called whenever a new {@link NotificationEntry} is initialized. This should be used for
41      * initializing any decorated state tied to the notification.
42      *
43      * Do not reference other registered {@link NotifCollectionListener} implementations here as
44      * there is no guarantee of order and they may not have had a chance to initialize yet. Instead,
45      * use {@link #onEntryAdded} which is called after all initialization.
46      */
onEntryInit(@onNull NotificationEntry entry)47     default void onEntryInit(@NonNull NotificationEntry entry) {
48     }
49 
50     /**
51      * Called whenever a notification with a new key is posted.
52      */
onEntryAdded(@onNull NotificationEntry entry)53     default void onEntryAdded(@NonNull NotificationEntry entry) {
54     }
55 
56     /**
57      * Called whenever a notification with the same key as an existing notification is posted. By
58      * the time this listener is called, the entry's SBN and Ranking will already have been updated.
59      * This delegates to {@link #onEntryUpdated(NotificationEntry)} by default.
60      * @param fromSystem If true, this update came from the NotificationManagerService.
61      *                   If false, the notification update is an internal change within systemui.
62      */
onEntryUpdated(@onNull NotificationEntry entry, boolean fromSystem)63     default void onEntryUpdated(@NonNull NotificationEntry entry, boolean fromSystem) {
64         onEntryUpdated(entry);
65     }
66 
67     /**
68      * Called whenever a notification with the same key as an existing notification is posted. By
69      * the time this listener is called, the entry's SBN and Ranking will already have been updated.
70      */
onEntryUpdated(@onNull NotificationEntry entry)71     default void onEntryUpdated(@NonNull NotificationEntry entry) {
72     }
73 
74     /**
75      * Called whenever a notification is retracted by system server. This method is not called
76      * immediately after a user dismisses a notification: we wait until we receive confirmation from
77      * system server before considering the notification removed.
78      */
onEntryRemoved(@onNull NotificationEntry entry, @CancellationReason int reason)79     default void onEntryRemoved(@NonNull NotificationEntry entry, @CancellationReason int reason) {
80     }
81 
82     /**
83      * Called whenever a {@link NotificationEntry} is considered deleted. This should be used for
84      * cleaning up any state tied to the notification.
85      *
86      * This is the deletion parallel of {@link #onEntryInit} and similarly means that you cannot
87      * expect other {@link NotifCollectionListener} implementations to still have valid state for
88      * the entry during this call. Instead, use {@link #onEntryRemoved} which will be called before
89      * deletion.
90      */
onEntryCleanUp(@onNull NotificationEntry entry)91     default void onEntryCleanUp(@NonNull NotificationEntry entry) {
92     }
93 
94     /**
95      * Called whenever a ranking update is applied. During a ranking update, all active,
96      * non-lifetime-extended notification entries will have their ranking object updated.
97      *
98      * Ranking updates occur whenever a notification is added, updated, or removed, or when a
99      * standalone ranking is sent from the server. If a non-standalone ranking is applied, the event
100      * that accompanied the ranking is emitted first (e.g. {@link #onEntryAdded}), followed by the
101      * ranking event.
102      */
onRankingApplied()103     default void onRankingApplied() {
104     }
105 
106     /**
107      * Called whenever system server sends a standalone ranking update (i.e. one that isn't
108      * associated with a notification being added or removed).
109      *
110      * In general it is unsafe to depend on this method as rankings can change for other reasons.
111      * Instead, listen for {@link #onRankingApplied()}, which is called whenever ANY ranking update
112      * is applied, regardless of source.
113      *
114      * @deprecated Use {@link #onRankingApplied()} instead.
115      */
onRankingUpdate(NotificationListenerService.RankingMap rankingMap)116     default void onRankingUpdate(NotificationListenerService.RankingMap rankingMap) {
117     }
118 }
119