1 /* 2 * Copyright (C) 2019 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.internal.logging; 18 19 import android.annotation.NonNull; 20 import android.annotation.Nullable; 21 22 /** 23 * Logging interface for UI events. Normal implementation is UiEventLoggerImpl. 24 * For testing, use fake implementation UiEventLoggerFake. 25 * 26 * See go/sysui-event-logs and UiEventReported atom in atoms.proto. 27 */ 28 public interface UiEventLogger { 29 /** Put your Event IDs in enums that implement this interface, and document them using the 30 * UiEventEnum annotation. 31 * Event IDs must be globally unique. This will be enforced by tooling (forthcoming). 32 * OEMs should use event IDs above 100000 and below 1000000 (1 million). 33 */ 34 interface UiEventEnum { getId()35 int getId(); 36 } 37 38 /** 39 * Log a simple event, with no package information. Does nothing if event.getId() <= 0. 40 * @param event an enum implementing UiEventEnum interface. 41 */ log(@onNull UiEventEnum event)42 void log(@NonNull UiEventEnum event); 43 44 /** 45 * Log an event with package information. Does nothing if event.getId() <= 0. 46 * Give both uid and packageName if both are known, but one may be omitted if unknown. 47 * @param event an enum implementing UiEventEnum interface. 48 * @param uid the uid of the relevant app, if known (0 otherwise). 49 * @param packageName the package name of the relevant app, if known (null otherwise). 50 */ log(@onNull UiEventEnum event, int uid, @Nullable String packageName)51 void log(@NonNull UiEventEnum event, int uid, @Nullable String packageName); 52 53 /** 54 * Log an event with package information and an instance ID. 55 * Does nothing if event.getId() <= 0. 56 * @param event an enum implementing UiEventEnum interface. 57 * @param uid the uid of the relevant app, if known (0 otherwise). 58 * @param packageName the package name of the relevant app, if known (null otherwise). 59 * @param instance An identifier obtained from an InstanceIdSequence. If null, reduces to log(). 60 */ logWithInstanceId(@onNull UiEventEnum event, int uid, @Nullable String packageName, @Nullable InstanceId instance)61 void logWithInstanceId(@NonNull UiEventEnum event, int uid, @Nullable String packageName, 62 @Nullable InstanceId instance); 63 64 /** 65 * Log an event with ranked-choice information along with package. 66 * Does nothing if event.getId() <= 0. 67 * @param event an enum implementing UiEventEnum interface. 68 * @param uid the uid of the relevant app, if known (0 otherwise). 69 * @param packageName the package name of the relevant app, if known (null otherwise). 70 * @param position the position picked. 71 */ logWithPosition(@onNull UiEventEnum event, int uid, @Nullable String packageName, int position)72 void logWithPosition(@NonNull UiEventEnum event, int uid, @Nullable String packageName, 73 int position); 74 75 /** 76 * Log an event with ranked-choice information along with package and instance ID. 77 * Does nothing if event.getId() <= 0. 78 * @param event an enum implementing UiEventEnum interface. 79 * @param uid the uid of the relevant app, if known (0 otherwise). 80 * @param packageName the package name of the relevant app, if known (null otherwise). 81 * @param instance An identifier obtained from an InstanceIdSequence. If null, reduces to 82 * logWithPosition(). 83 * @param position the position picked. 84 */ logWithInstanceIdAndPosition(@onNull UiEventEnum event, int uid, @Nullable String packageName, @Nullable InstanceId instance, int position)85 void logWithInstanceIdAndPosition(@NonNull UiEventEnum event, int uid, 86 @Nullable String packageName, @Nullable InstanceId instance, int position); 87 } 88