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