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 android.content.Intent; 19 20 import java.lang.annotation.Retention; 21 import java.lang.annotation.Target; 22 23 import static java.lang.annotation.ElementType.ANNOTATION_TYPE; 24 import static java.lang.annotation.ElementType.CONSTRUCTOR; 25 import static java.lang.annotation.ElementType.FIELD; 26 import static java.lang.annotation.ElementType.METHOD; 27 import static java.lang.annotation.ElementType.PARAMETER; 28 import static java.lang.annotation.RetentionPolicy.SOURCE; 29 30 /** 31 * Denotes that the annotated element requires (or may require) one or more permissions. 32 * <p/> 33 * Example of requiring a single permission: 34 * <pre>{@code 35 * {@literal @}RequiresPermission(Manifest.permission.SET_WALLPAPER) 36 * public abstract void setWallpaper(Bitmap bitmap) throws IOException; 37 * 38 * {@literal @}RequiresPermission(ACCESS_COARSE_LOCATION) 39 * public abstract Location getLastKnownLocation(String provider); 40 * }</pre> 41 * Example of requiring at least one permission from a set: 42 * <pre>{@code 43 * {@literal @}RequiresPermission(anyOf = {ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION}) 44 * public abstract Location getLastKnownLocation(String provider); 45 * }</pre> 46 * Example of requiring multiple permissions: 47 * <pre>{@code 48 * {@literal @}RequiresPermission(allOf = {ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION}) 49 * public abstract Location getLastKnownLocation(String provider); 50 * }</pre> 51 * Example of requiring separate read and write permissions for a content provider: 52 * <pre>{@code 53 * {@literal @}RequiresPermission.Read(@RequiresPermission(READ_HISTORY_BOOKMARKS)) 54 * {@literal @}RequiresPermission.Write(@RequiresPermission(WRITE_HISTORY_BOOKMARKS)) 55 * public static final Uri BOOKMARKS_URI = Uri.parse("content://browser/bookmarks"); 56 * }</pre> 57 * <p> 58 * When specified on a parameter, the annotation indicates that the method requires 59 * a permission which depends on the value of the parameter. For example, consider 60 * {@link android.app.Activity#startActivity(Intent)}: 61 * <pre>{@code 62 * public void startActivity(@RequiresPermission Intent intent) { ... } 63 * }</pre> 64 * Notice how there are no actual permission names listed in the annotation. The actual 65 * permissions required will depend on the particular intent passed in. For example, 66 * the code may look like this: 67 * <pre>{@code 68 * Intent intent = new Intent(Intent.ACTION_CALL); 69 * startActivity(intent); 70 * }</pre> 71 * and the actual permission requirement for this particular intent is described on 72 * the Intent name itself: 73 * <pre>{@code 74 * {@literal @}RequiresPermission(Manifest.permission.CALL_PHONE) 75 * public static final String ACTION_CALL = "android.intent.action.CALL"; 76 * }</pre> 77 * 78 * @hide 79 */ 80 @Retention(SOURCE) 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 */ 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 */ 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 */ 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 */ 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 { 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 { 135 RequiresPermission value() default @RequiresPermission; 136 } 137 } 138
