Context.java revision 278fb3b35920cd7d5ba4ce3a4c24776e89007bbd
1/* 2 * Copyright (C) 2006 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 17package android.content; 18 19import android.annotation.AttrRes; 20import android.annotation.CheckResult; 21import android.annotation.ColorInt; 22import android.annotation.ColorRes; 23import android.annotation.DrawableRes; 24import android.annotation.IntDef; 25import android.annotation.NonNull; 26import android.annotation.Nullable; 27import android.annotation.RequiresPermission; 28import android.annotation.StringDef; 29import android.annotation.StringRes; 30import android.annotation.StyleRes; 31import android.annotation.StyleableRes; 32import android.annotation.SystemApi; 33import android.annotation.TestApi; 34import android.annotation.UserIdInt; 35import android.content.pm.ApplicationInfo; 36import android.content.pm.PackageManager; 37import android.content.res.AssetManager; 38import android.content.res.ColorStateList; 39import android.content.res.Configuration; 40import android.content.res.Resources; 41import android.content.res.TypedArray; 42import android.database.DatabaseErrorHandler; 43import android.database.sqlite.SQLiteDatabase; 44import android.database.sqlite.SQLiteDatabase.CursorFactory; 45import android.graphics.Bitmap; 46import android.graphics.drawable.Drawable; 47import android.net.Uri; 48import android.os.Bundle; 49import android.os.Environment; 50import android.os.Handler; 51import android.os.IBinder; 52import android.os.Looper; 53import android.os.StatFs; 54import android.os.UserHandle; 55import android.os.UserManager; 56import android.provider.MediaStore; 57import android.util.AttributeSet; 58import android.view.Display; 59import android.view.DisplayAdjustments; 60import android.view.ViewDebug; 61import android.view.WindowManager; 62 63import java.io.File; 64import java.io.FileInputStream; 65import java.io.FileNotFoundException; 66import java.io.FileOutputStream; 67import java.io.IOException; 68import java.io.InputStream; 69import java.lang.annotation.Retention; 70import java.lang.annotation.RetentionPolicy; 71 72/** 73 * Interface to global information about an application environment. This is 74 * an abstract class whose implementation is provided by 75 * the Android system. It 76 * allows access to application-specific resources and classes, as well as 77 * up-calls for application-level operations such as launching activities, 78 * broadcasting and receiving intents, etc. 79 */ 80public abstract class Context { 81 /** 82 * File creation mode: the default mode, where the created file can only 83 * be accessed by the calling application (or all applications sharing the 84 * same user ID). 85 */ 86 public static final int MODE_PRIVATE = 0x0000; 87 88 /** 89 * File creation mode: allow all other applications to have read access to 90 * the created file. 91 * <p> 92 * As of {@link android.os.Build.VERSION_CODES#N} attempting to use this 93 * mode will throw a {@link SecurityException}. 94 * 95 * @deprecated Creating world-readable files is very dangerous, and likely 96 * to cause security holes in applications. It is strongly 97 * discouraged; instead, applications should use more formal 98 * mechanism for interactions such as {@link ContentProvider}, 99 * {@link BroadcastReceiver}, and {@link android.app.Service}. 100 * There are no guarantees that this access mode will remain on 101 * a file, such as when it goes through a backup and restore. 102 * @see android.support.v4.content.FileProvider 103 * @see Intent#FLAG_GRANT_WRITE_URI_PERMISSION 104 */ 105 @Deprecated 106 public static final int MODE_WORLD_READABLE = 0x0001; 107 108 /** 109 * File creation mode: allow all other applications to have write access to 110 * the created file. 111 * <p> 112 * As of {@link android.os.Build.VERSION_CODES#N} attempting to use this 113 * mode will throw a {@link SecurityException}. 114 * 115 * @deprecated Creating world-writable files is very dangerous, and likely 116 * to cause security holes in applications. It is strongly 117 * discouraged; instead, applications should use more formal 118 * mechanism for interactions such as {@link ContentProvider}, 119 * {@link BroadcastReceiver}, and {@link android.app.Service}. 120 * There are no guarantees that this access mode will remain on 121 * a file, such as when it goes through a backup and restore. 122 * @see android.support.v4.content.FileProvider 123 * @see Intent#FLAG_GRANT_WRITE_URI_PERMISSION 124 */ 125 @Deprecated 126 public static final int MODE_WORLD_WRITEABLE = 0x0002; 127 128 /** 129 * File creation mode: for use with {@link #openFileOutput}, if the file 130 * already exists then write data to the end of the existing file 131 * instead of erasing it. 132 * @see #openFileOutput 133 */ 134 public static final int MODE_APPEND = 0x8000; 135 136 /** 137 * SharedPreference loading flag: when set, the file on disk will 138 * be checked for modification even if the shared preferences 139 * instance is already loaded in this process. This behavior is 140 * sometimes desired in cases where the application has multiple 141 * processes, all writing to the same SharedPreferences file. 142 * Generally there are better forms of communication between 143 * processes, though. 144 * 145 * <p>This was the legacy (but undocumented) behavior in and 146 * before Gingerbread (Android 2.3) and this flag is implied when 147 * targetting such releases. For applications targetting SDK 148 * versions <em>greater than</em> Android 2.3, this flag must be 149 * explicitly set if desired. 150 * 151 * @see #getSharedPreferences 152 * 153 * @deprecated MODE_MULTI_PROCESS does not work reliably in 154 * some versions of Android, and furthermore does not provide any 155 * mechanism for reconciling concurrent modifications across 156 * processes. Applications should not attempt to use it. Instead, 157 * they should use an explicit cross-process data management 158 * approach such as {@link android.content.ContentProvider ContentProvider}. 159 */ 160 @Deprecated 161 public static final int MODE_MULTI_PROCESS = 0x0004; 162 163 /** 164 * Database open flag: when set, the database is opened with write-ahead 165 * logging enabled by default. 166 * 167 * @see #openOrCreateDatabase(String, int, CursorFactory) 168 * @see #openOrCreateDatabase(String, int, CursorFactory, DatabaseErrorHandler) 169 * @see SQLiteDatabase#enableWriteAheadLogging 170 */ 171 public static final int MODE_ENABLE_WRITE_AHEAD_LOGGING = 0x0008; 172 173 /** 174 * Database open flag: when set, the database is opened without support for 175 * localized collators. 176 * 177 * @see #openOrCreateDatabase(String, int, CursorFactory) 178 * @see #openOrCreateDatabase(String, int, CursorFactory, DatabaseErrorHandler) 179 * @see SQLiteDatabase#NO_LOCALIZED_COLLATORS 180 */ 181 public static final int MODE_NO_LOCALIZED_COLLATORS = 0x0010; 182 183 /** @hide */ 184 @IntDef(flag = true, 185 value = { 186 BIND_AUTO_CREATE, 187 BIND_DEBUG_UNBIND, 188 BIND_NOT_FOREGROUND, 189 BIND_ABOVE_CLIENT, 190 BIND_ALLOW_OOM_MANAGEMENT, 191 BIND_WAIVE_PRIORITY, 192 BIND_IMPORTANT, 193 BIND_ADJUST_WITH_ACTIVITY 194 }) 195 @Retention(RetentionPolicy.SOURCE) 196 public @interface BindServiceFlags {} 197 198 /** 199 * Flag for {@link #bindService}: automatically create the service as long 200 * as the binding exists. Note that while this will create the service, 201 * its {@link android.app.Service#onStartCommand} 202 * method will still only be called due to an 203 * explicit call to {@link #startService}. Even without that, though, 204 * this still provides you with access to the service object while the 205 * service is created. 206 * 207 * <p>Note that prior to {@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH}, 208 * not supplying this flag would also impact how important the system 209 * consider's the target service's process to be. When set, the only way 210 * for it to be raised was by binding from a service in which case it will 211 * only be important when that activity is in the foreground. Now to 212 * achieve this behavior you must explicitly supply the new flag 213 * {@link #BIND_ADJUST_WITH_ACTIVITY}. For compatibility, old applications 214 * that don't specify {@link #BIND_AUTO_CREATE} will automatically have 215 * the flags {@link #BIND_WAIVE_PRIORITY} and 216 * {@link #BIND_ADJUST_WITH_ACTIVITY} set for them in order to achieve 217 * the same result. 218 */ 219 public static final int BIND_AUTO_CREATE = 0x0001; 220 221 /** 222 * Flag for {@link #bindService}: include debugging help for mismatched 223 * calls to unbind. When this flag is set, the callstack of the following 224 * {@link #unbindService} call is retained, to be printed if a later 225 * incorrect unbind call is made. Note that doing this requires retaining 226 * information about the binding that was made for the lifetime of the app, 227 * resulting in a leak -- this should only be used for debugging. 228 */ 229 public static final int BIND_DEBUG_UNBIND = 0x0002; 230 231 /** 232 * Flag for {@link #bindService}: don't allow this binding to raise 233 * the target service's process to the foreground scheduling priority. 234 * It will still be raised to at least the same memory priority 235 * as the client (so that its process will not be killable in any 236 * situation where the client is not killable), but for CPU scheduling 237 * purposes it may be left in the background. This only has an impact 238 * in the situation where the binding client is a foreground process 239 * and the target service is in a background process. 240 */ 241 public static final int BIND_NOT_FOREGROUND = 0x0004; 242 243 /** 244 * Flag for {@link #bindService}: indicates that the client application 245 * binding to this service considers the service to be more important than 246 * the app itself. When set, the platform will try to have the out of 247 * memory killer kill the app before it kills the service it is bound to, though 248 * this is not guaranteed to be the case. 249 */ 250 public static final int BIND_ABOVE_CLIENT = 0x0008; 251 252 /** 253 * Flag for {@link #bindService}: allow the process hosting the bound 254 * service to go through its normal memory management. It will be 255 * treated more like a running service, allowing the system to 256 * (temporarily) expunge the process if low on memory or for some other 257 * whim it may have, and being more aggressive about making it a candidate 258 * to be killed (and restarted) if running for a long time. 259 */ 260 public static final int BIND_ALLOW_OOM_MANAGEMENT = 0x0010; 261 262 /** 263 * Flag for {@link #bindService}: don't impact the scheduling or 264 * memory management priority of the target service's hosting process. 265 * Allows the service's process to be managed on the background LRU list 266 * just like a regular application process in the background. 267 */ 268 public static final int BIND_WAIVE_PRIORITY = 0x0020; 269 270 /** 271 * Flag for {@link #bindService}: this service is very important to 272 * the client, so should be brought to the foreground process level 273 * when the client is. Normally a process can only be raised to the 274 * visibility level by a client, even if that client is in the foreground. 275 */ 276 public static final int BIND_IMPORTANT = 0x0040; 277 278 /** 279 * Flag for {@link #bindService}: If binding from an activity, allow the 280 * target service's process importance to be raised based on whether the 281 * activity is visible to the user, regardless whether another flag is 282 * used to reduce the amount that the client process's overall importance 283 * is used to impact it. 284 */ 285 public static final int BIND_ADJUST_WITH_ACTIVITY = 0x0080; 286 287 /** 288 * @hide Flag for {@link #bindService}: Like {@link #BIND_FOREGROUND_SERVICE}, 289 * but only applies while the device is awake. 290 */ 291 public static final int BIND_FOREGROUND_SERVICE_WHILE_AWAKE = 0x02000000; 292 293 /** 294 * @hide Flag for {@link #bindService}: For only the case where the binding 295 * is coming from the system, set the process state to FOREGROUND_SERVICE 296 * instead of the normal maximum of IMPORTANT_FOREGROUND. That is, this is 297 * saying that the process shouldn't participate in the normal power reduction 298 * modes (removing network access etc). 299 */ 300 public static final int BIND_FOREGROUND_SERVICE = 0x04000000; 301 302 /** 303 * @hide Flag for {@link #bindService}: Treat the binding as hosting 304 * an activity, an unbinding as the activity going in the background. 305 * That is, when unbinding, the process when empty will go on the activity 306 * LRU list instead of the regular one, keeping it around more aggressively 307 * than it otherwise would be. This is intended for use with IMEs to try 308 * to keep IME processes around for faster keyboard switching. 309 */ 310 public static final int BIND_TREAT_LIKE_ACTIVITY = 0x08000000; 311 312 /** 313 * @hide An idea that is not yet implemented. 314 * Flag for {@link #bindService}: If binding from an activity, consider 315 * this service to be visible like the binding activity is. That is, 316 * it will be treated as something more important to keep around than 317 * invisible background activities. This will impact the number of 318 * recent activities the user can switch between without having them 319 * restart. There is no guarantee this will be respected, as the system 320 * tries to balance such requests from one app vs. the importantance of 321 * keeping other apps around. 322 */ 323 public static final int BIND_VISIBLE = 0x10000000; 324 325 /** 326 * @hide 327 * Flag for {@link #bindService}: Consider this binding to be causing the target 328 * process to be showing UI, so it will be do a UI_HIDDEN memory trim when it goes 329 * away. 330 */ 331 public static final int BIND_SHOWING_UI = 0x20000000; 332 333 /** 334 * Flag for {@link #bindService}: Don't consider the bound service to be 335 * visible, even if the caller is visible. 336 * @hide 337 */ 338 public static final int BIND_NOT_VISIBLE = 0x40000000; 339 340 /** 341 * Flag for {@link #bindService}: The service being bound is an 342 * {@link android.R.attr#isolatedProcess isolated}, 343 * {@link android.R.attr#externalService external} service. This binds the service into the 344 * calling application's package, rather than the package in which the service is declared. 345 */ 346 public static final int BIND_EXTERNAL_SERVICE = 0x80000000; 347 348 /** 349 * Returns an AssetManager instance for the application's package. 350 * <p> 351 * <strong>Note:</strong> Implementations of this method should return 352 * an AssetManager instance that is consistent with the Resources instance 353 * returned by {@link #getResources()}. For example, they should share the 354 * same {@link Configuration} object. 355 * 356 * @return an AssetManager instance for the application's package 357 * @see #getResources() 358 */ 359 public abstract AssetManager getAssets(); 360 361 /** 362 * Returns a Resources instance for the application's package. 363 * <p> 364 * <strong>Note:</strong> Implementations of this method should return 365 * a Resources instance that is consistent with the AssetManager instance 366 * returned by {@link #getAssets()}. For example, they should share the 367 * same {@link Configuration} object. 368 * 369 * @return a Resources instance for the application's package 370 * @see #getAssets() 371 */ 372 public abstract Resources getResources(); 373 374 /** Return PackageManager instance to find global package information. */ 375 public abstract PackageManager getPackageManager(); 376 377 /** Return a ContentResolver instance for your application's package. */ 378 public abstract ContentResolver getContentResolver(); 379 380 /** 381 * Return the Looper for the main thread of the current process. This is 382 * the thread used to dispatch calls to application components (activities, 383 * services, etc). 384 * <p> 385 * By definition, this method returns the same result as would be obtained 386 * by calling {@link Looper#getMainLooper() Looper.getMainLooper()}. 387 * </p> 388 * 389 * @return The main looper. 390 */ 391 public abstract Looper getMainLooper(); 392 393 /** 394 * Return the context of the single, global Application object of the 395 * current process. This generally should only be used if you need a 396 * Context whose lifecycle is separate from the current context, that is 397 * tied to the lifetime of the process rather than the current component. 398 * 399 * <p>Consider for example how this interacts with 400 * {@link #registerReceiver(BroadcastReceiver, IntentFilter)}: 401 * <ul> 402 * <li> <p>If used from an Activity context, the receiver is being registered 403 * within that activity. This means that you are expected to unregister 404 * before the activity is done being destroyed; in fact if you do not do 405 * so, the framework will clean up your leaked registration as it removes 406 * the activity and log an error. Thus, if you use the Activity context 407 * to register a receiver that is static (global to the process, not 408 * associated with an Activity instance) then that registration will be 409 * removed on you at whatever point the activity you used is destroyed. 410 * <li> <p>If used from the Context returned here, the receiver is being 411 * registered with the global state associated with your application. Thus 412 * it will never be unregistered for you. This is necessary if the receiver 413 * is associated with static data, not a particular component. However 414 * using the ApplicationContext elsewhere can easily lead to serious leaks 415 * if you forget to unregister, unbind, etc. 416 * </ul> 417 */ 418 public abstract Context getApplicationContext(); 419 420 /** 421 * Add a new {@link ComponentCallbacks} to the base application of the 422 * Context, which will be called at the same times as the ComponentCallbacks 423 * methods of activities and other components are called. Note that you 424 * <em>must</em> be sure to use {@link #unregisterComponentCallbacks} when 425 * appropriate in the future; this will not be removed for you. 426 * 427 * @param callback The interface to call. This can be either a 428 * {@link ComponentCallbacks} or {@link ComponentCallbacks2} interface. 429 */ 430 public void registerComponentCallbacks(ComponentCallbacks callback) { 431 getApplicationContext().registerComponentCallbacks(callback); 432 } 433 434 /** 435 * Remove a {@link ComponentCallbacks} object that was previously registered 436 * with {@link #registerComponentCallbacks(ComponentCallbacks)}. 437 */ 438 public void unregisterComponentCallbacks(ComponentCallbacks callback) { 439 getApplicationContext().unregisterComponentCallbacks(callback); 440 } 441 442 /** 443 * Return a localized, styled CharSequence from the application's package's 444 * default string table. 445 * 446 * @param resId Resource id for the CharSequence text 447 */ 448 public final CharSequence getText(@StringRes int resId) { 449 return getResources().getText(resId); 450 } 451 452 /** 453 * Returns a localized string from the application's package's 454 * default string table. 455 * 456 * @param resId Resource id for the string 457 * @return The string data associated with the resource, stripped of styled 458 * text information. 459 */ 460 @NonNull 461 public final String getString(@StringRes int resId) { 462 return getResources().getString(resId); 463 } 464 465 /** 466 * Returns a localized formatted string from the application's package's 467 * default string table, substituting the format arguments as defined in 468 * {@link java.util.Formatter} and {@link java.lang.String#format}. 469 * 470 * @param resId Resource id for the format string 471 * @param formatArgs The format arguments that will be used for 472 * substitution. 473 * @return The string data associated with the resource, formatted and 474 * stripped of styled text information. 475 */ 476 @NonNull 477 public final String getString(@StringRes int resId, Object... formatArgs) { 478 return getResources().getString(resId, formatArgs); 479 } 480 481 /** 482 * Returns a color associated with a particular resource ID and styled for 483 * the current theme. 484 * 485 * @param id The desired resource identifier, as generated by the aapt 486 * tool. This integer encodes the package, type, and resource 487 * entry. The value 0 is an invalid identifier. 488 * @return A single color value in the form 0xAARRGGBB. 489 * @throws android.content.res.Resources.NotFoundException if the given ID 490 * does not exist. 491 */ 492 @ColorInt 493 public final int getColor(@ColorRes int id) { 494 return getResources().getColor(id, getTheme()); 495 } 496 497 /** 498 * Returns a drawable object associated with a particular resource ID and 499 * styled for the current theme. 500 * 501 * @param id The desired resource identifier, as generated by the aapt 502 * tool. This integer encodes the package, type, and resource 503 * entry. The value 0 is an invalid identifier. 504 * @return An object that can be used to draw this resource, or 505 * {@code null} if the resource could not be resolved. 506 * @throws android.content.res.Resources.NotFoundException if the given ID 507 * does not exist. 508 */ 509 @Nullable 510 public final Drawable getDrawable(@DrawableRes int id) { 511 return getResources().getDrawable(id, getTheme()); 512 } 513 514 /** 515 * Returns a color state list associated with a particular resource ID and 516 * styled for the current theme. 517 * 518 * @param id The desired resource identifier, as generated by the aapt 519 * tool. This integer encodes the package, type, and resource 520 * entry. The value 0 is an invalid identifier. 521 * @return A color state list, or {@code null} if the resource could not be 522 * resolved. 523 * @throws android.content.res.Resources.NotFoundException if the given ID 524 * does not exist. 525 */ 526 @Nullable 527 public final ColorStateList getColorStateList(@ColorRes int id) { 528 return getResources().getColorStateList(id, getTheme()); 529 } 530 531 /** 532 * Set the base theme for this context. Note that this should be called 533 * before any views are instantiated in the Context (for example before 534 * calling {@link android.app.Activity#setContentView} or 535 * {@link android.view.LayoutInflater#inflate}). 536 * 537 * @param resid The style resource describing the theme. 538 */ 539 public abstract void setTheme(@StyleRes int resid); 540 541 /** @hide Needed for some internal implementation... not public because 542 * you can't assume this actually means anything. */ 543 public int getThemeResId() { 544 return 0; 545 } 546 547 /** 548 * Return the Theme object associated with this Context. 549 */ 550 @ViewDebug.ExportedProperty(deepExport = true) 551 public abstract Resources.Theme getTheme(); 552 553 /** 554 * Retrieve styled attribute information in this Context's theme. See 555 * {@link android.content.res.Resources.Theme#obtainStyledAttributes(int[])} 556 * for more information. 557 * 558 * @see android.content.res.Resources.Theme#obtainStyledAttributes(int[]) 559 */ 560 public final TypedArray obtainStyledAttributes(@StyleableRes int[] attrs) { 561 return getTheme().obtainStyledAttributes(attrs); 562 } 563 564 /** 565 * Retrieve styled attribute information in this Context's theme. See 566 * {@link android.content.res.Resources.Theme#obtainStyledAttributes(int, int[])} 567 * for more information. 568 * 569 * @see android.content.res.Resources.Theme#obtainStyledAttributes(int, int[]) 570 */ 571 public final TypedArray obtainStyledAttributes( 572 @StyleRes int resid, @StyleableRes int[] attrs) throws Resources.NotFoundException { 573 return getTheme().obtainStyledAttributes(resid, attrs); 574 } 575 576 /** 577 * Retrieve styled attribute information in this Context's theme. See 578 * {@link android.content.res.Resources.Theme#obtainStyledAttributes(AttributeSet, int[], int, int)} 579 * for more information. 580 * 581 * @see android.content.res.Resources.Theme#obtainStyledAttributes(AttributeSet, int[], int, int) 582 */ 583 public final TypedArray obtainStyledAttributes( 584 AttributeSet set, @StyleableRes int[] attrs) { 585 return getTheme().obtainStyledAttributes(set, attrs, 0, 0); 586 } 587 588 /** 589 * Retrieve styled attribute information in this Context's theme. See 590 * {@link android.content.res.Resources.Theme#obtainStyledAttributes(AttributeSet, int[], int, int)} 591 * for more information. 592 * 593 * @see android.content.res.Resources.Theme#obtainStyledAttributes(AttributeSet, int[], int, int) 594 */ 595 public final TypedArray obtainStyledAttributes( 596 AttributeSet set, @StyleableRes int[] attrs, @AttrRes int defStyleAttr, 597 @StyleRes int defStyleRes) { 598 return getTheme().obtainStyledAttributes( 599 set, attrs, defStyleAttr, defStyleRes); 600 } 601 602 /** 603 * Return a class loader you can use to retrieve classes in this package. 604 */ 605 public abstract ClassLoader getClassLoader(); 606 607 /** Return the name of this application's package. */ 608 public abstract String getPackageName(); 609 610 /** @hide Return the name of the base context this context is derived from. */ 611 public abstract String getBasePackageName(); 612 613 /** @hide Return the package name that should be used for app ops calls from 614 * this context. This is the same as {@link #getBasePackageName()} except in 615 * cases where system components are loaded into other app processes, in which 616 * case this will be the name of the primary package in that process (so that app 617 * ops uid verification will work with the name). */ 618 public abstract String getOpPackageName(); 619 620 /** Return the full application info for this context's package. */ 621 public abstract ApplicationInfo getApplicationInfo(); 622 623 /** 624 * Return the full path to this context's primary Android package. 625 * The Android package is a ZIP file which contains the application's 626 * primary resources. 627 * 628 * <p>Note: this is not generally useful for applications, since they should 629 * not be directly accessing the file system. 630 * 631 * @return String Path to the resources. 632 */ 633 public abstract String getPackageResourcePath(); 634 635 /** 636 * Return the full path to this context's primary Android package. 637 * The Android package is a ZIP file which contains application's 638 * primary code and assets. 639 * 640 * <p>Note: this is not generally useful for applications, since they should 641 * not be directly accessing the file system. 642 * 643 * @return String Path to the code and assets. 644 */ 645 public abstract String getPackageCodePath(); 646 647 /** 648 * @hide 649 * @deprecated use {@link #getSharedPreferencesPath(String)} 650 */ 651 @Deprecated 652 public File getSharedPrefsFile(String name) { 653 return getSharedPreferencesPath(name); 654 } 655 656 /** 657 * Retrieve and hold the contents of the preferences file 'name', returning 658 * a SharedPreferences through which you can retrieve and modify its 659 * values. Only one instance of the SharedPreferences object is returned 660 * to any callers for the same name, meaning they will see each other's 661 * edits as soon as they are made. 662 * 663 * @param name Desired preferences file. If a preferences file by this name 664 * does not exist, it will be created when you retrieve an 665 * editor (SharedPreferences.edit()) and then commit changes (Editor.commit()). 666 * @param mode Operating mode. Use 0 or {@link #MODE_PRIVATE} for the 667 * default operation. 668 * 669 * @return The single {@link SharedPreferences} instance that can be used 670 * to retrieve and modify the preference values. 671 * 672 * @see #MODE_PRIVATE 673 */ 674 public abstract SharedPreferences getSharedPreferences(String name, int mode); 675 676 /** 677 * Retrieve and hold the contents of the preferences file, returning 678 * a SharedPreferences through which you can retrieve and modify its 679 * values. Only one instance of the SharedPreferences object is returned 680 * to any callers for the same name, meaning they will see each other's 681 * edits as soon as they are made. 682 * 683 * @param file Desired preferences file. If a preferences file by this name 684 * does not exist, it will be created when you retrieve an 685 * editor (SharedPreferences.edit()) and then commit changes (Editor.commit()). 686 * @param mode Operating mode. Use 0 or {@link #MODE_PRIVATE} for the 687 * default operation. 688 * 689 * @return The single {@link SharedPreferences} instance that can be used 690 * to retrieve and modify the preference values. 691 * 692 * @see #getSharedPreferencesPath(String) 693 * @see #MODE_PRIVATE 694 */ 695 public abstract SharedPreferences getSharedPreferences(File file, int mode); 696 697 /** 698 * Migrate an existing shared preferences file from the given source storage 699 * context to this context. This is typically used to migrate data between 700 * storage locations after an upgrade, such as migrating from credential 701 * encrypted to device encrypted storage. 702 * 703 * @param sourceContext The source context which contains the existing 704 * shared preferences to migrate. 705 * @param name The name of the shared preferences file. 706 * @return {@code true} if the migration was successful or if the shared 707 * preferences didn't exist in the source context, otherwise 708 * {@code false}. 709 * @see #createDeviceEncryptedStorageContext() 710 */ 711 public abstract boolean migrateSharedPreferencesFrom(Context sourceContext, String name); 712 713 /** 714 * Delete an existing shared preferences file. 715 * 716 * @param name The name (unique in the application package) of the shared 717 * preferences file. 718 * @return {@code true} if the shared preferences file was successfully 719 * deleted; else {@code false}. 720 * @see #getSharedPreferences(String, int) 721 */ 722 public abstract boolean deleteSharedPreferences(String name); 723 724 /** 725 * Open a private file associated with this Context's application package 726 * for reading. 727 * 728 * @param name The name of the file to open; can not contain path 729 * separators. 730 * 731 * @return The resulting {@link FileInputStream}. 732 * 733 * @see #openFileOutput 734 * @see #fileList 735 * @see #deleteFile 736 * @see java.io.FileInputStream#FileInputStream(String) 737 */ 738 public abstract FileInputStream openFileInput(String name) 739 throws FileNotFoundException; 740 741 /** 742 * Open a private file associated with this Context's application package 743 * for writing. Creates the file if it doesn't already exist. 744 * <p> 745 * No additional permissions are required for the calling app to read or 746 * write the returned file. 747 * 748 * @param name The name of the file to open; can not contain path 749 * separators. 750 * @param mode Operating mode. Use 0 or {@link #MODE_PRIVATE} for the 751 * default operation. Use {@link #MODE_APPEND} to append to an 752 * existing file. 753 * @return The resulting {@link FileOutputStream}. 754 * @see #MODE_APPEND 755 * @see #MODE_PRIVATE 756 * @see #openFileInput 757 * @see #fileList 758 * @see #deleteFile 759 * @see java.io.FileOutputStream#FileOutputStream(String) 760 */ 761 public abstract FileOutputStream openFileOutput(String name, int mode) 762 throws FileNotFoundException; 763 764 /** 765 * Delete the given private file associated with this Context's 766 * application package. 767 * 768 * @param name The name of the file to delete; can not contain path 769 * separators. 770 * 771 * @return {@code true} if the file was successfully deleted; else 772 * {@code false}. 773 * 774 * @see #openFileInput 775 * @see #openFileOutput 776 * @see #fileList 777 * @see java.io.File#delete() 778 */ 779 public abstract boolean deleteFile(String name); 780 781 /** 782 * Returns the absolute path on the filesystem where a file created with 783 * {@link #openFileOutput} is stored. 784 * <p> 785 * The returned path may change over time if the calling app is moved to an 786 * adopted storage device, so only relative paths should be persisted. 787 * 788 * @param name The name of the file for which you would like to get 789 * its path. 790 * 791 * @return An absolute path to the given file. 792 * 793 * @see #openFileOutput 794 * @see #getFilesDir 795 * @see #getDir 796 */ 797 public abstract File getFileStreamPath(String name); 798 799 /** 800 * Returns the absolute path on the filesystem where a file created with 801 * {@link #getSharedPreferences(String, int)} is stored. 802 * <p> 803 * The returned path may change over time if the calling app is moved to an 804 * adopted storage device, so only relative paths should be persisted. 805 * 806 * @param name The name of the shared preferences for which you would like 807 * to get a path. 808 * @return An absolute path to the given file. 809 * @see #getSharedPreferences(String, int) 810 */ 811 public abstract File getSharedPreferencesPath(String name); 812 813 /** 814 * Returns the absolute path to the directory on the filesystem where files 815 * created with {@link #openFileOutput} are stored. 816 * <p> 817 * The returned path may change over time if the calling app is moved to an 818 * adopted storage device, so only relative paths should be persisted. 819 * <p> 820 * No additional permissions are required for the calling app to read or 821 * write files under the returned path. 822 * 823 * @return The path of the directory holding application files. 824 * @see #openFileOutput 825 * @see #getFileStreamPath 826 * @see #getDir 827 */ 828 public abstract File getFilesDir(); 829 830 /** 831 * Returns the absolute path to the directory on the filesystem similar to 832 * {@link #getFilesDir()}. The difference is that files placed under this 833 * directory will be excluded from automatic backup to remote storage. See 834 * {@link android.app.backup.BackupAgent BackupAgent} for a full discussion 835 * of the automatic backup mechanism in Android. 836 * <p> 837 * The returned path may change over time if the calling app is moved to an 838 * adopted storage device, so only relative paths should be persisted. 839 * <p> 840 * No additional permissions are required for the calling app to read or 841 * write files under the returned path. 842 * 843 * @return The path of the directory holding application files that will not 844 * be automatically backed up to remote storage. 845 * @see #openFileOutput 846 * @see #getFileStreamPath 847 * @see #getDir 848 * @see android.app.backup.BackupAgent 849 */ 850 public abstract File getNoBackupFilesDir(); 851 852 /** 853 * Returns the absolute path to the directory on the primary shared/external 854 * storage device where the application can place persistent files it owns. 855 * These files are internal to the applications, and not typically visible 856 * to the user as media. 857 * <p> 858 * This is like {@link #getFilesDir()} in that these files will be deleted 859 * when the application is uninstalled, however there are some important 860 * differences: 861 * <ul> 862 * <li>Shared storage may not always be available, since removable media can 863 * be ejected by the user. Media state can be checked using 864 * {@link Environment#getExternalStorageState(File)}. 865 * <li>There is no security enforced with these files. For example, any 866 * application holding 867 * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} can write to 868 * these files. 869 * </ul> 870 * <p> 871 * If a shared storage device is emulated (as determined by 872 * {@link Environment#isExternalStorageEmulated(File)}), it's contents are 873 * backed by a private user data partition, which means there is little 874 * benefit to storing data here instead of the private directories returned 875 * by {@link #getFilesDir()}, etc. 876 * <p> 877 * Starting in {@link android.os.Build.VERSION_CODES#KITKAT}, no permissions 878 * are required to read or write to the returned path; it's always 879 * accessible to the calling app. This only applies to paths generated for 880 * package name of the calling application. To access paths belonging to 881 * other packages, 882 * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} and/or 883 * {@link android.Manifest.permission#READ_EXTERNAL_STORAGE} are required. 884 * <p> 885 * On devices with multiple users (as described by {@link UserManager}), 886 * each user has their own isolated shared storage. Applications only have 887 * access to the shared storage for the user they're running as. 888 * <p> 889 * The returned path may change over time if different shared storage media 890 * is inserted, so only relative paths should be persisted. 891 * <p> 892 * Here is an example of typical code to manipulate a file in an 893 * application's shared storage: 894 * </p> 895 * {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java 896 * private_file} 897 * <p> 898 * If you supply a non-null <var>type</var> to this function, the returned 899 * file will be a path to a sub-directory of the given type. Though these 900 * files are not automatically scanned by the media scanner, you can 901 * explicitly add them to the media database with 902 * {@link android.media.MediaScannerConnection#scanFile(Context, String[], String[], android.media.MediaScannerConnection.OnScanCompletedListener) 903 * MediaScannerConnection.scanFile}. Note that this is not the same as 904 * {@link android.os.Environment#getExternalStoragePublicDirectory 905 * Environment.getExternalStoragePublicDirectory()}, which provides 906 * directories of media shared by all applications. The directories returned 907 * here are owned by the application, and their contents will be removed 908 * when the application is uninstalled. Unlike 909 * {@link android.os.Environment#getExternalStoragePublicDirectory 910 * Environment.getExternalStoragePublicDirectory()}, the directory returned 911 * here will be automatically created for you. 912 * <p> 913 * Here is an example of typical code to manipulate a picture in an 914 * application's shared storage and add it to the media database: 915 * </p> 916 * {@sample development/samples/ApiDemos/src/com/example/android/apis/content/ExternalStorage.java 917 * private_picture} 918 * 919 * @param type The type of files directory to return. May be {@code null} 920 * for the root of the files directory or one of the following 921 * constants for a subdirectory: 922 * {@link android.os.Environment#DIRECTORY_MUSIC}, 923 * {@link android.os.Environment#DIRECTORY_PODCASTS}, 924 * {@link android.os.Environment#DIRECTORY_RINGTONES}, 925 * {@link android.os.Environment#DIRECTORY_ALARMS}, 926 * {@link android.os.Environment#DIRECTORY_NOTIFICATIONS}, 927 * {@link android.os.Environment#DIRECTORY_PICTURES}, or 928 * {@link android.os.Environment#DIRECTORY_MOVIES}. 929 * @return the absolute path to application-specific directory. May return 930 * {@code null} if shared storage is not currently available. 931 * @see #getFilesDir 932 * @see #getExternalFilesDirs(String) 933 * @see Environment#getExternalStorageState(File) 934 * @see Environment#isExternalStorageEmulated(File) 935 * @see Environment#isExternalStorageRemovable(File) 936 */ 937 @Nullable 938 public abstract File getExternalFilesDir(@Nullable String type); 939 940 /** 941 * Returns absolute paths to application-specific directories on all 942 * shared/external storage devices where the application can place 943 * persistent files it owns. These files are internal to the application, 944 * and not typically visible to the user as media. 945 * <p> 946 * This is like {@link #getFilesDir()} in that these files will be deleted 947 * when the application is uninstalled, however there are some important 948 * differences: 949 * <ul> 950 * <li>Shared storage may not always be available, since removable media can 951 * be ejected by the user. Media state can be checked using 952 * {@link Environment#getExternalStorageState(File)}. 953 * <li>There is no security enforced with these files. For example, any 954 * application holding 955 * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} can write to 956 * these files. 957 * </ul> 958 * <p> 959 * If a shared storage device is emulated (as determined by 960 * {@link Environment#isExternalStorageEmulated(File)}), it's contents are 961 * backed by a private user data partition, which means there is little 962 * benefit to storing data here instead of the private directories returned 963 * by {@link #getFilesDir()}, etc. 964 * <p> 965 * Shared storage devices returned here are considered a stable part of the 966 * device, including physical media slots under a protective cover. The 967 * returned paths do not include transient devices, such as USB flash drives 968 * connected to handheld devices. 969 * <p> 970 * An application may store data on any or all of the returned devices. For 971 * example, an app may choose to store large files on the device with the 972 * most available space, as measured by {@link StatFs}. 973 * <p> 974 * No additional permissions are required for the calling app to read or 975 * write files under the returned path. Write access outside of these paths 976 * on secondary external storage devices is not available. 977 * <p> 978 * The returned path may change over time if different shared storage media 979 * is inserted, so only relative paths should be persisted. 980 * 981 * @param type The type of files directory to return. May be {@code null} 982 * for the root of the files directory or one of the following 983 * constants for a subdirectory: 984 * {@link android.os.Environment#DIRECTORY_MUSIC}, 985 * {@link android.os.Environment#DIRECTORY_PODCASTS}, 986 * {@link android.os.Environment#DIRECTORY_RINGTONES}, 987 * {@link android.os.Environment#DIRECTORY_ALARMS}, 988 * {@link android.os.Environment#DIRECTORY_NOTIFICATIONS}, 989 * {@link android.os.Environment#DIRECTORY_PICTURES}, or 990 * {@link android.os.Environment#DIRECTORY_MOVIES}. 991 * @return the absolute paths to application-specific directories. Some 992 * individual paths may be {@code null} if that shared storage is 993 * not currently available. The first path returned is the same as 994 * {@link #getExternalFilesDir(String)}. 995 * @see #getExternalFilesDir(String) 996 * @see Environment#getExternalStorageState(File) 997 * @see Environment#isExternalStorageEmulated(File) 998 * @see Environment#isExternalStorageRemovable(File) 999 */ 1000 public abstract File[] getExternalFilesDirs(String type); 1001 1002 /** 1003 * Return the primary shared/external storage directory where this 1004 * application's OBB files (if there are any) can be found. Note if the 1005 * application does not have any OBB files, this directory may not exist. 1006 * <p> 1007 * This is like {@link #getFilesDir()} in that these files will be deleted 1008 * when the application is uninstalled, however there are some important 1009 * differences: 1010 * <ul> 1011 * <li>Shared storage may not always be available, since removable media can 1012 * be ejected by the user. Media state can be checked using 1013 * {@link Environment#getExternalStorageState(File)}. 1014 * <li>There is no security enforced with these files. For example, any 1015 * application holding 1016 * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} can write to 1017 * these files. 1018 * </ul> 1019 * <p> 1020 * Starting in {@link android.os.Build.VERSION_CODES#KITKAT}, no permissions 1021 * are required to read or write to the returned path; it's always 1022 * accessible to the calling app. This only applies to paths generated for 1023 * package name of the calling application. To access paths belonging to 1024 * other packages, 1025 * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} and/or 1026 * {@link android.Manifest.permission#READ_EXTERNAL_STORAGE} are required. 1027 * <p> 1028 * On devices with multiple users (as described by {@link UserManager}), 1029 * multiple users may share the same OBB storage location. Applications 1030 * should ensure that multiple instances running under different users don't 1031 * interfere with each other. 1032 * 1033 * @return the absolute path to application-specific directory. May return 1034 * {@code null} if shared storage is not currently available. 1035 * @see #getObbDirs() 1036 * @see Environment#getExternalStorageState(File) 1037 * @see Environment#isExternalStorageEmulated(File) 1038 * @see Environment#isExternalStorageRemovable(File) 1039 */ 1040 public abstract File getObbDir(); 1041 1042 /** 1043 * Returns absolute paths to application-specific directories on all 1044 * shared/external storage devices where the application's OBB files (if 1045 * there are any) can be found. Note if the application does not have any 1046 * OBB files, these directories may not exist. 1047 * <p> 1048 * This is like {@link #getFilesDir()} in that these files will be deleted 1049 * when the application is uninstalled, however there are some important 1050 * differences: 1051 * <ul> 1052 * <li>Shared storage may not always be available, since removable media can 1053 * be ejected by the user. Media state can be checked using 1054 * {@link Environment#getExternalStorageState(File)}. 1055 * <li>There is no security enforced with these files. For example, any 1056 * application holding 1057 * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} can write to 1058 * these files. 1059 * </ul> 1060 * <p> 1061 * Shared storage devices returned here are considered a stable part of the 1062 * device, including physical media slots under a protective cover. The 1063 * returned paths do not include transient devices, such as USB flash drives 1064 * connected to handheld devices. 1065 * <p> 1066 * An application may store data on any or all of the returned devices. For 1067 * example, an app may choose to store large files on the device with the 1068 * most available space, as measured by {@link StatFs}. 1069 * <p> 1070 * No additional permissions are required for the calling app to read or 1071 * write files under the returned path. Write access outside of these paths 1072 * on secondary external storage devices is not available. 1073 * 1074 * @return the absolute paths to application-specific directories. Some 1075 * individual paths may be {@code null} if that shared storage is 1076 * not currently available. The first path returned is the same as 1077 * {@link #getObbDir()} 1078 * @see #getObbDir() 1079 * @see Environment#getExternalStorageState(File) 1080 * @see Environment#isExternalStorageEmulated(File) 1081 * @see Environment#isExternalStorageRemovable(File) 1082 */ 1083 public abstract File[] getObbDirs(); 1084 1085 /** 1086 * Returns the absolute path to the application specific cache directory on 1087 * the filesystem. These files will be ones that get deleted first when the 1088 * device runs low on storage. There is no guarantee when these files will 1089 * be deleted. 1090 * <p> 1091 * <strong>Note: you should not <em>rely</em> on the system deleting these 1092 * files for you; you should always have a reasonable maximum, such as 1 MB, 1093 * for the amount of space you consume with cache files, and prune those 1094 * files when exceeding that space.</strong> 1095 * <p> 1096 * The returned path may change over time if the calling app is moved to an 1097 * adopted storage device, so only relative paths should be persisted. 1098 * <p> 1099 * Apps require no extra permissions to read or write to the returned path, 1100 * since this path lives in their private storage. 1101 * 1102 * @return The path of the directory holding application cache files. 1103 * @see #openFileOutput 1104 * @see #getFileStreamPath 1105 * @see #getDir 1106 */ 1107 public abstract File getCacheDir(); 1108 1109 /** 1110 * Returns the absolute path to the application specific cache directory on 1111 * the filesystem designed for storing cached code. The system will delete 1112 * any files stored in this location both when your specific application is 1113 * upgraded, and when the entire platform is upgraded. 1114 * <p> 1115 * This location is optimal for storing compiled or optimized code generated 1116 * by your application at runtime. 1117 * <p> 1118 * The returned path may change over time if the calling app is moved to an 1119 * adopted storage device, so only relative paths should be persisted. 1120 * <p> 1121 * Apps require no extra permissions to read or write to the returned path, 1122 * since this path lives in their private storage. 1123 * 1124 * @return The path of the directory holding application code cache files. 1125 */ 1126 public abstract File getCodeCacheDir(); 1127 1128 /** 1129 * Returns absolute path to application-specific directory on the primary 1130 * shared/external storage device where the application can place cache 1131 * files it owns. These files are internal to the application, and not 1132 * typically visible to the user as media. 1133 * <p> 1134 * This is like {@link #getCacheDir()} in that these files will be deleted 1135 * when the application is uninstalled, however there are some important 1136 * differences: 1137 * <ul> 1138 * <li>The platform does not always monitor the space available in shared 1139 * storage, and thus may not automatically delete these files. Apps should 1140 * always manage the maximum space used in this location. Currently the only 1141 * time files here will be deleted by the platform is when running on 1142 * {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1} or later and 1143 * {@link Environment#isExternalStorageEmulated(File)} returns true. 1144 * <li>Shared storage may not always be available, since removable media can 1145 * be ejected by the user. Media state can be checked using 1146 * {@link Environment#getExternalStorageState(File)}. 1147 * <li>There is no security enforced with these files. For example, any 1148 * application holding 1149 * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} can write to 1150 * these files. 1151 * </ul> 1152 * <p> 1153 * If a shared storage device is emulated (as determined by 1154 * {@link Environment#isExternalStorageEmulated(File)}), it's contents are 1155 * backed by a private user data partition, which means there is little 1156 * benefit to storing data here instead of the private directory returned by 1157 * {@link #getCacheDir()}. 1158 * <p> 1159 * Starting in {@link android.os.Build.VERSION_CODES#KITKAT}, no permissions 1160 * are required to read or write to the returned path; it's always 1161 * accessible to the calling app. This only applies to paths generated for 1162 * package name of the calling application. To access paths belonging to 1163 * other packages, 1164 * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} and/or 1165 * {@link android.Manifest.permission#READ_EXTERNAL_STORAGE} are required. 1166 * <p> 1167 * On devices with multiple users (as described by {@link UserManager}), 1168 * each user has their own isolated shared storage. Applications only have 1169 * access to the shared storage for the user they're running as. 1170 * <p> 1171 * The returned path may change over time if different shared storage media 1172 * is inserted, so only relative paths should be persisted. 1173 * 1174 * @return the absolute path to application-specific directory. May return 1175 * {@code null} if shared storage is not currently available. 1176 * @see #getCacheDir 1177 * @see #getExternalCacheDirs() 1178 * @see Environment#getExternalStorageState(File) 1179 * @see Environment#isExternalStorageEmulated(File) 1180 * @see Environment#isExternalStorageRemovable(File) 1181 */ 1182 @Nullable 1183 public abstract File getExternalCacheDir(); 1184 1185 /** 1186 * Returns absolute paths to application-specific directories on all 1187 * shared/external storage devices where the application can place cache 1188 * files it owns. These files are internal to the application, and not 1189 * typically visible to the user as media. 1190 * <p> 1191 * This is like {@link #getCacheDir()} in that these files will be deleted 1192 * when the application is uninstalled, however there are some important 1193 * differences: 1194 * <ul> 1195 * <li>The platform does not always monitor the space available in shared 1196 * storage, and thus may not automatically delete these files. Apps should 1197 * always manage the maximum space used in this location. Currently the only 1198 * time files here will be deleted by the platform is when running on 1199 * {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1} or later and 1200 * {@link Environment#isExternalStorageEmulated(File)} returns true. 1201 * <li>Shared storage may not always be available, since removable media can 1202 * be ejected by the user. Media state can be checked using 1203 * {@link Environment#getExternalStorageState(File)}. 1204 * <li>There is no security enforced with these files. For example, any 1205 * application holding 1206 * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} can write to 1207 * these files. 1208 * </ul> 1209 * <p> 1210 * If a shared storage device is emulated (as determined by 1211 * {@link Environment#isExternalStorageEmulated(File)}), it's contents are 1212 * backed by a private user data partition, which means there is little 1213 * benefit to storing data here instead of the private directory returned by 1214 * {@link #getCacheDir()}. 1215 * <p> 1216 * Shared storage devices returned here are considered a stable part of the 1217 * device, including physical media slots under a protective cover. The 1218 * returned paths do not include transient devices, such as USB flash drives 1219 * connected to handheld devices. 1220 * <p> 1221 * An application may store data on any or all of the returned devices. For 1222 * example, an app may choose to store large files on the device with the 1223 * most available space, as measured by {@link StatFs}. 1224 * <p> 1225 * No additional permissions are required for the calling app to read or 1226 * write files under the returned path. Write access outside of these paths 1227 * on secondary external storage devices is not available. 1228 * <p> 1229 * The returned paths may change over time if different shared storage media 1230 * is inserted, so only relative paths should be persisted. 1231 * 1232 * @return the absolute paths to application-specific directories. Some 1233 * individual paths may be {@code null} if that shared storage is 1234 * not currently available. The first path returned is the same as 1235 * {@link #getExternalCacheDir()}. 1236 * @see #getExternalCacheDir() 1237 * @see Environment#getExternalStorageState(File) 1238 * @see Environment#isExternalStorageEmulated(File) 1239 * @see Environment#isExternalStorageRemovable(File) 1240 */ 1241 public abstract File[] getExternalCacheDirs(); 1242 1243 /** 1244 * Returns absolute paths to application-specific directories on all 1245 * shared/external storage devices where the application can place media 1246 * files. These files are scanned and made available to other apps through 1247 * {@link MediaStore}. 1248 * <p> 1249 * This is like {@link #getExternalFilesDirs} in that these files will be 1250 * deleted when the application is uninstalled, however there are some 1251 * important differences: 1252 * <ul> 1253 * <li>Shared storage may not always be available, since removable media can 1254 * be ejected by the user. Media state can be checked using 1255 * {@link Environment#getExternalStorageState(File)}. 1256 * <li>There is no security enforced with these files. For example, any 1257 * application holding 1258 * {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} can write to 1259 * these files. 1260 * </ul> 1261 * <p> 1262 * Shared storage devices returned here are considered a stable part of the 1263 * device, including physical media slots under a protective cover. The 1264 * returned paths do not include transient devices, such as USB flash drives 1265 * connected to handheld devices. 1266 * <p> 1267 * An application may store data on any or all of the returned devices. For 1268 * example, an app may choose to store large files on the device with the 1269 * most available space, as measured by {@link StatFs}. 1270 * <p> 1271 * No additional permissions are required for the calling app to read or 1272 * write files under the returned path. Write access outside of these paths 1273 * on secondary external storage devices is not available. 1274 * <p> 1275 * The returned paths may change over time if different shared storage media 1276 * is inserted, so only relative paths should be persisted. 1277 * 1278 * @return the absolute paths to application-specific directories. Some 1279 * individual paths may be {@code null} if that shared storage is 1280 * not currently available. 1281 * @see Environment#getExternalStorageState(File) 1282 * @see Environment#isExternalStorageEmulated(File) 1283 * @see Environment#isExternalStorageRemovable(File) 1284 */ 1285 public abstract File[] getExternalMediaDirs(); 1286 1287 /** 1288 * Returns an array of strings naming the private files associated with 1289 * this Context's application package. 1290 * 1291 * @return Array of strings naming the private files. 1292 * 1293 * @see #openFileInput 1294 * @see #openFileOutput 1295 * @see #deleteFile 1296 */ 1297 public abstract String[] fileList(); 1298 1299 /** 1300 * Retrieve, creating if needed, a new directory in which the application 1301 * can place its own custom data files. You can use the returned File 1302 * object to create and access files in this directory. Note that files 1303 * created through a File object will only be accessible by your own 1304 * application; you can only set the mode of the entire directory, not 1305 * of individual files. 1306 * <p> 1307 * The returned path may change over time if the calling app is moved to an 1308 * adopted storage device, so only relative paths should be persisted. 1309 * <p> 1310 * Apps require no extra permissions to read or write to the returned path, 1311 * since this path lives in their private storage. 1312 * 1313 * @param name Name of the directory to retrieve. This is a directory 1314 * that is created as part of your application data. 1315 * @param mode Operating mode. Use 0 or {@link #MODE_PRIVATE} for the 1316 * default operation. 1317 * 1318 * @return A {@link File} object for the requested directory. The directory 1319 * will have been created if it does not already exist. 1320 * 1321 * @see #openFileOutput(String, int) 1322 */ 1323 public abstract File getDir(String name, int mode); 1324 1325 /** 1326 * Open a new private SQLiteDatabase associated with this Context's 1327 * application package. Create the database file if it doesn't exist. 1328 * 1329 * @param name The name (unique in the application package) of the database. 1330 * @param mode Operating mode. Use 0 or {@link #MODE_PRIVATE} for the 1331 * default operation. Use 1332 * {@link #MODE_ENABLE_WRITE_AHEAD_LOGGING} to enable write-ahead 1333 * logging by default. Use {@link #MODE_NO_LOCALIZED_COLLATORS} 1334 * to disable localized collators. 1335 * @param factory An optional factory class that is called to instantiate a 1336 * cursor when query is called. 1337 * @return The contents of a newly created database with the given name. 1338 * @throws android.database.sqlite.SQLiteException if the database file 1339 * could not be opened. 1340 * @see #MODE_PRIVATE 1341 * @see #MODE_ENABLE_WRITE_AHEAD_LOGGING 1342 * @see #MODE_NO_LOCALIZED_COLLATORS 1343 * @see #deleteDatabase 1344 */ 1345 public abstract SQLiteDatabase openOrCreateDatabase(String name, 1346 int mode, CursorFactory factory); 1347 1348 /** 1349 * Open a new private SQLiteDatabase associated with this Context's 1350 * application package. Creates the database file if it doesn't exist. 1351 * <p> 1352 * Accepts input param: a concrete instance of {@link DatabaseErrorHandler} 1353 * to be used to handle corruption when sqlite reports database corruption. 1354 * </p> 1355 * 1356 * @param name The name (unique in the application package) of the database. 1357 * @param mode Operating mode. Use 0 or {@link #MODE_PRIVATE} for the 1358 * default operation. Use 1359 * {@link #MODE_ENABLE_WRITE_AHEAD_LOGGING} to enable write-ahead 1360 * logging by default. Use {@link #MODE_NO_LOCALIZED_COLLATORS} 1361 * to disable localized collators. 1362 * @param factory An optional factory class that is called to instantiate a 1363 * cursor when query is called. 1364 * @param errorHandler the {@link DatabaseErrorHandler} to be used when 1365 * sqlite reports database corruption. if null, 1366 * {@link android.database.DefaultDatabaseErrorHandler} is 1367 * assumed. 1368 * @return The contents of a newly created database with the given name. 1369 * @throws android.database.sqlite.SQLiteException if the database file 1370 * could not be opened. 1371 * @see #MODE_PRIVATE 1372 * @see #MODE_ENABLE_WRITE_AHEAD_LOGGING 1373 * @see #MODE_NO_LOCALIZED_COLLATORS 1374 * @see #deleteDatabase 1375 */ 1376 public abstract SQLiteDatabase openOrCreateDatabase(String name, 1377 int mode, CursorFactory factory, 1378 @Nullable DatabaseErrorHandler errorHandler); 1379 1380 /** 1381 * Migrate an existing database file from the given source storage context 1382 * to this context. This is typically used to migrate data between storage 1383 * locations after an upgrade, such as migrating from credential encrypted 1384 * to device encrypted storage. 1385 * 1386 * @param sourceContext The source context which contains the existing 1387 * database to migrate. 1388 * @param name The name of the database file. 1389 * @return {@code true} if the migration was successful or if the database 1390 * didn't exist in the source context, otherwise {@code false}. 1391 * @see #createDeviceEncryptedStorageContext() 1392 */ 1393 public abstract boolean migrateDatabaseFrom(Context sourceContext, String name); 1394 1395 /** 1396 * Delete an existing private SQLiteDatabase associated with this Context's 1397 * application package. 1398 * 1399 * @param name The name (unique in the application package) of the 1400 * database. 1401 * 1402 * @return {@code true} if the database was successfully deleted; else {@code false}. 1403 * 1404 * @see #openOrCreateDatabase 1405 */ 1406 public abstract boolean deleteDatabase(String name); 1407 1408 /** 1409 * Returns the absolute path on the filesystem where a database created with 1410 * {@link #openOrCreateDatabase} is stored. 1411 * <p> 1412 * The returned path may change over time if the calling app is moved to an 1413 * adopted storage device, so only relative paths should be persisted. 1414 * 1415 * @param name The name of the database for which you would like to get 1416 * its path. 1417 * 1418 * @return An absolute path to the given database. 1419 * 1420 * @see #openOrCreateDatabase 1421 */ 1422 public abstract File getDatabasePath(String name); 1423 1424 /** 1425 * Returns an array of strings naming the private databases associated with 1426 * this Context's application package. 1427 * 1428 * @return Array of strings naming the private databases. 1429 * 1430 * @see #openOrCreateDatabase 1431 * @see #deleteDatabase 1432 */ 1433 public abstract String[] databaseList(); 1434 1435 /** 1436 * @deprecated Use {@link android.app.WallpaperManager#getDrawable 1437 * WallpaperManager.get()} instead. 1438 */ 1439 @Deprecated 1440 public abstract Drawable getWallpaper(); 1441 1442 /** 1443 * @deprecated Use {@link android.app.WallpaperManager#peekDrawable 1444 * WallpaperManager.peek()} instead. 1445 */ 1446 @Deprecated 1447 public abstract Drawable peekWallpaper(); 1448 1449 /** 1450 * @deprecated Use {@link android.app.WallpaperManager#getDesiredMinimumWidth() 1451 * WallpaperManager.getDesiredMinimumWidth()} instead. 1452 */ 1453 @Deprecated 1454 public abstract int getWallpaperDesiredMinimumWidth(); 1455 1456 /** 1457 * @deprecated Use {@link android.app.WallpaperManager#getDesiredMinimumHeight() 1458 * WallpaperManager.getDesiredMinimumHeight()} instead. 1459 */ 1460 @Deprecated 1461 public abstract int getWallpaperDesiredMinimumHeight(); 1462 1463 /** 1464 * @deprecated Use {@link android.app.WallpaperManager#setBitmap(Bitmap) 1465 * WallpaperManager.set()} instead. 1466 * <p>This method requires the caller to hold the permission 1467 * {@link android.Manifest.permission#SET_WALLPAPER}. 1468 */ 1469 @Deprecated 1470 public abstract void setWallpaper(Bitmap bitmap) throws IOException; 1471 1472 /** 1473 * @deprecated Use {@link android.app.WallpaperManager#setStream(InputStream) 1474 * WallpaperManager.set()} instead. 1475 * <p>This method requires the caller to hold the permission 1476 * {@link android.Manifest.permission#SET_WALLPAPER}. 1477 */ 1478 @Deprecated 1479 public abstract void setWallpaper(InputStream data) throws IOException; 1480 1481 /** 1482 * @deprecated Use {@link android.app.WallpaperManager#clear 1483 * WallpaperManager.clear()} instead. 1484 * <p>This method requires the caller to hold the permission 1485 * {@link android.Manifest.permission#SET_WALLPAPER}. 1486 */ 1487 @Deprecated 1488 public abstract void clearWallpaper() throws IOException; 1489 1490 /** 1491 * Same as {@link #startActivity(Intent, Bundle)} with no options 1492 * specified. 1493 * 1494 * @param intent The description of the activity to start. 1495 * 1496 * @throws ActivityNotFoundException 1497 *` 1498 * @see #startActivity(Intent, Bundle) 1499 * @see PackageManager#resolveActivity 1500 */ 1501 public abstract void startActivity(@RequiresPermission Intent intent); 1502 1503 /** 1504 * Version of {@link #startActivity(Intent)} that allows you to specify the 1505 * user the activity will be started for. This is not available to applications 1506 * that are not pre-installed on the system image. Using it requires holding 1507 * the INTERACT_ACROSS_USERS_FULL permission. 1508 * @param intent The description of the activity to start. 1509 * @param user The UserHandle of the user to start this activity for. 1510 * @throws ActivityNotFoundException 1511 * @hide 1512 */ 1513 public void startActivityAsUser(@RequiresPermission Intent intent, UserHandle user) { 1514 throw new RuntimeException("Not implemented. Must override in a subclass."); 1515 } 1516 1517 /** 1518 * Launch a new activity. You will not receive any information about when 1519 * the activity exits. 1520 * 1521 * <p>Note that if this method is being called from outside of an 1522 * {@link android.app.Activity} Context, then the Intent must include 1523 * the {@link Intent#FLAG_ACTIVITY_NEW_TASK} launch flag. This is because, 1524 * without being started from an existing Activity, there is no existing 1525 * task in which to place the new activity and thus it needs to be placed 1526 * in its own separate task. 1527 * 1528 * <p>This method throws {@link ActivityNotFoundException} 1529 * if there was no Activity found to run the given Intent. 1530 * 1531 * @param intent The description of the activity to start. 1532 * @param options Additional options for how the Activity should be started. 1533 * May be null if there are no options. See {@link android.app.ActivityOptions} 1534 * for how to build the Bundle supplied here; there are no supported definitions 1535 * for building it manually. 1536 * 1537 * @throws ActivityNotFoundException 1538 * 1539 * @see #startActivity(Intent) 1540 * @see PackageManager#resolveActivity 1541 */ 1542 public abstract void startActivity(@RequiresPermission Intent intent, 1543 @Nullable Bundle options); 1544 1545 /** 1546 * Version of {@link #startActivity(Intent, Bundle)} that allows you to specify the 1547 * user the activity will be started for. This is not available to applications 1548 * that are not pre-installed on the system image. Using it requires holding 1549 * the INTERACT_ACROSS_USERS_FULL permission. 1550 * @param intent The description of the activity to start. 1551 * @param options Additional options for how the Activity should be started. 1552 * May be null if there are no options. See {@link android.app.ActivityOptions} 1553 * for how to build the Bundle supplied here; there are no supported definitions 1554 * for building it manually. 1555 * @param userId The UserHandle of the user to start this activity for. 1556 * @throws ActivityNotFoundException 1557 * @hide 1558 */ 1559 public void startActivityAsUser(@RequiresPermission Intent intent, @Nullable Bundle options, 1560 UserHandle userId) { 1561 throw new RuntimeException("Not implemented. Must override in a subclass."); 1562 } 1563 1564 /** 1565 * Version of {@link #startActivity(Intent, Bundle)} that returns a result to the caller. This 1566 * is only supported for Views and Fragments. 1567 * @param who The identifier for the calling element that will receive the result. 1568 * @param intent The intent to start. 1569 * @param requestCode The code that will be returned with onActivityResult() identifying this 1570 * request. 1571 * @param options Additional options for how the Activity should be started. 1572 * May be null if there are no options. See {@link android.app.ActivityOptions} 1573 * for how to build the Bundle supplied here; there are no supported definitions 1574 * for building it manually. 1575 * @hide 1576 */ 1577 public void startActivityForResult( 1578 @NonNull String who, Intent intent, int requestCode, @Nullable Bundle options) { 1579 throw new RuntimeException("This method is only implemented for Activity-based Contexts. " 1580 + "Check canStartActivityForResult() before calling."); 1581 } 1582 1583 /** 1584 * Identifies whether this Context instance will be able to process calls to 1585 * {@link #startActivityForResult(String, Intent, int, Bundle)}. 1586 * @hide 1587 */ 1588 public boolean canStartActivityForResult() { 1589 return false; 1590 } 1591 1592 /** 1593 * Same as {@link #startActivities(Intent[], Bundle)} with no options 1594 * specified. 1595 * 1596 * @param intents An array of Intents to be started. 1597 * 1598 * @throws ActivityNotFoundException 1599 * 1600 * @see #startActivities(Intent[], Bundle) 1601 * @see PackageManager#resolveActivity 1602 */ 1603 public abstract void startActivities(@RequiresPermission Intent[] intents); 1604 1605 /** 1606 * Launch multiple new activities. This is generally the same as calling 1607 * {@link #startActivity(Intent)} for the first Intent in the array, 1608 * that activity during its creation calling {@link #startActivity(Intent)} 1609 * for the second entry, etc. Note that unlike that approach, generally 1610 * none of the activities except the last in the array will be created 1611 * at this point, but rather will be created when the user first visits 1612 * them (due to pressing back from the activity on top). 1613 * 1614 * <p>This method throws {@link ActivityNotFoundException} 1615 * if there was no Activity found for <em>any</em> given Intent. In this 1616 * case the state of the activity stack is undefined (some Intents in the 1617 * list may be on it, some not), so you probably want to avoid such situations. 1618 * 1619 * @param intents An array of Intents to be started. 1620 * @param options Additional options for how the Activity should be started. 1621 * See {@link android.content.Context#startActivity(Intent, Bundle) 1622 * Context.startActivity(Intent, Bundle)} for more details. 1623 * 1624 * @throws ActivityNotFoundException 1625 * 1626 * @see #startActivities(Intent[]) 1627 * @see PackageManager#resolveActivity 1628 */ 1629 public abstract void startActivities(@RequiresPermission Intent[] intents, Bundle options); 1630 1631 /** 1632 * @hide 1633 * Launch multiple new activities. This is generally the same as calling 1634 * {@link #startActivity(Intent)} for the first Intent in the array, 1635 * that activity during its creation calling {@link #startActivity(Intent)} 1636 * for the second entry, etc. Note that unlike that approach, generally 1637 * none of the activities except the last in the array will be created 1638 * at this point, but rather will be created when the user first visits 1639 * them (due to pressing back from the activity on top). 1640 * 1641 * <p>This method throws {@link ActivityNotFoundException} 1642 * if there was no Activity found for <em>any</em> given Intent. In this 1643 * case the state of the activity stack is undefined (some Intents in the 1644 * list may be on it, some not), so you probably want to avoid such situations. 1645 * 1646 * @param intents An array of Intents to be started. 1647 * @param options Additional options for how the Activity should be started. 1648 * @param userHandle The user for whom to launch the activities 1649 * See {@link android.content.Context#startActivity(Intent, Bundle) 1650 * Context.startActivity(Intent, Bundle)} for more details. 1651 * 1652 * @throws ActivityNotFoundException 1653 * 1654 * @see #startActivities(Intent[]) 1655 * @see PackageManager#resolveActivity 1656 */ 1657 public void startActivitiesAsUser(Intent[] intents, Bundle options, UserHandle userHandle) { 1658 throw new RuntimeException("Not implemented. Must override in a subclass."); 1659 } 1660 1661 /** 1662 * Same as {@link #startIntentSender(IntentSender, Intent, int, int, int, Bundle)} 1663 * with no options specified. 1664 * 1665 * @param intent The IntentSender to launch. 1666 * @param fillInIntent If non-null, this will be provided as the 1667 * intent parameter to {@link IntentSender#sendIntent}. 1668 * @param flagsMask Intent flags in the original IntentSender that you 1669 * would like to change. 1670 * @param flagsValues Desired values for any bits set in 1671 * <var>flagsMask</var> 1672 * @param extraFlags Always set to 0. 1673 * 1674 * @see #startActivity(Intent) 1675 * @see #startIntentSender(IntentSender, Intent, int, int, int, Bundle) 1676 */ 1677 public abstract void startIntentSender(IntentSender intent, 1678 Intent fillInIntent, int flagsMask, int flagsValues, int extraFlags) 1679 throws IntentSender.SendIntentException; 1680 1681 /** 1682 * Like {@link #startActivity(Intent, Bundle)}, but taking a IntentSender 1683 * to start. If the IntentSender is for an activity, that activity will be started 1684 * as if you had called the regular {@link #startActivity(Intent)} 1685 * here; otherwise, its associated action will be executed (such as 1686 * sending a broadcast) as if you had called 1687 * {@link IntentSender#sendIntent IntentSender.sendIntent} on it. 1688 * 1689 * @param intent The IntentSender to launch. 1690 * @param fillInIntent If non-null, this will be provided as the 1691 * intent parameter to {@link IntentSender#sendIntent}. 1692 * @param flagsMask Intent flags in the original IntentSender that you 1693 * would like to change. 1694 * @param flagsValues Desired values for any bits set in 1695 * <var>flagsMask</var> 1696 * @param extraFlags Always set to 0. 1697 * @param options Additional options for how the Activity should be started. 1698 * See {@link android.content.Context#startActivity(Intent, Bundle) 1699 * Context.startActivity(Intent, Bundle)} for more details. If options 1700 * have also been supplied by the IntentSender, options given here will 1701 * override any that conflict with those given by the IntentSender. 1702 * 1703 * @see #startActivity(Intent, Bundle) 1704 * @see #startIntentSender(IntentSender, Intent, int, int, int) 1705 */ 1706 public abstract void startIntentSender(IntentSender intent, 1707 @Nullable Intent fillInIntent, int flagsMask, int flagsValues, int extraFlags, 1708 Bundle options) throws IntentSender.SendIntentException; 1709 1710 /** 1711 * Broadcast the given intent to all interested BroadcastReceivers. This 1712 * call is asynchronous; it returns immediately, and you will continue 1713 * executing while the receivers are run. No results are propagated from 1714 * receivers and receivers can not abort the broadcast. If you want 1715 * to allow receivers to propagate results or abort the broadcast, you must 1716 * send an ordered broadcast using 1717 * {@link #sendOrderedBroadcast(Intent, String)}. 1718 * 1719 * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts. 1720 * 1721 * @param intent The Intent to broadcast; all receivers matching this 1722 * Intent will receive the broadcast. 1723 * 1724 * @see android.content.BroadcastReceiver 1725 * @see #registerReceiver 1726 * @see #sendBroadcast(Intent, String) 1727 * @see #sendOrderedBroadcast(Intent, String) 1728 * @see #sendOrderedBroadcast(Intent, String, BroadcastReceiver, Handler, int, String, Bundle) 1729 */ 1730 public abstract void sendBroadcast(@RequiresPermission Intent intent); 1731 1732 /** 1733 * Broadcast the given intent to all interested BroadcastReceivers, allowing 1734 * an optional required permission to be enforced. This 1735 * call is asynchronous; it returns immediately, and you will continue 1736 * executing while the receivers are run. No results are propagated from 1737 * receivers and receivers can not abort the broadcast. If you want 1738 * to allow receivers to propagate results or abort the broadcast, you must 1739 * send an ordered broadcast using 1740 * {@link #sendOrderedBroadcast(Intent, String)}. 1741 * 1742 * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts. 1743 * 1744 * @param intent The Intent to broadcast; all receivers matching this 1745 * Intent will receive the broadcast. 1746 * @param receiverPermission (optional) String naming a permission that 1747 * a receiver must hold in order to receive your broadcast. 1748 * If null, no permission is required. 1749 * 1750 * @see android.content.BroadcastReceiver 1751 * @see #registerReceiver 1752 * @see #sendBroadcast(Intent) 1753 * @see #sendOrderedBroadcast(Intent, String) 1754 * @see #sendOrderedBroadcast(Intent, String, BroadcastReceiver, Handler, int, String, Bundle) 1755 */ 1756 public abstract void sendBroadcast(@RequiresPermission Intent intent, 1757 @Nullable String receiverPermission); 1758 1759 1760 /** 1761 * Broadcast the given intent to all interested BroadcastReceivers, allowing 1762 * an array of required permissions to be enforced. This call is asynchronous; it returns 1763 * immediately, and you will continue executing while the receivers are run. No results are 1764 * propagated from receivers and receivers can not abort the broadcast. If you want to allow 1765 * receivers to propagate results or abort the broadcast, you must send an ordered broadcast 1766 * using {@link #sendOrderedBroadcast(Intent, String)}. 1767 * 1768 * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts. 1769 * 1770 * @param intent The Intent to broadcast; all receivers matching this 1771 * Intent will receive the broadcast. 1772 * @param receiverPermissions Array of names of permissions that a receiver must hold 1773 * in order to receive your broadcast. 1774 * If null or empty, no permissions are required. 1775 * 1776 * @see android.content.BroadcastReceiver 1777 * @see #registerReceiver 1778 * @see #sendBroadcast(Intent) 1779 * @see #sendOrderedBroadcast(Intent, String) 1780 * @see #sendOrderedBroadcast(Intent, String, BroadcastReceiver, Handler, int, String, Bundle) 1781 * @hide 1782 */ 1783 public abstract void sendBroadcastMultiplePermissions(Intent intent, 1784 String[] receiverPermissions); 1785 1786 /** 1787 * Broadcast the given intent to all interested BroadcastReceivers, allowing 1788 * an optional required permission to be enforced. This 1789 * call is asynchronous; it returns immediately, and you will continue 1790 * executing while the receivers are run. No results are propagated from 1791 * receivers and receivers can not abort the broadcast. If you want 1792 * to allow receivers to propagate results or abort the broadcast, you must 1793 * send an ordered broadcast using 1794 * {@link #sendOrderedBroadcast(Intent, String)}. 1795 * 1796 * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts. 1797 * 1798 * @param intent The Intent to broadcast; all receivers matching this 1799 * Intent will receive the broadcast. 1800 * @param receiverPermission (optional) String naming a permission that 1801 * a receiver must hold in order to receive your broadcast. 1802 * If null, no permission is required. 1803 * @param options (optional) Additional sending options, generated from a 1804 * {@link android.app.BroadcastOptions}. 1805 * 1806 * @see android.content.BroadcastReceiver 1807 * @see #registerReceiver 1808 * @see #sendBroadcast(Intent) 1809 * @see #sendOrderedBroadcast(Intent, String) 1810 * @see #sendOrderedBroadcast(Intent, String, BroadcastReceiver, Handler, int, String, Bundle) 1811 * @hide 1812 */ 1813 @SystemApi 1814 public abstract void sendBroadcast(Intent intent, 1815 @Nullable String receiverPermission, 1816 @Nullable Bundle options); 1817 1818 /** 1819 * Like {@link #sendBroadcast(Intent, String)}, but also allows specification 1820 * of an associated app op as per {@link android.app.AppOpsManager}. 1821 * @hide 1822 */ 1823 public abstract void sendBroadcast(Intent intent, 1824 String receiverPermission, int appOp); 1825 1826 /** 1827 * Broadcast the given intent to all interested BroadcastReceivers, delivering 1828 * them one at a time to allow more preferred receivers to consume the 1829 * broadcast before it is delivered to less preferred receivers. This 1830 * call is asynchronous; it returns immediately, and you will continue 1831 * executing while the receivers are run. 1832 * 1833 * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts. 1834 * 1835 * @param intent The Intent to broadcast; all receivers matching this 1836 * Intent will receive the broadcast. 1837 * @param receiverPermission (optional) String naming a permissions that 1838 * a receiver must hold in order to receive your broadcast. 1839 * If null, no permission is required. 1840 * 1841 * @see android.content.BroadcastReceiver 1842 * @see #registerReceiver 1843 * @see #sendBroadcast(Intent) 1844 * @see #sendOrderedBroadcast(Intent, String, BroadcastReceiver, Handler, int, String, Bundle) 1845 */ 1846 public abstract void sendOrderedBroadcast(@RequiresPermission Intent intent, 1847 @Nullable String receiverPermission); 1848 1849 /** 1850 * Version of {@link #sendBroadcast(Intent)} that allows you to 1851 * receive data back from the broadcast. This is accomplished by 1852 * supplying your own BroadcastReceiver when calling, which will be 1853 * treated as a final receiver at the end of the broadcast -- its 1854 * {@link BroadcastReceiver#onReceive} method will be called with 1855 * the result values collected from the other receivers. The broadcast will 1856 * be serialized in the same way as calling 1857 * {@link #sendOrderedBroadcast(Intent, String)}. 1858 * 1859 * <p>Like {@link #sendBroadcast(Intent)}, this method is 1860 * asynchronous; it will return before 1861 * resultReceiver.onReceive() is called. 1862 * 1863 * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts. 1864 * 1865 * @param intent The Intent to broadcast; all receivers matching this 1866 * Intent will receive the broadcast. 1867 * @param receiverPermission String naming a permissions that 1868 * a receiver must hold in order to receive your broadcast. 1869 * If null, no permission is required. 1870 * @param resultReceiver Your own BroadcastReceiver to treat as the final 1871 * receiver of the broadcast. 1872 * @param scheduler A custom Handler with which to schedule the 1873 * resultReceiver callback; if null it will be 1874 * scheduled in the Context's main thread. 1875 * @param initialCode An initial value for the result code. Often 1876 * Activity.RESULT_OK. 1877 * @param initialData An initial value for the result data. Often 1878 * null. 1879 * @param initialExtras An initial value for the result extras. Often 1880 * null. 1881 * 1882 * @see #sendBroadcast(Intent) 1883 * @see #sendBroadcast(Intent, String) 1884 * @see #sendOrderedBroadcast(Intent, String) 1885 * @see android.content.BroadcastReceiver 1886 * @see #registerReceiver 1887 * @see android.app.Activity#RESULT_OK 1888 */ 1889 public abstract void sendOrderedBroadcast(@RequiresPermission @NonNull Intent intent, 1890 @Nullable String receiverPermission, @Nullable BroadcastReceiver resultReceiver, 1891 @Nullable Handler scheduler, int initialCode, @Nullable String initialData, 1892 @Nullable Bundle initialExtras); 1893 1894 /** 1895 * Version of {@link #sendBroadcast(Intent)} that allows you to 1896 * receive data back from the broadcast. This is accomplished by 1897 * supplying your own BroadcastReceiver when calling, which will be 1898 * treated as a final receiver at the end of the broadcast -- its 1899 * {@link BroadcastReceiver#onReceive} method will be called with 1900 * the result values collected from the other receivers. The broadcast will 1901 * be serialized in the same way as calling 1902 * {@link #sendOrderedBroadcast(Intent, String)}. 1903 * 1904 * <p>Like {@link #sendBroadcast(Intent)}, this method is 1905 * asynchronous; it will return before 1906 * resultReceiver.onReceive() is called. 1907 * 1908 * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts. 1909 * 1910 * 1911 * @param intent The Intent to broadcast; all receivers matching this 1912 * Intent will receive the broadcast. 1913 * @param receiverPermission String naming a permissions that 1914 * a receiver must hold in order to receive your broadcast. 1915 * If null, no permission is required. 1916 * @param options (optional) Additional sending options, generated from a 1917 * {@link android.app.BroadcastOptions}. 1918 * @param resultReceiver Your own BroadcastReceiver to treat as the final 1919 * receiver of the broadcast. 1920 * @param scheduler A custom Handler with which to schedule the 1921 * resultReceiver callback; if null it will be 1922 * scheduled in the Context's main thread. 1923 * @param initialCode An initial value for the result code. Often 1924 * Activity.RESULT_OK. 1925 * @param initialData An initial value for the result data. Often 1926 * null. 1927 * @param initialExtras An initial value for the result extras. Often 1928 * null. 1929 * @see #sendBroadcast(Intent) 1930 * @see #sendBroadcast(Intent, String) 1931 * @see #sendOrderedBroadcast(Intent, String) 1932 * @see android.content.BroadcastReceiver 1933 * @see #registerReceiver 1934 * @see android.app.Activity#RESULT_OK 1935 * @hide 1936 */ 1937 @SystemApi 1938 public abstract void sendOrderedBroadcast(@NonNull Intent intent, 1939 @Nullable String receiverPermission, @Nullable Bundle options, 1940 @Nullable BroadcastReceiver resultReceiver, @Nullable Handler scheduler, 1941 int initialCode, @Nullable String initialData, @Nullable Bundle initialExtras); 1942 1943 /** 1944 * Like {@link #sendOrderedBroadcast(Intent, String, BroadcastReceiver, android.os.Handler, 1945 * int, String, android.os.Bundle)}, but also allows specification 1946 * of an associated app op as per {@link android.app.AppOpsManager}. 1947 * @hide 1948 */ 1949 public abstract void sendOrderedBroadcast(Intent intent, 1950 String receiverPermission, int appOp, BroadcastReceiver resultReceiver, 1951 Handler scheduler, int initialCode, String initialData, 1952 Bundle initialExtras); 1953 1954 /** 1955 * Version of {@link #sendBroadcast(Intent)} that allows you to specify the 1956 * user the broadcast will be sent to. This is not available to applications 1957 * that are not pre-installed on the system image. Using it requires holding 1958 * the INTERACT_ACROSS_USERS permission. 1959 * @param intent The intent to broadcast 1960 * @param user UserHandle to send the intent to. 1961 * @see #sendBroadcast(Intent) 1962 */ 1963 public abstract void sendBroadcastAsUser(@RequiresPermission Intent intent, 1964 UserHandle user); 1965 1966 /** 1967 * Version of {@link #sendBroadcast(Intent, String)} that allows you to specify the 1968 * user the broadcast will be sent to. This is not available to applications 1969 * that are not pre-installed on the system image. Using it requires holding 1970 * the INTERACT_ACROSS_USERS permission. 1971 * 1972 * @param intent The Intent to broadcast; all receivers matching this 1973 * Intent will receive the broadcast. 1974 * @param user UserHandle to send the intent to. 1975 * @param receiverPermission (optional) String naming a permission that 1976 * a receiver must hold in order to receive your broadcast. 1977 * If null, no permission is required. 1978 * 1979 * @see #sendBroadcast(Intent, String) 1980 */ 1981 public abstract void sendBroadcastAsUser(@RequiresPermission Intent intent, 1982 UserHandle user, @Nullable String receiverPermission); 1983 1984 1985 /** 1986 * Version of {@link #sendBroadcast(Intent, String)} that allows you to specify the 1987 * user the broadcast will be sent to. This is not available to applications 1988 * that are not pre-installed on the system image. Using it requires holding 1989 * the INTERACT_ACROSS_USERS permission. 1990 * 1991 * @param intent The Intent to broadcast; all receivers matching this 1992 * Intent will receive the broadcast. 1993 * @param user UserHandle to send the intent to. 1994 * @param receiverPermission (optional) String naming a permission that 1995 * a receiver must hold in order to receive your broadcast. 1996 * If null, no permission is required. 1997 * @param appOp The app op associated with the broadcast. 1998 * 1999 * @see #sendBroadcast(Intent, String) 2000 * 2001 * @hide 2002 */ 2003 public abstract void sendBroadcastAsUser(@RequiresPermission Intent intent, 2004 UserHandle user, @Nullable String receiverPermission, int appOp); 2005 2006 /** 2007 * Version of 2008 * {@link #sendOrderedBroadcast(Intent, String, BroadcastReceiver, Handler, int, String, Bundle)} 2009 * that allows you to specify the 2010 * user the broadcast will be sent to. This is not available to applications 2011 * that are not pre-installed on the system image. Using it requires holding 2012 * the INTERACT_ACROSS_USERS permission. 2013 * 2014 * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts. 2015 * 2016 * @param intent The Intent to broadcast; all receivers matching this 2017 * Intent will receive the broadcast. 2018 * @param user UserHandle to send the intent to. 2019 * @param receiverPermission String naming a permissions that 2020 * a receiver must hold in order to receive your broadcast. 2021 * If null, no permission is required. 2022 * @param resultReceiver Your own BroadcastReceiver to treat as the final 2023 * receiver of the broadcast. 2024 * @param scheduler A custom Handler with which to schedule the 2025 * resultReceiver callback; if null it will be 2026 * scheduled in the Context's main thread. 2027 * @param initialCode An initial value for the result code. Often 2028 * Activity.RESULT_OK. 2029 * @param initialData An initial value for the result data. Often 2030 * null. 2031 * @param initialExtras An initial value for the result extras. Often 2032 * null. 2033 * 2034 * @see #sendOrderedBroadcast(Intent, String, BroadcastReceiver, Handler, int, String, Bundle) 2035 */ 2036 public abstract void sendOrderedBroadcastAsUser(@RequiresPermission Intent intent, 2037 UserHandle user, @Nullable String receiverPermission, BroadcastReceiver resultReceiver, 2038 @Nullable Handler scheduler, int initialCode, @Nullable String initialData, 2039 @Nullable Bundle initialExtras); 2040 2041 /** 2042 * Similar to above but takes an appOp as well, to enforce restrictions. 2043 * @see #sendOrderedBroadcastAsUser(Intent, UserHandle, String, 2044 * BroadcastReceiver, Handler, int, String, Bundle) 2045 * @hide 2046 */ 2047 public abstract void sendOrderedBroadcastAsUser(Intent intent, UserHandle user, 2048 @Nullable String receiverPermission, int appOp, BroadcastReceiver resultReceiver, 2049 @Nullable Handler scheduler, int initialCode, @Nullable String initialData, 2050 @Nullable Bundle initialExtras); 2051 2052 /** 2053 * Similar to above but takes an appOp as well, to enforce restrictions, and an options Bundle. 2054 * @see #sendOrderedBroadcastAsUser(Intent, UserHandle, String, 2055 * BroadcastReceiver, Handler, int, String, Bundle) 2056 * @hide 2057 */ 2058 public abstract void sendOrderedBroadcastAsUser(Intent intent, UserHandle user, 2059 @Nullable String receiverPermission, int appOp, @Nullable Bundle options, 2060 BroadcastReceiver resultReceiver, @Nullable Handler scheduler, int initialCode, 2061 @Nullable String initialData, @Nullable Bundle initialExtras); 2062 2063 /** 2064 * <p>Perform a {@link #sendBroadcast(Intent)} that is "sticky," meaning the 2065 * Intent you are sending stays around after the broadcast is complete, 2066 * so that others can quickly retrieve that data through the return 2067 * value of {@link #registerReceiver(BroadcastReceiver, IntentFilter)}. In 2068 * all other ways, this behaves the same as 2069 * {@link #sendBroadcast(Intent)}. 2070 * 2071 * <p>You must hold the {@link android.Manifest.permission#BROADCAST_STICKY} 2072 * permission in order to use this API. If you do not hold that 2073 * permission, {@link SecurityException} will be thrown. 2074 * 2075 * @deprecated Sticky broadcasts should not be used. They provide no security (anyone 2076 * can access them), no protection (anyone can modify them), and many other problems. 2077 * The recommended pattern is to use a non-sticky broadcast to report that <em>something</em> 2078 * has changed, with another mechanism for apps to retrieve the current value whenever 2079 * desired. 2080 * 2081 * @param intent The Intent to broadcast; all receivers matching this 2082 * Intent will receive the broadcast, and the Intent will be held to 2083 * be re-broadcast to future receivers. 2084 * 2085 * @see #sendBroadcast(Intent) 2086 * @see #sendStickyOrderedBroadcast(Intent, BroadcastReceiver, Handler, int, String, Bundle) 2087 */ 2088 @Deprecated 2089 public abstract void sendStickyBroadcast(@RequiresPermission Intent intent); 2090 2091 /** 2092 * <p>Version of {@link #sendStickyBroadcast} that allows you to 2093 * receive data back from the broadcast. This is accomplished by 2094 * supplying your own BroadcastReceiver when calling, which will be 2095 * treated as a final receiver at the end of the broadcast -- its 2096 * {@link BroadcastReceiver#onReceive} method will be called with 2097 * the result values collected from the other receivers. The broadcast will 2098 * be serialized in the same way as calling 2099 * {@link #sendOrderedBroadcast(Intent, String)}. 2100 * 2101 * <p>Like {@link #sendBroadcast(Intent)}, this method is 2102 * asynchronous; it will return before 2103 * resultReceiver.onReceive() is called. Note that the sticky data 2104 * stored is only the data you initially supply to the broadcast, not 2105 * the result of any changes made by the receivers. 2106 * 2107 * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts. 2108 * 2109 * @deprecated Sticky broadcasts should not be used. They provide no security (anyone 2110 * can access them), no protection (anyone can modify them), and many other problems. 2111 * The recommended pattern is to use a non-sticky broadcast to report that <em>something</em> 2112 * has changed, with another mechanism for apps to retrieve the current value whenever 2113 * desired. 2114 * 2115 * @param intent The Intent to broadcast; all receivers matching this 2116 * Intent will receive the broadcast. 2117 * @param resultReceiver Your own BroadcastReceiver to treat as the final 2118 * receiver of the broadcast. 2119 * @param scheduler A custom Handler with which to schedule the 2120 * resultReceiver callback; if null it will be 2121 * scheduled in the Context's main thread. 2122 * @param initialCode An initial value for the result code. Often 2123 * Activity.RESULT_OK. 2124 * @param initialData An initial value for the result data. Often 2125 * null. 2126 * @param initialExtras An initial value for the result extras. Often 2127 * null. 2128 * 2129 * @see #sendBroadcast(Intent) 2130 * @see #sendBroadcast(Intent, String) 2131 * @see #sendOrderedBroadcast(Intent, String) 2132 * @see #sendStickyBroadcast(Intent) 2133 * @see android.content.BroadcastReceiver 2134 * @see #registerReceiver 2135 * @see android.app.Activity#RESULT_OK 2136 */ 2137 @Deprecated 2138 public abstract void sendStickyOrderedBroadcast(@RequiresPermission Intent intent, 2139 BroadcastReceiver resultReceiver, 2140 @Nullable Handler scheduler, int initialCode, @Nullable String initialData, 2141 @Nullable Bundle initialExtras); 2142 2143 /** 2144 * <p>Remove the data previously sent with {@link #sendStickyBroadcast}, 2145 * so that it is as if the sticky broadcast had never happened. 2146 * 2147 * <p>You must hold the {@link android.Manifest.permission#BROADCAST_STICKY} 2148 * permission in order to use this API. If you do not hold that 2149 * permission, {@link SecurityException} will be thrown. 2150 * 2151 * @deprecated Sticky broadcasts should not be used. They provide no security (anyone 2152 * can access them), no protection (anyone can modify them), and many other problems. 2153 * The recommended pattern is to use a non-sticky broadcast to report that <em>something</em> 2154 * has changed, with another mechanism for apps to retrieve the current value whenever 2155 * desired. 2156 * 2157 * @param intent The Intent that was previously broadcast. 2158 * 2159 * @see #sendStickyBroadcast 2160 */ 2161 @Deprecated 2162 public abstract void removeStickyBroadcast(@RequiresPermission Intent intent); 2163 2164 /** 2165 * <p>Version of {@link #sendStickyBroadcast(Intent)} that allows you to specify the 2166 * user the broadcast will be sent to. This is not available to applications 2167 * that are not pre-installed on the system image. Using it requires holding 2168 * the INTERACT_ACROSS_USERS permission. 2169 * 2170 * @deprecated Sticky broadcasts should not be used. They provide no security (anyone 2171 * can access them), no protection (anyone can modify them), and many other problems. 2172 * The recommended pattern is to use a non-sticky broadcast to report that <em>something</em> 2173 * has changed, with another mechanism for apps to retrieve the current value whenever 2174 * desired. 2175 * 2176 * @param intent The Intent to broadcast; all receivers matching this 2177 * Intent will receive the broadcast, and the Intent will be held to 2178 * be re-broadcast to future receivers. 2179 * @param user UserHandle to send the intent to. 2180 * 2181 * @see #sendBroadcast(Intent) 2182 */ 2183 @Deprecated 2184 public abstract void sendStickyBroadcastAsUser(@RequiresPermission Intent intent, 2185 UserHandle user); 2186 2187 /** 2188 * @hide 2189 * This is just here for sending CONNECTIVITY_ACTION. 2190 */ 2191 @Deprecated 2192 public abstract void sendStickyBroadcastAsUser(@RequiresPermission Intent intent, 2193 UserHandle user, Bundle options); 2194 2195 /** 2196 * <p>Version of 2197 * {@link #sendStickyOrderedBroadcast(Intent, BroadcastReceiver, Handler, int, String, Bundle)} 2198 * that allows you to specify the 2199 * user the broadcast will be sent to. This is not available to applications 2200 * that are not pre-installed on the system image. Using it requires holding 2201 * the INTERACT_ACROSS_USERS permission. 2202 * 2203 * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts. 2204 * 2205 * @deprecated Sticky broadcasts should not be used. They provide no security (anyone 2206 * can access them), no protection (anyone can modify them), and many other problems. 2207 * The recommended pattern is to use a non-sticky broadcast to report that <em>something</em> 2208 * has changed, with another mechanism for apps to retrieve the current value whenever 2209 * desired. 2210 * 2211 * @param intent The Intent to broadcast; all receivers matching this 2212 * Intent will receive the broadcast. 2213 * @param user UserHandle to send the intent to. 2214 * @param resultReceiver Your own BroadcastReceiver to treat as the final 2215 * receiver of the broadcast. 2216 * @param scheduler A custom Handler with which to schedule the 2217 * resultReceiver callback; if null it will be 2218 * scheduled in the Context's main thread. 2219 * @param initialCode An initial value for the result code. Often 2220 * Activity.RESULT_OK. 2221 * @param initialData An initial value for the result data. Often 2222 * null. 2223 * @param initialExtras An initial value for the result extras. Often 2224 * null. 2225 * 2226 * @see #sendStickyOrderedBroadcast(Intent, BroadcastReceiver, Handler, int, String, Bundle) 2227 */ 2228 @Deprecated 2229 public abstract void sendStickyOrderedBroadcastAsUser(@RequiresPermission Intent intent, 2230 UserHandle user, BroadcastReceiver resultReceiver, 2231 @Nullable Handler scheduler, int initialCode, @Nullable String initialData, 2232 @Nullable Bundle initialExtras); 2233 2234 /** 2235 * <p>Version of {@link #removeStickyBroadcast(Intent)} that allows you to specify the 2236 * user the broadcast will be sent to. This is not available to applications 2237 * that are not pre-installed on the system image. Using it requires holding 2238 * the INTERACT_ACROSS_USERS permission. 2239 * 2240 * <p>You must hold the {@link android.Manifest.permission#BROADCAST_STICKY} 2241 * permission in order to use this API. If you do not hold that 2242 * permission, {@link SecurityException} will be thrown. 2243 * 2244 * @deprecated Sticky broadcasts should not be used. They provide no security (anyone 2245 * can access them), no protection (anyone can modify them), and many other problems. 2246 * The recommended pattern is to use a non-sticky broadcast to report that <em>something</em> 2247 * has changed, with another mechanism for apps to retrieve the current value whenever 2248 * desired. 2249 * 2250 * @param intent The Intent that was previously broadcast. 2251 * @param user UserHandle to remove the sticky broadcast from. 2252 * 2253 * @see #sendStickyBroadcastAsUser 2254 */ 2255 @Deprecated 2256 public abstract void removeStickyBroadcastAsUser(@RequiresPermission Intent intent, 2257 UserHandle user); 2258 2259 /** 2260 * Register a BroadcastReceiver to be run in the main activity thread. The 2261 * <var>receiver</var> will be called with any broadcast Intent that 2262 * matches <var>filter</var>, in the main application thread. 2263 * 2264 * <p>The system may broadcast Intents that are "sticky" -- these stay 2265 * around after the broadcast as finished, to be sent to any later 2266 * registrations. If your IntentFilter matches one of these sticky 2267 * Intents, that Intent will be returned by this function 2268 * <strong>and</strong> sent to your <var>receiver</var> as if it had just 2269 * been broadcast. 2270 * 2271 * <p>There may be multiple sticky Intents that match <var>filter</var>, 2272 * in which case each of these will be sent to <var>receiver</var>. In 2273 * this case, only one of these can be returned directly by the function; 2274 * which of these that is returned is arbitrarily decided by the system. 2275 * 2276 * <p>If you know the Intent your are registering for is sticky, you can 2277 * supply null for your <var>receiver</var>. In this case, no receiver is 2278 * registered -- the function simply returns the sticky Intent that 2279 * matches <var>filter</var>. In the case of multiple matches, the same 2280 * rules as described above apply. 2281 * 2282 * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts. 2283 * 2284 * <p>As of {@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH}, receivers 2285 * registered with this method will correctly respect the 2286 * {@link Intent#setPackage(String)} specified for an Intent being broadcast. 2287 * Prior to that, it would be ignored and delivered to all matching registered 2288 * receivers. Be careful if using this for security.</p> 2289 * 2290 * <p class="note">Note: this method <em>cannot be called from a 2291 * {@link BroadcastReceiver} component;</em> that is, from a BroadcastReceiver 2292 * that is declared in an application's manifest. It is okay, however, to call 2293 * this method from another BroadcastReceiver that has itself been registered 2294 * at run time with {@link #registerReceiver}, since the lifetime of such a 2295 * registered BroadcastReceiver is tied to the object that registered it.</p> 2296 * 2297 * @param receiver The BroadcastReceiver to handle the broadcast. 2298 * @param filter Selects the Intent broadcasts to be received. 2299 * 2300 * @return The first sticky intent found that matches <var>filter</var>, 2301 * or null if there are none. 2302 * 2303 * @see #registerReceiver(BroadcastReceiver, IntentFilter, String, Handler) 2304 * @see #sendBroadcast 2305 * @see #unregisterReceiver 2306 */ 2307 @Nullable 2308 public abstract Intent registerReceiver(@Nullable BroadcastReceiver receiver, 2309 IntentFilter filter); 2310 2311 /** 2312 * Register to receive intent broadcasts, to run in the context of 2313 * <var>scheduler</var>. See 2314 * {@link #registerReceiver(BroadcastReceiver, IntentFilter)} for more 2315 * information. This allows you to enforce permissions on who can 2316 * broadcast intents to your receiver, or have the receiver run in 2317 * a different thread than the main application thread. 2318 * 2319 * <p>See {@link BroadcastReceiver} for more information on Intent broadcasts. 2320 * 2321 * <p>As of {@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH}, receivers 2322 * registered with this method will correctly respect the 2323 * {@link Intent#setPackage(String)} specified for an Intent being broadcast. 2324 * Prior to that, it would be ignored and delivered to all matching registered 2325 * receivers. Be careful if using this for security.</p> 2326 * 2327 * @param receiver The BroadcastReceiver to handle the broadcast. 2328 * @param filter Selects the Intent broadcasts to be received. 2329 * @param broadcastPermission String naming a permissions that a 2330 * broadcaster must hold in order to send an Intent to you. If null, 2331 * no permission is required. 2332 * @param scheduler Handler identifying the thread that will receive 2333 * the Intent. If null, the main thread of the process will be used. 2334 * 2335 * @return The first sticky intent found that matches <var>filter</var>, 2336 * or null if there are none. 2337 * 2338 * @see #registerReceiver(BroadcastReceiver, IntentFilter) 2339 * @see #sendBroadcast 2340 * @see #unregisterReceiver 2341 */ 2342 @Nullable 2343 public abstract Intent registerReceiver(BroadcastReceiver receiver, 2344 IntentFilter filter, @Nullable String broadcastPermission, 2345 @Nullable Handler scheduler); 2346 2347 /** 2348 * @hide 2349 * Same as {@link #registerReceiver(BroadcastReceiver, IntentFilter, String, Handler) 2350 * but for a specific user. This receiver will receiver broadcasts that 2351 * are sent to the requested user. It 2352 * requires holding the {@link android.Manifest.permission#INTERACT_ACROSS_USERS_FULL} 2353 * permission. 2354 * 2355 * @param receiver The BroadcastReceiver to handle the broadcast. 2356 * @param user UserHandle to send the intent to. 2357 * @param filter Selects the Intent broadcasts to be received. 2358 * @param broadcastPermission String naming a permissions that a 2359 * broadcaster must hold in order to send an Intent to you. If null, 2360 * no permission is required. 2361 * @param scheduler Handler identifying the thread that will receive 2362 * the Intent. If null, the main thread of the process will be used. 2363 * 2364 * @return The first sticky intent found that matches <var>filter</var>, 2365 * or null if there are none. 2366 * 2367 * @see #registerReceiver(BroadcastReceiver, IntentFilter, String, Handler) 2368 * @see #sendBroadcast 2369 * @see #unregisterReceiver 2370 */ 2371 @Nullable 2372 public abstract Intent registerReceiverAsUser(BroadcastReceiver receiver, 2373 UserHandle user, IntentFilter filter, @Nullable String broadcastPermission, 2374 @Nullable Handler scheduler); 2375 2376 /** 2377 * Unregister a previously registered BroadcastReceiver. <em>All</em> 2378 * filters that have been registered for this BroadcastReceiver will be 2379 * removed. 2380 * 2381 * @param receiver The BroadcastReceiver to unregister. 2382 * 2383 * @see #registerReceiver 2384 */ 2385 public abstract void unregisterReceiver(BroadcastReceiver receiver); 2386 2387 /** 2388 * Request that a given application service be started. The Intent 2389 * should contain either contain the complete class name of a specific service 2390 * implementation to start or a specific package name to target. If the 2391 * Intent is less specified, it log a warning about this and which of the 2392 * multiple matching services it finds and uses will be undefined. If this service 2393 * is not already running, it will be instantiated and started (creating a 2394 * process for it if needed); if it is running then it remains running. 2395 * 2396 * <p>Every call to this method will result in a corresponding call to 2397 * the target service's {@link android.app.Service#onStartCommand} method, 2398 * with the <var>intent</var> given here. This provides a convenient way 2399 * to submit jobs to a service without having to bind and call on to its 2400 * interface. 2401 * 2402 * <p>Using startService() overrides the default service lifetime that is 2403 * managed by {@link #bindService}: it requires the service to remain 2404 * running until {@link #stopService} is called, regardless of whether 2405 * any clients are connected to it. Note that calls to startService() 2406 * are not nesting: no matter how many times you call startService(), 2407 * a single call to {@link #stopService} will stop it. 2408 * 2409 * <p>The system attempts to keep running services around as much as 2410 * possible. The only time they should be stopped is if the current 2411 * foreground application is using so many resources that the service needs 2412 * to be killed. If any errors happen in the service's process, it will 2413 * automatically be restarted. 2414 * 2415 * <p>This function will throw {@link SecurityException} if you do not 2416 * have permission to start the given service. 2417 * 2418 * @param service Identifies the service to be started. The Intent must be either 2419 * fully explicit (supplying a component name) or specify a specific package 2420 * name it is targetted to. Additional values 2421 * may be included in the Intent extras to supply arguments along with 2422 * this specific start call. 2423 * 2424 * @return If the service is being started or is already running, the 2425 * {@link ComponentName} of the actual service that was started is 2426 * returned; else if the service does not exist null is returned. 2427 * 2428 * @throws SecurityException 2429 * 2430 * @see #stopService 2431 * @see #bindService 2432 */ 2433 @Nullable 2434 public abstract ComponentName startService(Intent service); 2435 2436 /** 2437 * Request that a given application service be stopped. If the service is 2438 * not running, nothing happens. Otherwise it is stopped. Note that calls 2439 * to startService() are not counted -- this stops the service no matter 2440 * how many times it was started. 2441 * 2442 * <p>Note that if a stopped service still has {@link ServiceConnection} 2443 * objects bound to it with the {@link #BIND_AUTO_CREATE} set, it will 2444 * not be destroyed until all of these bindings are removed. See 2445 * the {@link android.app.Service} documentation for more details on a 2446 * service's lifecycle. 2447 * 2448 * <p>This function will throw {@link SecurityException} if you do not 2449 * have permission to stop the given service. 2450 * 2451 * @param service Description of the service to be stopped. The Intent must be either 2452 * fully explicit (supplying a component name) or specify a specific package 2453 * name it is targetted to. 2454 * 2455 * @return If there is a service matching the given Intent that is already 2456 * running, then it is stopped and {@code true} is returned; else {@code false} is returned. 2457 * 2458 * @throws SecurityException 2459 * 2460 * @see #startService 2461 */ 2462 public abstract boolean stopService(Intent service); 2463 2464 /** 2465 * @hide like {@link #startService(Intent)} but for a specific user. 2466 */ 2467 public abstract ComponentName startServiceAsUser(Intent service, UserHandle user); 2468 2469 /** 2470 * @hide like {@link #stopService(Intent)} but for a specific user. 2471 */ 2472 public abstract boolean stopServiceAsUser(Intent service, UserHandle user); 2473 2474 /** 2475 * Connect to an application service, creating it if needed. This defines 2476 * a dependency between your application and the service. The given 2477 * <var>conn</var> will receive the service object when it is created and be 2478 * told if it dies and restarts. The service will be considered required 2479 * by the system only for as long as the calling context exists. For 2480 * example, if this Context is an Activity that is stopped, the service will 2481 * not be required to continue running until the Activity is resumed. 2482 * 2483 * <p>This function will throw {@link SecurityException} if you do not 2484 * have permission to bind to the given service. 2485 * 2486 * <p class="note">Note: this method <em>can not be called from a 2487 * {@link BroadcastReceiver} component</em>. A pattern you can use to 2488 * communicate from a BroadcastReceiver to a Service is to call 2489 * {@link #startService} with the arguments containing the command to be 2490 * sent, with the service calling its 2491 * {@link android.app.Service#stopSelf(int)} method when done executing 2492 * that command. See the API demo App/Service/Service Start Arguments 2493 * Controller for an illustration of this. It is okay, however, to use 2494 * this method from a BroadcastReceiver that has been registered with 2495 * {@link #registerReceiver}, since the lifetime of this BroadcastReceiver 2496 * is tied to another object (the one that registered it).</p> 2497 * 2498 * @param service Identifies the service to connect to. The Intent may 2499 * specify either an explicit component name, or a logical 2500 * description (action, category, etc) to match an 2501 * {@link IntentFilter} published by a service. 2502 * @param conn Receives information as the service is started and stopped. 2503 * This must be a valid ServiceConnection object; it must not be null. 2504 * @param flags Operation options for the binding. May be 0, 2505 * {@link #BIND_AUTO_CREATE}, {@link #BIND_DEBUG_UNBIND}, 2506 * {@link #BIND_NOT_FOREGROUND}, {@link #BIND_ABOVE_CLIENT}, 2507 * {@link #BIND_ALLOW_OOM_MANAGEMENT}, or 2508 * {@link #BIND_WAIVE_PRIORITY}. 2509 * @return If you have successfully bound to the service, {@code true} is returned; 2510 * {@code false} is returned if the connection is not made so you will not 2511 * receive the service object. 2512 * 2513 * @throws SecurityException 2514 * 2515 * @see #unbindService 2516 * @see #startService 2517 * @see #BIND_AUTO_CREATE 2518 * @see #BIND_DEBUG_UNBIND 2519 * @see #BIND_NOT_FOREGROUND 2520 */ 2521 public abstract boolean bindService(@RequiresPermission Intent service, 2522 @NonNull ServiceConnection conn, @BindServiceFlags int flags); 2523 2524 /** 2525 * Same as {@link #bindService(Intent, ServiceConnection, int)}, but with an explicit userHandle 2526 * argument for use by system server and other multi-user aware code. 2527 * @hide 2528 */ 2529 @SystemApi 2530 @SuppressWarnings("unused") 2531 public boolean bindServiceAsUser(@RequiresPermission Intent service, ServiceConnection conn, 2532 int flags, UserHandle user) { 2533 throw new RuntimeException("Not implemented. Must override in a subclass."); 2534 } 2535 2536 /** 2537 * Disconnect from an application service. You will no longer receive 2538 * calls as the service is restarted, and the service is now allowed to 2539 * stop at any time. 2540 * 2541 * @param conn The connection interface previously supplied to 2542 * bindService(). This parameter must not be null. 2543 * 2544 * @see #bindService 2545 */ 2546 public abstract void unbindService(@NonNull ServiceConnection conn); 2547 2548 /** 2549 * Start executing an {@link android.app.Instrumentation} class. The given 2550 * Instrumentation component will be run by killing its target application 2551 * (if currently running), starting the target process, instantiating the 2552 * instrumentation component, and then letting it drive the application. 2553 * 2554 * <p>This function is not synchronous -- it returns as soon as the 2555 * instrumentation has started and while it is running. 2556 * 2557 * <p>Instrumentation is normally only allowed to run against a package 2558 * that is either unsigned or signed with a signature that the 2559 * the instrumentation package is also signed with (ensuring the target 2560 * trusts the instrumentation). 2561 * 2562 * @param className Name of the Instrumentation component to be run. 2563 * @param profileFile Optional path to write profiling data as the 2564 * instrumentation runs, or null for no profiling. 2565 * @param arguments Additional optional arguments to pass to the 2566 * instrumentation, or null. 2567 * 2568 * @return {@code true} if the instrumentation was successfully started, 2569 * else {@code false} if it could not be found. 2570 */ 2571 public abstract boolean startInstrumentation(@NonNull ComponentName className, 2572 @Nullable String profileFile, @Nullable Bundle arguments); 2573 2574 /** @hide */ 2575 @StringDef({ 2576 POWER_SERVICE, 2577 WINDOW_SERVICE, 2578 LAYOUT_INFLATER_SERVICE, 2579 ACCOUNT_SERVICE, 2580 ACTIVITY_SERVICE, 2581 ALARM_SERVICE, 2582 NOTIFICATION_SERVICE, 2583 ACCESSIBILITY_SERVICE, 2584 CAPTIONING_SERVICE, 2585 KEYGUARD_SERVICE, 2586 LOCATION_SERVICE, 2587 //@hide: COUNTRY_DETECTOR, 2588 SEARCH_SERVICE, 2589 SENSOR_SERVICE, 2590 STORAGE_SERVICE, 2591 WALLPAPER_SERVICE, 2592 VIBRATOR_SERVICE, 2593 //@hide: STATUS_BAR_SERVICE, 2594 CONNECTIVITY_SERVICE, 2595 //@hide: UPDATE_LOCK_SERVICE, 2596 //@hide: NETWORKMANAGEMENT_SERVICE, 2597 NETWORK_STATS_SERVICE, 2598 //@hide: NETWORK_POLICY_SERVICE, 2599 WIFI_SERVICE, 2600 WIFI_NAN_SERVICE, 2601 WIFI_P2P_SERVICE, 2602 WIFI_SCANNING_SERVICE, 2603 //@hide: WIFI_RTT_SERVICE, 2604 //@hide: ETHERNET_SERVICE, 2605 WIFI_RTT_SERVICE, 2606 NSD_SERVICE, 2607 AUDIO_SERVICE, 2608 FINGERPRINT_SERVICE, 2609 MEDIA_ROUTER_SERVICE, 2610 TELEPHONY_SERVICE, 2611 TELEPHONY_SUBSCRIPTION_SERVICE, 2612 CARRIER_CONFIG_SERVICE, 2613 TELECOM_SERVICE, 2614 CLIPBOARD_SERVICE, 2615 INPUT_METHOD_SERVICE, 2616 TEXT_SERVICES_MANAGER_SERVICE, 2617 APPWIDGET_SERVICE, 2618 //@hide: VOICE_INTERACTION_MANAGER_SERVICE, 2619 //@hide: BACKUP_SERVICE, 2620 DROPBOX_SERVICE, 2621 //@hide: DEVICE_IDLE_CONTROLLER, 2622 DEVICE_POLICY_SERVICE, 2623 UI_MODE_SERVICE, 2624 DOWNLOAD_SERVICE, 2625 NFC_SERVICE, 2626 BLUETOOTH_SERVICE, 2627 //@hide: SIP_SERVICE, 2628 USB_SERVICE, 2629 LAUNCHER_APPS_SERVICE, 2630 //@hide: SERIAL_SERVICE, 2631 //@hide: HDMI_CONTROL_SERVICE, 2632 INPUT_SERVICE, 2633 DISPLAY_SERVICE, 2634 USER_SERVICE, 2635 RESTRICTIONS_SERVICE, 2636 APP_OPS_SERVICE, 2637 CAMERA_SERVICE, 2638 PRINT_SERVICE, 2639 CONSUMER_IR_SERVICE, 2640 //@hide: TRUST_SERVICE, 2641 TV_INPUT_SERVICE, 2642 //@hide: NETWORK_SCORE_SERVICE, 2643 USAGE_STATS_SERVICE, 2644 MEDIA_SESSION_SERVICE, 2645 BATTERY_SERVICE, 2646 JOB_SCHEDULER_SERVICE, 2647 //@hide: PERSISTENT_DATA_BLOCK_SERVICE, 2648 MEDIA_PROJECTION_SERVICE, 2649 MIDI_SERVICE, 2650 RADIO_SERVICE, 2651 HARDWARE_PROPERTIES_SERVICE, 2652 //@hide: SOUND_TRIGGER_SERVICE, 2653 }) 2654 @Retention(RetentionPolicy.SOURCE) 2655 public @interface ServiceName {} 2656 2657 /** 2658 * Return the handle to a system-level service by name. The class of the 2659 * returned object varies by the requested name. Currently available names 2660 * are: 2661 * 2662 * <dl> 2663 * <dt> {@link #WINDOW_SERVICE} ("window") 2664 * <dd> The top-level window manager in which you can place custom 2665 * windows. The returned object is a {@link android.view.WindowManager}. 2666 * <dt> {@link #LAYOUT_INFLATER_SERVICE} ("layout_inflater") 2667 * <dd> A {@link android.view.LayoutInflater} for inflating layout resources 2668 * in this context. 2669 * <dt> {@link #ACTIVITY_SERVICE} ("activity") 2670 * <dd> A {@link android.app.ActivityManager} for interacting with the 2671 * global activity state of the system. 2672 * <dt> {@link #POWER_SERVICE} ("power") 2673 * <dd> A {@link android.os.PowerManager} for controlling power 2674 * management. 2675 * <dt> {@link #ALARM_SERVICE} ("alarm") 2676 * <dd> A {@link android.app.AlarmManager} for receiving intents at the 2677 * time of your choosing. 2678 * <dt> {@link #NOTIFICATION_SERVICE} ("notification") 2679 * <dd> A {@link android.app.NotificationManager} for informing the user 2680 * of background events. 2681 * <dt> {@link #KEYGUARD_SERVICE} ("keyguard") 2682 * <dd> A {@link android.app.KeyguardManager} for controlling keyguard. 2683 * <dt> {@link #LOCATION_SERVICE} ("location") 2684 * <dd> A {@link android.location.LocationManager} for controlling location 2685 * (e.g., GPS) updates. 2686 * <dt> {@link #SEARCH_SERVICE} ("search") 2687 * <dd> A {@link android.app.SearchManager} for handling search. 2688 * <dt> {@link #VIBRATOR_SERVICE} ("vibrator") 2689 * <dd> A {@link android.os.Vibrator} for interacting with the vibrator 2690 * hardware. 2691 * <dt> {@link #CONNECTIVITY_SERVICE} ("connection") 2692 * <dd> A {@link android.net.ConnectivityManager ConnectivityManager} for 2693 * handling management of network connections. 2694 * <dt> {@link #WIFI_SERVICE} ("wifi") 2695 * <dd> A {@link android.net.wifi.WifiManager WifiManager} for management of 2696 * Wi-Fi connectivity. 2697 * <dt> {@link #WIFI_P2P_SERVICE} ("wifip2p") 2698 * <dd> A {@link android.net.wifi.p2p.WifiP2pManager WifiP2pManager} for management of 2699 * Wi-Fi Direct connectivity. 2700 * <dt> {@link #INPUT_METHOD_SERVICE} ("input_method") 2701 * <dd> An {@link android.view.inputmethod.InputMethodManager InputMethodManager} 2702 * for management of input methods. 2703 * <dt> {@link #UI_MODE_SERVICE} ("uimode") 2704 * <dd> An {@link android.app.UiModeManager} for controlling UI modes. 2705 * <dt> {@link #DOWNLOAD_SERVICE} ("download") 2706 * <dd> A {@link android.app.DownloadManager} for requesting HTTP downloads 2707 * <dt> {@link #BATTERY_SERVICE} ("batterymanager") 2708 * <dd> A {@link android.os.BatteryManager} for managing battery state 2709 * <dt> {@link #JOB_SCHEDULER_SERVICE} ("taskmanager") 2710 * <dd> A {@link android.app.job.JobScheduler} for managing scheduled tasks 2711 * <dt> {@link #NETWORK_STATS_SERVICE} ("netstats") 2712 * <dd> A {@link android.app.usage.NetworkStatsManager NetworkStatsManager} for querying network 2713 * usage statistics. 2714 * <dt> {@link #HARDWARE_PROPERTIES_SERVICE} ("hardwareproperties") 2715 * <dd> A {@link android.os.HardwarePropertiesManager} for accessing hardware properties. 2716 * </dl> 2717 * 2718 * <p>Note: System services obtained via this API may be closely associated with 2719 * the Context in which they are obtained from. In general, do not share the 2720 * service objects between various different contexts (Activities, Applications, 2721 * Services, Providers, etc.) 2722 * 2723 * @param name The name of the desired service. 2724 * 2725 * @return The service or null if the name does not exist. 2726 * 2727 * @see #WINDOW_SERVICE 2728 * @see android.view.WindowManager 2729 * @see #LAYOUT_INFLATER_SERVICE 2730 * @see android.view.LayoutInflater 2731 * @see #ACTIVITY_SERVICE 2732 * @see android.app.ActivityManager 2733 * @see #POWER_SERVICE 2734 * @see android.os.PowerManager 2735 * @see #ALARM_SERVICE 2736 * @see android.app.AlarmManager 2737 * @see #NOTIFICATION_SERVICE 2738 * @see android.app.NotificationManager 2739 * @see #KEYGUARD_SERVICE 2740 * @see android.app.KeyguardManager 2741 * @see #LOCATION_SERVICE 2742 * @see android.location.LocationManager 2743 * @see #SEARCH_SERVICE 2744 * @see android.app.SearchManager 2745 * @see #SENSOR_SERVICE 2746 * @see android.hardware.SensorManager 2747 * @see #STORAGE_SERVICE 2748 * @see android.os.storage.StorageManager 2749 * @see #VIBRATOR_SERVICE 2750 * @see android.os.Vibrator 2751 * @see #CONNECTIVITY_SERVICE 2752 * @see android.net.ConnectivityManager 2753 * @see #WIFI_SERVICE 2754 * @see android.net.wifi.WifiManager 2755 * @see #AUDIO_SERVICE 2756 * @see android.media.AudioManager 2757 * @see #MEDIA_ROUTER_SERVICE 2758 * @see android.media.MediaRouter 2759 * @see #TELEPHONY_SERVICE 2760 * @see android.telephony.TelephonyManager 2761 * @see #TELEPHONY_SUBSCRIPTION_SERVICE 2762 * @see android.telephony.SubscriptionManager 2763 * @see #CARRIER_CONFIG_SERVICE 2764 * @see android.telephony.CarrierConfigManager 2765 * @see #INPUT_METHOD_SERVICE 2766 * @see android.view.inputmethod.InputMethodManager 2767 * @see #UI_MODE_SERVICE 2768 * @see android.app.UiModeManager 2769 * @see #DOWNLOAD_SERVICE 2770 * @see android.app.DownloadManager 2771 * @see #BATTERY_SERVICE 2772 * @see android.os.BatteryManager 2773 * @see #JOB_SCHEDULER_SERVICE 2774 * @see android.app.job.JobScheduler 2775 * @see #NETWORK_STATS_SERVICE 2776 * @see android.app.usage.NetworkStatsManager 2777 * @see android.os.HardwarePropertiesManager 2778 * @see #HARDWARE_PROPERTIES_SERVICE 2779 */ 2780 public abstract Object getSystemService(@ServiceName @NonNull String name); 2781 2782 /** 2783 * Return the handle to a system-level service by class. 2784 * <p> 2785 * Currently available classes are: 2786 * {@link android.view.WindowManager}, {@link android.view.LayoutInflater}, 2787 * {@link android.app.ActivityManager}, {@link android.os.PowerManager}, 2788 * {@link android.app.AlarmManager}, {@link android.app.NotificationManager}, 2789 * {@link android.app.KeyguardManager}, {@link android.location.LocationManager}, 2790 * {@link android.app.SearchManager}, {@link android.os.Vibrator}, 2791 * {@link android.net.ConnectivityManager}, 2792 * {@link android.net.wifi.WifiManager}, 2793 * {@link android.media.AudioManager}, {@link android.media.MediaRouter}, 2794 * {@link android.telephony.TelephonyManager}, {@link android.telephony.SubscriptionManager}, 2795 * {@link android.view.inputmethod.InputMethodManager}, 2796 * {@link android.app.UiModeManager}, {@link android.app.DownloadManager}, 2797 * {@link android.os.BatteryManager}, {@link android.app.job.JobScheduler}, 2798 * {@link android.app.usage.NetworkStatsManager}. 2799 * </p><p> 2800 * Note: System services obtained via this API may be closely associated with 2801 * the Context in which they are obtained from. In general, do not share the 2802 * service objects between various different contexts (Activities, Applications, 2803 * Services, Providers, etc.) 2804 * </p> 2805 * 2806 * @param serviceClass The class of the desired service. 2807 * @return The service or null if the class is not a supported system service. 2808 */ 2809 @SuppressWarnings("unchecked") 2810 public final <T> T getSystemService(Class<T> serviceClass) { 2811 // Because subclasses may override getSystemService(String) we cannot 2812 // perform a lookup by class alone. We must first map the class to its 2813 // service name then invoke the string-based method. 2814 String serviceName = getSystemServiceName(serviceClass); 2815 return serviceName != null ? (T)getSystemService(serviceName) : null; 2816 } 2817 2818 /** 2819 * Gets the name of the system-level service that is represented by the specified class. 2820 * 2821 * @param serviceClass The class of the desired service. 2822 * @return The service name or null if the class is not a supported system service. 2823 */ 2824 public abstract String getSystemServiceName(Class<?> serviceClass); 2825 2826 /** 2827 * Use with {@link #getSystemService} to retrieve a 2828 * {@link android.os.PowerManager} for controlling power management, 2829 * including "wake locks," which let you keep the device on while 2830 * you're running long tasks. 2831 */ 2832 public static final String POWER_SERVICE = "power"; 2833 2834 /** 2835 * Use with {@link #getSystemService} to retrieve a 2836 * {@link android.view.WindowManager} for accessing the system's window 2837 * manager. 2838 * 2839 * @see #getSystemService 2840 * @see android.view.WindowManager 2841 */ 2842 public static final String WINDOW_SERVICE = "window"; 2843 2844 /** 2845 * Use with {@link #getSystemService} to retrieve a 2846 * {@link android.view.LayoutInflater} for inflating layout resources in this 2847 * context. 2848 * 2849 * @see #getSystemService 2850 * @see android.view.LayoutInflater 2851 */ 2852 public static final String LAYOUT_INFLATER_SERVICE = "layout_inflater"; 2853 2854 /** 2855 * Use with {@link #getSystemService} to retrieve a 2856 * {@link android.accounts.AccountManager} for receiving intents at a 2857 * time of your choosing. 2858 * 2859 * @see #getSystemService 2860 * @see android.accounts.AccountManager 2861 */ 2862 public static final String ACCOUNT_SERVICE = "account"; 2863 2864 /** 2865 * Use with {@link #getSystemService} to retrieve a 2866 * {@link android.app.ActivityManager} for interacting with the global 2867 * system state. 2868 * 2869 * @see #getSystemService 2870 * @see android.app.ActivityManager 2871 */ 2872 public static final String ACTIVITY_SERVICE = "activity"; 2873 2874 /** 2875 * Use with {@link #getSystemService} to retrieve a 2876 * {@link android.app.AlarmManager} for receiving intents at a 2877 * time of your choosing. 2878 * 2879 * @see #getSystemService 2880 * @see android.app.AlarmManager 2881 */ 2882 public static final String ALARM_SERVICE = "alarm"; 2883 2884 /** 2885 * Use with {@link #getSystemService} to retrieve a 2886 * {@link android.app.NotificationManager} for informing the user of 2887 * background events. 2888 * 2889 * @see #getSystemService 2890 * @see android.app.NotificationManager 2891 */ 2892 public static final String NOTIFICATION_SERVICE = "notification"; 2893 2894 /** 2895 * Use with {@link #getSystemService} to retrieve a 2896 * {@link android.view.accessibility.AccessibilityManager} for giving the user 2897 * feedback for UI events through the registered event listeners. 2898 * 2899 * @see #getSystemService 2900 * @see android.view.accessibility.AccessibilityManager 2901 */ 2902 public static final String ACCESSIBILITY_SERVICE = "accessibility"; 2903 2904 /** 2905 * Use with {@link #getSystemService} to retrieve a 2906 * {@link android.view.accessibility.CaptioningManager} for obtaining 2907 * captioning properties and listening for changes in captioning 2908 * preferences. 2909 * 2910 * @see #getSystemService 2911 * @see android.view.accessibility.CaptioningManager 2912 */ 2913 public static final String CAPTIONING_SERVICE = "captioning"; 2914 2915 /** 2916 * Use with {@link #getSystemService} to retrieve a 2917 * {@link android.app.NotificationManager} for controlling keyguard. 2918 * 2919 * @see #getSystemService 2920 * @see android.app.KeyguardManager 2921 */ 2922 public static final String KEYGUARD_SERVICE = "keyguard"; 2923 2924 /** 2925 * Use with {@link #getSystemService} to retrieve a {@link 2926 * android.location.LocationManager} for controlling location 2927 * updates. 2928 * 2929 * @see #getSystemService 2930 * @see android.location.LocationManager 2931 */ 2932 public static final String LOCATION_SERVICE = "location"; 2933 2934 /** 2935 * Use with {@link #getSystemService} to retrieve a 2936 * {@link android.location.CountryDetector} for detecting the country that 2937 * the user is in. 2938 * 2939 * @hide 2940 */ 2941 public static final String COUNTRY_DETECTOR = "country_detector"; 2942 2943 /** 2944 * Use with {@link #getSystemService} to retrieve a {@link 2945 * android.app.SearchManager} for handling searches. 2946 * 2947 * @see #getSystemService 2948 * @see android.app.SearchManager 2949 */ 2950 public static final String SEARCH_SERVICE = "search"; 2951 2952 /** 2953 * Use with {@link #getSystemService} to retrieve a {@link 2954 * android.hardware.SensorManager} for accessing sensors. 2955 * 2956 * @see #getSystemService 2957 * @see android.hardware.SensorManager 2958 */ 2959 public static final String SENSOR_SERVICE = "sensor"; 2960 2961 /** 2962 * Use with {@link #getSystemService} to retrieve a {@link 2963 * android.os.storage.StorageManager} for accessing system storage 2964 * functions. 2965 * 2966 * @see #getSystemService 2967 * @see android.os.storage.StorageManager 2968 */ 2969 public static final String STORAGE_SERVICE = "storage"; 2970 2971 /** 2972 * Use with {@link #getSystemService} to retrieve a 2973 * com.android.server.WallpaperService for accessing wallpapers. 2974 * 2975 * @see #getSystemService 2976 */ 2977 public static final String WALLPAPER_SERVICE = "wallpaper"; 2978 2979 /** 2980 * Use with {@link #getSystemService} to retrieve a {@link 2981 * android.os.Vibrator} for interacting with the vibration hardware. 2982 * 2983 * @see #getSystemService 2984 * @see android.os.Vibrator 2985 */ 2986 public static final String VIBRATOR_SERVICE = "vibrator"; 2987 2988 /** 2989 * Use with {@link #getSystemService} to retrieve a {@link 2990 * android.app.StatusBarManager} for interacting with the status bar. 2991 * 2992 * @see #getSystemService 2993 * @see android.app.StatusBarManager 2994 * @hide 2995 */ 2996 public static final String STATUS_BAR_SERVICE = "statusbar"; 2997 2998 /** 2999 * Use with {@link #getSystemService} to retrieve a {@link 3000 * android.net.ConnectivityManager} for handling management of 3001 * network connections. 3002 * 3003 * @see #getSystemService 3004 * @see android.net.ConnectivityManager 3005 */ 3006 public static final String CONNECTIVITY_SERVICE = "connectivity"; 3007 3008 /** 3009 * Use with {@link #getSystemService} to retrieve a {@link 3010 * android.os.IUpdateLock} for managing runtime sequences that 3011 * must not be interrupted by headless OTA application or similar. 3012 * 3013 * @hide 3014 * @see #getSystemService 3015 * @see android.os.UpdateLock 3016 */ 3017 public static final String UPDATE_LOCK_SERVICE = "updatelock"; 3018 3019 /** 3020 * Constant for the internal network management service, not really a Context service. 3021 * @hide 3022 */ 3023 public static final String NETWORKMANAGEMENT_SERVICE = "network_management"; 3024 3025 /** 3026 * Use with {@link #getSystemService} to retrieve a {@link 3027 * android.app.usage.NetworkStatsManager} for querying network usage stats. 3028 * 3029 * @see #getSystemService 3030 * @see android.app.usage.NetworkStatsManager 3031 */ 3032 public static final String NETWORK_STATS_SERVICE = "netstats"; 3033 /** {@hide} */ 3034 public static final String NETWORK_POLICY_SERVICE = "netpolicy"; 3035 3036 /** 3037 * Use with {@link #getSystemService} to retrieve a {@link 3038 * android.net.wifi.WifiManager} for handling management of 3039 * Wi-Fi access. 3040 * 3041 * @see #getSystemService 3042 * @see android.net.wifi.WifiManager 3043 */ 3044 public static final String WIFI_SERVICE = "wifi"; 3045 3046 /** 3047 * Use with {@link #getSystemService} to retrieve a {@link 3048 * android.net.wifi.p2p.WifiP2pManager} for handling management of 3049 * Wi-Fi peer-to-peer connections. 3050 * 3051 * @see #getSystemService 3052 * @see android.net.wifi.p2p.WifiP2pManager 3053 */ 3054 public static final String WIFI_P2P_SERVICE = "wifip2p"; 3055 3056 /** 3057 * Use with {@link #getSystemService} to retrieve a 3058 * {@link android.net.wifi.nan.WifiNanManager} for handling management of 3059 * Wi-Fi NAN discovery and connections. 3060 * 3061 * @see #getSystemService 3062 * @see android.net.wifi.nan.WifiNanManager 3063 * @hide PROPOSED_NAN_API 3064 */ 3065 public static final String WIFI_NAN_SERVICE = "wifinan"; 3066 3067 /** 3068 * Use with {@link #getSystemService} to retrieve a {@link 3069 * android.net.wifi.WifiScanner} for scanning the wifi universe 3070 * 3071 * @see #getSystemService 3072 * @see android.net.wifi.WifiScanner 3073 * @hide 3074 */ 3075 @SystemApi 3076 public static final String WIFI_SCANNING_SERVICE = "wifiscanner"; 3077 3078 /** 3079 * Use with {@link #getSystemService} to retrieve a {@link 3080 * android.net.wifi.RttManager} for ranging devices with wifi 3081 * 3082 * @see #getSystemService 3083 * @see android.net.wifi.RttManager 3084 * @hide 3085 */ 3086 @SystemApi 3087 public static final String WIFI_RTT_SERVICE = "rttmanager"; 3088 3089 /** 3090 * Use with {@link #getSystemService} to retrieve a {@link 3091 * android.net.EthernetManager} for handling management of 3092 * Ethernet access. 3093 * 3094 * @see #getSystemService 3095 * @see android.net.EthernetManager 3096 * 3097 * @hide 3098 */ 3099 public static final String ETHERNET_SERVICE = "ethernet"; 3100 3101 /** 3102 * Use with {@link #getSystemService} to retrieve a {@link 3103 * android.net.nsd.NsdManager} for handling management of network service 3104 * discovery 3105 * 3106 * @see #getSystemService 3107 * @see android.net.nsd.NsdManager 3108 */ 3109 public static final String NSD_SERVICE = "servicediscovery"; 3110 3111 /** 3112 * Use with {@link #getSystemService} to retrieve a 3113 * {@link android.media.AudioManager} for handling management of volume, 3114 * ringer modes and audio routing. 3115 * 3116 * @see #getSystemService 3117 * @see android.media.AudioManager 3118 */ 3119 public static final String AUDIO_SERVICE = "audio"; 3120 3121 /** 3122 * Use with {@link #getSystemService} to retrieve a 3123 * {@link android.hardware.fingerprint.FingerprintManager} for handling management 3124 * of fingerprints. 3125 * 3126 * @see #getSystemService 3127 * @see android.hardware.fingerprint.FingerprintManager 3128 */ 3129 public static final String FINGERPRINT_SERVICE = "fingerprint"; 3130 3131 /** 3132 * Use with {@link #getSystemService} to retrieve a 3133 * {@link android.media.MediaRouter} for controlling and managing 3134 * routing of media. 3135 * 3136 * @see #getSystemService 3137 * @see android.media.MediaRouter 3138 */ 3139 public static final String MEDIA_ROUTER_SERVICE = "media_router"; 3140 3141 /** 3142 * Use with {@link #getSystemService} to retrieve a 3143 * {@link android.media.session.MediaSessionManager} for managing media Sessions. 3144 * 3145 * @see #getSystemService 3146 * @see android.media.session.MediaSessionManager 3147 */ 3148 public static final String MEDIA_SESSION_SERVICE = "media_session"; 3149 3150 /** 3151 * Use with {@link #getSystemService} to retrieve a 3152 * {@link android.telephony.TelephonyManager} for handling management the 3153 * telephony features of the device. 3154 * 3155 * @see #getSystemService 3156 * @see android.telephony.TelephonyManager 3157 */ 3158 public static final String TELEPHONY_SERVICE = "phone"; 3159 3160 /** 3161 * Use with {@link #getSystemService} to retrieve a 3162 * {@link android.telephony.SubscriptionManager} for handling management the 3163 * telephony subscriptions of the device. 3164 * 3165 * @see #getSystemService 3166 * @see android.telephony.SubscriptionManager 3167 */ 3168 public static final String TELEPHONY_SUBSCRIPTION_SERVICE = "telephony_subscription_service"; 3169 3170 /** 3171 * Use with {@link #getSystemService} to retrieve a 3172 * {@link android.telecom.TelecomManager} to manage telecom-related features 3173 * of the device. 3174 * 3175 * @see #getSystemService 3176 * @see android.telecom.TelecomManager 3177 */ 3178 public static final String TELECOM_SERVICE = "telecom"; 3179 3180 /** 3181 * Use with {@link #getSystemService} to retrieve a 3182 * {@link android.telephony.CarrierConfigManager} for reading carrier configuration values. 3183 * 3184 * @see #getSystemService 3185 * @see android.telephony.CarrierConfigManager 3186 */ 3187 public static final String CARRIER_CONFIG_SERVICE = "carrier_config"; 3188 3189 /** 3190 * Use with {@link #getSystemService} to retrieve a 3191 * {@link android.text.ClipboardManager} for accessing and modifying 3192 * {@link android.content.ClipboardManager} for accessing and modifying 3193 * the contents of the global clipboard. 3194 * 3195 * @see #getSystemService 3196 * @see android.content.ClipboardManager 3197 */ 3198 public static final String CLIPBOARD_SERVICE = "clipboard"; 3199 3200 /** 3201 * Use with {@link #getSystemService} to retrieve a 3202 * {@link android.view.inputmethod.InputMethodManager} for accessing input 3203 * methods. 3204 * 3205 * @see #getSystemService 3206 */ 3207 public static final String INPUT_METHOD_SERVICE = "input_method"; 3208 3209 /** 3210 * Use with {@link #getSystemService} to retrieve a 3211 * {@link android.view.textservice.TextServicesManager} for accessing 3212 * text services. 3213 * 3214 * @see #getSystemService 3215 */ 3216 public static final String TEXT_SERVICES_MANAGER_SERVICE = "textservices"; 3217 3218 /** 3219 * Use with {@link #getSystemService} to retrieve a 3220 * {@link android.appwidget.AppWidgetManager} for accessing AppWidgets. 3221 * 3222 * @see #getSystemService 3223 */ 3224 public static final String APPWIDGET_SERVICE = "appwidget"; 3225 3226 /** 3227 * Official published name of the (internal) voice interaction manager service. 3228 * 3229 * @hide 3230 * @see #getSystemService 3231 */ 3232 public static final String VOICE_INTERACTION_MANAGER_SERVICE = "voiceinteraction"; 3233 3234 /** 3235 * Use with {@link #getSystemService} to access the 3236 * {@link com.android.server.voiceinteraction.SoundTriggerService}. 3237 * 3238 * @hide 3239 * @see #getSystemService 3240 */ 3241 public static final String SOUND_TRIGGER_SERVICE = "soundtrigger"; 3242 3243 3244 /** 3245 * Use with {@link #getSystemService} to retrieve an 3246 * {@link android.app.backup.IBackupManager IBackupManager} for communicating 3247 * with the backup mechanism. 3248 * @hide 3249 * 3250 * @see #getSystemService 3251 */ 3252 @SystemApi 3253 public static final String BACKUP_SERVICE = "backup"; 3254 3255 /** 3256 * Use with {@link #getSystemService} to retrieve a 3257 * {@link android.os.DropBoxManager} instance for recording 3258 * diagnostic logs. 3259 * @see #getSystemService 3260 */ 3261 public static final String DROPBOX_SERVICE = "dropbox"; 3262 3263 /** 3264 * System service name for the DeviceIdleController. There is no Java API for this. 3265 * @see #getSystemService 3266 * @hide 3267 */ 3268 public static final String DEVICE_IDLE_CONTROLLER = "deviceidle"; 3269 3270 /** 3271 * Use with {@link #getSystemService} to retrieve a 3272 * {@link android.app.admin.DevicePolicyManager} for working with global 3273 * device policy management. 3274 * 3275 * @see #getSystemService 3276 */ 3277 public static final String DEVICE_POLICY_SERVICE = "device_policy"; 3278 3279 /** 3280 * Use with {@link #getSystemService} to retrieve a 3281 * {@link android.app.UiModeManager} for controlling UI modes. 3282 * 3283 * @see #getSystemService 3284 */ 3285 public static final String UI_MODE_SERVICE = "uimode"; 3286 3287 /** 3288 * Use with {@link #getSystemService} to retrieve a 3289 * {@link android.app.DownloadManager} for requesting HTTP downloads. 3290 * 3291 * @see #getSystemService 3292 */ 3293 public static final String DOWNLOAD_SERVICE = "download"; 3294 3295 /** 3296 * Use with {@link #getSystemService} to retrieve a 3297 * {@link android.os.BatteryManager} for managing battery state. 3298 * 3299 * @see #getSystemService 3300 */ 3301 public static final String BATTERY_SERVICE = "batterymanager"; 3302 3303 /** 3304 * Use with {@link #getSystemService} to retrieve a 3305 * {@link android.nfc.NfcManager} for using NFC. 3306 * 3307 * @see #getSystemService 3308 */ 3309 public static final String NFC_SERVICE = "nfc"; 3310 3311 /** 3312 * Use with {@link #getSystemService} to retrieve a 3313 * {@link android.bluetooth.BluetoothManager} for using Bluetooth. 3314 * 3315 * @see #getSystemService 3316 */ 3317 public static final String BLUETOOTH_SERVICE = "bluetooth"; 3318 3319 /** 3320 * Use with {@link #getSystemService} to retrieve a 3321 * {@link android.net.sip.SipManager} for accessing the SIP related service. 3322 * 3323 * @see #getSystemService 3324 */ 3325 /** @hide */ 3326 public static final String SIP_SERVICE = "sip"; 3327 3328 /** 3329 * Use with {@link #getSystemService} to retrieve a {@link 3330 * android.hardware.usb.UsbManager} for access to USB devices (as a USB host) 3331 * and for controlling this device's behavior as a USB device. 3332 * 3333 * @see #getSystemService 3334 * @see android.hardware.usb.UsbManager 3335 */ 3336 public static final String USB_SERVICE = "usb"; 3337 3338 /** 3339 * Use with {@link #getSystemService} to retrieve a {@link 3340 * android.hardware.SerialManager} for access to serial ports. 3341 * 3342 * @see #getSystemService 3343 * @see android.hardware.SerialManager 3344 * 3345 * @hide 3346 */ 3347 public static final String SERIAL_SERVICE = "serial"; 3348 3349 /** 3350 * Use with {@link #getSystemService} to retrieve a 3351 * {@link android.hardware.hdmi.HdmiControlManager} for controlling and managing 3352 * HDMI-CEC protocol. 3353 * 3354 * @see #getSystemService 3355 * @see android.hardware.hdmi.HdmiControlManager 3356 * @hide 3357 */ 3358 @SystemApi 3359 public static final String HDMI_CONTROL_SERVICE = "hdmi_control"; 3360 3361 /** 3362 * Use with {@link #getSystemService} to retrieve a 3363 * {@link android.hardware.input.InputManager} for interacting with input devices. 3364 * 3365 * @see #getSystemService 3366 * @see android.hardware.input.InputManager 3367 */ 3368 public static final String INPUT_SERVICE = "input"; 3369 3370 /** 3371 * Use with {@link #getSystemService} to retrieve a 3372 * {@link android.hardware.display.DisplayManager} for interacting with display devices. 3373 * 3374 * @see #getSystemService 3375 * @see android.hardware.display.DisplayManager 3376 */ 3377 public static final String DISPLAY_SERVICE = "display"; 3378 3379 /** 3380 * Use with {@link #getSystemService} to retrieve a 3381 * {@link android.os.UserManager} for managing users on devices that support multiple users. 3382 * 3383 * @see #getSystemService 3384 * @see android.os.UserManager 3385 */ 3386 public static final String USER_SERVICE = "user"; 3387 3388 /** 3389 * Use with {@link #getSystemService} to retrieve a 3390 * {@link android.content.pm.LauncherApps} for querying and monitoring launchable apps across 3391 * profiles of a user. 3392 * 3393 * @see #getSystemService 3394 * @see android.content.pm.LauncherApps 3395 */ 3396 public static final String LAUNCHER_APPS_SERVICE = "launcherapps"; 3397 3398 /** 3399 * Use with {@link #getSystemService} to retrieve a 3400 * {@link android.content.RestrictionsManager} for retrieving application restrictions 3401 * and requesting permissions for restricted operations. 3402 * @see #getSystemService 3403 * @see android.content.RestrictionsManager 3404 */ 3405 public static final String RESTRICTIONS_SERVICE = "restrictions"; 3406 3407 /** 3408 * Use with {@link #getSystemService} to retrieve a 3409 * {@link android.app.AppOpsManager} for tracking application operations 3410 * on the device. 3411 * 3412 * @see #getSystemService 3413 * @see android.app.AppOpsManager 3414 */ 3415 public static final String APP_OPS_SERVICE = "appops"; 3416 3417 /** 3418 * Use with {@link #getSystemService} to retrieve a 3419 * {@link android.hardware.camera2.CameraManager} for interacting with 3420 * camera devices. 3421 * 3422 * @see #getSystemService 3423 * @see android.hardware.camera2.CameraManager 3424 */ 3425 public static final String CAMERA_SERVICE = "camera"; 3426 3427 /** 3428 * {@link android.print.PrintManager} for printing and managing 3429 * printers and print tasks. 3430 * 3431 * @see #getSystemService 3432 * @see android.print.PrintManager 3433 */ 3434 public static final String PRINT_SERVICE = "print"; 3435 3436 /** 3437 * Use with {@link #getSystemService} to retrieve a 3438 * {@link android.hardware.ConsumerIrManager} for transmitting infrared 3439 * signals from the device. 3440 * 3441 * @see #getSystemService 3442 * @see android.hardware.ConsumerIrManager 3443 */ 3444 public static final String CONSUMER_IR_SERVICE = "consumer_ir"; 3445 3446 /** 3447 * {@link android.app.trust.TrustManager} for managing trust agents. 3448 * @see #getSystemService 3449 * @see android.app.trust.TrustManager 3450 * @hide 3451 */ 3452 public static final String TRUST_SERVICE = "trust"; 3453 3454 /** 3455 * Use with {@link #getSystemService} to retrieve a 3456 * {@link android.media.tv.TvInputManager} for interacting with TV inputs 3457 * on the device. 3458 * 3459 * @see #getSystemService 3460 * @see android.media.tv.TvInputManager 3461 */ 3462 public static final String TV_INPUT_SERVICE = "tv_input"; 3463 3464 /** 3465 * {@link android.net.NetworkScoreManager} for managing network scoring. 3466 * @see #getSystemService 3467 * @see android.net.NetworkScoreManager 3468 * @hide 3469 */ 3470 @SystemApi 3471 public static final String NETWORK_SCORE_SERVICE = "network_score"; 3472 3473 /** 3474 * Use with {@link #getSystemService} to retrieve a {@link 3475 * android.app.usage.UsageStatsManager} for querying device usage stats. 3476 * 3477 * @see #getSystemService 3478 * @see android.app.usage.UsageStatsManager 3479 */ 3480 public static final String USAGE_STATS_SERVICE = "usagestats"; 3481 3482 /** 3483 * Use with {@link #getSystemService} to retrieve a {@link 3484 * android.app.job.JobScheduler} instance for managing occasional 3485 * background tasks. 3486 * @see #getSystemService 3487 * @see android.app.job.JobScheduler 3488 */ 3489 public static final String JOB_SCHEDULER_SERVICE = "jobscheduler"; 3490 3491 /** 3492 * Use with {@link #getSystemService} to retrieve a {@link 3493 * android.service.persistentdata.PersistentDataBlockManager} instance 3494 * for interacting with a storage device that lives across factory resets. 3495 * 3496 * @see #getSystemService 3497 * @see android.service.persistentdata.PersistentDataBlockManager 3498 * @hide 3499 */ 3500 @SystemApi 3501 public static final String PERSISTENT_DATA_BLOCK_SERVICE = "persistent_data_block"; 3502 3503 /** 3504 * Use with {@link #getSystemService} to retrieve a {@link 3505 * android.media.projection.MediaProjectionManager} instance for managing 3506 * media projection sessions. 3507 * @see #getSystemService 3508 * @see android.media.projection.MediaProjectionManager 3509 */ 3510 public static final String MEDIA_PROJECTION_SERVICE = "media_projection"; 3511 3512 /** 3513 * Use with {@link #getSystemService} to retrieve a 3514 * {@link android.media.midi.MidiManager} for accessing the MIDI service. 3515 * 3516 * @see #getSystemService 3517 */ 3518 public static final String MIDI_SERVICE = "midi"; 3519 3520 3521 /** 3522 * Use with {@link #getSystemService} to retrieve a 3523 * {@link android.hardware.radio.RadioManager} for accessing the broadcast radio service. 3524 * 3525 * @see #getSystemService 3526 * @hide 3527 */ 3528 public static final String RADIO_SERVICE = "radio"; 3529 3530 /** 3531 * Use with {@link #getSystemService} to retrieve a 3532 * {@link android.os.HardwarePropertiesManager} for accessing the hardware properties service. 3533 * 3534 * @see #getSystemService 3535 */ 3536 public static final String HARDWARE_PROPERTIES_SERVICE = "hardwareproperties"; 3537 3538 /** 3539 * Determine whether the given permission is allowed for a particular 3540 * process and user ID running in the system. 3541 * 3542 * @param permission The name of the permission being checked. 3543 * @param pid The process ID being checked against. Must be > 0. 3544 * @param uid The user ID being checked against. A uid of 0 is the root 3545 * user, which will pass every permission check. 3546 * 3547 * @return {@link PackageManager#PERMISSION_GRANTED} if the given 3548 * pid/uid is allowed that permission, or 3549 * {@link PackageManager#PERMISSION_DENIED} if it is not. 3550 * 3551 * @see PackageManager#checkPermission(String, String) 3552 * @see #checkCallingPermission 3553 */ 3554 @CheckResult(suggest="#enforcePermission(String,int,int,String)") 3555 @PackageManager.PermissionResult 3556 public abstract int checkPermission(@NonNull String permission, int pid, int uid); 3557 3558 /** @hide */ 3559 @PackageManager.PermissionResult 3560 public abstract int checkPermission(@NonNull String permission, int pid, int uid, 3561 IBinder callerToken); 3562 3563 /** 3564 * Determine whether the calling process of an IPC you are handling has been 3565 * granted a particular permission. This is basically the same as calling 3566 * {@link #checkPermission(String, int, int)} with the pid and uid returned 3567 * by {@link android.os.Binder#getCallingPid} and 3568 * {@link android.os.Binder#getCallingUid}. One important difference 3569 * is that if you are not currently processing an IPC, this function 3570 * will always fail. This is done to protect against accidentally 3571 * leaking permissions; you can use {@link #checkCallingOrSelfPermission} 3572 * to avoid this protection. 3573 * 3574 * @param permission The name of the permission being checked. 3575 * 3576 * @return {@link PackageManager#PERMISSION_GRANTED} if the calling 3577 * pid/uid is allowed that permission, or 3578 * {@link PackageManager#PERMISSION_DENIED} if it is not. 3579 * 3580 * @see PackageManager#checkPermission(String, String) 3581 * @see #checkPermission 3582 * @see #checkCallingOrSelfPermission 3583 */ 3584 @CheckResult(suggest="#enforceCallingPermission(String,String)") 3585 @PackageManager.PermissionResult 3586 public abstract int checkCallingPermission(@NonNull String permission); 3587 3588 /** 3589 * Determine whether the calling process of an IPC <em>or you</em> have been 3590 * granted a particular permission. This is the same as 3591 * {@link #checkCallingPermission}, except it grants your own permissions 3592 * if you are not currently processing an IPC. Use with care! 3593 * 3594 * @param permission The name of the permission being checked. 3595 * 3596 * @return {@link PackageManager#PERMISSION_GRANTED} if the calling 3597 * pid/uid is allowed that permission, or 3598 * {@link PackageManager#PERMISSION_DENIED} if it is not. 3599 * 3600 * @see PackageManager#checkPermission(String, String) 3601 * @see #checkPermission 3602 * @see #checkCallingPermission 3603 */ 3604 @CheckResult(suggest="#enforceCallingOrSelfPermission(String,String)") 3605 @PackageManager.PermissionResult 3606 public abstract int checkCallingOrSelfPermission(@NonNull String permission); 3607 3608 /** 3609 * Determine whether <em>you</em> have been granted a particular permission. 3610 * 3611 * @param permission The name of the permission being checked. 3612 * 3613 * @return {@link PackageManager#PERMISSION_GRANTED} if you have the 3614 * permission, or {@link PackageManager#PERMISSION_DENIED} if not. 3615 * 3616 * @see PackageManager#checkPermission(String, String) 3617 * @see #checkCallingPermission(String) 3618 */ 3619 @PackageManager.PermissionResult 3620 public abstract int checkSelfPermission(@NonNull String permission); 3621 3622 /** 3623 * If the given permission is not allowed for a particular process 3624 * and user ID running in the system, throw a {@link SecurityException}. 3625 * 3626 * @param permission The name of the permission being checked. 3627 * @param pid The process ID being checked against. Must be > 0. 3628 * @param uid The user ID being checked against. A uid of 0 is the root 3629 * user, which will pass every permission check. 3630 * @param message A message to include in the exception if it is thrown. 3631 * 3632 * @see #checkPermission(String, int, int) 3633 */ 3634 public abstract void enforcePermission( 3635 @NonNull String permission, int pid, int uid, @Nullable String message); 3636 3637 /** 3638 * If the calling process of an IPC you are handling has not been 3639 * granted a particular permission, throw a {@link 3640 * SecurityException}. This is basically the same as calling 3641 * {@link #enforcePermission(String, int, int, String)} with the 3642 * pid and uid returned by {@link android.os.Binder#getCallingPid} 3643 * and {@link android.os.Binder#getCallingUid}. One important 3644 * difference is that if you are not currently processing an IPC, 3645 * this function will always throw the SecurityException. This is 3646 * done to protect against accidentally leaking permissions; you 3647 * can use {@link #enforceCallingOrSelfPermission} to avoid this 3648 * protection. 3649 * 3650 * @param permission The name of the permission being checked. 3651 * @param message A message to include in the exception if it is thrown. 3652 * 3653 * @see #checkCallingPermission(String) 3654 */ 3655 public abstract void enforceCallingPermission( 3656 @NonNull String permission, @Nullable String message); 3657 3658 /** 3659 * If neither you nor the calling process of an IPC you are 3660 * handling has been granted a particular permission, throw a 3661 * {@link SecurityException}. This is the same as {@link 3662 * #enforceCallingPermission}, except it grants your own 3663 * permissions if you are not currently processing an IPC. Use 3664 * with care! 3665 * 3666 * @param permission The name of the permission being checked. 3667 * @param message A message to include in the exception if it is thrown. 3668 * 3669 * @see #checkCallingOrSelfPermission(String) 3670 */ 3671 public abstract void enforceCallingOrSelfPermission( 3672 @NonNull String permission, @Nullable String message); 3673 3674 /** 3675 * Grant permission to access a specific Uri to another package, regardless 3676 * of whether that package has general permission to access the Uri's 3677 * content provider. This can be used to grant specific, temporary 3678 * permissions, typically in response to user interaction (such as the 3679 * user opening an attachment that you would like someone else to 3680 * display). 3681 * 3682 * <p>Normally you should use {@link Intent#FLAG_GRANT_READ_URI_PERMISSION 3683 * Intent.FLAG_GRANT_READ_URI_PERMISSION} or 3684 * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION 3685 * Intent.FLAG_GRANT_WRITE_URI_PERMISSION} with the Intent being used to 3686 * start an activity instead of this function directly. If you use this 3687 * function directly, you should be sure to call 3688 * {@link #revokeUriPermission} when the target should no longer be allowed 3689 * to access it. 3690 * 3691 * <p>To succeed, the content provider owning the Uri must have set the 3692 * {@link android.R.styleable#AndroidManifestProvider_grantUriPermissions 3693 * grantUriPermissions} attribute in its manifest or included the 3694 * {@link android.R.styleable#AndroidManifestGrantUriPermission 3695 * <grant-uri-permissions>} tag. 3696 * 3697 * @param toPackage The package you would like to allow to access the Uri. 3698 * @param uri The Uri you would like to grant access to. 3699 * @param modeFlags The desired access modes. Any combination of 3700 * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION 3701 * Intent.FLAG_GRANT_READ_URI_PERMISSION}, 3702 * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION 3703 * Intent.FLAG_GRANT_WRITE_URI_PERMISSION}, 3704 * {@link Intent#FLAG_GRANT_PERSISTABLE_URI_PERMISSION 3705 * Intent.FLAG_GRANT_PERSISTABLE_URI_PERMISSION}, or 3706 * {@link Intent#FLAG_GRANT_PREFIX_URI_PERMISSION 3707 * Intent.FLAG_GRANT_PREFIX_URI_PERMISSION}. 3708 * 3709 * @see #revokeUriPermission 3710 */ 3711 public abstract void grantUriPermission(String toPackage, Uri uri, 3712 @Intent.GrantUriMode int modeFlags); 3713 3714 /** 3715 * Remove all permissions to access a particular content provider Uri 3716 * that were previously added with {@link #grantUriPermission}. The given 3717 * Uri will match all previously granted Uris that are the same or a 3718 * sub-path of the given Uri. That is, revoking "content://foo/target" will 3719 * revoke both "content://foo/target" and "content://foo/target/sub", but not 3720 * "content://foo". It will not remove any prefix grants that exist at a 3721 * higher level. 3722 * 3723 * <p>Prior to {@link android.os.Build.VERSION_CODES#LOLLIPOP}, if you did not have 3724 * regular permission access to a Uri, but had received access to it through 3725 * a specific Uri permission grant, you could not revoke that grant with this 3726 * function and a {@link SecurityException} would be thrown. As of 3727 * {@link android.os.Build.VERSION_CODES#LOLLIPOP}, this function will not throw a security exception, 3728 * but will remove whatever permission grants to the Uri had been given to the app 3729 * (or none).</p> 3730 * 3731 * @param uri The Uri you would like to revoke access to. 3732 * @param modeFlags The desired access modes. Any combination of 3733 * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION 3734 * Intent.FLAG_GRANT_READ_URI_PERMISSION} or 3735 * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION 3736 * Intent.FLAG_GRANT_WRITE_URI_PERMISSION}. 3737 * 3738 * @see #grantUriPermission 3739 */ 3740 public abstract void revokeUriPermission(Uri uri, @Intent.AccessUriMode int modeFlags); 3741 3742 /** 3743 * Determine whether a particular process and user ID has been granted 3744 * permission to access a specific URI. This only checks for permissions 3745 * that have been explicitly granted -- if the given process/uid has 3746 * more general access to the URI's content provider then this check will 3747 * always fail. 3748 * 3749 * @param uri The uri that is being checked. 3750 * @param pid The process ID being checked against. Must be > 0. 3751 * @param uid The user ID being checked against. A uid of 0 is the root 3752 * user, which will pass every permission check. 3753 * @param modeFlags The type of access to grant. May be one or both of 3754 * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or 3755 * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}. 3756 * 3757 * @return {@link PackageManager#PERMISSION_GRANTED} if the given 3758 * pid/uid is allowed to access that uri, or 3759 * {@link PackageManager#PERMISSION_DENIED} if it is not. 3760 * 3761 * @see #checkCallingUriPermission 3762 */ 3763 @CheckResult(suggest="#enforceUriPermission(Uri,int,int,String)") 3764 public abstract int checkUriPermission(Uri uri, int pid, int uid, 3765 @Intent.AccessUriMode int modeFlags); 3766 3767 /** @hide */ 3768 public abstract int checkUriPermission(Uri uri, int pid, int uid, 3769 @Intent.AccessUriMode int modeFlags, IBinder callerToken); 3770 3771 /** 3772 * Determine whether the calling process and user ID has been 3773 * granted permission to access a specific URI. This is basically 3774 * the same as calling {@link #checkUriPermission(Uri, int, int, 3775 * int)} with the pid and uid returned by {@link 3776 * android.os.Binder#getCallingPid} and {@link 3777 * android.os.Binder#getCallingUid}. One important difference is 3778 * that if you are not currently processing an IPC, this function 3779 * will always fail. 3780 * 3781 * @param uri The uri that is being checked. 3782 * @param modeFlags The type of access to grant. May be one or both of 3783 * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or 3784 * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}. 3785 * 3786 * @return {@link PackageManager#PERMISSION_GRANTED} if the caller 3787 * is allowed to access that uri, or 3788 * {@link PackageManager#PERMISSION_DENIED} if it is not. 3789 * 3790 * @see #checkUriPermission(Uri, int, int, int) 3791 */ 3792 @CheckResult(suggest="#enforceCallingUriPermission(Uri,int,String)") 3793 public abstract int checkCallingUriPermission(Uri uri, @Intent.AccessUriMode int modeFlags); 3794 3795 /** 3796 * Determine whether the calling process of an IPC <em>or you</em> has been granted 3797 * permission to access a specific URI. This is the same as 3798 * {@link #checkCallingUriPermission}, except it grants your own permissions 3799 * if you are not currently processing an IPC. Use with care! 3800 * 3801 * @param uri The uri that is being checked. 3802 * @param modeFlags The type of access to grant. May be one or both of 3803 * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or 3804 * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}. 3805 * 3806 * @return {@link PackageManager#PERMISSION_GRANTED} if the caller 3807 * is allowed to access that uri, or 3808 * {@link PackageManager#PERMISSION_DENIED} if it is not. 3809 * 3810 * @see #checkCallingUriPermission 3811 */ 3812 @CheckResult(suggest="#enforceCallingOrSelfUriPermission(Uri,int,String)") 3813 public abstract int checkCallingOrSelfUriPermission(Uri uri, 3814 @Intent.AccessUriMode int modeFlags); 3815 3816 /** 3817 * Check both a Uri and normal permission. This allows you to perform 3818 * both {@link #checkPermission} and {@link #checkUriPermission} in one 3819 * call. 3820 * 3821 * @param uri The Uri whose permission is to be checked, or null to not 3822 * do this check. 3823 * @param readPermission The permission that provides overall read access, 3824 * or null to not do this check. 3825 * @param writePermission The permission that provides overall write 3826 * access, or null to not do this check. 3827 * @param pid The process ID being checked against. Must be > 0. 3828 * @param uid The user ID being checked against. A uid of 0 is the root 3829 * user, which will pass every permission check. 3830 * @param modeFlags The type of access to grant. May be one or both of 3831 * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or 3832 * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}. 3833 * 3834 * @return {@link PackageManager#PERMISSION_GRANTED} if the caller 3835 * is allowed to access that uri or holds one of the given permissions, or 3836 * {@link PackageManager#PERMISSION_DENIED} if it is not. 3837 */ 3838 @CheckResult(suggest="#enforceUriPermission(Uri,String,String,int,int,int,String)") 3839 public abstract int checkUriPermission(@Nullable Uri uri, @Nullable String readPermission, 3840 @Nullable String writePermission, int pid, int uid, 3841 @Intent.AccessUriMode int modeFlags); 3842 3843 /** 3844 * If a particular process and user ID has not been granted 3845 * permission to access a specific URI, throw {@link 3846 * SecurityException}. This only checks for permissions that have 3847 * been explicitly granted -- if the given process/uid has more 3848 * general access to the URI's content provider then this check 3849 * will always fail. 3850 * 3851 * @param uri The uri that is being checked. 3852 * @param pid The process ID being checked against. Must be > 0. 3853 * @param uid The user ID being checked against. A uid of 0 is the root 3854 * user, which will pass every permission check. 3855 * @param modeFlags The type of access to grant. May be one or both of 3856 * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or 3857 * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}. 3858 * @param message A message to include in the exception if it is thrown. 3859 * 3860 * @see #checkUriPermission(Uri, int, int, int) 3861 */ 3862 public abstract void enforceUriPermission( 3863 Uri uri, int pid, int uid, @Intent.AccessUriMode int modeFlags, String message); 3864 3865 /** 3866 * If the calling process and user ID has not been granted 3867 * permission to access a specific URI, throw {@link 3868 * SecurityException}. This is basically the same as calling 3869 * {@link #enforceUriPermission(Uri, int, int, int, String)} with 3870 * the pid and uid returned by {@link 3871 * android.os.Binder#getCallingPid} and {@link 3872 * android.os.Binder#getCallingUid}. One important difference is 3873 * that if you are not currently processing an IPC, this function 3874 * will always throw a SecurityException. 3875 * 3876 * @param uri The uri that is being checked. 3877 * @param modeFlags The type of access to grant. May be one or both of 3878 * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or 3879 * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}. 3880 * @param message A message to include in the exception if it is thrown. 3881 * 3882 * @see #checkCallingUriPermission(Uri, int) 3883 */ 3884 public abstract void enforceCallingUriPermission( 3885 Uri uri, @Intent.AccessUriMode int modeFlags, String message); 3886 3887 /** 3888 * If the calling process of an IPC <em>or you</em> has not been 3889 * granted permission to access a specific URI, throw {@link 3890 * SecurityException}. This is the same as {@link 3891 * #enforceCallingUriPermission}, except it grants your own 3892 * permissions if you are not currently processing an IPC. Use 3893 * with care! 3894 * 3895 * @param uri The uri that is being checked. 3896 * @param modeFlags The type of access to grant. May be one or both of 3897 * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or 3898 * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}. 3899 * @param message A message to include in the exception if it is thrown. 3900 * 3901 * @see #checkCallingOrSelfUriPermission(Uri, int) 3902 */ 3903 public abstract void enforceCallingOrSelfUriPermission( 3904 Uri uri, @Intent.AccessUriMode int modeFlags, String message); 3905 3906 /** 3907 * Enforce both a Uri and normal permission. This allows you to perform 3908 * both {@link #enforcePermission} and {@link #enforceUriPermission} in one 3909 * call. 3910 * 3911 * @param uri The Uri whose permission is to be checked, or null to not 3912 * do this check. 3913 * @param readPermission The permission that provides overall read access, 3914 * or null to not do this check. 3915 * @param writePermission The permission that provides overall write 3916 * access, or null to not do this check. 3917 * @param pid The process ID being checked against. Must be > 0. 3918 * @param uid The user ID being checked against. A uid of 0 is the root 3919 * user, which will pass every permission check. 3920 * @param modeFlags The type of access to grant. May be one or both of 3921 * {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or 3922 * {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}. 3923 * @param message A message to include in the exception if it is thrown. 3924 * 3925 * @see #checkUriPermission(Uri, String, String, int, int, int) 3926 */ 3927 public abstract void enforceUriPermission( 3928 @Nullable Uri uri, @Nullable String readPermission, 3929 @Nullable String writePermission, int pid, int uid, @Intent.AccessUriMode int modeFlags, 3930 @Nullable String message); 3931 3932 /** @hide */ 3933 @IntDef(flag = true, 3934 value = {CONTEXT_INCLUDE_CODE, CONTEXT_IGNORE_SECURITY, CONTEXT_RESTRICTED}) 3935 @Retention(RetentionPolicy.SOURCE) 3936 public @interface CreatePackageOptions {} 3937 3938 /** 3939 * Flag for use with {@link #createPackageContext}: include the application 3940 * code with the context. This means loading code into the caller's 3941 * process, so that {@link #getClassLoader()} can be used to instantiate 3942 * the application's classes. Setting this flags imposes security 3943 * restrictions on what application context you can access; if the 3944 * requested application can not be safely loaded into your process, 3945 * java.lang.SecurityException will be thrown. If this flag is not set, 3946 * there will be no restrictions on the packages that can be loaded, 3947 * but {@link #getClassLoader} will always return the default system 3948 * class loader. 3949 */ 3950 public static final int CONTEXT_INCLUDE_CODE = 0x00000001; 3951 3952 /** 3953 * Flag for use with {@link #createPackageContext}: ignore any security 3954 * restrictions on the Context being requested, allowing it to always 3955 * be loaded. For use with {@link #CONTEXT_INCLUDE_CODE} to allow code 3956 * to be loaded into a process even when it isn't safe to do so. Use 3957 * with extreme care! 3958 */ 3959 public static final int CONTEXT_IGNORE_SECURITY = 0x00000002; 3960 3961 /** 3962 * Flag for use with {@link #createPackageContext}: a restricted context may 3963 * disable specific features. For instance, a View associated with a restricted 3964 * context would ignore particular XML attributes. 3965 */ 3966 public static final int CONTEXT_RESTRICTED = 0x00000004; 3967 3968 /** 3969 * Flag for use with {@link #createPackageContext}: point all file APIs at 3970 * device-encrypted storage. 3971 * 3972 * @hide 3973 */ 3974 public static final int CONTEXT_DEVICE_ENCRYPTED_STORAGE = 0x00000008; 3975 3976 /** 3977 * Flag for use with {@link #createPackageContext}: point all file APIs at 3978 * credential-encrypted storage. 3979 * 3980 * @hide 3981 */ 3982 public static final int CONTEXT_CREDENTIAL_ENCRYPTED_STORAGE = 0x00000010; 3983 3984 /** 3985 * @hide Used to indicate we should tell the activity manager about the process 3986 * loading this code. 3987 */ 3988 public static final int CONTEXT_REGISTER_PACKAGE = 0x40000000; 3989 3990 /** 3991 * Return a new Context object for the given application name. This 3992 * Context is the same as what the named application gets when it is 3993 * launched, containing the same resources and class loader. Each call to 3994 * this method returns a new instance of a Context object; Context objects 3995 * are not shared, however they share common state (Resources, ClassLoader, 3996 * etc) so the Context instance itself is fairly lightweight. 3997 * 3998 * <p>Throws {@link android.content.pm.PackageManager.NameNotFoundException} if there is no 3999 * application with the given package name. 4000 * 4001 * <p>Throws {@link java.lang.SecurityException} if the Context requested 4002 * can not be loaded into the caller's process for security reasons (see 4003 * {@link #CONTEXT_INCLUDE_CODE} for more information}. 4004 * 4005 * @param packageName Name of the application's package. 4006 * @param flags Option flags, one of {@link #CONTEXT_INCLUDE_CODE} 4007 * or {@link #CONTEXT_IGNORE_SECURITY}. 4008 * 4009 * @return A {@link Context} for the application. 4010 * 4011 * @throws SecurityException 4012 * @throws PackageManager.NameNotFoundException if there is no application with 4013 * the given package name. 4014 */ 4015 public abstract Context createPackageContext(String packageName, 4016 @CreatePackageOptions int flags) throws PackageManager.NameNotFoundException; 4017 4018 /** 4019 * Similar to {@link #createPackageContext(String, int)}, but with a 4020 * different {@link UserHandle}. For example, {@link #getContentResolver()} 4021 * will open any {@link Uri} as the given user. 4022 * 4023 * @hide 4024 */ 4025 public abstract Context createPackageContextAsUser( 4026 String packageName, int flags, UserHandle user) 4027 throws PackageManager.NameNotFoundException; 4028 4029 /** 4030 * Creates a context given an {@link android.content.pm.ApplicationInfo}. 4031 * 4032 * @hide 4033 */ 4034 public abstract Context createApplicationContext(ApplicationInfo application, 4035 int flags) throws PackageManager.NameNotFoundException; 4036 4037 /** 4038 * Get the userId associated with this context 4039 * @return user id 4040 * 4041 * @hide 4042 */ 4043 @TestApi 4044 public abstract @UserIdInt int getUserId(); 4045 4046 /** 4047 * Return a new Context object for the current Context but whose resources 4048 * are adjusted to match the given Configuration. Each call to this method 4049 * returns a new instance of a Context object; Context objects are not 4050 * shared, however common state (ClassLoader, other Resources for the 4051 * same configuration) may be so the Context itself can be fairly lightweight. 4052 * 4053 * @param overrideConfiguration A {@link Configuration} specifying what 4054 * values to modify in the base Configuration of the original Context's 4055 * resources. If the base configuration changes (such as due to an 4056 * orientation change), the resources of this context will also change except 4057 * for those that have been explicitly overridden with a value here. 4058 * 4059 * @return A {@link Context} with the given configuration override. 4060 */ 4061 public abstract Context createConfigurationContext( 4062 @NonNull Configuration overrideConfiguration); 4063 4064 /** 4065 * Return a new Context object for the current Context but whose resources 4066 * are adjusted to match the metrics of the given Display. Each call to this method 4067 * returns a new instance of a Context object; Context objects are not 4068 * shared, however common state (ClassLoader, other Resources for the 4069 * same configuration) may be so the Context itself can be fairly lightweight. 4070 * 4071 * The returned display Context provides a {@link WindowManager} 4072 * (see {@link #getSystemService(String)}) that is configured to show windows 4073 * on the given display. The WindowManager's {@link WindowManager#getDefaultDisplay} 4074 * method can be used to retrieve the Display from the returned Context. 4075 * 4076 * @param display A {@link Display} object specifying the display 4077 * for whose metrics the Context's resources should be tailored and upon which 4078 * new windows should be shown. 4079 * 4080 * @return A {@link Context} for the display. 4081 */ 4082 public abstract Context createDisplayContext(@NonNull Display display); 4083 4084 /** 4085 * Return a new Context object for the current Context but whose storage 4086 * APIs are backed by device-encrypted storage. 4087 * <p> 4088 * Data stored in device-encrypted storage is typically encrypted with a key 4089 * tied to the physical device, and it can be accessed when the device has 4090 * booted successfully, both <em>before and after</em> the user has 4091 * authenticated with their credentials (such as a lock pattern or PIN). 4092 * Because device-encrypted data is available before user authentication, 4093 * you should carefully consider what data you store using this Context. 4094 * <p> 4095 * If the underlying device does not have the ability to store 4096 * device-encrypted and credential-encrypted data using different keys, then 4097 * both storage areas will become available at the same time. They remain 4098 * two distinct storage areas, and only the window of availability changes. 4099 * <p> 4100 * Each call to this method returns a new instance of a Context object; 4101 * Context objects are not shared, however common state (ClassLoader, other 4102 * Resources for the same configuration) may be so the Context itself can be 4103 * fairly lightweight. 4104 * 4105 * @see #isDeviceEncryptedStorage() 4106 */ 4107 public abstract Context createDeviceEncryptedStorageContext(); 4108 4109 /** 4110 * Return a new Context object for the current Context but whose storage 4111 * APIs are backed by credential-encrypted storage. 4112 * <p> 4113 * Data stored in credential-encrypted storage is typically encrypted with a 4114 * key tied to user credentials, and they can be accessed 4115 * <em>only after</em> the user has entered their credentials (such as a 4116 * lock pattern or PIN). 4117 * <p> 4118 * If the underlying device does not have the ability to store 4119 * device-encrypted and credential-encrypted data using different keys, then 4120 * both storage areas will become available at the same time. They remain 4121 * two distinct storage areas, and only the window of availability changes. 4122 * <p> 4123 * Each call to this method returns a new instance of a Context object; 4124 * Context objects are not shared, however common state (ClassLoader, other 4125 * Resources for the same configuration) may be so the Context itself can be 4126 * fairly lightweight. 4127 * 4128 * @see #isCredentialEncryptedStorage() 4129 * @hide 4130 */ 4131 @SystemApi 4132 public abstract Context createCredentialEncryptedStorageContext(); 4133 4134 /** 4135 * Gets the display adjustments holder for this context. This information 4136 * is provided on a per-application or activity basis and is used to simulate lower density 4137 * display metrics for legacy applications and restricted screen sizes. 4138 * 4139 * @param displayId The display id for which to get compatibility info. 4140 * @return The compatibility info holder, or null if not required by the application. 4141 * @hide 4142 */ 4143 public abstract DisplayAdjustments getDisplayAdjustments(int displayId); 4144 4145 /** 4146 * Indicates whether this Context is restricted. 4147 * 4148 * @return {@code true} if this Context is restricted, {@code false} otherwise. 4149 * 4150 * @see #CONTEXT_RESTRICTED 4151 */ 4152 public boolean isRestricted() { 4153 return false; 4154 } 4155 4156 /** 4157 * Indicates if the storage APIs of this Context are backed by 4158 * device-encrypted storage. 4159 * 4160 * @see #createDeviceEncryptedStorageContext() 4161 */ 4162 public abstract boolean isDeviceEncryptedStorage(); 4163 4164 /** 4165 * Indicates if the storage APIs of this Context are backed by 4166 * credential-encrypted storage. 4167 * 4168 * @see #createCredentialEncryptedStorageContext() 4169 * @hide 4170 */ 4171 @SystemApi 4172 public abstract boolean isCredentialEncryptedStorage(); 4173} 4174