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