1 /* 2 * Copyright (C) 2025 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.annotation; 18 19 import static java.lang.annotation.ElementType.ANNOTATION_TYPE; 20 import static java.lang.annotation.ElementType.FIELD; 21 import static java.lang.annotation.ElementType.METHOD; 22 import static java.lang.annotation.ElementType.LOCAL_VARIABLE; 23 import static java.lang.annotation.ElementType.PARAMETER; 24 import static java.lang.annotation.ElementType.TYPE; 25 import static java.lang.annotation.ElementType.TYPE_USE; 26 import static java.lang.annotation.RetentionPolicy.SOURCE; 27 28 import java.lang.annotation.Retention; 29 import java.lang.annotation.Target; 30 31 /** 32 * Contains annotations to indicate whether special {@link android.os.UserHandle} values 33 * are permitted for a given {@link android.os.UserHandle} or {@link UserIdInt}. 34 * 35 * <p>User IDs are typically specified by either a UserHandle or a userId int, which ultimately are 36 * whole numbers (0 or larger). There also exist special userId values that correspond to 37 * special cases ("all users", "the current user", etc.), which are internally handled using 38 * negative integers. Some method parameters, return values, and variables accept such special 39 * values, but others do not. This annotation indicates whether they are supported, and which. 40 * 41 * <p>Example usage: 42 * <li><code> 43 * public @CanBeALL @CanBeCURRENT UserHandle myMethod(@CanBeALL @UserIdInt int userId) {} 44 * </code> 45 * 46 * @see android.os.UserHandle#ALL 47 * @see android.os.UserHandle#CURRENT 48 * @see UserHandleAware#specialUsersAllowed() Specification usage for @UserHandleAware 49 * 50 * @hide 51 */ 52 @Retention(SOURCE) 53 public @interface SpecialUsers { 54 /** 55 * Special UserHandle and userId ints corresponding to 56 * <li>{@link android.os.UserHandle#ALL} and {@link android.os.UserHandle#USER_ALL}</li> 57 * <li>{@link android.os.UserHandle#CURRENT} and {@link android.os.UserHandle#USER_CURRENT}</li> 58 * as well as more advanced options (and their negations, catchalls, etc.). 59 */ 60 static enum SpecialUser { 61 // Values direct from UserHandle (common) 62 USER_ALL, USER_CURRENT, 63 // Values direct from UserHandle (less common) 64 USER_CURRENT_OR_SELF, USER_NULL, 65 // Negation of the UserHandle values 66 DISALLOW_USER_ALL, DISALLOW_USER_CURRENT, DISALLOW_USER_CURRENT_OR_SELF, DISALLOW_USER_NULL, 67 // Catchall values (caution: needs to remain valid even if more specials are ever added!) 68 ALLOW_EVERY, DISALLOW_EVERY, 69 // Indication that the answer is as-yet unknown 70 UNSPECIFIED; 71 } 72 73 /** 74 * Indication that a {@link android.os.UserHandle} or {@link UserIdInt} can be 75 * {@link android.os.UserHandle#ALL} and {@link android.os.UserHandle#USER_ALL}, respectively. 76 */ 77 @Retention(SOURCE) 78 @Target({TYPE, TYPE_USE, FIELD, METHOD, PARAMETER, LOCAL_VARIABLE, ANNOTATION_TYPE}) 79 @CanBeUsers(specialUsersAllowed = {SpecialUser.USER_ALL}) 80 public @interface CanBeALL { 81 } 82 83 /** 84 * Indication that a {@link android.os.UserHandle} or {@link UserIdInt} can be 85 * {@link android.os.UserHandle#CURRENT} and {@link android.os.UserHandle#USER_CURRENT}, 86 * respectively. 87 */ 88 @Retention(SOURCE) 89 @Target({TYPE, TYPE_USE, FIELD, METHOD, PARAMETER, LOCAL_VARIABLE, ANNOTATION_TYPE}) 90 @CanBeUsers(specialUsersAllowed = {SpecialUser.USER_CURRENT}) 91 public @interface CanBeCURRENT { 92 } 93 94 /** 95 * Indication that a {@link android.os.UserHandle} or {@link UserIdInt} can be 96 * {@link android.os.UserHandle#NULL} and {@link android.os.UserHandle#USER_NULL}, respectively. 97 * (This is unrelated to the Java concept of <code>null</code>.) 98 */ 99 @Retention(SOURCE) 100 @Target({TYPE, TYPE_USE, FIELD, METHOD, PARAMETER, LOCAL_VARIABLE, ANNOTATION_TYPE}) 101 @CanBeUsers(specialUsersAllowed = {SpecialUser.USER_NULL}) 102 public @interface CanBeNULL { 103 } 104 105 /** 106 * Indication that a {@link android.os.UserHandle} or {@link UserIdInt} cannot take on any 107 * special values. 108 */ 109 @Retention(SOURCE) 110 @Target({TYPE, TYPE_USE, FIELD, METHOD, PARAMETER, LOCAL_VARIABLE, ANNOTATION_TYPE}) 111 @CanBeUsers(specialUsersAllowed = {SpecialUser.DISALLOW_EVERY}) 112 public @interface CannotBeSpecialUser { 113 } 114 115 /** 116 * Indication that a {@link android.os.UserHandle} or {@link UserIdInt} can take on 117 * {@link SpecialUser special values} as specified. 118 * <p> For use when simple {@link CanBeALL} and {@link CanBeCURRENT} do not suffice. 119 */ 120 @Retention(SOURCE) 121 @Target({TYPE, TYPE_USE, FIELD, METHOD, PARAMETER, LOCAL_VARIABLE, ANNOTATION_TYPE}) 122 public @interface CanBeUsers { 123 /** Specify which types of {@link SpecialUser}s are allowed. For use in advanced cases. */ specialUsersAllowed()124 SpecialUser[] specialUsersAllowed() default {SpecialUser.UNSPECIFIED}; 125 } 126 } 127