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      */
onEntryUpdated(NotificationEntry entry)60     default void onEntryUpdated(NotificationEntry entry) {
61     }
62 
63     /**
64      * Called whenever a notification is retracted by system server. This method is not called
65      * immediately after a user dismisses a notification: we wait until we receive confirmation from
66      * system server before considering the notification removed.
67      */
onEntryRemoved(@onNull NotificationEntry entry, @CancellationReason int reason)68     default void onEntryRemoved(@NonNull NotificationEntry entry, @CancellationReason int reason) {
69     }
70 
71     /**
72      * Called whenever a {@link NotificationEntry} is considered deleted. This should be used for
73      * cleaning up any state tied to the notification.
74      *
75      * This is the deletion parallel of {@link #onEntryInit} and similarly means that you cannot
76      * expect other {@link NotifCollectionListener} implementations to still have valid state for
77      * the entry during this call. Instead, use {@link #onEntryRemoved} which will be called before
78      * deletion.
79      */
onEntryCleanUp(@onNull NotificationEntry entry)80     default void onEntryCleanUp(@NonNull NotificationEntry entry) {
81     }
82 
83     /**
84      * Called whenever a ranking update is applied. During a ranking update, all active,
85      * non-lifetime-extended notification entries will have their ranking object updated.
86      *
87      * Ranking updates occur whenever a notification is added, updated, or removed, or when a
88      * standalone ranking is sent from the server. If a non-standalone ranking is applied, the event
89      * that accompanied the ranking is emitted first (e.g. {@link #onEntryAdded}), followed by the
90      * ranking event.
91      */
onRankingApplied()92     default void onRankingApplied() {
93     }
94 
95     /**
96      * Called whenever system server sends a standalone ranking update (i.e. one that isn't
97      * associated with a notification being added or removed).
98      *
99      * In general it is unsafe to depend on this method as rankings can change for other reasons.
100      * Instead, listen for {@link #onRankingApplied()}, which is called whenever ANY ranking update
101      * is applied, regardless of source.
102      *
103      * @deprecated Use {@link #onRankingApplied()} instead.
104      */
onRankingUpdate(NotificationListenerService.RankingMap rankingMap)105     default void onRankingUpdate(NotificationListenerService.RankingMap rankingMap) {
106     }
107 }
108