1 /* 2 * Copyright (C) 2015 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 androidx.annotation; 17 18 import static java.lang.annotation.ElementType.ANNOTATION_TYPE; 19 import static java.lang.annotation.ElementType.CONSTRUCTOR; 20 import static java.lang.annotation.ElementType.FIELD; 21 import static java.lang.annotation.ElementType.METHOD; 22 import static java.lang.annotation.ElementType.PARAMETER; 23 import static java.lang.annotation.RetentionPolicy.CLASS; 24 25 import java.lang.annotation.Retention; 26 import java.lang.annotation.Target; 27 28 /** 29 * Denotes that the annotated element requires (or may require) one or more permissions. 30 * <p> 31 * Example of requiring a single permission: 32 * <pre><code> 33 * @RequiresPermission(Manifest.permission.SET_WALLPAPER) 34 * public abstract void setWallpaper(Bitmap bitmap) throws IOException; 35 * 36 * @RequiresPermission(ACCESS_COARSE_LOCATION) 37 * public abstract Location getLastKnownLocation(String provider); 38 * </code></pre> 39 * Example of requiring at least one permission from a set: 40 * <pre><code> 41 * @RequiresPermission(anyOf = {ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION}) 42 * public abstract Location getLastKnownLocation(String provider); 43 * </code></pre> 44 * Example of requiring multiple permissions: 45 * <pre><code> 46 * @RequiresPermission(allOf = {ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION}) 47 * public abstract Location getLastKnownLocation(String provider); 48 * </code></pre> 49 * Example of requiring separate read and write permissions for a content provider: 50 * <pre><code> 51 * @RequiresPermission.Read(@RequiresPermission(READ_HISTORY_BOOKMARKS)) 52 * @RequiresPermission.Write(@RequiresPermission(WRITE_HISTORY_BOOKMARKS)) 53 * public static final Uri BOOKMARKS_URI = Uri.parse("content://browser/bookmarks"); 54 * </code></pre> 55 * <p> 56 * When specified on a parameter, the annotation indicates that the method requires 57 * a permission which depends on the value of the parameter. For example, consider 58 * {@code android.app.Activity.startActivity(android.content.Intent)}: 59 * <pre>{@code 60 * public void startActivity(@RequiresPermission Intent intent) { ... } 61 * }</pre> 62 * Notice how there are no actual permission names listed in the annotation. The actual 63 * permissions required will depend on the particular intent passed in. For example, 64 * the code may look like this: 65 * <pre>{@code 66 * Intent intent = new Intent(Intent.ACTION_CALL); 67 * startActivity(intent); 68 * }</pre> 69 * and the actual permission requirement for this particular intent is described on 70 * the Intent name itself: 71 * <pre><code> 72 * @RequiresPermission(Manifest.permission.CALL_PHONE) 73 * public static final String ACTION_CALL = "android.intent.action.CALL"; 74 * </code></pre> 75 */ 76 @Retention(CLASS) 77 @Target({ANNOTATION_TYPE,METHOD,CONSTRUCTOR,FIELD,PARAMETER}) 78 public @interface RequiresPermission { 79 /** 80 * The name of the permission that is required, if precisely one permission 81 * is required. If more than one permission is required, specify either 82 * {@link #allOf()} or {@link #anyOf()} instead. 83 * <p> 84 * If specified, {@link #anyOf()} and {@link #allOf()} must both be null. 85 */ 86 String value() default ""; 87 88 /** 89 * Specifies a list of permission names that are all required. 90 * <p> 91 * If specified, {@link #anyOf()} and {@link #value()} must both be null. 92 */ 93 String[] allOf() default {}; 94 95 /** 96 * Specifies a list of permission names where at least one is required 97 * <p> 98 * If specified, {@link #allOf()} and {@link #value()} must both be null. 99 */ 100 String[] anyOf() default {}; 101 102 /** 103 * If true, the permission may not be required in all cases (e.g. it may only be 104 * enforced on certain platforms, or for certain call parameters, etc. 105 */ 106 boolean conditional() default false; 107 108 /** 109 * Specifies that the given permission is required for read operations. 110 * <p> 111 * When specified on a parameter, the annotation indicates that the method requires 112 * a permission which depends on the value of the parameter (and typically 113 * the corresponding field passed in will be one of a set of constants which have 114 * been annotated with a {@code @RequiresPermission} annotation.) 115 */ 116 @Target({FIELD, METHOD, PARAMETER}) 117 @interface Read { 118 RequiresPermission value() default @RequiresPermission; 119 } 120 121 /** 122 * Specifies that the given permission is required for write operations. 123 * <p> 124 * When specified on a parameter, the annotation indicates that the method requires 125 * a permission which depends on the value of the parameter (and typically 126 * the corresponding field passed in will be one of a set of constants which have 127 * been annotated with a {@code @RequiresPermission} annotation.) 128 */ 129 @Target({FIELD, METHOD, PARAMETER}) 130 @interface Write { 131 RequiresPermission value() default @RequiresPermission; 132 } 133 } 134
