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.SOURCE; 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 * @hide 78 */ 79 @Retention(SOURCE) 80 @Target({ANNOTATION_TYPE,METHOD,CONSTRUCTOR,FIELD,PARAMETER}) 81 public @interface RequiresPermission { 82 /** 83 * The name of the permission that is required, if precisely one permission 84 * is required. If more than one permission is required, specify either 85 * {@link #allOf()} or {@link #anyOf()} instead. 86 * <p> 87 * If specified, {@link #anyOf()} and {@link #allOf()} must both be null. 88 */ value()89 String value() default ""; 90 91 /** 92 * Specifies a list of permission names that are all required. 93 * <p> 94 * If specified, {@link #anyOf()} and {@link #value()} must both be null. 95 */ allOf()96 String[] allOf() default {}; 97 98 /** 99 * Specifies a list of permission names where at least one is required 100 * <p> 101 * If specified, {@link #allOf()} and {@link #value()} must both be null. 102 */ anyOf()103 String[] anyOf() default {}; 104 105 /** 106 * If true, the permission may not be required in all cases (e.g. it may only be 107 * enforced on certain platforms, or for certain call parameters, etc. 108 */ conditional()109 boolean conditional() default false; 110 111 /** 112 * Specifies that the given permission is required for read operations. 113 * <p> 114 * When specified on a parameter, the annotation indicates that the method requires 115 * a permission which depends on the value of the parameter (and typically 116 * the corresponding field passed in will be one of a set of constants which have 117 * been annotated with a <code>@RequiresPermission</code> annotation.) 118 */ 119 @Target({FIELD, METHOD, PARAMETER}) 120 @interface Read { value()121 RequiresPermission value() default @RequiresPermission; 122 } 123 124 /** 125 * Specifies that the given permission is required for write operations. 126 * <p> 127 * When specified on a parameter, the annotation indicates that the method requires 128 * a permission which depends on the value of the parameter (and typically 129 * the corresponding field passed in will be one of a set of constants which have 130 * been annotated with a <code>@RequiresPermission</code> annotation.) 131 */ 132 @Target({FIELD, METHOD, PARAMETER}) 133 @interface Write { value()134 RequiresPermission value() default @RequiresPermission; 135 } 136 } 137