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 package android.annotation; 17 18 import static android.annotation.SpecialUsers.SpecialUser.DISALLOW_EVERY; 19 20 import static java.lang.annotation.ElementType.CONSTRUCTOR; 21 import static java.lang.annotation.ElementType.METHOD; 22 import static java.lang.annotation.ElementType.PACKAGE; 23 import static java.lang.annotation.ElementType.TYPE; 24 import static java.lang.annotation.RetentionPolicy.SOURCE; 25 26 import java.lang.annotation.Retention; 27 import java.lang.annotation.Target; 28 29 /** 30 * Indicates an API that uses {@code context.getUser} or {@code context.getUserId} 31 * to operate across users (as the user associated with the context) 32 * <p> 33 * To create a {@link android.content.Context} associated with a different user, 34 * use {@link android.content.Context#createContextAsUser} or 35 * {@link android.content.Context#createPackageContextAsUser} 36 * <p> 37 * Example: 38 * <pre>{@code 39 * {@literal @}UserHandleAware 40 * public abstract PackageInfo getPackageInfo({@literal @}NonNull String packageName, 41 * {@literal @}PackageInfoFlags int flags) throws NameNotFoundException; 42 * }</pre> 43 * This method uses {@linkplain android.content.Context#getUser()} or 44 * {@linkplain android.content.Context#getUserId()} to execute across users. 45 * 46 * @hide 47 */ 48 @Retention(SOURCE) 49 @Target({TYPE, METHOD, CONSTRUCTOR, PACKAGE}) 50 public @interface UserHandleAware { 51 52 /** 53 * Specifies the SDK version at which this method became {@literal @}UserHandleAware, 54 * if it was not always so. 55 * 56 * Prior to this level, the method is not considered {@literal @}UserHandleAware and therefore 57 * uses the {@link android.os.Process#myUserHandle() calling user}, 58 * not the {@link android.content.Context#getUser context user}. 59 * 60 * Note that when an API marked with this parameter is run on a device whose OS predates the 61 * stated version, the calling user will be used, since on such a 62 * device, the API is not {@literal @}UserHandleAware yet. 63 */ enabledSinceTargetSdkVersion()64 int enabledSinceTargetSdkVersion() default 0; 65 66 /** 67 * Specifies the permission name required 68 * if the context user differs from the calling user. 69 * 70 * This requirement is in addition to any specified by 71 * {@link android.annotation.RequiresPermission}. 72 * 73 * @see android.annotation.RequiresPermission#value() 74 */ requiresPermissionIfNotCaller()75 String requiresPermissionIfNotCaller() default ""; 76 77 /** 78 * Specifies a list of permission names where at least one is required 79 * if the context user differs from the calling user. 80 * 81 * This requirement is in addition to any specified by 82 * {@link android.annotation.RequiresPermission}. 83 * 84 * @see android.annotation.RequiresPermission#anyOf() 85 */ requiresAnyOfPermissionsIfNotCaller()86 String[] requiresAnyOfPermissionsIfNotCaller() default {}; 87 88 /** 89 * Specifies a list of permission names where at least one is required if the context 90 * user is not in the same profile group as the calling user. 91 * 92 * This requirement is in addition to any specified by 93 * {@link android.annotation.RequiresPermission}. 94 * 95 * @see android.annotation.RequiresPermission#anyOf() 96 */ requiresAnyOfPermissionsIfNotCallerProfileGroup()97 String[] requiresAnyOfPermissionsIfNotCallerProfileGroup() default {}; 98 99 /** 100 * Indicates whether special {@link android.os.UserHandle UserHandle} values are supported by 101 * this method or class. 102 * 103 * <p>When creating a Context using (e.g. via 104 * {@link android.content.Context#createContextAsUser}), a special UserHandle (such as 105 * {@link android.os.UserHandle#CURRENT}) can be used. 106 * However, most UserHandleAware methods do not support Contexts built upon such special 107 * users. This annotation indicates whether they are supported, and which. Note that it is 108 * likely rare that any special users are supported. 109 * 110 * <p>Typical values could include one or more of 111 * <li>{@link SpecialUsers.SpecialUser#USER_ALL} 112 * <li>{@link SpecialUsers.SpecialUser#USER_CURRENT} 113 * <li>{@link SpecialUsers.SpecialUser#DISALLOW_EVERY} 114 */ specialUsersAllowed()115 SpecialUsers.SpecialUser[] specialUsersAllowed() default {DISALLOW_EVERY}; 116 } 117