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