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