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 &nbsp;
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 &nbsp;
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 &nbsp;
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 &nbsp;
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 &nbsp;
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 &nbsp;
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 &nbsp;
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 &nbsp;
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 &nbsp;
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 &nbsp;
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 &gt; 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      * &lt;grant-uri-permissions&gt;} 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 &gt; 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 &gt; 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 &gt; 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 &gt; 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 &nbsp;
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